docs: 添加DAN测评服务闭环流程设计文档

docs/DAN测评服务闭环流程设计.md

@@ -0,0 +1,223 @@
+# DAN测评服务闭环流程设计
+
+## 1. 概述
+本文档设计DAN测评订单的完整服务闭环流程，作为平台商品订单流程的平行体系。
+- **目标**：实现从预约到服务完成、用户评价、资金结算的全流程线上化管理
+- **范围**：测评服务+成长规划师组合预约流程
+- **使用场景**：
+  - 家长为孩子预约测评（+可选规划师服务）
+  - 测评机构+规划师提供服务
+  - 平台自动结算服务费用
+
+## 2. 现状分析
+### 2.1 现有流程
+```mermaid
+graph LR
+A[下单支付] --> B[预约时间/地点]
+B --> C[服务执行]
+C --> D[填写结果]
+```
+
+### 2.2 问题与缺口
+| 问题 | 影响 | 办法 |
+|------|------|------|
+| 服务完成状态不明确 | 服务方未确认完成，无法计费 | 增加"服务方确认完成"流程 |
+| 用户满意度无记录 | 无法评估服务质量 | 增加用户评分评价系统 |
+| 资金手动结算 | 体验差，延迟多 | 自动化结算流程 |
+
+## 3. 完整流程设计
+```mermaid
+graph TD
+A[下单支付] --> B[选择预约时间]
+B --> C[可选预约规划师]
+C --> D{规划师预约?}
+D -->|有规划师| E[等待双方确认]
+D -->|无规划师| F[等待测评师确认]
+E --> F
+F --> G[测评师填写完成]
+D -->|有规划师| H[规划师填写完成]
+G --> I[用户确认+评分]
+H --> I
+I --> J[自动结算]
+```
+
+## 4. 实体设计
+### 4.1 DanAssessmentExecution
+```sql
+CREATE TABLE `dan_assessment_executions` (
+  `id` bigint AUTO_INCREMENT PRIMARY KEY,
+
+  -- 基本关联
+  `assessment_execution_id` bigint NOT NULL COMMENT '执行记录ID',
+  `assessment_order_id` bigint NOT NULL COMMENT '订单ID',
+  `child_id` bigint NOT NULL COMMENT '孩子ID',
+  `family_id` bigint NOT NULL COMMENT '家庭ID',
+  `quota_id` bigint COMMENT '额度ID',
+
+  -- 测评师
+  `assessor_id` bigint NOT NULL COMMENT '测评师userId',
+  `assessor_status` enum('pending','completed','rejected') DEFAULT 'pending' COMMENT '测评师状态',
+  `assessor_completed_at` datetime COMMENT '测评师完成时间',
+  `assessor_notes` varchar(200) COMMENT '测评摘要/服务备注',
+
+  -- 成长规划师（可选）
+  `planner_id` bigint COMMENT '规划师userId',
+  `planner_status` enum('pending','completed','rejected') DEFAULT 'pending' COMMENT '规划师状态',
+  `planner_completed_at` datetime COMMENT '规划师完成时间',
+  `planner_notes` varchar(200) COMMENT '规划服务备注',
+
+  -- 用户确认
+  `user_confirmed` tinyint(1) DEFAULT 0 COMMENT '用户确认：0未确认,1已确认',
+  `user_confirmed_at` datetime COMMENT '用户确认时间',
+
+  `created_at` datetime DEFAULT CURRENT_TIMESTAMP,
+  `updated_at` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  
+  KEY `idx_assessment_execution_id` (`assessment_execution_id`),
+  KEY `idx_assessment_order_id` (`assessment_order_id`),
+  KEY `idx_assessor_id` (`assessor_id`),
+  KEY `idx_planner_id` (`planner_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='DAN测评服务执行记录';
+```
+
+### 4.2 ServiceRating
+```sql
+CREATE TABLE `service_ratings` (
+  `id` bigint AUTO_INCREMENT PRIMARY KEY,
+
+  -- 基本关联
+  `execution_id` bigint NOT NULL COMMENT '执行记录ID',
+  `assessment_order_id` bigint NOT NULL COMMENT '订单ID',
+  `user_id` bigint NOT NULL COMMENT '评分用户ID',
+
+  -- 测评师评分
+  `assessor_id` bigint NOT NULL COMMENT '测评师userId',
+  `assessor_rating` tinyint DEFAULT 0 COMMENT '测评师评分 1-5',
+  `assessor_comment` varchar(500) COMMENT '评价内容',
+
+  -- 规划师评分（可选）
+  `planner_id` bigint COMMENT '规划师userId',
+  `planner_rating` tinyint COMMENT '规划师评分 1-5',
+  `planner_comment` varchar(500) COMMENT '评价内容',
+
+  `created_at` datetime DEFAULT CURRENT_TIMESTAMP,
+  
+  UNIQUE KEY `uniq_execution_user` (`execution_id`, `user_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='服务评分记录';
+```
+
+### 4.3 ServiceSettlement
+```sql
+CREATE TABLE `service_settlements` (
+  `id` bigint AUTO_INCREMENT PRIMARY KEY,
+
+  -- 基本关联
+  `execution_id` bigint NOT NULL COMMENT '执行记录ID',
+  `assessment_order_id` bigint NOT NULL COMMENT '订单ID',
+  `provider_id` bigint NOT NULL COMMENT '服务提供方userId',
+  `provider_type` enum('assessor','planner') NOT NULL COMMENT '服务方类型',
+
+  `service_fee` bigint DEFAULT 0 COMMENT '服务费用(分)',
+  `commission_rate` int COMMENT '佣金比例(bps)',
+  `commission_amount` bigint DEFAULT 0 COMMENT '结算金额(分)',
+
+  `status` enum('pending','settled','failed') DEFAULT 'pending' COMMENT '结算状态',
+  `settled_at` datetime COMMENT '结算时间',
+  `transaction_id` varchar(100) COMMENT '转账交易ID',
+
+  `created_at` datetime DEFAULT CURRENT_TIMESTAMP,
+  `updated_at` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  
+  KEY `idx_execution_id` (`execution_id`),
+  KEY `idx_provider_id` (`provider_id`),
+  KEY `idx_status` (`status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='服务结算记录';
+```
+
+## 5. 运营配置
+| 配置项 | 类型 | 描述 | 默认值 |
+|---------|------|------|--------|
+| `dan_assessment_assessor_commission_rate` | int | 测评师佣金比例(bps) | 7000 |
+| `dan_assessment_planner_commission_rate` | int | 规划师佣金比例(bps) | 5000 |
+| `dan_assessment_auto_settle` | bool | 用户确认后自动结算 | true |
+| `dan_assessment_settlement_days` | int | 结算延迟天数 | 0 |
+
+## 6. API 接口设计
+### 6.1 服务提供方接口
+| 接口 | 方法 | 描述 | 参数 |
+|------|------|------|------|
+| `/api/assessment/execution/{id}/complete` | POST | 服务方填写完成 | `{ notes: string }` |
+| `/api/assessment/execution/my-list` | POST | 我的服务单列表 | `{ status: enum }` |
+
+### 6.2 用户接口
+| 接口 | 方法 | 描述 | 参数 |
+|------|------|------|------|
+| `/api/assessment/execution/{id}/confirm` | POST | 确认服务完成 | `{}` |
+| `/api/assessment/execution/{id}/rate` | POST | 评分 | `{ assessorRating, assessorComment, [plannerRating], [plannerComment] }` |
+
+### 6.3 管理端接口
+| 接口 | 方法 | 描述 | 参数 |
+|------|------|------|------|
+| `/api/admin/assessment/execution/list` | POST | 执行记录列表 | `{ dateRange, status }` |
+| `/api/admin/assessment/execution/{id}/settle` | POST | 手动结算 | `{}` |
+
+## 7. 状态机设计
+```mermaid
+stateDiagram
+[*] --> pending: 下单+预约
+pending --> confirmed: 测评师确认
+confirmed --> planner_confirmed: 规划师确认（如有）
+confirmed --> user_rated: 仅测评师
+planner_confirmed --> user_rated
+user_rated --> auto_settled: 自动结算
+pending --> rejected: 服务方拒绝
+```
+
+## 8. 操作界面需求
+### 8.1 小程序端（用户）
+- **订单详情页**：服务完成进度展示、确认按钮
+- **评分入口**：测评结果查看后弹窗评分，或消息中心跳转评分
+- **评分界面**：双评分（测评师+规划师）+双评价
+
+### 8.2 小程序端（服务方）
+- **服务消息中心**：待办服务提醒
+- **服务完成**：备注说明+确认完成
+
+### 8.3 管理后台
+- **执行记录查询**：多维度过滤
+- **结算管理**：手动结算、异常处理
+
+## 9. 结算规则
+1. **结算金额计算**
+```
+结算金额 = 历史服务费用 × (佣金比例 / 10000)
+```
+
+2. **自动结算触发**
+- 条件1：`ServiceExecution.user_confirmed = 1`
+- 条件2：`SysConfig.dan_assessment_auto_settle = true`
+- 延迟：`N = SysConfig.dan_assessment_settlement_days` 天后
+
+## 10. 安全考虑
+| 风险项 | 应对措施 |
+|--------|----------|
+| 服务方虚假完成 | 二次确认(短信/人工) |
+| 用户误评价 | 评价前确认提示 |
+| 结算异常 | 短信通知管理员 |
+
+## 11. 实施计划
+| 阶段 | 工作内容 | 人天 |
+|------|---------|------|
+| 1 | 数据库设计+迁移 | 1 |
+| 2 | 后端服务层开发 | 3 |
+| 3 | API层开发+测试 | 2 |
+| 4 | 小程序端界面 | 2 |
+| 5 | 管理后台界面 | 1 |
+| 6 | 整体测试+验证 | 2 |
+
+## 12. 兼容性
+- **与现有流程**：扩展但不重构（新流程平行运行）
+- **与额度系统**：关联但独立（不影响现有额度消耗逻辑）
+- **与佣金系统**：复用结算逻辑（新增service类型）
+
+> 下一步：基于本设计方案，启动开发工作。需求细节确认后，分阶段实现。