From ff968766b87b84a9a65bbe745b12094119e78165 Mon Sep 17 00:00:00 2001 From: liuyun Date: Thu, 15 Oct 2026 01:19:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(openspec):=20C4=20=E8=B4=A8=E6=8E=A7?= =?UTF-8?q?=E9=97=B8=E9=97=A8=20change=20=E6=8F=90=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- openspec/changes/svc-org-c4-qc/.openspec.yaml | 2 + openspec/changes/svc-org-c4-qc/design.md | 38 ++++++++++++ openspec/changes/svc-org-c4-qc/proposal.md | 32 ++++++++++ .../svc-org-c4-qc/specs/backend/qc/spec.md | 58 +++++++++++++++++++ .../specs/frontend/ad/qc/spec.md | 26 +++++++++ .../specs/shared/api-contract/spec.md | 19 ++++++ .../specs/shared/data-model/spec.md | 15 +++++ openspec/changes/svc-org-c4-qc/tasks.md | 30 ++++++++++ 8 files changed, 220 insertions(+) create mode 100644 openspec/changes/svc-org-c4-qc/.openspec.yaml create mode 100644 openspec/changes/svc-org-c4-qc/design.md create mode 100644 openspec/changes/svc-org-c4-qc/proposal.md create mode 100644 openspec/changes/svc-org-c4-qc/specs/backend/qc/spec.md create mode 100644 openspec/changes/svc-org-c4-qc/specs/frontend/ad/qc/spec.md create mode 100644 openspec/changes/svc-org-c4-qc/specs/shared/api-contract/spec.md create mode 100644 openspec/changes/svc-org-c4-qc/specs/shared/data-model/spec.md create mode 100644 openspec/changes/svc-org-c4-qc/tasks.md diff --git a/openspec/changes/svc-org-c4-qc/.openspec.yaml b/openspec/changes/svc-org-c4-qc/.openspec.yaml new file mode 100644 index 0000000..a216797 --- /dev/null +++ b/openspec/changes/svc-org-c4-qc/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-15 diff --git a/openspec/changes/svc-org-c4-qc/design.md b/openspec/changes/svc-org-c4-qc/design.md new file mode 100644 index 0000000..6c759ac --- /dev/null +++ b/openspec/changes/svc-org-c4-qc/design.md @@ -0,0 +1,38 @@ +## Context + +C3 已有 ho_record（submitted）、abnormal（handle_status）、C2 的 plan.change、C1 的 elder。C4 新增质控闸门，纯新增、不侵入脚手架。设计背景见 `docs/superpowers/specs/2026-10-15-服务机构端-C4质控闸门-design.md`。 + +## Goals / Non-Goals + +**Goals:** qc + ho_record_correction 两表、全量质控（定时任务）、放行/退回（4001 自审自放行）、五类推送聚合、异常联动改计划、补正、admin 质控中心页。 + +**Non-Goals:** 上报池（二期）、真推送（APP 期）、APP 补正录入、家属端。 + +## Decisions + +1. **表命名**：`qc`（无前缀）、`ho_record_correction`（补正属留痕域 ho_）。 +2. **全量质控**：`@Cron` 每小时扫描 submitted 无 qc → 生成 qc（pending）。 +3. **qc 生命周期**：pending → passed/returned；退回补正后 recheck（first_qc_id）。 +4. **放行自检**：四要素(1004) → 必拍(3001) → 幂等 → 非自审(4001)。 +5. **五类推送** = pending/list 跨表聚合（异常/逾期/住院/计划/待质控），带消除条件。 +6. **异常联动改计划**：复用 plan.change + link_plan_change。 +7. **补正**：ho_record_correction 新增说明，不改原记录；≥3 次进质控重点。 +8. **批量放行**：排除异常/未执行项/临时加项/时长异常/补正过。 + +## 数据模型 + +qc（id/tenant_code/record_id/qc_type/qc_result/qc_note/qc_staff_id/qc_time/pass_time/first_qc_id，SOFT_DELETE）、ho_record_correction（id/tenant_code/record_id/qc_id/correction_note/corrected_by/corrected_at，子表不入 SOFT_DELETE）。UUID v7、@map snake_case、utf8mb4_general_ci。 + +## 接口 + +qc：GET /qc/pending/list、GET /qc/detail、POST /qc/pass、POST /qc/return、POST /qc/exception/link、POST /qc/correct、POST /qc/batch-pass。权限码 qc.*；错误码域 46；规则号 1004/3001/4001 写 message。 + +## Risks / Trade-offs + +- 定时任务延迟（≤1h）→ 可后续改 checkout 同步。 +- 补正=新增说明（不可无痕修改）→ 合规。 +- 自审自放行 4001 → 单人机构必须再配审的人（PRD 底线）。 + +## Migration Plan + +新增 2 表（utf8mb4_general_ci 手改）。迁移链损坏：migrate diff + 手工目录 + deploy。 diff --git a/openspec/changes/svc-org-c4-qc/proposal.md b/openspec/changes/svc-org-c4-qc/proposal.md new file mode 100644 index 0000000..1280907 --- /dev/null +++ b/openspec/changes/svc-org-c4-qc/proposal.md @@ -0,0 +1,32 @@ +## Why + +C3 已落地履约留痕（ho_record 四表，record_status=submitted）+ 异常上报。C4 交付 PRD 第四块「质控闸门」：对每条已提交留痕做全量质控（放行/退回，禁止自审自放行）、五类主动推送聚合、异常处理台 + 异常联动改计划、补正。这是「先质控再上报」铁律的代码落地。 + +## What Changes + +- 新增 `qc` 表（质控记录）+ `ho_record_correction` 表（补正说明）。 +- 全量质控：定时任务扫描 `submitted` 留痕生成 qc 记录（非抽检）。 +- 放行/退回：放行前按序自检（四要素 1004 → 必拍 3001 → 幂等 → 放行人≠录入人 4001）；退回必填原因；批量放行排除异常/未执行项/临时加项/时长异常/补正过。 +- 五类主动推送：后台聚合（异常待处理/逾期未做/住院仍有派单/计划未制定/留痕待放行），每类带消除条件。 +- 异常处理台 + 异常联动改计划（复用 plan.change + link_plan_change）。 +- 补正：原记录保留 + 新增更正说明（ho_record_correction），不可补正签到时间/定位/照片。 +- 前端「质控中心」页（B4）。 + +## Capabilities + +### New Capabilities + +- `backend/qc`: 全量质控生成、放行/退回/4001 自检、五类推送聚合、异常联动改计划、补正。 +- `frontend/ad/qc`: admin 质控中心页（待我处理/待放行队列/异常处理台）。 + +### Modified Capabilities + +- `shared/data-model`: 新增 `qc` + `ho_record_correction` 两实体。 +- `shared/api-contract`: 新增 qc 接口（pending-list/detail/pass/return/exception-link/correct/batch-pass）。 + +## Impact + +- 后端 ec-nest：新增 qc 模块（纯新增），依赖 record/abnormal/plan/order/elder 模块。 +- 前端 ec-admin：质控中心页（替换 qc 占位）。 +- 数据：新增 2 张表（迁移，utf8mb4_general_ci）。 +- 依赖：C3 的 record（submitted）、abnormal、C2 的 plan.change、C1 的 elder。 diff --git a/openspec/changes/svc-org-c4-qc/specs/backend/qc/spec.md b/openspec/changes/svc-org-c4-qc/specs/backend/qc/spec.md new file mode 100644 index 0000000..0042e32 --- /dev/null +++ b/openspec/changes/svc-org-c4-qc/specs/backend/qc/spec.md @@ -0,0 +1,58 @@ +## Purpose + +定义服务机构端质控闸门的后端行为——全量质控、放行/退回（自审自放行 4001）、五类推送聚合、异常联动改计划、补正。 + +## ADDED Requirements + +### Requirement: 全量质控生成 +定时任务 MUST 扫描 `record_status='submitted'` 且无 qc 记录的留痕 → 生成 qc（qc_result=pending）。非抽检。 + +#### Scenario: 兜底生成 +- **WHEN** 一条留痕 submitted 后无 qc +- **THEN** 定时任务为其生成 qc 记录 + +### Requirement: 放行 +`POST /qc/pass` MUST 按序校验：① 四要素齐（时间/项目/时长/护理员，否则 1004）→ ② 必拍已拍（3001）→ ③ 状态=待质控（幂等）→ ④ **放行人 ≠ 录入人**（4001 自审自放行）；通过则 qc_result=passed + pass_time。 + +#### Scenario: 自审自放行拒绝 +- **WHEN** 放行人 = 该记录的录入人 +- **THEN** 返回 4001 拒绝 + +#### Scenario: 缺要素拒绝 +- **WHEN** 留痕缺必填要素 +- **THEN** 返回 1004 拒绝 + +### Requirement: 退回 +`POST /qc/return` MUST qc_note 必填 → qc_result=returned；退回后护理员可补正。 + +#### Scenario: 退回需原因 +- **WHEN** 退回缺 qc_note +- **THEN** 拒绝 + +### Requirement: 五类主动推送聚合 +`GET /qc/pending/list` MUST 聚合五类：异常待处理(abnormal.handle_status=open)、逾期未做(order 过时段无 record 超 24h)、住院仍有派单(elder.treat_status=hosp_pause 且有未完成 order)、计划未制定(待遇生效 5 工作日无 active plan)、留痕待放行(qc pending)；每类带消除条件。 + +#### Scenario: 逾期未做 +- **WHEN** 工单过时段超 24h 仍无 record +- **THEN** 出现在「逾期未做」待办 + +### Requirement: 异常处理与联动改计划 +`POST /qc/exception/link` MUST 复用 plan.change 生成新 plan + 回填 record_abnormal.link_plan_change=true。 + +#### Scenario: 异常联动改计划 +- **WHEN** 质控员判断异常需加专项 +- **THEN** 生成新计划并回填 link_plan_change + +### Requirement: 补正 +`POST /qc/correct` MUST 写 ho_record_correction（correction_note）+ record 重新 submitted（触发 recheck）；不可补正签到时间/定位/照片；同记录补正 ≥3 次 ⇒ 进质控重点。 + +#### Scenario: 补正不改原值 +- **WHEN** 补正一条留痕 +- **THEN** 原记录不动，新增更正说明，record 重新进质控 + +### Requirement: 批量放行 +`POST /qc/batch-pass` MUST 排除有异常/未执行项/临时加项/时长异常/补正过的记录。 + +#### Scenario: 批量安全边界 +- **WHEN** 批量放行含异常记录 +- **THEN** 拒绝（必须逐条看） diff --git a/openspec/changes/svc-org-c4-qc/specs/frontend/ad/qc/spec.md b/openspec/changes/svc-org-c4-qc/specs/frontend/ad/qc/spec.md new file mode 100644 index 0000000..f5b6d6c --- /dev/null +++ b/openspec/changes/svc-org-c4-qc/specs/frontend/ad/qc/spec.md @@ -0,0 +1,26 @@ +## Purpose + +定义服务机构端「质控中心」页面的交互。 + +## ADDED Requirements + +### Requirement: 质控中心页 +admin「质控中心」页 MUST 提供三区：① 待我处理（五类主动推送聚合 + 计数）② 待放行队列（逐条放行/退回）③ 异常处理台（处理/转派/关闭 + 处理意见）。 + +#### Scenario: 查看待办 +- **WHEN** 质控员打开质控中心 +- **THEN** 看到五类待办计数 + 待放行队列 + 异常处理台 + +### Requirement: 放行与退回 +放行 MUST 一键；退回 MUST 选原因（下拉）；批量放行 MUST 排除异常/未执行项记录。 + +#### Scenario: 放行 +- **WHEN** 质控员点放行 +- **THEN** 记录转 passed，从待放行队列消失 + +### Requirement: 异常处理 +质控员 MUST 能对异常记录处理/转派/关闭并附处理意见；判断需加专项时 MUST 能联动到计划变更。 + +#### Scenario: 联动改计划 +- **WHEN** 质控员对异常选「联动改计划」 +- **THEN** 生成新计划并回填 link_plan_change diff --git a/openspec/changes/svc-org-c4-qc/specs/shared/api-contract/spec.md b/openspec/changes/svc-org-c4-qc/specs/shared/api-contract/spec.md new file mode 100644 index 0000000..13270fc --- /dev/null +++ b/openspec/changes/svc-org-c4-qc/specs/shared/api-contract/spec.md @@ -0,0 +1,19 @@ +## ADDED Requirements + +### Requirement: 质控接口 +`GET /qc/pending/list`、`GET /qc/detail`、`POST /qc/pass`、`POST /qc/return`、`POST /qc/exception/link`、`POST /qc/correct`、`POST /qc/batch-pass` MUST 存在，遵循统一响应。 + +#### Scenario: 放行前自检 +- **WHEN** 放行一条留痕 +- **THEN** 按序校验四要素(1004)/必拍(3001)/幂等/非自审(4001)，任一不过拒绝 + +#### Scenario: 退回必填原因 +- **WHEN** 退回留痕缺 qc_note +- **THEN** 拒绝 + +### Requirement: 五类主动推送 +`GET /qc/pending/list` MUST 聚合五类待办：异常待处理、逾期未做(>24h)、住院仍有派单、计划未制定(5 工作日)、留痕待放行，每类带消除条件。 + +#### Scenario: 消除条件 +- **WHEN** 某类待办已处理 +- **THEN** 该类从待办列表消除 diff --git a/openspec/changes/svc-org-c4-qc/specs/shared/data-model/spec.md b/openspec/changes/svc-org-c4-qc/specs/shared/data-model/spec.md new file mode 100644 index 0000000..f71949e --- /dev/null +++ b/openspec/changes/svc-org-c4-qc/specs/shared/data-model/spec.md @@ -0,0 +1,15 @@ +## ADDED Requirements + +### Requirement: 质控记录实体 qc +`qc` 表 MUST 存在（record_id、qc_type、push_reason、qc_result、qc_note、qc_staff_id、qc_time、pass_time、first_qc_id）。`qc_result` MUST ∈ {pending, passed, returned}；退回时 `qc_note` 必填；recheck 时 `first_qc_id` 指向首次 qc。 + +#### Scenario: 全量生成 +- **WHEN** 一条留痕 submitted 且无 qc 记录 +- **THEN** 定时任务生成一条 qc（qc_result=pending） + +### Requirement: 补正实体 ho_record_correction +`ho_record_correction` 表 MUST 存在（record_id、qc_id、correction_note、corrected_by、corrected_at）。补正 MUST 新增说明、不直接改原记录。 + +#### Scenario: 补正留痕 +- **WHEN** 退回后护理员补正 +- **THEN** 写一条更正说明，原记录保留不动 diff --git a/openspec/changes/svc-org-c4-qc/tasks.md b/openspec/changes/svc-org-c4-qc/tasks.md new file mode 100644 index 0000000..8aa8883 --- /dev/null +++ b/openspec/changes/svc-org-c4-qc/tasks.md @@ -0,0 +1,30 @@ +# Tasks — svc-org-c4-qc + +## 1. 数据层 + +- [ ] 1.1 `schema.prisma` 新增 `Qc`（表名 qc）+ `RecordCorrection`（表名 ho_record_correction）模型。 +- [ ] 1.2 `prisma.service.ts`：`Qc` 加入 SOFT_DELETE；`RecordCorrection` 子表不入。 +- [ ] 1.3 迁移 `c4_qc`（utf8mb4_general_ci，migrate diff + deploy）+ `prisma generate`。 + +## 2. 权限码 + 错误码 + APIS + +- [ ] 2.1 `permissions.ts` 新增 `qc.*`（pendingList/detail/pass/return/exceptionLink/correct/batchPass）。 +- [ ] 2.2 `error-codes.ts` 补域 46：QC_NOT_FOUND、QC_ALREADY_HANDLED、QC_SELF_REVIEW(4001)、QC_ELEMENT_MISSING(1004)、QC_NOTE_REQUIRED、QC_BATCH_UNSAFE 等。 +- [ ] 2.3 `tenant-template.ts` APIS 登记 qc 接口资源（parent 'qc'）。 + +## 3. qc 模块（全量质控 + 放行/退回 + 五类推送 + 异常联动 + 补正） + +- [ ] 3.1 `src/qc/` 模块：定时任务（@Cron）全量生成 qc；pass（自检 1004/3001/幂等/4001）；return（qc_note 必填）；pending-list（五类聚合）；detail；exception-link（plan.change + link_plan_change）；correct（补正 + 重新 submitted + ≥3 次进重点）；batch-pass（排除异常等）。 +- [ ] 3.2 TDD：全量生成、放行自检四步、4001 自审、退回必填原因、五类聚合各消除条件、联动改计划、补正不改原值、批量安全边界；`pnpm test` + `tsc --noEmit`。 + +## 4. 前端 + +- [ ] 4.1 `src/api/qc.ts`。 +- [ ] 4.2 质控中心页（`ltc/qc`）：待我处理（五类聚合）+ 待放行队列（放行/退回/批量）+ 异常处理台（处理/联动改计划）。 +- [ ] 4.3 `pnpm type-check` 通过。 + +## 5. 验证 + +- [ ] 5.1 冒烟：submitted 留痕 → 定时任务生成 qc → 放行（4001 自审拒/通过）→ 退回（补正）→ recheck → 放行。 +- [ ] 5.2 五类推送：异常/逾期/住院/计划/待放行各出现与消除。 +- [ ] 5.3 异常联动改计划生成新 plan + link_plan_change；审计落库。