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

DAN测评服务闭环流程设计

1. 概述

本文档设计DAN测评订单的完整服务闭环流程，作为平台商品订单流程的平行体系。

• 目标：实现从预约到服务完成、用户评价、资金结算的全流程线上化管理
• 范围：测评服务+成长规划师组合预约流程
• 使用场景：
  • 家长为孩子预约测评（+可选规划师服务）
  • 测评机构+规划师提供服务
  • 平台自动结算服务费用

2. 现状分析

2.1 现有流程

graph LR
A[下单支付] --> B[预约时间/地点]
B --> C[服务执行]
C --> D[填写结果]

2.2 问题与缺口

问题	影响	办法
服务完成状态不明确	服务方未确认完成，无法计费	增加"服务方确认完成"流程
用户满意度无记录	无法评估服务质量	增加用户评分评价系统
资金手动结算	体验差，延迟多	自动化结算流程

3. 完整流程设计

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

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

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

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. 状态机设计

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. 自动结算触发

3. 条件1：ServiceExecution.user_confirmed = 1

4. 条件2：SysConfig.dan_assessment_auto_settle = true

5. 延迟：N = SysConfig.dan_assessment_settlement_days 天后

10. 安全考虑

风险项	应对措施
服务方虚假完成	二次确认(短信/人工)
用户误评价	评价前确认提示
结算异常	短信通知管理员

11. 实施计划

阶段	工作内容	人天
1	数据库设计+迁移	1
2	后端服务层开发	3
3	API层开发+测试	2
4	小程序端界面	2
5	管理后台界面	1
6	整体测试+验证	2

12. 兼容性

• 与现有流程：扩展但不重构（新流程平行运行）
• 与额度系统：关联但独立（不影响现有额度消耗逻辑）
• 与佣金系统：复用结算逻辑（新增service类型）

下一步：基于本设计方案，启动开发工作。需求细节确认后，分阶段实现。