medical-mall/docs/home-service/BACKEND_RPC_GAP_SUMMARY.md

居家服务（Home Service）后端 RPC 缺口清单

生成日期：2026-06-02 适用项目：医疗-consumer / 医疗-delivery 目标：替代前端直接写 ec_* / hc_* 新链表，所有状态变更必须由后端 RPC 驱动

---

1. 当前完成状态（前端侧）

1.1 Delivery 履约动作 ✅ 已完成

api/delivery.uts 中所有 delivery worker 动作已优先调用 rpc_delivery_* RPC，fallback 为本地 mock（不碰数据库）。

前端动作	RPC 名称	状态
接单	rpc_delivery_accept_order	✅
拒单	rpc_delivery_reject_order	✅
出发	rpc_delivery_start_depart	✅
到达	rpc_delivery_arrive_order	✅
签到	rpc_delivery_checkin_order	✅
开始服务	rpc_delivery_start_service	✅
保存进度	rpc_delivery_save_progress	✅
上传留痕	rpc_delivery_upload_evidence	✅
重试留痕	rpc_delivery_retry_evidence	✅
提交异常	rpc_delivery_submit_exception	✅
完成服务	rpc_delivery_finish_service	✅
工单列表	rpc_delivery_order_list	✅
工单详情	rpc_delivery_order_detail	✅
仪表盘	rpc_delivery_dashboard	✅
服务记录	rpc_delivery_record_list	✅
消息列表	rpc_delivery_message_list	✅
在线状态	rpc_delivery_set_online_status	✅

1.2 Home Service 服务人员动作 ✅ 已完成

homeServiceService.uts 中 worker 侧方法已切换为调用 delivery RPC：

前端方法	调用 RPC	状态
completeWorkerTask	rpc_delivery_finish_service	✅
submitWorkerCheckIn	rpc_delivery_checkin_order + rpc_delivery_start_service	✅
submitWorkerServiceRecord	rpc_delivery_save_progress	✅
submitWorkerException	rpc_delivery_submit_exception	✅

注：以上方法不再直接 update ec_care_tasks / insert hc_work_order_events。

1.3 Consumer 验收动作 ⚠️ 已设安全门

serviceOrderService.uts 中对 care task（UUID 格式 ID）已拒绝直接写表，返回提示：

前端方法	旧行为	当前行为
confirmServiceOrder	直接 update ec_care_tasks + insert ec_care_records	❌ 拦截，提示“验收功能正在升级”
rejectServiceOrderAcceptance	直接 update ec_care_tasks + insert hc_work_order_exceptions	❌ 拦截，提示“验收功能正在升级”
saveServiceRecord	直接 insert ec_care_records	❌ 拦截，提示“服务记录功能正在升级”
dispatchPaidHomecareOrder	调用旧 rpc_homecare_auto_dispatch	✅ 对 UUID 格式订单返回“同步中”安全提示；仅对 so- 前缀旧订单调用旧 RPC

1.4 Admin 管理动作 ⚠️ 已设安全门

homeServiceService.uts 中 admin 方法不再直接写表，仅返回本地构建的 mock 详情：

前端方法	状态
submitAdminAssessment	⚠️ 返回本地构造的 assessment 对象，未写库
submitAdminServicePlan	⚠️ 返回本地构造的 plan 对象，未写库
submitAdminRectification	⚠️ 返回本地构造的 rectification 对象，未写库
submitAdminSettlementArchive	⚠️ 操作本地 mock 数组 ADMIN_SETTLEMENTS，未写库

1.5 工单创建 ⚠️ 过渡保留

tryCreateCareTask 在 consumer 和 delivery 的 serviceOrderService.uts 中仍直接 insert ec_service_requests + ec_care_tasks，但已：

• 移除前端自动派单逻辑（不再写入 assigned_to + ORDER_ASSIGNED）
• 移除前端直接 insert hc_work_order_events
• 增加 ecServiceRequestCreateUnavailable / ecCareTaskCreateUnavailable 开关，遇到表字段缺失时自动停用

---

2. 后端 RPC 缺口清单（按优先级）

🔴 P0 — 阻断核心流程，必须补齐

缺口编号	RPC 名称	用途	调用方	当前替代方案
P0-1	rpc_consumer_create_homecare_task	消费者下单后创建/激活 ec_service_requests + ec_care_tasks	serviceOrderService.uts tryCreateCareTask	前端直接 INSERT（过渡保留）
P0-2	rpc_payment_callback_activate_care_task	支付成功后由后端自动/手动激活 care task	payment.uvue dispatchPaidHomecareOrder	返回“同步中”提示，无实际激活

说明：P0-1 和 P0-2 解决的是“工单从哪里来”的问题。理想流程是：

1. 消费者下单 → 写 hss_service_orders（旧交易链，保留）
2. 支付成功 → 后端回调/RPC 创建 ec_service_requests + ec_care_tasks
3. 后端调度系统派单 → update ec_care_tasks assigned_to + ORDER_ASSIGNED 当前步骤 2/3 缺失，导致非套餐单走前端直接 INSERT。

🟡 P1 — 影响用户体验，应尽快补齐

缺口编号	RPC 名称	用途	调用方	当前替代方案
P1-1	rpc_consumer_confirm_acceptance	消费者确认验收：ec_care_tasks → ACCEPTED，写入 ec_care_records（review）	serviceOrderService.uts confirmServiceOrder	拦截，提示“正在升级”
P1-2	rpc_consumer_reject_acceptance	消费者拒绝验收：ec_care_tasks → ACCEPTANCE_REJECTED，写入 hc_work_order_exceptions	serviceOrderService.uts rejectServiceOrderAcceptance	拦截，提示“正在升级”
P1-3	rpc_consumer_save_service_record	消费者/家属补充服务记录	serviceOrderService.uts saveServiceRecord	拦截，提示“正在升级”

🟢 P2 — 管理后台功能，可排期实现

缺口编号	RPC 名称	用途	调用方	当前替代方案
P2-1	rpc_admin_submit_assessment	Admin 提交评估结果，写入评估表 + 事件	homeServiceService.uts submitAdminAssessment	仅返回本地对象，未持久化
P2-2	rpc_admin_submit_service_plan	Admin 提交服务计划	homeServiceService.uts submitAdminServicePlan	仅返回本地对象，未持久化
P2-3	rpc_admin_submit_rectification	Admin 提交整改结论	homeServiceService.uts submitAdminRectification	仅返回本地对象，未持久化
P2-4	rpc_admin_settlement_archive	Admin 结算归档	homeServiceService.uts submitAdminSettlementArchive	仅操作本地 mock 数组

---

3. 前端已清理的直接写表现状

3.1 已完全消除的前端直接写表

以下前端直接写表行为已彻底移除：

• ❌ update ec_care_tasks（由 delivery worker 动作触发）— 已全部改为 rpc_delivery_*
• ❌ insert hc_work_order_events（由 worker/consumer 动作触发）— 已改为后端 RPC 统一写入
• ❌ insert ec_care_records（由 worker checkin/service record 触发）— 已改为 rpc_delivery_checkin_order / rpc_delivery_save_progress
• ❌ insert hc_work_order_exceptions（由 worker exception 触发）— 已改为 rpc_delivery_submit_exception
• ❌ insert hss_service_order_status_logs（旧链）— insertLegacyStatusLog 已改为 NO-OP + console.warn

3.2 仍保留的前端直接写表（仅限过渡）

• ⚠️ insert ec_service_requests — tryCreateCareTask（consumer），有 ecServiceRequestCreateUnavailable 自动停用保护
• ⚠️ insert ec_care_tasks — tryCreateCareTask（consumer + delivery），有字段缺失自动停用保护
• ⚠️ insert hss_service_orders — 旧交易链路，用于套餐订单支付（预期中长期保留）
• ⚠️ update hss_service_orders — confirmServiceOrder / rejectServiceOrderAcceptance 的 legacy 分支（仅对 so- 前缀订单）

---

4. 数据库表职责划分（当前约定）

表名	职责	前端是否直接读写
ec_service_requests	新链服务申请	⚠️ 仅 tryCreateCareTask 过渡 INSERT，待 P0-1 RPC
ec_care_tasks	新链履约工单（核心状态）	❌ 禁止前端直接 UPDATE，仅 SELECT 读详情/列表
ec_care_records	服务记录（checkin、progress、review）	❌ 禁止前端直接 INSERT/UPDATE
hc_work_order_events	状态事件/时间轴	❌ 禁止前端直接 INSERT
hc_work_order_exceptions	异常/整改记录	❌ 禁止前端直接 INSERT
hc_evidence_files	留痕文件	❌ 禁止前端直接 INSERT（走 rpc_delivery_upload_evidence）
hss_service_orders	旧交易链（套餐、支付）	⚠️ 仍由前端直接 INSERT/SELECT（旧链路）
hss_service_assignments	旧派单链	❌ 前端不再直接写入
hss_service_order_status_logs	旧状态日志	❌ 前端不再直接写入

---

5. 建议的后端实现顺序

1. P0-2 rpc_payment_callback_activate_care_task：在支付成功回调或支付页面调用，自动根据 hss_service_orders 创建 ec_service_requests + ec_care_tasks，并触发后端调度。
2. P0-1 rpc_consumer_create_homecare_task：如果需要在支付前创建工单（如非套餐单），提供此 RPC。
3. P1-1 / P1-2 消费者验收 RPC：解除前端拦截，让用户可以正常完成验收流程。
4. P2-1 ~ P2-4 Admin 管理 RPC：补齐后台评估、计划、整改、归档功能。

---

6. 相关文件索引

文件	说明
mall_sql/migrations/20260526_delivery_homecare_rpc_v1.sql	已实现的 delivery RPC（ accept/reject/depart/arrive/checkin/start/save/finish/exception ）
mall_sql/migrations/20260601_hss_auto_dispatch_rpc_v2.sql	旧派单 RPC rpc_homecare_auto_dispatch（仅操作 hss_*，不应作为新链入口）
医疗-delivery/api/delivery.uts	Delivery 端 API 层，已全量切换 RPC-first
医疗-consumer/api/delivery.uts	Consumer 端 API 层，已全量切换 RPC-first
医疗-delivery/services/homeServiceService.uts	Home Service 服务层，worker 动作已切 RPC，admin 动作已设安全门
医疗-consumer/services/homeServiceService.uts	同上（consumer 端镜像）
医疗-consumer/services/serviceOrderService.uts	Consumer 订单服务，care task 路径已设安全门，legacy 路径保留
医疗-delivery/services/serviceOrderService.uts	Delivery 订单服务，tryCreateCareTask 有过渡保护
医疗-delivery/utils/homecare.constants.ts	统一状态常量 ORDER_* 与 isCareTask() 辅助函数