# 儿童 AI 体态管理平台 · 系统架构与建设规划

> **版本**：V1.0 · **日期**：2026-07-23  
> **适用阶段**：MVP → 商业试点 → 商业交付 V1.0  
> **主要读者**：创始团队、合伙人、产品、研发、运营、机构合作方

---

## 1. 项目定位与建设目标

### 1.1 产品定位

面向 **3–16 岁儿童青少年** 的 AI 体态管理与运动康复平台，围绕含胸驼背、头前伸、高低肩、骨盆姿态、膝内扣、足弓与运动协调等常见问题，提供：

- **AI 筛查**（非医疗诊断）
- **结构化报告**与可解释建议
- **训练计划**与打卡复测
- **机构 SaaS** 运营与转化闭环

> **合规边界**：平台输出用于健康管理与运动训练，不替代医院诊断；涉及疼痛、明显畸形、外伤或医生已明确限制运动的情况，必须提示线下专业评估。

### 1.2 本期建设目标

| 维度 | 目标 |
|------|------|
| 业务闭环 | 建档 → 视频采集 → AI 分析 → 报告 → 训练 → 复测 → 机构转化 |
| 技术目标 | 业务与 AI 解耦、多租户隔离、全链路可追溯、异步分析 ≤ 5 分钟 |
| 商业目标 | 4–6 周可演示 MVP，8–10 周接入 1–3 家机构试点 |

### 1.3 核心成功指标（试点阶段）

| 指标 | 定义 | 目标 |
|------|------|------|
| 分析任务达成率 | 任务进入 PROCESSING 并生成报告或可解释失败 | ≥ 90% |
| 报告查看率 | 报告产生后 30 分钟内家长首次查看 | ≥ 80% |
| 训练任务完成率 | 14 天内计划任务完成比例 | ≥ 60% |
| 训练后复测率 | 60 天内完成复测的儿童比例 | ≥ 50% |
| 课程转化率 | 看完报告后进入课程/会员 | ≥ 20% |

---

## 2. 总体系统架构

### 2.1 分层架构概览

系统采用 **云原生分层架构**：客户端层 → 网关层 → 业务服务层 → AI 服务层 → 数据设施层。

```
┌─────────────────────────────────────────────────────────────────┐
│                        客户端层 (Client)                         │
│   微信小程序/H5 家长端  │  儿童训练端  │  Web 管理后台            │
└───────────────────────────────┬─────────────────────────────────┘
                                │ HTTPS
┌───────────────────────────────▼─────────────────────────────────┐
│                      网关层 (API Gateway)                          │
│         鉴权 JWT · 限流 · 审计 · 请求追踪 (requestId)              │
└───────────────────────────────┬─────────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────┐
│                    业务服务层 (Business Services)                  │
│  Auth/User │ Child Profile │ Video/Analysis │ Training │ Commerce │
│                        Admin/Ops                                   │
└───────────────┬─────────────────────────────┬───────────────────┘
                │ REST + 任务创建               │ 异步回调
┌───────────────▼───────────────┐   ┌───────────▼───────────────────┐
│      AI 服务层 (AI Layer)      │   │     消息队列 (Queue)           │
│  Video Worker │ Pose │ Score  │◄──│  Redis/RabbitMQ               │
│  Agent 解释服务                │   └───────────────────────────────┘
└───────────────┬───────────────┘
                │
┌───────────────▼─────────────────────────────────────────────────┐
│                      数据设施层 (Data Layer)                       │
│  MySQL 8.x │ Redis │ 对象存储 OSS │ 向量记忆 │ 日志/监控平台      │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 关键设计原则

1. **业务与 AI 解耦**：长任务异步化，前端只创建任务并轮询/WebSocket 查状态，不阻塞 HTTP 链路。
2. **全链路可追溯**：保留原始关键点、计算指标、模型版本、Agent 提示词版本与审核状态。
3. **多租户隔离**：机构数据按 `tenant_id` 隔离，教练仅访问授权儿童。
4. **接口契约优先**：以 `openapi.yaml` 为单一事实来源，向后兼容扩展。
5. **幂等与审计**：写接口支持 `Idempotency-Key`；报告复核、退款、权限变更全量审计。

---

## 3. 模块划分与职责

### 3.1 业务服务模块

| 模块 | 职责 | 核心数据表 |
|------|------|-----------|
| **Auth/User** | 手机/微信登录、角色、租户、隐私协议 | `users`, `tenants`, `users_passwords` |
| **Child Profile** | 儿童档案、成长指标、授权关系 | `children`, `child_measurements` |
| **Video/Analysis** | 直传签名、视频登记、分析任务、报告 | `videos`, `analysis_tasks`, `reports` |
| **Training** | 动作库、训练计划、打卡、复测 | `exercises`, `training_plans`, `training_records` |
| **Commerce** | 套餐、订单、会员权益 | `products`, `orders` |
| **Admin/Ops** | 运营线索、看板、审计、配置 | `operation_leads`, `audit_logs`, `data_retention_rules` |

### 3.2 AI 服务模块

| 组件 | 输入 | 输出 | 技术选型 |
|------|------|------|----------|
| **Video Worker** | 对象存储视频 | 帧序列、质量检测结果 | FFmpeg + 队列消费 |
| **Pose 服务** | 图片/视频帧 | 33 关键点坐标 + 置信度 | MediaPipe Pose（一期） |
| **评分服务** | 关键点序列 | 体态指标、动作评分、风险等级 | 规则引擎 + 加权算法 |
| **Agent 服务** | 结构化指标 | 报告文案、训练建议、家长话术 | LLM + 模板约束 |

#### Agent 角色分工

| Agent | 职责 | 输出 |
|-------|------|------|
| Assessment Agent | 解读视觉指标与置信度 | 风险摘要、重点指标、复核建议 |
| Coach Agent | 结合年龄与目标生成计划 | 周期计划、每日动作、进阶规则 |
| Parent Agent | 专业内容家长化翻译 | 报告文案、提醒、复测建议 |
| Operation Agent | 机构线索分层与触达 | 人群标签、话术、任务建议 |

### 3.3 客户端模块

| 端 | 用户 | 核心页面/流程 |
|----|------|--------------|
| **小程序/H5 家长端** | 家长 | 登录 → 建档 → 拍摄引导上传 → 报告 → 训练计划 → 订单 |
| **儿童训练端** | 儿童/家长陪同 | 今日训练 → 动作演示 → 跟练计时 → 打卡反馈 |
| **Web 管理后台** | 教练/运营/管理员 | 线索 → 档案 → 报告复核 → 课程 → 数据看板 |

---

## 4. 核心业务流程

### 4.1 家长端主流程

```
授权登录 → 隐私协议确认 → 创建儿童档案
    → 按引导拍摄/upload-token 直传 OSS
    → 登记视频 → 创建 analysis_task
    → 异步 AI 处理（Pose + 评分 + Agent）
    → 生成 report → 家长查看
    → 购买/领取 training_plan → 每日打卡 → 复测
```

### 4.2 AI 分析异步链路

```
POST /api/analysis/tasks  (返回 taskId)
        │
        ▼
   队列 QUEUED → Worker 拉取
        │
        ▼
   PROCESSING: 抽帧 → Pose → 指标计算 → 质量校验
        │
        ├── 置信度不足 → FAILED + 建议重拍
        │
        ▼
   Agent 生成报告文案 → 写入 reports
        │
        ▼
   Webhook 回调后端 → status=SUCCEEDED + reportId
        │
        ▼
   家长端轮询/推送 → 展示报告
```

### 4.3 教练复核流程（试点阶段）

```
AI 报告 (draft) → 教练后台复核 → 调整建议/关联课程
    → 报告 published → 下发家长端 → 跟踪训练与复测
```

---

## 5. 技术选型建议

### 5.1 推荐技术栈（MVP 阶段）

| 层级 | 推荐方案 | 说明 |
|------|----------|------|
| **后端 API** | Python FastAPI 或 Node.js NestJS | 与 OpenAPI 契约对齐，异步友好 |
| **任务队列** | Redis + Celery / BullMQ | 分析任务削峰、重试 |
| **数据库** | MySQL 8.x | 已有完整 schema（`database.sql`） |
| **缓存** | Redis | Session、限流、队列、热点数据 |
| **对象存储** | 阿里云 OSS / MinIO（dev） | 视频直传、生命周期归档 |
| **AI 推理** | MediaPipe Pose + Python Worker | 一期快速落地，后续可替换模型 |
| **Agent** | OpenAI API / 国产大模型 + Prompt 模板 | 输出受控，版本化管理 |
| **家长端** | 微信小程序（Taro/uni-app） | 覆盖微信生态 |
| **管理后台** | Vue 3 + Element Plus | 高密度信息布局 |
| **网关** | Nginx / Kong | 鉴权、限流、TLS 终结 |
| **监控** | Prometheus + Grafana / 云监控 | 业务 + AI 任务双维度 |

### 5.2 环境规划

| 环境 | 用途 | 要求 |
|------|------|------|
| dev | 日常开发联调 | 模拟支付、测试 OSS |
| test | 测试验收回归 | 数据可重置，配置接近生产 |
| staging | 预发布/客户演示 | 与生产同版本、同拓扑 |
| prod | 正式服务 | 备份、监控、告警、权限收敛 |

---

## 6. 分阶段建设规划

### 6.1 阶段总览

| 阶段 | 周期 | 目标 | 关键交付物 |
|------|------|------|-----------|
| **P0 方案确认** | 1 周 | 范围、架构、数据、合规边界对齐 | PRD 签字、架构文档、接口/DB 契约、Git 工程初始化 |
| **P1 MVP 研发** | 4–6 周 | 家长端 + 视频分析 + 报告 + 基础后台 | 可演示版本、测试报告、staging 部署 |
| **P2 试点交付** | 4 周 | 接入 1–3 家机构，跑通筛查→课程闭环 | 试点数据、运营 SOP、教练培训材料 |
| **P3 商业化增强** | 6–8 周 | 支付、权限、模型评估、生产运维 | 商业版 V1.0、监控告警、备份演练 |

### 6.2 P1 MVP 详细排期（建议）

| 周次 | 模块 | 交付标准 |
|------|------|----------|
| W1 | 工程初始化 + Auth + 儿童档案 | 登录、建档 CRUD、DB 迁移跑通 |
| W2 | 视频上传链路 | OSS 直传、视频登记、质量预检 UI |
| W3 | AI Worker 骨架 | 抽帧 + MediaPipe + 基础指标输出 |
| W4 | 报告生成 + Agent | 结构化 report + 家长可读文案 |
| W5 | 家长端小程序 | 建档→上传→看报告完整流程 |
| W6 | 基础管理后台 + 联调 | 报告列表、任务监控、冒烟测试 |

**MVP 最小闭环（Must Have）：**

> 家长 2 分钟内完成建档 + 视频上传 → 5 分钟内收到 AI 报告 → 报告含风险等级、指标解释、建议动作、免责声明

**MVP 可后置（Should/Could）：**

- 支付与会员
- 完整训练打卡
- 运营线索漏斗
- 多机构租户管理

### 6.3 团队分工建议

| 角色 | 人数 | 职责 |
|------|------|------|
| 产品负责人 | 1 | 需求拆解、验收标准、试点反馈闭环 |
| 前端工程师 | 1 | 小程序/H5、儿童训练页、Web 后台 |
| 后端工程师 | 1 | API、任务队列、权限、数据模型 |
| 算法工程师 | 1 | 关键点、评分规则、质量检测、Agent 约束 |
| 测试/交付 | 0.5–1 | 场景测试、部署验证、SOP 落地 |

---

## 7. 数据与安全架构

### 7.1 数据分层

| 等级 | 数据类型 | 存储策略 |
|------|----------|----------|
| L1 敏感 | 手机号、儿童姓名、视频原片 | 加密/哈希、脱敏展示、访问审计 |
| L2 业务 | 报告、训练记录、订单 | MySQL + 租户隔离 |
| L3 衍生 | 关键点、指标 JSON、Agent 输出 | 与任务绑定，保留模型版本 |
| L4 运营 | 线索、看板聚合 | 脱敏聚合，按租户隔离 |

### 7.2 安全与合规要点

- 报告 **不得** 出现确诊、治疗、治愈等医疗表述
- Agent 输出引用输入字段，保留提示词版本
- 低置信度 → 仅输出「建议重拍/教练复核」，不给强结论
- 审计日志保留 ≥ 180 天；视频/报告按 `retention_days` 归档
- 写接口幂等保护（`api_idempotency_keys` 表）

---

## 8. 部署拓扑

### 8.1 MVP 单区域部署

```
                    ┌─────────────┐
   用户 ──────────► │   Nginx     │
                    │  API Gateway│
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ API 服务  │ │AI Worker │ │ 后台服务  │
        └────┬─────┘ └────┬─────┘ └────┬─────┘
             │            │            │
        ┌────┴────────────┴────────────┴────┐
        │  MySQL  │  Redis  │  OSS  │ 日志  │
        └───────────────────────────────────┘
```

### 8.2 商业化阶段演进

- AI Worker、视频转码、报告生成 **拆分为独立队列消费者**
- 引入灰度发布、多环境配置、自动扩缩容
- 模型/评分规则/报告模板 **版本化独立发布**

---

## 9. 风险与应对

| 风险 | 影响 | 应对策略 |
|------|------|----------|
| AI 置信度不足导致报告不可用 | 用户体验差、机构信任低 | 拍摄质量前置检测 + 低置信度降级文案 |
| 医疗合规边界模糊 | 法律风险 | PRD 硬性约束 + Agent 过滤 + 人工复核 |
| MVP 范围膨胀 | 延期交付 | 严格 MoSCoW，支付/运营后置 |
| 机构试点数据隔离 | 合作受阻 | 一期即引入 tenant_id，权限最小化 |
| 算法儿童个体差异 | 误报/漏报 | 保留教练复核环节，不做全自动闭环 |

---

## 10. 工程化 Monorepo（P3）

### 10.1 仓库结构

```
happy-up/
├── contracts/          # openapi.yaml + database.sql（从 doc/ 同步）
├── apps/api/           # FastAPI 后端 Starter
├── doc/                # 商业交付文档包 V1.0
├── docker-compose.yml  # MySQL 8 + Redis 7
└── Makefile
```

### 10.2 产品 Demo 能力（P1/P2）

| 能力 | 状态 | 说明 |
|------|------|------|
| AI 实时跟练打卡 | ✅ | Ghost 叠加 · Coach Agent cue · 五维评分 |
| WebRTC 摄像头预览 | ✅ | 机位校准/跟练/拍摄引导页 |
| 真实 PDF 导出 | ✅ | 筛查/跟练/趋势/三报告对比 |
| 28 天趋势 + 三报告对比 | ✅ | 商业闭环可视化 |
| 儿童训练端 | ✅ | 大按钮 + 儿童版 cue |

入口：`doc/.../03_技术架构/产品交互Demo.html`

### 10.3 API Starter

- **框架**：FastAPI + Pydantic v2 + SQLAlchemy 2
- **契约对齐**：路由覆盖 `openapi.yaml` 全部 path（当前 Mock 数据，与 Demo 一致）
- **统一响应**：`StandardResponse` + `requestId` 中间件
- **本地依赖**：`make up` 启动 MySQL/Redis，`make api-dev` 启动 API

详见仓库根目录 `README.md` 与 `apps/api/README.md`。

### 10.4 Sprint 1 已完成

- JWT 登录（验证码 682139）+ Bearer 鉴权
- 儿童档案 CRUD 落库（MySQL）
- Alembic baseline + `make api-seed`
- 产品 Demo **API 联调模式**（登录 + 首页档案）

### 10.5 Sprint 2 已完成

- 视频直传凭证 + 登记落库（`videos` 表）
- 分析任务 Redis 队列 + Worker 骨架 + 内联处理（开发模式）
- 报告生成落库（`reports` 表 · 对齐 Demo 指标）
- Demo **筛查全流程 API 联调**（上传 → 分析 → 报告）

### 10.6 Sprint 3 已完成

- 训练计划 CRUD + 打卡记录落库（`training_plans` / `training_records`）
- Admin 运营看板真实 DB 聚合
- Demo 全链路 API 联调（含训练计划页 + 打卡写入 + 后台 KPI）
- `apps/web/` 前端工程占位

### 10.7 Sprint 4 已完成

- 本地直传 + MinIO 预签名 URL（`OSS_ENABLED=true` + `docker compose` MinIO）
- `PUT /api/videos/direct-upload` 本地上传回退
- MediaPipe 分析骨架（`pip install -e ".[ai]"` 可选）
- `apps/web` Vue 3 H5（登录 / 档案 / 筛查联调）
- Admin 看板按 `tenant_id` 隔离聚合

### 10.8 Sprint 5 已完成

- MediaPipe 帧级评分（`pose_metrics.py` 纯函数 + OpenCV 抽帧）
- 服务端 PDF 导出 `GET /api/reports/{id}/pdf`
- OSS 生产配置：`OSS_PROVIDER=aliyun` + `OSS_CDN_BASE_URL`
- H5 四 Tab UI（首页/筛查/报告/训练）对齐 Demo 配色
- 微信小程序壳 `apps/mini`

### 10.9 Sprint 6 已完成

- 报告复核工作流（高风险 → `pending_review` → 教练 approve/reject）
- 姿态指标标定配置 `app/ai/calibration.py`
- Gitea CI（`.gitea/workflows/ci.yaml`）+ K8s 部署骨架（`deploy/k8s/`）
- H5 跟练页 + 小程序 TabBar（首页/筛查/训练）

### 10.10 Sprint 7 下一步

1. 生产镜像构建与 Registry 推送
2. 报告复核后台 UI（Admin Web）
3. 消息通知（短信/模板消息）
4. 真实数据集标定与 A/B 指标对比

---

## 11. 近期行动清单（合伙人讨论用）

### 本周（P0）

- [ ] 合伙人确认 MVP 范围与 6 周交付目标
- [ ] 确认技术选型（FastAPI vs NestJS、云厂商）
- [ ] 确认团队配置与外包边界
- [x] Git 初始化 + monorepo 目录结构
- [x] 从 `openapi.yaml` / `database.sql` 生成工程骨架

### 下周起（P1 启动）

- [ ] Sprint 1：Auth + 儿童档案 + DB 迁移
- [ ] 确定 1 家种子机构作为试点需求来源
- [ ] 算法同学完成 MediaPipe 本地验证（正面/侧面站姿）

---

## 附录：文档索引

| 文档 | 路径 |
|------|------|
| 产品 PRD | `02_企业级PRD/PRD完整版.docx` |
| 企业级架构 | `03_技术架构/企业级系统架构.docx` |
| **本架构与建设规划** | `03_技术架构/系统架构与建设规划.md` |
| **合伙人讨论 HTML** | `03_技术架构/系统架构与建设规划.html` |
| 数据库设计 | `06_数据库设计/database.sql` |
| API 契约 | `07_API接口/openapi.yaml` |
| AI 算法设计 | `04_AI视觉算法/AI视觉算法详细设计.docx` |
| Agent 规范 | `08_Agent智能系统/Agent设计规范.docx` |
| 研发计划 | `12_研发计划/研发计划与项目管理.docx` |
| 部署运维 | `14_部署运维/生产部署运维.docx` |

---

*本文档基于商业交付包 V1.0 现有材料整理，用于创始团队与合伙人架构讨论及研发启动对齐。*
