Appearance
QM-ServerV2 知识库总索引
📍 位置：
docs/｜ 维护：架构师 + AI 协作负责人 ｜ 版本：2026-09-17 v3（收拢版结构） 覆盖：84 页 · 8 大区 —— API Docs / Internal Wiki / 模块手册 / V1 提炼资料 / 快速上手 / AI Contexts / Runbooks / 首页🔗 相关入口：线上站 · CNB Pipeline · Docker 制品（
docker.cnb.cool/qingmu2026/qm-serverv2/qm-serverv2-api:latest）
1. 知识库地图（8 大区）
| 区 | 受众 | 定位 | 入口 | 页数 |
|---|---|---|---|---|
| 🔵 API Docs | 前端 / 第三方集成 | 接口契约 — 字段表、错误码矩阵、状态机、模块契约卡 | /api-docs/ | 47 |
| 🟢 Internal Wiki | 团队 / 架构师 | 架构决策 + 范式沉淀 + 运维 + 迁移参考 | /internal-wiki/ | 22 |
| 📦 模块手册 | 后端开发 | 26 模块权威开发手册（按 6 域收拢） | /modules/ | 7 |
| 🟣 V1 提炼资料 | 迁移开发 | QM-APP（V1）→ V2 迁移参考（算法/契约/AI/DB/设备安全 5 卡） | /internal-wiki/migration/INDEX | 1 |
| 🧭 快速上手 | 新成员 / 联调方 | 5 步启动 + 命令清单 | /guide/quickstart | 1 |
| 🟡 AI Contexts | Claude / Cursor / Cody | 代码风格 + 模块约定 + 错误码权威注册表 | /ai-contexts/ | 4 |
| 📕 Runbooks | 运维 | 部署与回滚 | /runbooks/deploy-rollback | 1 |
| 🏠 首页 | 全员 | hero 卡片导航 | / | 1 |
结构说明（2026-09-17 收拢）：碎片页按主题合并为「文档内目录」型大页（迁移 5 卡→1 页、ADR 12 篇→1 页、深挖 3 篇→1 页、测试报告 5 期→1 页、模块手册 26 篇→6 域页），页数 127→84，信息零删减。
写作约定：字段表 → OpenAPI schema 自动生成；业务说明 → AI 初稿 + 开发者 review；状态机图 → Mermaid。版本对齐：知识库跟随 API 版本（v1）。
2. ADR 决策索引（0001-0011 + 范式）
📄 已收拢为单页全集：ADR 决策记录全集 ｜ 写作约定：背景 → 方案 → 权衡 → 后果 四段式
| # | 标题 | Status | 一句话摘要 |
|---|---|---|---|
| 0001 | 选 CNB cnb.cool 作为 CI/CD 平台 | Accepted | 国内 SaaS 友好 + 原生代码托管 + 4 环境 promote 一体化 |
| 0002 | 四环境 Promote 链（dev→test→staging→prod） | Accepted | 前 3 环自动 + prod tag 触发手动 |
| 0003 | 多租户数据隔离（Postgres schema-per-tenant） | Accepted（接口预留） | schema_translate_map + alembic 循环迁移；当前单租户 |
| 0004 | JWT RS256 + 业务异常注册顺序 | Accepted | 业务异常 Handler 必须在 HTTPException 之前（OATH-M-006 教训） |
| 0005 | 管理后台前端选 React Native Web | Accepted | web 优先，未来加 iOS/Android 改动可控 |
| 0006 | 状态管理选 Redux Toolkit + RTK Query | Accepted | OpenAPI 自动 hooks + tag 失效 |
| 0007 | UI 库选 Tamagui | Accepted | 编译时样式提取 + 跨端一致性 |
| 0008 | Web 端 Token 加密存储（IndexedDB + AES-GCM） | Accepted | 双 token 本地加密持久化 |
| 0009 | Admin RBAC 选 3 角色矩阵（自实现） | Accepted | SUPER / OPERATOR / IT + 编译期矩阵；不引入 Casbin / OPA |
| 0010 | admin 审计日志强约束 | Accepted | 所有写操作必写 audit log（Phase 4 批量写入） |
| 0011 | 服务器原生构建 | Accepted | 跨架构镜像 exec format error → 服务器原生 docker build |
| — | 核心范式沉淀 15 条（P1-P15） | — | 双仓储 / 端口契约 / 工厂 / Schema strict / 三步走 / Lua 原子等 |
3. 架构与规范
| 文档 | 一句话 |
|---|---|
| OAuth 实施总览 ⭐ | 9 action 完整实施规范、错误码体系、验证码状态机 |
| DDD 4 层架构 | src/app/{domain,application,infrastructure,interface}/ 边界与依赖方向 |
| 错误码体系（OATH-M-006） | 业务码分配规则 + Handler 注册顺序教训 |
| Admin MIS 设计 | 82 use case / 12 子域 / RBAC / 5 Phase 路线图（后端最大模块） |
| Admin Web RN 设计 | 19 项选型 + Tamagui 深挖 + 构建部署 |
| 设备云对接研究 | 12 平台矩阵 + 授权中心四态 + IDeviceVendor 框架 |
| IDeviceVendor v2 计划 | G1 webhook / G2 import 缺口 + 五步路线 |
| OAuth 深度解析（合集） | 联调 cookbook + JWT 解剖 + 多设备会话（3 篇收拢） |
| 代码风格 · 模块约定 · 错误码权威注册表 | AI 协作三件套（注册表 = 201 码 / 25 段权威表） |
4. API Docs 索引
4.1 OAuth（10 篇 · 契约面向前端）
| 文档 | 用途 |
|---|---|
| 概览 · 9 Action 字段表 | 登录认证链全字段 |
| 错误码矩阵（40101xxx） · （HTTP 视角） | 业务码 / HTTP 双视角互补 |
| 验证码状态机 · 安全规范 · 限流规则 | 风控三件套 |
| SDK 参考 · uniapp 开发指南 · 前后联调实录 | 落地与联调 |
4.2 Admin MIS（13 篇）· 4.3 User / Device
| 文档 | 用途 |
|---|---|
| admin 总览 + 12 子域 | 82 use case / RBAC 26 权限位 / 40201xxx / confirm_text 6 操作 |
| user/actions | C 端 11 action（40301xxx） |
| device 总览 + 4 子域 | 授权中心四态 + honor / zepp / xiaomi / vendors |
4.4 模块契约卡（20 篇 · 代码直出）
每篇 = 路由 + 错误码段 + 鉴权 + action 一览 + 通用约定（对接速查，字段真相在 usecase dataclass）
跑者向：shoes · training · goal · sport · upload 资产域：wallet · points · coupon · cart · mall · group_buy · distribution 社区：feed · follow · favorite · review 设备：suunto
5. 模块手册（6 域 · 26 模块）
| 域 | 模块 | 入口 |
|---|---|---|
| 认证与用户 | oauth · user · shared | /modules/auth-user |
| 设备线 | device · honor · zepp · xiaomi · suunto | /modules/device-line |
| 运动健康 | sport · training · goal · stats · shoes · upload | /modules/sport-health |
| 交易与资产 | wallet · points · coupon · cart · mall · group_buy · distribution | /modules/trade-assets |
| 社区 | feed · follow · favorite · review | /modules/community |
| 管理 | admin | /modules/admin |
6. 运维与 Runbook
| 文档 | 一句话 |
|---|---|
| CI Pipeline（CNB） · CNB 仓初始化 | 流水线与平台配置 |
| Docker Compose · Secrets 与 Envs | 本地栈与密钥管理 |
| API 冒烟测试 · 报告合集（5 期） | 四层全量 + 时间戳留档 |
| 性能压测基线 | locust QPS/p50/p95/p99 |
| 生产重装 Checklist · 踩坑实录 2026-09-16 | 灾备手册 + 23 坑 |
| Admin Web 对接 Backlog · 小米开放平台申请 | 待办与商务流程 |
| 部署回滚 Runbook | 生产部署与秒级回滚 |
7. 工程化文件清单
.cnb/ # CNB 主 pipeline + 四环境 envs
alembic/ # 迁移链（env.py / versions/）
scripts/ # backup / health-check / rollback / smoke-test /
# check_exception_handlers.py / check_layers.py
pyproject.toml # 依赖 + Ruff / mypy / pytest 80% 门禁
Dockerfile # 多阶段构建（python:3.12-alpine）8. 阅读路径推荐
| 角色 | 路径（按序） |
|---|---|
| 🚀 新成员 | 快速上手 → 范式 15 条 → OAuth 实施 → Admin MIS 设计 |
| 🔧 后端 | DDD 4 层 → 错误码体系 → 模块手册 → 按需查 ADR 全集 |
| 🎨 前端 | Admin Web RN 设计 → admin 契约 → uniapp SDK → CI Pipeline |
| 📱 C 端 / 设备线 | user actions → device 总览 → 设备云对接研究 → 模块手册·设备线 |
| ⚙️ 运维 | CI Pipeline → Secrets → 重装 Checklist → 部署回滚 |
| 🟣 V1 → V2 迁移 | V1 提炼资料（统一章节） → 对照 模块手册 落地 |
附录 · 文档统计（2026-09-17 v3）
| 区 | 页数 | 说明 |
|---|---|---|
| 🔵 API Docs | 47 | oauth 10 / admin 13 / device 5 / user 1 / 契约卡 18 / 索引 |
| 🟢 Internal Wiki | 22 | 架构 7 / ADR 全集 1 / 深挖合集 1 / 迁移单页 1 / 运维 11 / index |
| 📦 模块手册 | 7 | 26 模块 → 6 域页 + 索引 |
| 🟡 AI Contexts | 4 ｜ 🧭 Guide 2 ｜ 📕 Runbooks 1 ｜ 🏠 首页 1 | — |
| 合计 | 84 页 | 127 → 84 收拢（信息零删减）· 线上 api.qingmulife.cn/docs |
实测口径（2026-09-17）：29 个业务模块目录（26 个已配模块手册）· 121 条 API 路由 · 201 个错误码 · 2114 项测试（collect）· DDD 守卫 0 违规。
🤙 Be water, my friend. 文档如流水 — 用时取之，闲时汇之。