Sfoglia il codice sorgente

docs: add 阶段性需求规格说明书 V1.0

Comprehensive spec covering business model, role system, five-dimension
happiness model, membership/distribution, module status assessment,
P0/P1/P2 roadmap, tech debt, data model overview, architecture, risks.
Xiaogang Liao 3 mesi fa
parent
commit
1e672868b2
1 ha cambiato i file con 757 aggiunte e 0 eliminazioni
  1. 757 0
      docs/SPECS-阶段V1.0.md

+ 757 - 0
docs/SPECS-阶段V1.0.md

@@ -0,0 +1,757 @@
+# 浠艾福(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 或联系项目负责人