# 居家服务（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()` 辅助函数 |