# 服务机构端 C1 待遇档案 实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在 C0 骨架上落地「待遇档案」域：老人档案（elder）+ 十态状态机 + 状态日志（elder_status_log）+ 评估结论副本上传（MinIO）+ 身份证掩码/防重。

**Architecture:** 纯新增，不侵入脚手架。后端新增 elder 模块 + storage 模块（MinIO），前端「服务对象」页面。复用 C0 的多租户过滤、RBAC、审计、目录、菜单。

**Tech Stack:** NestJS 12 + Prisma 6 + MySQL 8（utf8mb4_general_ci）、Vue 3 + Vite + Pinia + UnoCSS、MinIO（minio npm 包）。

**Spec:** `openspec/changes/svc-org-c1-elder/`（proposal + specs + design + tasks）；设计背景 `docs/superpowers/specs/2026-10-14-服务机构端-C1待遇档案-design.md`。

## Global Constraints

- 机构=租户：业务表带 `tenant_code`，继承 PrismaService 多租户过滤；主键 UUID v7；列 snake_case（camelCase + `@map`）；软删 `deleted_at`。
- 字符集硬要求：新表 `utf8mb4_general_ci`（迁移 SQL 手改，不得残留 `utf8mb4_unicode_ci`）。
- 等级唯一来源：建档不接受前端传 `assess_level/care_level`；`assess_level/care_level` 与 `assess_evidence_file` 绑定（有副本才能填等级）。
- 身份证掩码在服务端（`maskIdCard`），列表不返回明文；明文仅 admin/qc + 落审计。
- `id_card_no` 存储层加密后置（存明文 + TODO），掩码/查看留痕本期做。
- 不动脚手架现有文件；业务代码落新目录（`src/elder/`、`src/storage/`、`src/pages/ltc/elder/`）。
- 权限码 `elder:list/create/detail/status-change`（C0 已预留）；错误码域 43。

## Review Focus

1. 等级绑定绕过：有等级但无 `assess_evidence_file`（或反之）→ 建档必须被拒。
2. 身份证掩码泄露：`/elder` 列表返回明文 id_card_no → 必须返回掩码。
3. 明文查看无留痕：admin/qc 调 `/elder/:id` 拿明文却没落审计 → 必须落审计。
4. 状态变更缺 `change_reason` → 必须拒绝，且不写日志。
5. 建档初始状态判定错：等待期（benefit_start 未来）被置成 active → 必须置 waiting_period。

---

### Task 1: Prisma 模型 + 迁移

**Files:**
- Modify: `sources/ec-nest/prisma/schema.prisma`（追加 Elder、ElderStatusLog）
- Modify: `sources/ec-nest/src/prisma/prisma.service.ts`（SOFT_DELETE 加 `Elder`）

**Interfaces:**
- Produces: Prisma 模型 `Elder`、`ElderStatusLog`。

- [ ] **Step 1: 追加 Elder + ElderStatusLog 模型**（schema.prisma 末尾）

```prisma
/// 老人档案
model Elder {
  id                  String    @id @default(uuid(7)) @db.VarChar(36)
  tenantCode          String    @map("tenant_code") @db.VarChar(64)
  locCode             String    @map("loc_code") @db.VarChar(12)
  prevLocCode         String?   @map("prev_loc_code") @db.VarChar(12)
  transferConfirmAt   DateTime? @map("transfer_confirm_at")
  name                String    @db.VarChar(30)
  gender              String    @db.Char(1)
  birthDate           DateTime  @map("birth_date") @db.Date
  idCardNo            String    @map("id_card_no") @db.VarChar(255)
  phone               String?   @db.VarChar(15)
  address             String    @db.VarChar(200)
  guardianName        String?   @map("guardian_name") @db.VarChar(30)
  guardianPhone       String?   @map("guardian_phone") @db.VarChar(15)
  insurNo             String    @map("insur_no") @db.VarChar(30)
  insurType           String    @map("insur_type") @db.VarChar(10)
  insurYears          Int?      @map("insur_years")
  insurVerifyStatus   String?   @map("insur_verify_status") @db.VarChar(20)
  insurVerifyDate     DateTime? @map("insur_verify_date") @db.Date
  assessLevel         String?   @map("assess_level") @db.VarChar(20)
  careLevel           String?   @map("care_level") @db.VarChar(20)
  assessDate          DateTime? @map("assess_date") @db.Date
  assessOrg           String?   @map("assess_org") @db.VarChar(100)
  assessEvidenceFile  String?   @map("assess_evidence_file") @db.VarChar(255)
  benefitStart        DateTime? @map("benefit_start") @db.Date
  benefitEnd          DateTime? @map("benefit_end") @db.Date
  treatStatus         String    @default("pending_file") @map("treat_status") @db.VarChar(20)
  statusSource        String    @default("manual") @map("status_source") @db.VarChar(10)
  statusChangeDate    DateTime? @map("status_change_date") @db.Date
  hospStart           DateTime? @map("hosp_start") @db.Date
  hospEnd             DateTime? @map("hosp_end") @db.Date
  photoTierOverride   Json?     @map("photo_tier_override")
  needAssess          Json?     @map("need_assess")
  note                String?   @db.Text
  bizLine             String    @default("ltci") @map("biz_line") @db.VarChar(20)
  createdAt           DateTime  @default(now()) @map("created_at")
  createdBy           String?   @map("created_by") @db.VarChar(36)
  updatedAt           DateTime  @updatedAt @map("updated_at")
  deletedAt           DateTime? @map("deleted_at")

  @@unique([tenantCode, idCardNo])
  @@index([tenantCode, name])
  @@map("ltc_elder")
}

/// 待遇状态变更日志
model ElderStatusLog {
  id           String   @id @default(uuid(7)) @db.VarChar(36)
  elderId      String   @map("elder_id") @db.VarChar(36)
  tenantCode   String   @map("tenant_code") @db.VarChar(64)
  fromStatus   String   @map("from_status") @db.VarChar(20)
  toStatus     String   @map("to_status") @db.VarChar(20)
  changeReason String   @map("change_reason") @db.VarChar(200)
  source       String   @default("manual") @db.VarChar(10)
  operatorId   String   @map("operator_id") @db.VarChar(36)
  evidenceFile String?  @map("evidence_file") @db.VarChar(255)
  changedAt    DateTime @default(now()) @map("changed_at")

  @@index([elderId])
  @@map("ltc_elder_status_log")
}
```

- [ ] **Step 2: SOFT_DELETE 加 Elder**（prisma.service.ts 第 8 行集合）

```ts
const SOFT_DELETE = new Set([..., 'Elder', 'SvcOrg']);
```

- [ ] **Step 3: 迁移（utf8mb4_general_ci）**

Run: `cd sources/ec-nest && pnpm exec prisma migrate dev --create-only --name c1_elder`；编辑生成的 `*_c1_elder/migration.sql` 把 `utf8mb4_unicode_ci` 全改为 `utf8mb4_general_ci`；再 `pnpm exec prisma migrate deploy && pnpm exec prisma generate`。

- [ ] **Step 4: Commit**

```bash
git -C sources/ec-nest add prisma/schema.prisma prisma/migrations src/prisma/prisma.service.ts
git -C sources/ec-nest commit -m "feat(c1): elder + elder_status_log 数据模型"
```

---

### Task 2: 权限码 + 错误码 + APIS 资源

**Files:**
- Modify: `sources/ec-nest/src/common/permissions.ts`
- Modify: `sources/ec-nest/src/common/error-codes.ts`
- Modify: `sources/ec-nest/src/common/tenant-template.ts`（APIS）

**Interfaces:**
- Produces: `Permissions.elder.*`、`ErrorCodes.ELDER_*`、6 条 APIS 资源。

- [ ] **Step 1: 确认/补 permissions.ts 的 elder 权限码**（C0 已预留，确保存在 `elder.list/create/detail/status-change`；缺则补）

```ts
  elder: { list: 'elder:list', detail: 'elder:detail', create: 'elder:create', statusChange: 'elder:status-change' },
```

- [ ] **Step 2: 追加 elder 错误码**（error-codes.ts，域 43）

```ts
  // 服务机构端·老人档案（43）
  ELDER_NOT_FOUND: 43001,
  ELDER_ID_CARD_EXISTS: 43002,
  ELDER_STATUS_REASON_REQUIRED: 43003,
  ELDER_LEVEL_REQUIRES_EVIDENCE: 43004,
```

- [ ] **Step 3: APIS 登记 6 条 elder 接口**（tenant-template.ts APIS 数组，parent='elder'）

```ts
  { code: Permissions.elder.list, name: '老人列表', method: 'GET', path: '/api/v1/elder', parent: 'elder' },
  { code: Permissions.elder.create, name: '创建老人', method: 'POST', path: '/api/v1/elder', parent: 'elder' },
  { code: Permissions.elder.detail, name: '老人详情', method: 'GET', path: '/api/v1/elder/:id', parent: 'elder' },
  { code: Permissions.elder.statusChange, name: '变更待遇状态', method: 'POST', path: '/api/v1/elder/:id/status', parent: 'elder' },
  { code: Permissions.elder.detail, name: '状态日志', method: 'GET', path: '/api/v1/elder/:id/status/log', parent: 'elder' },
  { code: Permissions.elder.create, name: '上传评估结论', method: 'POST', path: '/api/v1/elder/assess-evidence', parent: 'elder' },
```

- [ ] **Step 4: tsc 校验 + Commit**

Run: `cd sources/ec-nest && pnpm exec tsc --noEmit`
```bash
git -C sources/ec-nest add src/common/permissions.ts src/common/error-codes.ts src/common/tenant-template.ts
git -C sources/ec-nest commit -m "feat(c1): elder 权限码/错误码/接口资源"
```

---

### Task 3: MinIO 存储模块

**Files:**
- Create: `sources/ec-nest/src/storage/storage.module.ts`、`storage.service.ts`
- Modify: `sources/ec-nest/src/app.module.ts`、`sources/ec-nest/.env`、`package.json`（依赖）

**Interfaces:**
- Produces: `StorageService.upload(buffer: Buffer, key: string): Promise<string>`（返回对象 key）；`StorageService.buildKey(tenantCode, filename): string`。

- [ ] **Step 1: 装依赖 + 配 .env**

```bash
cd sources/ec-nest && pnpm add minio
```
`.env` 追加：
```env
MINIO_ENDPOINT="localhost"
MINIO_PORT=9000
MINIO_ACCESS_KEY="minioadmin"
MINIO_SECRET_KEY="minioadmin"
MINIO_BUCKET="carelink"
```

- [ ] **Step 2: 写失败测试**（`src/storage/storage.service.spec.ts`——无参构造，测试时替换内部 client 为 mock，避免真实连接 MinIO）

```ts
import { describe, it, expect, vi } from 'vitest';
import { StorageService } from './storage.service.js';

describe('StorageService', () => {
  it('upload 写桶并返回 key', async () => {
    const putObject = vi.fn().mockResolvedValue({ etag: 'x' });
    const svc = new StorageService();
    (svc as any).client = { putObject };
    (svc as any).bucket = 'carelink';
    const key = await svc.upload(Buffer.from('x'), 'elder/evidence/a.jpg');
    expect(putObject).toHaveBeenCalledWith('carelink', 'elder/evidence/a.jpg', expect.any(Buffer), expect.any(Number));
    expect(key).toBe('elder/evidence/a.jpg');
  });

  it('buildKey 带租户前缀', () => {
    const svc = new StorageService();
    const key = svc.buildKey('T001', 'a.jpg');
    expect(key).toMatch(/^elder\/T001\/\d+-a\.jpg$/);
  });
});
```

- [ ] **Step 3: 跑测试确认失败**

Run: `cd sources/ec-nest && pnpm test -- storage`
Expected: FAIL（StorageService 不存在）

- [ ] **Step 4: 实现 storage.service.ts + module**

```ts
import { Injectable } from '@nestjs/common';
import { Client } from 'minio';

@Injectable()
export class StorageService {
  private readonly client: Client;
  private readonly bucket: string;

  constructor() {
    // new Client() 只是构造客户端对象、不建立连接；putObject 时才连。
    // 测试里直接替换 (svc as any).client / .bucket 为 mock。
    this.client = new Client({
      endPoint: process.env.MINIO_ENDPOINT ?? 'localhost',
      port: Number(process.env.MINIO_PORT ?? 9000),
      useSSL: false,
      accessKey: process.env.MINIO_ACCESS_KEY ?? 'minioadmin',
      secretKey: process.env.MINIO_SECRET_KEY ?? 'minioadmin',
    });
    this.bucket = process.env.MINIO_BUCKET ?? 'carelink';
  }

  buildKey(tenantCode: string, filename: string): string {
    return `elder/${tenantCode}/${Date.now()}-${filename}`;
  }

  async upload(buffer: Buffer, key: string): Promise<string> {
    await this.client.putObject(this.bucket, key, buffer, buffer.length);
    return key;
  }
}
```

（`StorageModule` 声明 provider 并 `exports`；`app.module.ts` imports 注册。）

- [ ] **Step 5: 跑测试确认通过**

Run: `cd sources/ec-nest && pnpm test -- storage`
Expected: PASS

- [ ] **Step 6: Commit**

```bash
git -C sources/ec-nest add src/storage src/app.module.ts .env package.json pnpm-lock.yaml
git -C sources/ec-nest commit -m "feat(c1): MinIO 存储模块"
```

---

### Task 4: elder 后端模块

**Files:**
- Create: `sources/ec-nest/src/elder/elder.module.ts`、`elder.controller.ts`、`elder.service.ts`、`dto.ts`、`elder.service.spec.ts`
- Modify: `sources/ec-nest/src/app.module.ts`

**Interfaces:**
- Consumes: `StorageService.upload/buildKey`（Task 3）、`PrismaService.client`、`getRequestContext()`、`Permissions.elder.*`、`ErrorCodes.ELDER_*`。
- Produces: `maskIdCard(idCardNo: string): string`；`ElderService` 六个接口（list/create/detail/changeStatus/statusLog/uploadEvidence）。

- [ ] **Step 1: 写失败测试**（`elder.service.spec.ts`，覆盖 5 个 Review Focus 场景）

```ts
// 关键用例（mock PrismaService + StorageService + ctx）：
// 1. create 时 assess_level 有值但 assessEvidenceFile 为空 → 抛 ELDER_LEVEL_REQUIRES_EVIDENCE
// 2. create 时 benefit_start 未来 → treatStatus = 'waiting_period'
// 3. changeStatus 缺 changeReason → 抛 ELDER_STATUS_REASON_REQUIRED
// 4. list 返回的 idCardNo 是掩码（前4+*+后4）
// 5. detail 明文分支：非 admin/qc 不返回明文；admin/qc 返回明文 + 写审计
```

- [ ] **Step 2: 跑测试确认失败**

Run: `cd sources/ec-nest && pnpm test -- elder`
Expected: FAIL

- [ ] **Step 3: 实现 maskIdCard + ElderService**

```ts
export function maskIdCard(id: string): string {
  if (!id) return '';
  if (id.length === 18) return `${id.slice(0, 4)}**********${id.slice(-4)}`;
  if (id.length === 15) return `${id.slice(0, 3)}********${id.slice(-4)}`;
  return id;
}

// 建档：18 位 + 校验位校验（GB11643 加权算法）、出生日期由身份证带出、
// 同机构 id_card_no 唯一（命中抛 ELDER_ID_CARD_EXISTS）、
// 等级与副本绑定（assess_level/care_level 有值则 assessEvidenceFile 必填，否则 ELDER_LEVEL_REQUIRES_EVIDENCE）、
// 初始状态：benefit_start<=today<=benefit_end ? active : waiting_period。
// changeStatus：change_reason 必填；写 ElderStatusLog（from/to/reason/operator/changedAt）。
// list：分页 + 掩码 id_card_no。detail：admin/qc 明文 + 审计，否则掩码。
// uploadEvidence：multipart 读 buffer → StorageService.buildKey + upload → 返回 { key }。
```

- [ ] **Step 4: 实现 controller + dto + module**（`@Controller('elder')`；写操作 `@AuditLog('elder','xxx')`；`app.module.ts` 注册 `ElderModule`）

- [ ] **Step 5: 跑测试确认通过 + tsc**

Run: `cd sources/ec-nest && pnpm test -- elder && pnpm exec tsc --noEmit`
Expected: PASS

- [ ] **Step 6: Commit**

```bash
git -C sources/ec-nest add src/elder src/app.module.ts
git -C sources/ec-nest commit -m "feat(c1): elder 待遇档案模块（建档/状态机/掩码/上传）"
```

---

### Task 5: 前端服务对象页面

**Files:**
- Create: `sources/ec-admin/src/api/elder.ts`
- Modify: `sources/ec-admin/src/pages/ltc/elder/index.vue`（替换占位页）
- Create: `sources/ec-admin/src/pages/ltc/elder/components/elder-form.vue`（建档表单）、`elder-detail.vue`（详情+状态变更）

**Interfaces:**
- Consumes: `http`（`@/api/http`）、`ty-crud`、`ty-form`、`showDialog`、`useDict`。
- Produces: `/ltc/elder` 列表 + 建档弹窗 + 详情弹窗。

- [ ] **Step 1: api 封装**（`src/api/elder.ts`）

```ts
import { http } from '@/api/http'
export interface Elder { id: string; name: string; gender: string; idCardNo: string; assessLevel?: string; careLevel?: string; treatStatus: string; birthDate?: number }
export const listElders = (params: { page: number; pageSize: number; treatStatus?: string; name?: string }) =>
  http.get<{ list: Elder[]; total: number }>('/elder', { params })
export const createElder = (data: Record<string, unknown>) => http.post<Elder>('/elder', data)
export const getElder = (id: string) => http.get<Elder>(`/elder/${id}`)
export const changeElderStatus = (id: string, data: { toStatus: string; changeReason: string }) => http.post(`/elder/${id}/status`, data)
export const getStatusLog = (id: string) => http.get(`/elder/${id}/status/log`)
export const uploadEvidence = (file: File) => { const fd = new FormData(); fd.append('file', file); return http.post<{ key: string }>('/elder/assess-evidence', fd) }
```

- [ ] **Step 2: 列表页**（`ltc/elder/index.vue`，`defineOptions({name:'elder'})`）用 `ty-crud`：列＝姓名/护理等级（带「（最高级）」）/状态（dictCode）/下次服务占位/操作；状态筛选用 `ty-search-form`；「查看」打开详情弹窗、「建档」打开建档弹窗。

- [ ] **Step 3: 建档表单**（`elder-form.vue`）用 `ty-form` JSON Schema：name/gender/birth_date(身份证带出)/id_card_no/phone/address/insur_no/insur_type/insur_verify_status/assess_* 区块。等级区块：上传评估结论副本（`uploadEvidence`）+ 录入 assess_org/assess_date/assess_level/care_level（**有副本才能填等级**，前端联动校验）。

- [ ] **Step 4: 详情弹窗**（`elder-detail.vue`）：完整信息 + 状态变更（下拉十态 + 原因必填）+ 状态日志时间线。

- [ ] **Step 5: type-check + Commit**

Run: `cd sources/ec-admin && pnpm type-check`
```bash
git -C sources/ec-admin add src/api/elder.ts src/pages/ltc/elder
git -C sources/ec-admin commit -m "feat(c1): 服务对象列表/建档/详情/状态变更"
```

---

### Task 6: 端到端验证

- [ ] **Step 1:** 起后端 + 登录 `touyun`，冒烟：建档（带评估结论上传）→ 列表（掩码）→ 详情（qc 明文 + 审计）→ 状态变更（原因必填）→ 状态日志。
- [ ] **Step 2:** 等级绑定：无副本填等级被拒；有等级无副本被拒。
- [ ] **Step 3:** 身份证防重：同机构重复建档被拦（ELDER_ID_CARD_EXISTS）。
- [ ] **Step 4:** 停后端、清理端口。

---

## Self-Review Notes

- Spec 覆盖：data-model 两个实体→T1；api-contract 掩码/接口→T4；backend/elder 五条 requirement→T4；frontend/ad/elder 三条→T5。
- Review Focus 5 条均有对应测试（T4 Step 1/3）。
- 类型一致：`maskIdCard`、`StorageService.upload/buildKey`、`Permissions.elder.*`、`ErrorCodes.ELDER_*` 在 T2/T3/T4 间一致。