# 浠艾福（Care Family）阶段性需求规格说明书 V1.0

> **文档状态**：初稿  
> **编写日期**：2026-07-08  
> **适用范围**：微信小程序 + Web 管理端 + 后端 API  
> **项目技术栈**：Spring Boot 2.7.18 + MyBatis-Plus / uni-app Vue 2 小程序 / Vue 2 + Element UI 管理端

---

## 目录

1. [项目概述与商业目标](#1-项目概述与商业目标)
2. [商业模式全景](#2-商业模式全景)
3. [角色体系与权限矩阵](#3-角色体系与权限矩阵)
4. [五维幸福模型](#4-五维幸福模型)
5. [会员体系与销售机制](#5-会员体系与销售机制)
6. [功能模块全景](#6-功能模块全景)
7. [阶段规划与优先级](#7-阶段规划与优先级)
8. [当前实现状态评估](#8-当前实现状态评估)
9. [数据模型概览](#9-数据模型概览)
10. [技术架构](#10-技术架构)
11. [风险与依赖](#11-风险与依赖)
12. [附录](#12-附录)

---

## 1. 项目概述与商业目标

### 1.1 项目定位

**浠艾福（Care Family）**——亿图腾科技倾力打造的家庭健康成长俱乐部，围绕 **身·智·富·行·心** 五大核心领域，以五行智慧为根基，以五维能量为引擎，为每个家庭定制全生命周期解决方案。

### 1.2 商业目标

| 目标 | 指标 | 时间线 |
|------|------|--------|
| 引流产品获客 | 10,000+ 家庭完成 DAN 测评或菌群检测 | 上线后 6 个月 |
| FREE → FAMILY 转化 | 付费转化率 ≥ 15% | 上线后 12 个月 |
| 商城复购 | 付费用户 30 天内复购率 ≥ 25% | 上线后 12 个月 |
| 服务商入驻 | 200+ 认证成长规划师 / 供应商 | 上线后 12 个月 |

### 1.3 核心商业逻辑

```
引流产品（DAN测评 / 菌群检测）
       │
       ▼
AI 初评 + 专家深度解读
       │
       ▼
个性化调整方案（身·心·智行动计划）
       │
       ▼
方案执行（任务打卡 + 能量累积）
       │
       ▼
商城复购（积分 + 微信混合支付）
       │
       ▼
推荐推荐 → 新用户循环
```

---

## 2. 商业模式全景

### 2.1 引流产品（P0 · 已上线基础版）

#### DAN 认知测评

| 项目 | 说明 |
|------|------|
| 目标用户 | 3-18 岁儿童及青少年 |
| 测评维度 | 6 维认知（注意力/专注力/记忆力/逻辑思维/感知/空间思维）+ EMI 情绪商数（7 子维度）+ 大五人格 |
| 形式 | 线下预约 + 规划师引导游戏化测评 |
| 输出 | DAN 测评报告（百分位常模对比）+ 成长建议 |
| 积分激励 | 完成测评奖励积分 + 五维能量 |
| 实现状态 | ✅ 订单/预约/结果录入/报告查询已完整实现 |

#### 菌群检测（精准营养入口）

| 项目 | 说明 |
|------|------|
| 目标用户 | 全年龄段家庭成员 |
| 形式 | 居家采样 → 邮寄实验室 → 线上报告 |
| 检测内容 | 肠道菌群分析 + 慢病风险 + 营养状况 |
| 输出 | 健康检测报告（`health_reports` 表，含总分/菌群健康分/慢病控制分/营养均衡分/肠型分类） |
| 指标体系 | 全域指标定义（`indicator_definitions`），支持指标值记录与比对 |
| 实现状态 | ✅ 报告上传/草稿两阶段入库/指标明细/查看权限已实现；❌ 菌群检测商品流程（在线下单 → 采样盒发货 → 扫码激活 → 结果回传）未完整闭环 |

### 2.2 会员转化路径

```
免费用户 (FREE)
    │ 免费使用：DAN测评初始化、基础文章浏览、家属关系管理、基础任务
    │
    ├── 完成引流测评 → 获得解读报告免费摘要
    │
    ├── 邀请 3 人注册 → 7 天免费 FAMILY 体验
    │
    ▼
家庭会员 (FAMILY · ¥365/年)
    │ 完整测评报告/专家解读/个性方案/积分商城/能量系统/高级文章
    │
    ├── 首页推荐佣金（20% 消费返积分）
    │
    ▼
创客会员 (PROVIDER · 审核制)
    │ 供应商入驻/商品管理/订单管理/团队销售
    │
    ▼
认证成长规划师 (GUIDE · 审核制)
    │ 套餐发布/家庭绑定/任务下发/测评录入/佣金结算
```

### 2.3 核心盈利模型

| 收入来源 | 说明 | 阶段 |
|----------|------|------|
| FAMILY 会员费 | ¥365/年 | P1 |
| DAN 测评服务费 | 套餐销售（平台抽佣） | P0 |
| 商城商品佣金 | 供应商销售分成 | P2 |
| 精准营养复购 | 菌群检测 + 个性化营养包持续销售 | P2 |

### 2.4 积分体系 × 五维能量双轨制

| 机制 | 范围 | 用途 | 流向 |
|------|------|------|------|
| **积分 (Points)** | `User.totalPoints`（家长）<br>`FamilyMember.totalPoints`（孩子心愿） | 商城抵扣（1 分 = ¥0.01）、孩子心愿兑换 | 任务获得 → 商城消费 → 供应链结算 |
| **五维能量** | 身·智·富·行·心 各维度 | 维度健康指数计算、沙盘评分、服务推荐 | 活动/任务/测评/消费 触发 → 能量规则引擎 |

积分和能量是**独立双轨**：积分用于交易流通，能量用于维度成长评估。两者通过"任务完成"等事件联动，但不可互换。

---

## 3. 角色体系与权限矩阵

### 3.1 系统角色定义

| 角色标识 | 显示名称 | 说明 | 注册方式 |
|----------|----------|------|----------|
| `parent` | 家长/客户 | 付费决策者，管理家庭、审批任务、消费服务 | 微信授权 + 手机号 |
| `child` | 孩子/附属 | 家长监护下执行任务、兑换心愿、玩游戏 | 家长添加（关联） |
| `teacher` | 成长规划师 | 认证后绑定家庭、发布套餐、录入测评 | 审核制（`guide_applications`） |
| `admin` | 平台运营 | 审核、系统配置、数据管理 | 内部创建 |
| `supplier_admin` | 供应商管理员 | 商品管理、订单处理 | 审核制 |
| `activity_provider` | 活动规划师 | 发布活动、管理报名 | 审核制 |

### 3.2 角色切换机制

- **家长端 ↔ 孩子端**：家长可随时切换至孩子端查看进度；孩子端不可切换到家长端（需密码）
- **规划师 ↔ 家长端**：认证规划师可切换回自己家庭账号的家长端
- **TabBar 感知**：不同角色进入小程序显示不同 TabBar 内容

### 3.3 权限矩阵（核心模块）

| 模块 | parent | child | teacher | admin |
|------|:------:|:-----:|:-------:|:-----:|
| 家庭管理 | ● 创建/邀请 | ○ 查看 | ○ 查看 | ● |
| 任务 | ● 创建/审批 | ● 执行 | ● 下发 | ● 配置 |
| 积分/心愿 | ● 调整/审批 | ● 兑换 | — | ● 调整 |
| 五维能量 | ● 查看 | ● 查看 | ● 查看 | ● 配置 |
| 测评 | ● 预约/支付 | ○ 参与 | ● 录入 | ● 审核 |
| 商城 | ● 购买 | ○ 浏览 | ● 管理 | ● 审核 |
| 套餐 | ● 购买 | — | ● 创建 | ● 审核 |
| 入驻 | — | — | ● 申请 | ● 审核 |

● 完全权限  ○ 受限权限  — 无权限

---

## 4. 五维幸福模型

### 4.1 五维定义

| 维度 | 五行 | 色值 | 核心释义 | 核心功能 |
|:----:|:----:|:----:|----------|----------|
| **身** (Body) | 土 | `#FF8C42` | 主动健康——用最适合的方法（好水与精准营养）从根源调理体质 | 精准营养推荐、健康报告解析、体质调理方案 |
| **智** (Wisdom) | 金 | `#6366F1` | 赋能未来——专业心智测评与综合素质培养 | DAN 认知测评、六维常模对比、训练推荐 |
| **富** (Wealth) | 水 | `#F59E0B` | 利他创富——创客成长生态，分享中实现第二收入 | 销售体系、推广奖励、积分商城 |
| **行** (Action) | 木 | `#10B981` | 人际和谐——亲子/夫妻/社交关系建设 | 家庭关系图、关系类型配置、生肖/血型配对 |
| **心** (Mind) | 火 | `#FF6B9D` | 大爱相随——心理学视角解读自我与家人 | 情绪认知疏导、家庭关系心理学、人格探索 |

### 4.2 五行相生相克 · 动态平衡

**相生**（推动系统前进）：身→智→富→行→心→身（循环）
**相克**（防止系统失控）：
- 身克富：健康是最大财富，莫用健康换金钱
- 智克行：算计人际关系得失不如真诚以待
- 富克心：勿让铜臭掩盖温情，财富服务于家庭
- 行克身：人际有度，关爱有方，莫透支自身健康
- 心克智：大爱需留理性空间，不过度保护

### 4.3 能量系统架构

```
能量规则引擎 (energy_rule)
    │ 事件驱动：checkin / register / complete / cancel / overdue
    │ 动作：increase / decrease
    │ 维度：body / mind / wisdom / action / wealth 或 NULL（五维均衡）
    │ 计算公式：amount（固定）或 amount_formula（动态）
    ▼
五维度账本（维度 × 用户）
    │ 沙盘评分（百分比，0-100，对标常模）
    │ 账本积分（总量，每日/每周变动记录）
    ▼
维度健康指数 = (沙盘评分 × 0.6) + (账本积分归一化 × 0.4)
    ▼
服务推荐引擎：根据最低维度推荐对应商品/活动/文章
```

**实现状态**：
- ✅ 规则引擎表（`energy_rule`）已创建，支持事件类型 + 动作 + 维度 + 条件 JSON
- ✅ 活动表（`activities`）含维度标记 + 报名流程
- ✅ 能量发放/消耗 API 已实现（`EnergyController`）
- ❌ 沙盘评分（常模对比百分位）未完整实现
- ❌ 维度健康指数聚合计算未实现
- ❌ 基于维度的服务推荐引擎未实现

---

## 5. 会员体系与销售机制

### 5.1 会员等级

| 等级 | 价格 | 权益 | 系统标识 |
|------|------|------|----------|
| FREE | 免费 | 基础任务、1 次 DAN 测评初始化、基础文章 | `membership = 'free'` |
| FAMILY | ¥365/年 | 完整报告、专家解读、积分商城、能量系统、高级内容、推荐佣金 | `membership = 'family'` |
| PROVIDER | 审核制 | 供应商入驻 + 商品管理 + 订单处理 + 销售团队 | `vendor_type` + `guide` 认证 |

### 5.2 销售体系

```
用户 A（推荐人）
    │ 邀请码 / 邀请卡片
    ▼
用户 B（新注册）
    │ B 首次消费时，A 获得积分奖励（平台出资）
    │ B 后续消费时，A 获得消费金额 × 佣金比例（供应商承担）
    ▼
销售层级
    ├── 一级：直接邀请（佣金比例最高）
    └── 二级：下级邀请（佣金比例递减，视配置）
```

#### 已实现的销售表结构

| 表 | 用途 | 状态 |
|----|------|------|
| `distribution_systems` | 虚拟服务商团队 | ✅ 已建表 |
| `distribution_relations` | 团队-服务商关系（树形） | ✅ 已建表 |
| `invite_card` | 邀请卡片（child/family/guide 类型） | ✅ 已建表 |
| `referral_leaderboard` | 推广排行榜周记录 | ✅ 已建表 |
| `invite_milestone` | 邀请里程碑奖励 | ✅ 已建表 |
| `onboarding_task` | 新手引导奖励 | ✅ 已建表 |
| `growth_task` / `growth_task_log` | 成长任务配置与进度 | ✅ 已建表 |
| ❌ 佣金结算 | 订单级佣金拆分与到账 | 待实现 |

### 5.3 暂未实现的会员功能

| 功能 | 说明 | 优先级 |
|------|------|--------|
| FAMILY 会员订阅扣费 | 微信自动续费 | P1 |
| 会员到期提醒 | 到期前 N 天推送 | P1 |
| 会员专享内容遮罩 | 免费用户不可查看会员文章 | P1 |
| 试用期管理 | 邀请 3 人送 7 天体验 | P1 |
| 佣金自动结算 | 订单完成 → 佣金到账可提现 | P2 |

---

## 6. 功能模块全景

### 6.1 模块总览

| 编号 | 模块 | 实现状态 | 优先级 | TabBar |
|:----:|------|:--------:|:------:|:------:|
| M01 | 认证与登录 | ✅ 完整 | P0 | — |
| M02 | 家庭管理 | ✅ 完整 | P0 | — |
| M03 | 任务系统 | ✅ 完整 | P0 | — |
| M04 | 积分系统 | ✅ 完整 | P0 | — |
| M05 | 心愿/奖励 | ✅ 完整 | P0 | — |
| M06 | DAN 认知测评 | ✅ 完整 | P0 | 🔥 心 |
| M07 | 支付（微信） | ✅ 完整 | P0 | — |
| M08 | 商品/订单（商城） | ✅ 基本完整 | P0 | 💧 富 |
| M09 | 混合支付（积分+微信） | ✅ 完整 | P0 | — |
| M10 | 五维能量系统 | ⚠️ 表结构完整，规则引擎待完善 | P1 | 🌿 行 |
| M11 | 健康检测（菌群） | ⚠️ 报告模块完整，商品流程未闭环 | P1 | 🌏 身 |
| M12 | 会员体系 | ⚠️ 表完整，付费流程待实现 | P1 | — |
| M13 | 服务商入驻 | ⚠️ 申请流程完整，管理后台待完善 | P1 | — |
| M14 | 销售体系 | ⚠️ 表完整，佣金结算待实现 | P2 | 💧 富 |
| M15 | 五维首页 | ⚠️ 部分页面已实现，新设计待重构 | P1 | 全部 |
| M16 | AI 解读 | ❌ 未启动 | P1 | 🔥 心 |
| M17 | 精准营养方案 | ❌ 未启动 | P2 | 🌏 身 |
| M18 | 供应商供应链 | ⚠️ 表完整，结算流程待实现 | P2 | — |
| M19 | 活动报名 | ❌ 页面未接入 | P2 | 🌿 行 |
| M20 | 舌诊功能 | ⚠️ 指标定义就绪，前端未接入 | P2 | 🌏 身 |

### 6.2 已上线功能详情

#### M01 认证与登录 ✅
- 微信授权登录（openid + unionid）
- 手机号绑定
- JWT Token 认证（拦截器 + Bearer Header）
- 角色切换（parent ↔ child / teacher ↔ parent）
- 8 个公开路径免认证

#### M02 家庭管理 ✅
- 家庭创建（invite_code 邀请码）
- 家庭成员添加/移除（family_members 表）
- 关系类型配置（relationship_types 表，管理端可配置）
- 家庭成员关系图
- 孩子添加/编辑（家长端）

#### M03 任务系统 ✅
- 任务创建（家长/规划师）- 标题、描述、积分、截止日期
- 任务执行（孩子端）- 含小游戏/媒体记录
- 任务审核（家长端）- 分类审核/按分类审核
- 任务模板（`task_templates` 表）
- 重复设置（none/daily/weekly）
- 超时判定（overdue 状态）

#### M04 积分系统 ✅
- 家长积分（`User.totalPoints`）：任务审核通过/手动调整/商城消费
- 孩子积分（`FamilyMember.totalPoints`）：任务执行/心愿兑换
- 系统积分（`FamilyMember.systemPoints`）：平台发放/干预奖励
- 积分流水（`points_log`，按类型 earn/spend/bonus/penalty/adjust/reset/refund）
- 积分清零记录（`points_reset_log`）

#### M05 心愿/奖励 ✅
- 孩子创建心愿 → 家长审批 → 扣减积分 → 兑现
- 预设奖励模板（看动画片/玩平板/买玩具等）
- 奖励分类配置（物质/精神/特权/活动）
- 愿望完整工作流（draft/active/pending_exchange/approved/exchanging/fulfilled/cancelled/rejected）

#### M06 DAN 认知测评 ✅
- 测评资料管理（CRUD + 状态控制）
- 积分配置（完成测评奖励积分）
- 家庭测评配置（启用/停用 + 提醒周期）
- 测评记录创建/完成
- 六维认知评分 + EMI 情绪商数 + 大五人格
- 百分位常模对比（`CognitiveNormService`）
- 训练推荐（YAML 配置驱动）
- 测评报告自动创建成长档案

#### M07-M09 支付与商城 ✅
- 商品 CRUD + 会员价/普通价
- 商品分类树（三级类目）
- 购物车（`cart` 表）
- **混合支付**：创建订单时指定积分抵扣数量 → 支付时先扣积分 → 剩余现金走微信
- 积分不足时全部走微信
- 支付失败积分原路退回
- 订单生命周期：待支付 → 已支付 → 已发货 → 已确认 → 已完成
- 售后申请 + 管理端审核
- 物流查询

### 6.3 未上线/待完善功能详情

#### M10 五维能量系统 ⚠️
**现状**：
- 能量规则表（`energy_rule`）已建，含事件类型 + 动作 + 维度 + 条件
- `EnergyController` 提供概览/流水/配置 API
- 活动注册时奖励能量（`AssessmentAppointmentService` 创建预约 +10，完成 +30）
- 任务完成/打卡能量奖励种子数据未完整填充

**遗留工作**：
- 沙盘评分（百分位对标常模）算法
- 维度健康指数聚合公式
- 能量流水前端展示（折线图/雷达图）
- 低维度智能推荐

#### M11 健康检测（菌群） ⚠️
**现状**：
- `health_reports` 表完整（总分/菌群分/慢病分/营养分/肠型/肠道年龄）
- `health_indicators` 表支持分类（营养状况/疾病风险/肠道屏障/神经递质）
- `health_report_drafts` 两阶段入库（草稿 → 确认）
- `health_report_permissions` 查看权限控制

**遗留工作**：
- 菌群检测商品下单流程（采样盒 → 扫码 → 结果上传）
- 报告 AI 解读（接入 AI 服务）
- 精准营养方案生成（基于检测结果 + 五维模型）

#### M16 AI 解读 ❌
**未实现**：
- DAN 测评报告 AI 摘要生成
- 菌群检测报告 AI 解读
- 个性化调整方案 AI 推荐
- AI 对话助手（`growth_task` 种子数据含 'DAILY_AI' 但未实现）

---

## 7. 阶段规划与优先级

### 7.1 阶段划分总览

```
       2026 Q3               2026 Q4               2027 Q1
├───────────┼───────────┼───────────┼───────────┼───────────┤
  P0 · 基础闭环            P1 · 会员商业               P2 · 生态构建
  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
  │ • 引流产品上线     │    │ • 会员订阅付费     │    │ • 供应链结算       │
  │ • 商品交易         │    │ • AI 解读         │    │ • 精准营养       │
  │ • 五维能量基础     │    │ • 销售佣金         │    │ • 舌诊功能       │
  │ • 角色体系         │    │ • 五维首页改版     │    │ • 活动生态       │
  │ • 积分体系         │    │ • 能量系统完善     │    │ • 开放平台       │
  └─────────────────┘    └─────────────────┘    └─────────────────┘
```

### 7.2 P0 · 基础闭环（当前状态已基本完成）

| 序号 | 需求 | 说明 | 实现状态 |
|:----:|------|------|:--------:|
| P0-01 | 微信登录认证 | 微信授权 + JWT + 角色切换 | ✅ 已上线 |
| P0-02 | 家庭管理 | 创建/邀请/关系管理 | ✅ 已上线 |
| P0-03 | 任务系统 | 创建/执行/审核/模板 | ✅ 已上线 |
| P0-04 | 积分体系 | 家长积分 + 孩子积分 + 流水 | ✅ 已上线 |
| P0-05 | 心愿/奖励 | 创建/审批/兑换/模板 | ✅ 已上线 |
| P0-06 | DAN 测评 | 预约/支付/结果/报告 | ✅ 已上线 |
| P0-07 | 微信支付 | V3 支付 + 回调处理 | ✅ 已上线 |
| P0-08 | 商品商城 | 商品/分类/购物车/订单 | ✅ 已上线 |
| P0-09 | 混合支付 | 积分+现金混合支付 | ✅ 已上线 |
| P0-10 | 五维能量基础 | 维度配置/基础发放 | ⚠️ 规则引擎待完善 |
| P0-11 | 服务商入驻 | 申请/审核/套餐 | ⚠️ 管理端待完善 |
| P0-12 | 文章系统 | 分类/文章/阅读 | ✅ 已上线 |
| P0-13 | 管理后台 | 审核/配置/数据管理 | ⚠️ 功能群已搭建 |

**P0 待补全项**：
1. 能量规则引擎种子数据完整配置（`energy_rule` 事件→规则映射）
2. 服务商管理后台（审核/统计/结算）
3. 菌群检测商品流程闭环

### 7.3 P1 · 会员商业体系

| 序号 | 需求 | 说明 | 预估工时 |
|:----:|------|------|:--------:|
| P1-01 | 会员订阅 | FAMILY ¥365/年，微信自动续费 | 2 周 |
| P1-02 | 会员权益控制 | 内容遮罩、功能白名单、过期处理 | 1 周 |
| P1-03 | 五维首页改版 | 新 TabBar 设计（行/身/智/心/富） | 3 周 |
| P1-04 | 能量系统完善 | 沙盘评分、健康指数、推荐引擎 | 3 周 |
| P1-05 | AI 解读接入 | DAN 报告 + 菌群报告 AI 解读 | 3 周 |
| P1-06 | 推荐佣金 | 一级销售佣金自动计算/发放 | 2 周 |
| P1-07 | 邀请体验 | 邀请 3 人送 7 天 FAMILY | 1 周 |
| P1-08 | 菌群检测闭环 | 采样盒下单 → 扫码激活 → 结果回传 | 2 周 |
| P1-09 | 规划师套餐管理 | 套餐发布/下架/统计 | 1 周 |

**P1 总预估**：18 周（含并行开发）

### 7.4 P2 · 生态构建

| 序号 | 需求 | 说明 | 优先级 |
|:----:|------|------|:------:|
| P2-01 | 供应链结算 | 账期管理/自动结算/提现 | 高 |
| P2-02 | 精准营养方案 | 基于检测报告 + 五维模型的个性化营养包 | 高 |
| P2-03 | 多层销售 | 二级销售 + 团队返利 | 中 |
| P2-04 | 舌诊功能 | 舌象拍照上传 → AI 体质辨识 | 中 |
| P2-05 | 活动生态 | 活动发布/报名/打卡/审核/能量奖励 | 中 |
| P2-06 | 优惠券系统 | 平台券/商家券/满减 | 中 |
| P2-07 | 开放平台 | API 开放给外部服务商 | 低 |
| P2-08 | 数据看板 | 家庭成长数据可视化 | 低 |

---

## 8. 当前实现状态评估

### 8.1 后端实现统计

| 指标 | 数值 |
|------|:----:|
| 控制器总数 | 48 |
| Service 类 | ~35 |
| Entity 类 | ~40 |
| DTO 类 | ~30 |
| Mapper 接口 | ~35 |
| 数据表（schema.sql） | 40+ |
| 数据库迁移（DatabaseInitializer） | 38+ |
| 前端总页面（uni-app） | ~50 |
| Web 管理端页面 | ~29 |

### 8.2 按模块实现度评估

| 模块 | 后端 | 前端（小程序） | 后端API数 | 前端页面数 | 完成度 |
|------|:----:|:------------:|:---------:|:---------:|:------:|
| 认证 | ✅ 完整 | ✅ 完整 | 5+ | 3 | 95% |
| 家庭 | ✅ 完整 | ✅ 完整 | 12+ | 4 | 90% |
| 任务 | ✅ 完整 | ✅ 完整 | 10+ | 5 | 90% |
| 积分 | ✅ 完整 | ✅ 完整 | 8+ | 3 | 95% |
| 心愿 | ✅ 完整 | ✅ 完整 | 8+ | 3 | 90% |
| DAN测评 | ✅ 完整 | ✅ 完整 | 20+ | 5 | 85% |
| 支付 | ✅ 完整 | ✅ 完整 | 6+ | 2 | 90% |
| 商城 | ✅ 完整 | ⚠️ 基础 | 15+ | 5 | 70% |
| 五维能量 | ⚠️基础 | ⚠️ 基础 | 6+ | 2 | 40% |
| 菌群检测 | ✅ 报告端 | ❌ 未接入 | 8+ | 0 | 35% |
| 会员体系 | ⚠️ 表完整 | ❌ 未接入 | 0 | 0 | 10% |
| 服务商入驻 | ✅ 申请端 | ✅ 入驻页 | 10+ | 2 | 60% |
| 销售体系 | ⚠️ 表完整 | ❌ 未接入 | 0 | 0 | 15% |
| AI 解读 | ❌ 未开始 | ❌ 未开始 | 0 | 0 | 0% |
| 活动 | ⚠️ 表完整 | ❌ 未接入 | 4 | 0 | 20% |
| 舌诊 | ⚠️ 表完整 | ❌ 未开始 | 0 | 0 | 10% |

### 8.3 已知技术债务

| 问题 | 影响 | 严重性 |
|------|------|:------:|
| `DanAssessmentController` 使用 `@GetMapping` 违反项目规范（应为 `@PostMapping`） | 接口风格不一致 | 低 |
| `AssessmentPermissionServiceInterface.getAssessmentById()` 返回类型声明为 `AssessmentAppointment` 但实际返回 `DanAssessmentResult` | 类型安全风险 | 中 |
| `AssessmentOrderService.paySuccess()` 未被调用 —— `payOrder()` 未触发佣金结算 | 测评订单佣金遗漏 | 中 |
| 新旧两套测评 Controller 并存（`DanAssessmentController` vs `assessment/` 子包） | 逻辑重复 | 低 |
| `OrderItem` 实体已建表但 `createMultiItem` 未写入 order_items | 多商品订单无明细 | 中 |
| 可选链 `?.` 在部分前端页面残留（违反小程序规范） | 兼容性风险 | 低 |
| 后端部分异常未统一包装为 `Result<T>` | 前端处理不一致 | 中 |

---

## 9. 数据模型概览

### 9.1 核心表结构

```
用户与家庭
├── users                    # 用户主表（openid/unionid/role/membership/points）
├── families                 # 家庭表（name/invite_code）
├── family_members           # 家庭成员（relation_type/role_override/points）
├── relationship_types       # 关系类型配置（管理端可配置）
├── user_address             # 收货地址

任务与积分
├── tasks                    # 任务表（points/deadline/repeat_type/status）
├── points_log               # 积分流水（type/category/amount）
├── points_reset_log         # 清零记录
├── task_templates           # 任务模板

心愿与奖励
├── wishes                   # 心愿（status 工作流完整）
├── rewards                  # 奖励（模板/兑换）
├── reward_categories        # 奖励分类

测评与成长
├── dan_assessment_results   # DAN测评结果（六维+EMI+大五人格+孩子快照）
├── dan_assessments          # DAN测评记录（API/manual 来源）
├── assessment_results       # 评估结果（兼容旧版）
├── assessment_appointments  # 测评预约
├── assessment_orders        # 测评订单
├── assessment_materials     # 测评资料
├── assessment_records       # 测评记录
├── assessment_points_config # 积分配置
├── family_assessment_config # 家庭测评配置
├── growth_plans             # 成长规划
├── growth_records           # 成长档案
├── growth_task / log        # 成长任务与进度

商品与订单
├── products                 # 商品（type/domain/vendor/member_price）
├── product_orders           # 订单（points_used/points_cost/money_amount）
├── order_items              # 订单明细
├── product_skus             # SKU
├── shop_categories          # 商品分类
├── cart                     # 购物车
├── after_sales_requests     # 售后申请

支付
├── payment_orders           # 支付订单
├── package_orders           # 套餐订单

五维能量
├── energy_rule              # 能量规则引擎
├── activities               # 活动（dimension_code/vendor/price）
├── activity_registrations   # 活动报名

健康
├── health_reports           # 健康报告（gut_flora/physical_exam）
├── health_indicators        # 健康指标明细
├── health_report_drafts     # 报告草稿
├── health_report_permissions# 查看权限
├── indicator_definitions    # 全域指标定义
├── indicator_values         # 全域指标值
├── tongue_records           # 舌诊记录

销售与供应链
├── distribution_systems     # 销售体系
├── distribution_relations   # 销售关系（树形）
├── supply_system            # 供应商体系
├── supply_system_member     # 体系成员
├── supply_settlement        # 结算记录
├── supply_settlement_detail # 结算明细

先天属性
├── family_member_attributes # 先天属性（八字/五行/生肖/血型）
├── zodiac_config            # 配置
├── blood_type_config        # 血型配置
├── heavenly_stems_config    # 天干配置
├── zodiac_pairing           # 生肖配对
├── blood_type_pairing       # 血型配对
├── life_number_relationship # 生命灵数关系解读

系统
├── sys_config               # 配置
├── system_config            # 系统配置（年龄阈值等）
├── content_sections         # 内容区块
├── article_categories       # 文章分类
├── articles                 # 文章
├── coupon / user_coupon     # 优惠券
├── mini_games               # 小游戏
├── media_records            # 媒体记录
├── guides / guide_applications / records # 服务商
├── invite_card              # 邀请卡片
├── onboarding_task          # 新手引导
├── streets                  # 街道地址维度
├── user_operation_logs      # 操作日志
```

### 9.2 关键字段说明

**User 用户表**：
- `totalPoints`：家长积分（商城抵扣用），1 分 = ¥0.01
- `membership`：会员等级（free/family/provider）
- `role`：角色（parent/child/teacher/admin/supplier_admin）
- `roles`：多角色字段（JSON 数组，支持一人多角色）

**ProductOrder 订单表**：
- `pointsUsed`：使用的积分数量
- `pointsCost`：积分抵扣金额（分）
- `moneyAmount`：实际现金支付金额（分）
- `totalAmount = pointsCost + moneyAmount`（积分不足时 `moneyAmount = totalAmount`）

**family_members 家庭成员表**：
- `role_override`：角色覆盖（auto/parent/child/elderly）
- `relationship_type`：关系类型 key（外键 relationship_types.type_key）
- `total_points`：孩子积分余额（用于心愿兑换）

---

## 10. 技术架构

### 10.1 系统架构图

```
┌──────────────────────────────────────────────────────────────┐
│                    微信小程序 (uni-app Vue 2)                  │
│  ~50 页面 · 5 TabBar · 角色感知 UI · 自定义 TabBar             │
└──────────────────────┬───────────────────────────────────────┘
                       │ HTTPS / WSS
┌──────────────────────▼───────────────────────────────────────┐
│              Nginx 反向代理 (cfc.etotem.com.cn)                │
└──────────────────────┬───────────────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────────────┐
│              Spring Boot 2.7.18 (Port 9082)                  │
│  ┌─────────┐ ┌──────────┐ ┌────────┐ ┌──────────────┐       │
│  │Controller│ │ Service  │ │ MyBatis│ │ Scheduled    │       │
│  │  ×48     │ │  ×35     │ │ Plus   │ │ Tasks        │       │
│  └─────────┘ └──────────┘ └────────┘ └──────────────┘       │
│  ┌─────────┐ ┌──────────┐ ┌────────┐ ┌──────────────┐       │
│  │ JWT Auth │ │ Swagger  │ │ WeChat │ │ DataMigrate  │       │
│  │ Intercept│ │  Doc     │ │ Pay V3 │ │ (sfms→cfc)   │       │
│  └─────────┘ └──────────┘ └────────┘ └──────────────┘       │
└──────────────────────┬───────────────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────────────┐
│                    MySQL 8.0 × 2                             │
│  ┌──────────────────────┐  ┌──────────────────────────┐      │
│  │ cfc (主库)            │  │ sfms (只读源库)            │      │
│  │ 192.168.16.251:3306   │  │ bianwoyou.mysql.rds...   │      │
│  └──────────────────────┘  └──────────────────────────┘      │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                 Web 管理端 (Vue 2 + Element UI)               │
│  ~29 页面 · admin/* + teacher/* · 路由权限守卫                 │
└──────────────────────────────────────────────────────────────┘
```

### 10.2 技术选型

| 层 | 技术 | 版本 | 说明 |
|----|------|:----:|------|
| 后端框架 | Spring Boot | 2.7.18 | Java 8 |
| ORM | MyBatis-Plus | 3.x | 注解 + BaseMapper |
| 数据库 | MySQL | 8.0 | InnoDB + utf8mb4 |
| 认证 | JWT | — | Bearer Token + 拦截器 |
| 支付 | 微信支付 V3 | — | JSAPI 支付 + 回调 |
| API 文档 | Swagger | — | Knife4j 增强 |
| 前端 | uni-app | Vue 2 | 微信小程序 |
| 管理端 | Vue 2 + Element UI | — | SPA |
| 部署 | Nginx + rsync | — | 静态分离 |

### 10.3 关键设计决策

| 决策 | 选择 | 理由 |
|------|------|------|
| 接口风格 | 统一 `@PostMapping` | 简化前端调用（小程序 wx.request 默认 POST） |
| 响应格式 | `Result<T>` (code/message/data) | 统一前端错误处理 |
| 数据库迁移 | Java `DatabaseInitializer.runMigrations()` | 幂等迁移，自动建表 |
| 测评结果存储 | 孩子快照（姓名/年龄/学校等动态字段冗余到结果表） | 历史数据不随用户信息变更而改变 |
| 积分体系 | 家长（`User.totalPoints`）+ 孩子（`FamilyMember.totalPoints`）双轨制 | 家长积分可商城市花，孩子积分用于心愿闭环 |
| 角色切换 | JWT payload 中存当前角色 | 不依赖前端状态，后端每次请求验证 |

---

## 11. 风险与依赖

### 11.1 技术风险

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|:----:|----------|
| 微信小程序合规审核 | 功能上线延迟 | 中 | 确保先提交无支付版本审核 |
| 支付牌照/资质 | 商城支付被限制 | 低 | 使用微信支付标准接口 |
| 数据迁移（sfms→cfc）中断 | 历史数据丢失 | 低 | 迁移服务可重复执行 |
| AI 解读接口不稳定 | 用户体验下降 | 中 | 设计降级方案（AI 不可用时展示模板报告） |

### 11.2 业务依赖

| 依赖 | 说明 | 阶段 |
|------|------|:----:|
| 微信支付商户号 | 已开通 | P0 |
| 菌群检测实验室合作 | 需洽谈 | P1 |
| AI 服务商 | 需采购或自建 LLM 服务 | P1 |
| 精准营养方案制定 | 需营养师团队 | P2 |
| 舌诊 AI 模型 | 需采购或训练 | P2 |

### 11.3 已知阻塞项

1. **菌群检测商品流程未闭环**：已有完整报告模块，但从前端下单到采样盒发货、扫码激活、结果回传的完整链路未打通
2. **会员订阅付费未实现**：微信签约扣费的对接需要额外开发
3. **AI 解读为独立系统**：需要决定是采购第三方服务还是自建，影响架构设计

---

## 12. 附录

### 12.1 需求文档索引

| 文档 | 路径 | 说明 |
|------|------|------|
| 精准营养与健康报告功能需求 | `docs/需求分析/精准营养与健康报告功能需求.md` | 健康报告 + 营养方案需求 |
| 会员与销售体系设计 | `docs/需求分析/会员与销售体系设计.md` | 会员等级、销售佣金规则 |
| 健康能量设计 | `docs/需求分析/健康能量设计.md` | 五维能量系统完整设计 |
| TabBar 重构需求 | `docs/需求分析/TabBar重构需求.md` | 首页 TabBar 按五维重新分组 |
| 底签页面详细设计 | `docs/需求分析/底签页面详细设计.md` | TabBar 各页面内容设计 |
| 小程序页面重设计划 | `docs/系统设计/小程序页面重设计划.md` | 前端页面重构规划 |

### 12.2 数据库迁移记录

当前最大迁移编号：**迁移 38**（见 `DatabaseInitializer.java`）
迁移模式：`ensureColumn(table, column, definition)` 为列添加首选方法

### 12.3 版本记录

| 版本 | 日期 | 变更内容 |
|------|------|----------|
| V1.0 | 2026-07-08 | 初始版本，涵盖 P0 实现评估 + P1/P2 规划 |

---

> **文档维护者**：亿图腾科技 · 浠艾福开发团队  
> **下次评审**：2026-07-15  
> **意见反馈**：请提交 Issue 或联系项目负责人