qipai/docs/devlogs/2026-06-18-M02-A-多小程序租户模型.md

M02-A 多小程序/租户模型

• 日期：2026-06-18
• 起始 commit：9d13f75
• 工程 commit：8b8fb28
• 推送校验：HEAD == origin/main == 8b8fb28c36c7a27e34bde3dcb60eada45025913e
• ENGINEERING_DELTA=YES
• 子阶段状态：DONE

工程增量

• 新增 qipai_platform_apps、qipai_tenant_apps、qipai_tenant_configs 迁移、验证和回滚 SQL。
• 新增 PlatformConfigRepository，按 AppID 与租户绑定读取品牌启动配置。
• 新增 GET /app-api/bootstrap，提供 AppID/租户解析、格式校验和明确的 400/404/409 错误。
• 后端进程创建 MySQL 连接池并在关闭时释放；启动配置路由使用正式仓储。
• 增加迁移契约、仓储隔离、HTTP 注入和真实 MySQL 往返测试。

验收结果

• 一个 AppID 可绑定一个或多个租户；首期一对一无需传 tenant-id，多租户绑定必须明确选择。
• 租户配置唯一键包含 tenant_id，读取 SQL 同时校验应用绑定与租户归属。
• 品牌、Logo、主题、电话、分享配置按 AppID/tenant 返回。
• 同一 AppID 下两个租户读取到各自品牌配置；不存在的跨租户 ID 无法读取。

已执行验证

1. npm test（目录 backend/）
   • 退出码：0
   • TypeScript 构建、迁移契约、仓储、HTTP 注入等测试全部 PASS。
2. WSL 原生临时副本执行 bash scripts/dev/wsl/mysql-migration-roundtrip.sh
   • MySQL：8.4.9-0ubuntu0.26.04.1
   • 序列：up → verify → down → up → verify
   • 退出码：0
   • 18 条 up、9 条 verify、17 条 down；应用绑定、跨租户拒绝和旧库兼容均 PASS。
3. git diff --check
   • 退出码：0。

边界与影响

• 数据库：新增迁移 2026061803。
• API：新增 /app-api/bootstrap。
• 部署影响：后端启动会创建 MySQL 连接池；沿用现有 MySQL 环境变量，无新增生产密钥。
• 小程序：本阶段未纳管工作区未跟踪模板；ISSUE-007 继续隔离。
• 下一阶段：M02-B 微信登录、用户身份、JWT 与可撤销会话。