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

docs/07-本项目HTTP接口.md

@@ -1,6 +1,6 @@
 # 07 · 本项目 HTTP 接口
 
-`chis_osi` **server 模式**对外提供的 HTTP 查询接口——供前端/运维/PHIS 侧调用。
+`chis_osi` **server 模式**对外提供的 HTTP 查询与健康档案 upsert 接口——供前端/运维/PHIS 侧调用。
 
 > 这是本项目**自己**对外的接口的单一事实来源；调用**上游厂家 OSI** 的接口契约看 `docs/01`、`docs/04`。
 > 新增/修改端点后同步本文（与 `handler/`、`server.go` 保持一致）。
@@ -25,8 +25,9 @@ go run . -mode server -addr 127.0.0.1:9000   # 指定地址
 
 | 项 | 说明 |
 | --- | --- |
-| 方法 | 一律 `GET`，查询条件走 query string |
-| 成功响应 | **直接回写平台完整 JSON**（`{code,message,data}`，不裁字段），`Content-Type: application/json` |
+| 查询方法 | `GET`，查询条件走 query string |
+| Upsert 方法 | `POST`，请求体为 PHIS 健康档案响应信封，最大 1 MiB |
+| 查询成功响应 | **直接回写平台完整 JSON**（`{code,message,data}`，不裁字段），`Content-Type: application/json` |
 | 平台成功码 | `code="01"`（字符串，见 docs/01 §1）——本服务不改写，原样透传 |
 | 参数错误 | `400`，体为 `{"error":"..."}`（如缺必填标识符） |
 | 上游失败/网络错误 | `502`，体为 `{"error":"..."}` |
@@ -34,6 +35,8 @@ go run . -mode server -addr 127.0.0.1:9000   # 指定地址
 
 > 设计取舍：端点**原样回写平台响应**（同 `Result.Raw`），不做字段裁剪/转换——保证平台未建模字段也能拿到，便于查看完整档案/体检。
 
+健康档案 upsert 不透传 OSI 原文，只返回脱敏的结构化结果。其运行时先做无网络字段/码表预校验，再按档案 `manaUnitId` 查询责任医生和机构主数据，最后调用 T-213 的 query-first 应用服务。当前 HTTP 模式只使用**进程内并发租约**：可防同进程同时投递，成功后立即释放，后续版本仍会重新查询并更新；它不提供跨重启完成记录，持久化幂等仍属于路线图阶段 3。
+
 ---
 
 ## 端点清单
@@ -183,6 +186,35 @@ GET /api/elderly/self-care
 
 - 上游：`LNRZLPG00002` `/auto/lnr/query`（厂家文档契约，待真实联调确认）
 - 返回：`data` 为**数组**，每条含进餐/梳洗/穿衣/如厕/活动及总评的原始值、等级和评分；完整字段原样回写
+
+### 11. 创建或更新个人健康档案
+
+```
+POST /api/health-record/upsert
+Content-Type: application/json
+```
+
+请求体使用 PHIS 健康档案响应信封：顶层 `code` 必须为 `200`，`data.archId` 必填；`data.doctor` 和 `data.record` 字段结构见 `source.HealthRecordTask`。医生账号、密码即使出现在原始 JSON 中也会被解码器忽略，不进入领域模型和 OSI 请求。
+
+处理规则：按身份证查询 CHIS，明确 0 条时创建，1 条且身份证、状态、机构、责任医生和 `phrId` 均安全时更新；多条或不安全目标转人工处理。查询失败绝不降级创建。
+
+| HTTP 状态 | pipeline 状态 | 说明 |
+| --- | --- | --- |
+| `200` | `done` | 创建、更新或幂等跳过完成 |
+| `409` | `manual_review` | 多档案、跨机构、跨医生、状态不可更新等，禁止自动写入 |
+| `422` | `failed` | PHIS 字段、必填、格式、码表或主数据校验失败 |
+| `502` | `failed` 或内部错误 | CHIS/字典上游失败，或写入成功后的本地收尾失败 |
+| `503` | `retry` | 查询/写入暂时失败或同一档案正在处理 |
+
+正常响应示例：
+
+```json
+{"status":"done","action":"update","serviceId":"JKDA00003","responseCode":"01","phrIdHint":"****1234"}
+```
+
+内部错误响应包含 `retrySafe`。若 CHIS 已明确写入成功但幂等完成或通知失败，会保留 `outcome.status="done"` 且返回 `retrySafe=false`，调用方不得重放整个 upsert，只能按错误补偿后置动作。
+
+> 当前未完成 T-215 真实写入验收。没有安全测试档案和明确写入授权时，不得用真实居民调用此端点。
 ---
 
 ## 调用示例
@@ -198,12 +230,13 @@ curl "http://127.0.0.1:8080/api/dictionaries/doctors?manaUnitId=<机构码>&oper
 curl "http://127.0.0.1:8080/api/dictionaries/drugs?pageNo=1&pageSize=10&ypmc=<药品名>&pym=<拼音码>"   # pageNo 必填
 curl "http://127.0.0.1:8080/api/dictionaries/orgs?organizCode=<机构码>&parentId=<上级机构ID>"
 curl "http://127.0.0.1:8080/api/elderly/self-care?idCard=<身份证>&phrId=<档案号>&checkId=<检查主键>"
+curl -X POST "http://127.0.0.1:8080/api/health-record/upsert" -H "Content-Type: application/json" --data-binary "@<phis-health-record.json>"
 ```
 
 ---
 
 ## 尚未提供（后续）
 
-- 写入类端点（档案/体检 create/update）：`handler` 侧 `/api/health-record/save` 等待 T-204/T-206 及厂家写入授权。
+- 体检等其他业务写入端点：待对应 PHIS 转换、upsert 编排及厂家写入授权。
 - 老年人中医体质辨识、中医指导查询端点：待对应 OSI serviceId/字段契约（docs/06 B4）。
 - 鉴权、访问日志、限流：当前是本机联调工具形态，对外前必须补齐。