docs(openspec): C5 后台配置与文书补齐 change 提案

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/superpowers/specs/2026-10-15-服务机构端-C5后台配置与文书补齐-design.md

@@ -0,0 +1,51 @@
+# 服务机构端 C5 后台配置与文书补齐 · 设计文档
+
+> 本文是 C5 的设计背景，规范权威见 `openspec/changes/svc-org-c5-config/`（proposal + specs + design + tasks）与 PRD §5.6 B7 / §5.7 B8。
+
+## Context
+
+C0–C4 已落地 P0 四块主线（待遇档案/派单工单/履约留痕/质控闸门）。但 admin 后台「服务机构设置」的 6 个子菜单（机构信息/属地与目录/服务项目与配价/拍照分档配置/质控提醒配置/对接档位）+「文书档案」7 个菜单一直是占位符（C0 只建了 agency/catalog/staff 后端 + 前端 API 文件，页面未落地）。C5 补齐这 7 个空菜单。
+
+## Goals / Non-Goals
+
+**Goals**：7 个空菜单补全——3 个纯前端页（机构信息/属地与目录/服务项目与配价）+ 3 个配置页（拍照分档/质控提醒/对接档位，需小后端）+ 文书档案页（一人一档导出）。
+
+**Non-Goals**：电子签章、公文流转、模板自定义（PRD 明确留二期）；精确「国家 2026 版文书」版式（模板不在仓库，属地采纳权在医保，N4 待核）；账号与权限页（复用脚手架用户/角色管理，不新增菜单）。
+
+## Decisions
+
+1. **拍照分档落点**：`svc_org` 加 `photo_tier`（`must`/`free`/`optional`），默认 seed 按 PRD 分档表（沐浴/转移/导管类/鼻饲喂食/压疮=must；翻身/喂饭/陪伴/剪指甲/整理床铺/口腔/更衣等日常=free；擦身/如厕/失禁=optional）。机构可批量改（加严提示、不建议放宽）。plan/order 的 photo_required 仍从 item_list 快照推导，plan 创建时 photo_tier 默认取 svc_org.photo_tier。
+2. **机构配置落点**：`ltc_agency` 加 `qc_threshold`（int 小时，默认 24）、`docking_tier`（`A`/`B`/`C`，默认 B，C 显示「待接口发布」）、`new_national_notify`（bool 默认 true）。复用 agency.update。
+3. **文书导出**：P0 做结构化导出（一人一档：基本信息 + 服务计划 + 全部服务记录 + 异常记录），按老人/时间检索；带水印（机构名 + 时间 + 操作人）+ 审计落库。格式用 Excel（引入轻量库）或 CSV，精确国家版式后置。措辞纪律：界面只写「日常留痕，随时可导出」，禁用「迎检/应对巡查」等表述。
+4. **主键/表命名**：svc_org 加字段（已有表，改迁移）；ltc_agency 加字段（已有表）；无新表。
+
+## 数据模型（DDL 概览，均改现有表）
+
+- **svc_org**：加 `photo_tier VARCHAR(10) DEFAULT 'free'`（must/free/optional）。迁移。
+- **ltc_agency**：加 `qc_threshold INT DEFAULT 24`、`docking_tier VARCHAR(10) DEFAULT 'B'`、`new_national_notify BOOLEAN DEFAULT true`。迁移。
+
+## 接口
+
+- `POST /svc/org/photo-tier/batch` — 批量更新 L4 项目 photo_tier（机构加严提示）。
+- `PATCH /agency` — 扩展：qc_threshold/docking_tier/new_national_notify（复用 C0 agency.update）。
+- `GET /document/export?elderId=&startDate=&endDate=` — 一人一档导出（Excel/CSV，带水印），写审计。
+
+## 前端 7 页
+
+1. 机构信息（form：名称/地址/法人/联系方式/参保地只读 + 质控阈值/对接档位/新增项开关）。
+2. 属地与目录（只读列表：L1 国家库/L2 属地库/L4 机构项目 + 新增项提示开关）。
+3. 服务项目与配价（L4 勾选 + 配价，复用 svc_org config）。
+4. 拍照分档配置（L4 项目列表 → 批量改 tier，放宽提示）。
+5. 质控提醒配置（阈值编辑）。
+6. 对接档位（档位显示 + 切换 A/B，C 显示待接口发布）。
+7. 文书档案（老人档案查看 + 按老人/时间导出）。
+
+## Risks / Trade-offs
+
+- [文书版式后置] → 结构化导出先落地，国家版式拿到官方模板再接（N4 已注）。
+- [photo_tier 溯源] → svc_org 为源，plan/order 快照，不反向改历史快照。
+- [导出数据量] → 按老人/时间过滤 + 分页，避免全表导出卡死。
+
+## Migration Plan
+
+改 2 张现有表（svc_org + ltc_agency 各加字段）。utf8mb4_general_ci 手改。迁移链损坏：migrate diff + 手工目录 + deploy。

openspec/changes/svc-org-c5-config/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-15

openspec/changes/svc-org-c5-config/design.md

@@ -0,0 +1,31 @@
+## Context
+
+C0–C4 已落地 P0 四块主线。C5 补齐后台 7 个空菜单（服务机构设置 6 子项 + 文书档案）。纯配置 + 前端 + 文书导出，无新表（改 svc_org/ltc_agency 加字段）。
+
+## Goals / Non-Goals
+
+**Goals:** 拍照分档批量改、机构配置（阈值/档位/开关）、文书一人一档导出、7 个前端页。
+
+**Non-Goals:** 电子签章/公文流转/模板自定义（二期）、精确国家 2026 版式（模板后置）、账号与权限页（复用脚手架）。
+
+## Decisions
+
+1. photo_tier 落 svc_org（源），plan/order 快照溯源。
+2. qc_threshold/docking_tier/new_national_notify 落 ltc_agency。
+3. 文书导出用 Excel/CSV（结构化），带水印 + 审计；精确版式后置。
+
+## 数据模型
+
+svc_org + photo_tier；ltc_agency + qc_threshold/docking_tier/new_national_notify。迁移改 2 表。
+
+## 接口
+
+POST /svc/org/photo-tier/batch、PATCH /agency（扩展）、GET /document/export。
+
+## Risks
+
+文书版式后置；photo_tier 溯源不改历史快照；导出按老人/时间过滤防卡死。
+
+## Migration Plan
+
+改 2 表加字段（utf8mb4_general_ci）。迁移链损坏：migrate diff + 手工 + deploy。

openspec/changes/svc-org-c5-config/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+C0–C4 已落地 P0 四块主线，但 admin 后台「服务机构设置」6 个子菜单 + 「文书档案」7 个菜单一直是占位符（C0 只建了 agency/catalog/staff 后端 + API 文件，页面未落地）。C5 补齐这 7 个空菜单。
+
+## What Changes
+
+- `svc_org` 加 `photo_tier`（must/free/optional，默认 seed 按 PRD 分档表）；`ltc_agency` 加 `qc_threshold`/`docking_tier`/`new_national_notify`。
+- 拍照分档配置：批量更新 L4 项目 photo_tier（加严提示、不建议放宽）；plan/order photo_required 快照溯源到 svc_org.photo_tier。
+- 质控提醒配置（阈值）、对接档位（A/B/C，C 预留）、国家新增项提示开关。
+- 文书档案（B7 精简版）：一人一档（基本信息+计划+服务记录+异常），按老人/时间导出，带水印 + 审计。
+- 前端 7 页：机构信息/属地与目录/服务项目与配价/拍照分档配置/质控提醒配置/对接档位/文书档案。
+
+## Capabilities
+
+### New Capabilities
+
+- `backend/config`: 机构配置（qc_threshold/docking_tier/new_national_notify）+ 拍照分档批量改 + 文书导出。
+- `frontend/ad/config`: 后台 7 个配置/文书页。
+
+### Modified Capabilities
+
+- `shared/data-model`: `svc_org` 加 photo_tier；`ltc_agency` 加 3 个配置字段。
+- `shared/api-contract`: 新增 photo-tier 批量更新、agency 配置扩展、文书导出接口。
+
+## Impact
+
+- 后端 ec-nest：agency/catalog 模块扩展 + document 导出（纯新增逻辑）。
+- 前端 ec-admin：7 个页面（替换占位）。
+- 数据：2 张表加字段（迁移，utf8mb4_general_ci）。
+- 依赖：C0 的 agency/catalog/staff、C2/C3 的 photo_required 快照。

openspec/changes/svc-org-c5-config/specs/backend/config/spec.md

@@ -0,0 +1,26 @@
+## Purpose
+
+定义服务机构端后台配置与文书导出的后端行为——拍照分档批量改、机构配置、文书一人一档导出。
+
+## ADDED Requirements
+
+### Requirement: 拍照分档批量改
+`POST /svc/org/photo-tier/batch` MUST 批量更新本机构 L4 项目的 photo_tier（must/free/optional）；放宽（must→free/optional）时返回提示。plan/order 的 photo_required MUST 快照溯源到 svc_org.photo_tier。
+
+#### Scenario: 批量改分档
+- **WHEN** 机构批量把若干项目从 free 改为 must
+- **THEN** svc_org.photo_tier 更新，后续计划快照生效
+
+### Requirement: 机构配置
+`PATCH /agency` MUST 支持 qc_threshold（小时）、docking_tier（A/B/C）、new_national_notify（bool）。
+
+#### Scenario: 改质控阈值
+- **WHEN** 机构把质控提醒阈值改为 48 小时
+- **THEN** agency.qc_threshold=48
+
+### Requirement: 文书一人一档导出
+`GET /document/export` MUST 按老人/时间导出（基本信息 + 服务计划 + 全部服务记录 + 异常记录），带水印（机构名+时间+操作人）并写审计。
+
+#### Scenario: 按老人导出
+- **WHEN** 质控员按老人导出文书
+- **THEN** 生成一人一档文件（含水印），审计落库

openspec/changes/svc-org-c5-config/specs/frontend/ad/config/spec.md

@@ -0,0 +1,19 @@
+## Purpose
+
+定义服务机构端后台 7 个配置/文书页面的交互。
+
+## ADDED Requirements
+
+### Requirement: 服务机构设置六页
+「服务机构设置」MUST 提供：机构信息（表单）、属地与目录（只读列表+新增项开关）、服务项目与配价（L4 勾选+配价）、拍照分档配置（批量改 tier，放宽提示）、质控提醒配置（阈值）、对接档位（A/B 显示，C 待接口发布）。
+
+#### Scenario: 批量改分档
+- **WHEN** 机构在拍照分档配置页批量调整
+- **THEN** L4 项目 photo_tier 批量更新
+
+### Requirement: 文书档案页
+「文书档案」MUST 提供一人一档查看 + 按老人/时间导出；界面措辞只用「日常留痕，随时可导出」。
+
+#### Scenario: 导出文书
+- **WHEN** 质控员按老人导出
+- **THEN** 下载一人一档文件（含水印）

openspec/changes/svc-org-c5-config/specs/shared/api-contract/spec.md

@@ -0,0 +1,12 @@
+## ADDED Requirements
+
+### Requirement: 配置与文书接口
+`POST /svc/org/photo-tier/batch`、`PATCH /agency`（扩展 qc_threshold/docking_tier/new_national_notify）、`GET /document/export` MUST 存在，遵循统一响应。
+
+#### Scenario: 批量改分档
+- **WHEN** 机构批量更新 L4 项目 photo_tier
+- **THEN** 返回更新后的项目列表
+
+#### Scenario: 文书导出
+- **WHEN** 按老人/时间导出文书
+- **THEN** 返回一人一档（基本信息+计划+服务记录+异常），带水印

openspec/changes/svc-org-c5-config/specs/shared/data-model/spec.md

@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: svc_org 增加 photo_tier
+`svc_org` 表 MUST 增加 `photo_tier`（VARCHAR(10)，must/free/optional，默认 free）。默认分档 seed：沐浴/转移/导管类/鼻饲喂食/压疮=must；日常照护项=free；擦身/如厕/失禁=optional。
+
+#### Scenario: 机构调整分档
+- **WHEN** 机构批量调整 L4 项目 photo_tier
+- **THEN** svc_org.photo_tier 更新，plan/order 快照溯源
+
+### Requirement: ltc_agency 增加机构配置
+`ltc_agency` 表 MUST 增加 `qc_threshold`（int 默认 24 小时）、`docking_tier`（A/B/C 默认 B）、`new_national_notify`（bool 默认 true）。
+
+#### Scenario: 配置质控阈值
+- **WHEN** 机构改质控提醒阈值
+- **THEN** agency.qc_threshold 更新

openspec/changes/svc-org-c5-config/tasks.md

@@ -0,0 +1,28 @@
+# Tasks — svc-org-c5-config
+
+## 1. 数据层
+
+- [ ] 1.1 `schema.prisma`：`SvcOrg` 加 `photoTier`（默认 free）；`Agency` 加 `qcThreshold`/`dockingTier`/`newNationalNotify`。
+- [ ] 1.2 迁移 `c5_config`（utf8mb4_general_ci，migrate diff + deploy）+ `prisma generate`；seed 默认 photo_tier 分档表。
+
+## 2. 后端
+
+- [ ] 2.1 svc_org photo_tier 批量更新（`POST /svc/org/photo-tier/batch`）+ 放宽提示。
+- [ ] 2.2 agency.update 扩展 qc_threshold/docking_tier/new_national_notify。
+- [ ] 2.3 文书导出 `GET /document/export`（一人一档 Excel/CSV + 水印 + 审计）。
+- [ ] 2.4 TDD + `pnpm test` + `tsc --noEmit`。
+
+## 3. 前端
+
+- [ ] 3.1 机构信息页（form + 阈值/档位/开关）。
+- [ ] 3.2 属地与目录页（只读列表 + 开关）。
+- [ ] 3.3 服务项目与配价页（L4 勾选 + 配价）。
+- [ ] 3.4 拍照分档配置页（批量改 tier + 放宽提示）。
+- [ ] 3.5 质控提醒配置页 + 对接档位页。
+- [ ] 3.6 文书档案页（一人一档 + 导出）。
+- [ ] 3.7 `pnpm type-check` 通过。
+
+## 4. 验证
+
+- [ ] 4.1 冒烟：7 个页面可访问；photo_tier 批量改生效；文书导出落库 + 水印 + 审计。
+- [ ] 4.2 停后端清理。