---
url: /docs/guide/kb-map.md
---
# QM-ServerV2 知识库总索引

> 📍 **位置**：`docs/` ｜ **维护**：架构师 + AI 协作负责人 ｜ **版本**：2026-09-17 v3（收拢版结构）
> **覆盖**：**84 页 · 8 大区** —— API Docs / Internal Wiki / 模块手册 / V1 提炼资料 / 快速上手 / AI Contexts / Runbooks / 首页
>
> 🔗 **相关入口**：[线上站](https://api.qingmulife.cn/docs/) · [CNB Pipeline](https://cnb.cool/qingmu2026/qm-serverv2) · [Docker 制品](https://cnb.cool/qingmu2026/qm-serverv2/-/packages)（`docker.cnb.cool/qingmu2026/qm-serverv2/qm-serverv2-api:latest`）

***

## 1. 知识库地图（8 大区）

| 区 | 受众 | 定位 | 入口 | 页数 |
|---|---|---|---|---|
| 🔵 **API Docs** | 前端 / 第三方集成 | 接口契约 — 字段表、错误码矩阵、状态机、模块契约卡 | [/api-docs/](/api-docs/) | 47 |
| 🟢 **Internal Wiki** | 团队 / 架构师 | 架构决策 + 范式沉淀 + 运维 + 迁移参考 | [/internal-wiki/](/internal-wiki/) | 22 |
| 📦 **模块手册** | 后端开发 | 26 模块权威开发手册（按 6 域收拢） | [/modules/](/modules/) | 7 |
| 🟣 **V1 提炼资料** | 迁移开发 | QM-APP（V1）→ V2 迁移参考（算法/契约/AI/DB/设备安全 5 卡） | [/internal-wiki/migration/INDEX](/internal-wiki/migration/INDEX) | 1 |
| 🧭 **快速上手** | 新成员 / 联调方 | 5 步启动 + 命令清单 | [/guide/quickstart](/guide/quickstart) | 1 |
| 🟡 **AI Contexts** | Claude / Cursor / Cody | 代码风格 + 模块约定 + 错误码权威注册表 | [/ai-contexts/](/ai-contexts/) | 4 |
| 📕 **Runbooks** | 运维 | 部署与回滚 | [/runbooks/deploy-rollback](/runbooks/deploy-rollback) | 1 |
| 🏠 **首页** | 全员 | hero 卡片导航 | [/](/index) | 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 决策记录全集](/internal-wiki/decisions/) ｜ 写作约定：背景 → 方案 → 权衡 → 后果 四段式

| # | 标题 | 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 实施总览 ⭐](/internal-wiki/architecture/oauth-implementation) | 9 action 完整实施规范、错误码体系、验证码状态机 |
| [DDD 4 层架构](/internal-wiki/architecture/ddd-layers) | `src/app/{domain,application,infrastructure,interface}/` 边界与依赖方向 |
| [错误码体系（OATH-M-006）](/internal-wiki/architecture/error-codes) | 业务码分配规则 + Handler 注册顺序教训 |
| [Admin MIS 设计](/internal-wiki/architecture/admin-mis-design) | 82 use case / 12 子域 / RBAC / 5 Phase 路线图（后端最大模块）|
| [Admin Web RN 设计](/internal-wiki/architecture/admin-web-rn-design) | 19 项选型 + Tamagui 深挖 + 构建部署 |
| [设备云对接研究](/internal-wiki/architecture/device-cloud-integration-research) | 12 平台矩阵 + 授权中心四态 + IDeviceVendor 框架 |
| [IDeviceVendor v2 计划](/internal-wiki/architecture/idevice-vendor-v2-plan) | G1 webhook / G2 import 缺口 + 五步路线 |
| [OAuth 深度解析（合集）](/internal-wiki/oauth-deep-dive/) | 联调 cookbook + JWT 解剖 + 多设备会话（3 篇收拢）|
| [代码风格](/ai-contexts/code-style) · [模块约定](/ai-contexts/module-conventions) · [错误码权威注册表](/ai-contexts/error-code-registry) | AI 协作三件套（注册表 = 201 码 / 25 段权威表）|

***

## 4. API Docs 索引

### 4.1 OAuth（10 篇 · 契约面向前端）

| 文档 | 用途 |
|---|---|
| [概览](/api-docs/v1/oauth/) · [9 Action 字段表](/api-docs/v1/oauth/actions) | 登录认证链全字段 |
| [错误码矩阵（40101xxx）](/api-docs/v1/oauth/error-codes) · [（HTTP 视角）](/api-docs/v1/oauth/errors) | 业务码 / HTTP 双视角互补 |
| [验证码状态机](/api-docs/v1/oauth/state-machine) · [安全规范](/api-docs/v1/oauth/security) · [限流规则](/api-docs/v1/oauth/rate-limits) | 风控三件套 |
| [SDK 参考](/api-docs/v1/oauth/sdk) · [uniapp 开发指南](/api-docs/v1/oauth/uniapp-dev-guide) · [前后联调实录](/api-docs/v1/oauth/integration-notes) | 落地与联调 |

### 4.2 Admin MIS（13 篇）· 4.3 User / Device

| 文档 | 用途 |
|---|---|
| [admin 总览 + 12 子域](/api-docs/v1/admin/) | 82 use case / RBAC 26 权限位 / 40201xxx / confirm\_text 6 操作 |
| [user/actions](/api-docs/v1/user/actions) | C 端 11 action（40301xxx） |
| [device 总览 + 4 子域](/api-docs/v1/device/) | 授权中心四态 + honor / zepp / xiaomi / vendors |

### 4.4 模块契约卡（20 篇 · 代码直出）

> 每篇 = 路由 + 错误码段 + 鉴权 + action 一览 + 通用约定（对接速查，字段真相在 usecase dataclass）

跑者向：[shoes](/api-docs/v1/shoes/) · [training](/api-docs/v1/training/) · [goal](/api-docs/v1/goal/) · [sport](/api-docs/v1/sport/) · [upload](/api-docs/v1/upload/)
资产域：[wallet](/api-docs/v1/wallet/) · [points](/api-docs/v1/points/) · [coupon](/api-docs/v1/coupon/) · [cart](/api-docs/v1/cart/) · [mall](/api-docs/v1/mall/) · [group\_buy](/api-docs/v1/group_buy/) · [distribution](/api-docs/v1/distribution/)
社区：[feed](/api-docs/v1/feed/) · [follow](/api-docs/v1/follow/) · [favorite](/api-docs/v1/favorite/) · [review](/api-docs/v1/review/)
设备：[suunto](/api-docs/v1/suunto/)

***

## 5. 模块手册（6 域 · 26 模块）

| 域 | 模块 | 入口 |
|---|---|---|
| 认证与用户 | oauth · user · shared | [/modules/auth-user](/modules/auth-user) |
| 设备线 | device · honor · zepp · xiaomi · suunto | [/modules/device-line](/modules/device-line) |
| 运动健康 | sport · training · goal · stats · shoes · upload | [/modules/sport-health](/modules/sport-health) |
| 交易与资产 | wallet · points · coupon · cart · mall · group\_buy · distribution | [/modules/trade-assets](/modules/trade-assets) |
| 社区 | feed · follow · favorite · review | [/modules/community](/modules/community) |
| 管理 | admin | [/modules/admin](/modules/admin) |

***

## 6. 运维与 Runbook

| 文档 | 一句话 |
|---|---|
| [CI Pipeline（CNB）](/internal-wiki/operations/ci-pipeline) · [CNB 仓初始化](/internal-wiki/operations/cnb-setup) | 流水线与平台配置 |
| [Docker Compose](/internal-wiki/operations/docker-compose) · [Secrets 与 Envs](/internal-wiki/operations/secrets-and-envs) | 本地栈与密钥管理 |
| [API 冒烟测试](/internal-wiki/operations/api-testing) · [报告合集（5 期）](/internal-wiki/operations/api-test-reports) | 四层全量 + 时间戳留档 |
| [性能压测基线](/internal-wiki/operations/perf-baseline-v2.0.12) | locust QPS/p50/p95/p99 |
| [生产重装 Checklist](/internal-wiki/operations/server-rebuild-checklist) · [踩坑实录 2026-09-16](/internal-wiki/operations/pitfalls-20260916-rebuild) | 灾备手册 + 23 坑 |
| [Admin Web 对接 Backlog](/internal-wiki/operations/admin-web-backlog) · [小米开放平台申请](/internal-wiki/operations/xiaomi-open-platform-application) | 待办与商务流程 |
| [部署回滚 Runbook](/runbooks/deploy-rollback) | 生产部署与秒级回滚 |

***

## 7. 工程化文件清单

> 不在 docs/ 目录但与知识库强相关（[ADR 0001](/internal-wiki/decisions/) / [0002](/internal-wiki/decisions/)）

```
.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. 阅读路径推荐

| 角色 | 路径（按序） |
|---|---|
| 🚀 **新成员** | [快速上手](/guide/quickstart) → [范式 15 条](/internal-wiki/decisions/) → [OAuth 实施](/internal-wiki/architecture/oauth-implementation) → [Admin MIS 设计](/internal-wiki/architecture/admin-mis-design) |
| 🔧 **后端** | [DDD 4 层](/internal-wiki/architecture/ddd-layers) → [错误码体系](/internal-wiki/architecture/error-codes) → [模块手册](/modules/) → 按需查 [ADR 全集](/internal-wiki/decisions/) |
| 🎨 **前端** | [Admin Web RN 设计](/internal-wiki/architecture/admin-web-rn-design) → [admin 契约](/api-docs/v1/admin/) → [uniapp SDK](/api-docs/v1/oauth/sdk) → [CI Pipeline](/internal-wiki/operations/ci-pipeline) |
| 📱 **C 端 / 设备线** | [user actions](/api-docs/v1/user/actions) → [device 总览](/api-docs/v1/device/) → [设备云对接研究](/internal-wiki/architecture/device-cloud-integration-research) → [模块手册·设备线](/modules/device-line) |
| ⚙️ **运维** | [CI Pipeline](/internal-wiki/operations/ci-pipeline) → [Secrets](/internal-wiki/operations/secrets-and-envs) → [重装 Checklist](/internal-wiki/operations/server-rebuild-checklist) → [部署回滚](/runbooks/deploy-rollback) |
| 🟣 **V1 → V2 迁移** | [V1 提炼资料（统一章节）](/internal-wiki/migration/INDEX) → 对照 [模块手册](/modules/) 落地 |

***

## 附录 · 文档统计（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](https://api.qingmulife.cn/docs/) |

> 实测口径（2026-09-17）：29 个业务模块目录（26 个已配模块手册）· 121 条 API 路由 · 201 个错误码 · 2114 项测试（collect）· DDD 守卫 0 违规。

***

🤙 **Be water, my friend.** 文档如流水 — 用时取之，闲时汇之。