feat(handler): 暴露健康档案 upsert 接口（T-204）

progress.md

@@ -361,3 +361,14 @@
 - 安全与边界：普通报告事件只含哈希 `trace_id`、业务状态、serviceId、响应码及脱敏 `phrId`，原始源标识只交给受控 PHIS 回写端口；`data:null`/缺失不得视为 0 条；幂等完成失败不发送 `done`，副作用失败通过 `NotificationError` 区分租约/报告/PHIS 回写错误并只暴露失败端补偿数据。持久化、重试调度、HTTP 和 PHIS 真实回写不在 T-213 实现。
 - 验证：`go test ./pipeline -count=1`、`go test ./... -count=1`、`go build ./...`、`go vet ./...`、`git diff --check` 均通过。`bash ./init.sh` 在当前 PowerShell 调起的 Bash 环境失败（`go: command not found`），未误报通过；其内部等价 Go 命令已在 PowerShell 单独验证。
 - 下一步：T-204 `POST /api/health-record/upsert` HTTP 适配；T-215 继续等待安全测试档案和写入授权。
+
+## 2026-07-16 T-204 健康档案 upsert HTTP 适配
+
+- 状态：DONE（真实 curl 写入验收仍归 T-215，未使用真实居民调用）。
+- RED：`go test ./handler -run HealthRecordUpsert -count=1` 初次因 `NewHealthRecordUpsertHandler` 不存在而编译失败；`go test ./pipeline -run MemoryIdempotency -count=1` 初次因无进程内租约实现失败；根包运行时测试初次因 `newServerHealthRecordUpserter/newServerMux` 不存在失败。
+- GREEN：新增 `POST /api/health-record/upsert`，接收最大 1 MiB 的 PHIS 健康档案响应信封，复用 T-213 服务并按 `done/manual_review/retry/failed` 返回 200/409/503/422 或上游 502；内部错误不回显代理/平台细节。
+- 运行时：先做无网络字段/码表预校验，再按 `manaUnitId` 查询责任医生和机构字典并注入 mapping；新增 owner-token 进程内并发租约，防同进程并发和 stale token，成功后释放而不缓存 completed，避免稳定 `checkId` 阻断后续更新；HTTP 模式不做 PHIS 状态回调。
+- 安全：若 CHIS 已成功但幂等完成/通知失败，502 响应保留 `outcome.status=done` 且 `retrySafe=false`，调用方不得重放整个 upsert；普通响应只含脱敏 `phrIdHint`。
+- 文档：更新 `docs/03`、`docs/07` 和 `docs/openapi.yaml`，OpenAPI 版本升至 0.2.0，增加 PHIS 请求信封、outcome、错误与 HTTP 状态定义。
+- 验证：`go test ./... -count=1`、`go build ./...`、`go vet ./...`、OpenAPI YAML 解析与端点断言、`git diff --check` 均通过；`go test -race ./pipeline ./handler -count=1` 因当前 Go 环境未启用 CGO 无法执行；`bash ./init.sh` 在当前 Bash 环境因找不到 `go` 失败，其内部等价 Go 命令已在 PowerShell 验证，均未误报通过。
+- 下一步：取得安全写入授权后做 T-215；否则拆分路线图阶段 3 的持久化幂等和补偿任务。