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

docs/openapi.yaml

@@ -1,8 +1,8 @@
 openapi: 3.0.3
 info:
   title: chis_osi Server API
-  version: 0.1.0
-  description: 'chis_osi server 模式对外提供的本机 HTTP 查询接口。
+  version: 0.2.0
+  description: 'chis_osi server 模式对外提供的本机 HTTP 查询与健康档案 upsert 接口。
 
 
     本文档描述的是本项目自己的 HTTP API，不是上游 CHIS OSI 平台接口。
@@ -21,7 +21,7 @@ servers:
   description: 本地默认 server 模式地址
 tags:
 - name: health-record
-  description: 健康档案查询
+  description: 健康档案查询与 upsert
 - name: health-check
   description: 健康体检查询
 - name: dictionaries
@@ -29,6 +29,72 @@ tags:
 - name: elderly
   description: 老年人业务查询
 paths:
+  /api/health-record/upsert:
+    post:
+      tags:
+      - health-record
+      summary: 创建或更新个人健康档案
+      description: '接收 PHIS 健康档案响应信封，复用 query-first upsert 应用服务。
+
+
+        只有 JKDA00002 明确返回非 nil 空数组时才创建；单条安全目标更新，多条或跨机构等转人工。
+        当前使用成功即释放的进程内并发租约，不保存跨请求完成记录；真实写入验收仍由 T-215 阻断。
+
+        '
+      operationId: upsertHealthRecord
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PHISHealthRecordEnvelope'
+      responses:
+        '200':
+          description: 创建、更新或幂等跳过完成。
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthRecordUpsertOutcome'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '409':
+          description: 目标档案必须人工处理，未执行写入。
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthRecordUpsertOutcome'
+        '413':
+          description: 请求体超过 1 MiB。
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '422':
+          description: PHIS 字段、格式、码表或主数据校验失败。
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthRecordUpsertOutcome'
+        '502':
+          description: CHIS/字典上游失败或 upsert 后置动作失败。
+          content:
+            application/json:
+              schema:
+                oneOf:
+                - $ref: '#/components/schemas/HealthRecordUpsertOutcome'
+                - $ref: '#/components/schemas/HealthRecordUpsertError'
+        '503':
+          description: 暂时失败可重试，或同一档案正在处理中。
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthRecordUpsertOutcome'
+        '405':
+          description: 仅支持 POST。
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
   /api/health-record/find:
     get:
       tags:
@@ -585,6 +651,113 @@ components:
               value:
                 error: empty response from OSI
   schemas:
+    PHISHealthRecordEnvelope:
+      type: object
+      required:
+      - code
+      - data
+      properties:
+        code:
+          type: integer
+          enum:
+          - 200
+        msg:
+          type: string
+        compress:
+          type: boolean
+        data:
+          type: object
+          required:
+          - archId
+          - record
+          properties:
+            archId:
+              type: string
+              description: PHIS 健康档案稳定源主键。
+            businessId:
+              type: string
+              description: PHIS 业务追踪/回写标识，不参与 checkId 主键选择。
+            empiId:
+              type: string
+            phrId:
+              type: string
+            doctor:
+              type: object
+              properties:
+                doctorId:
+                  type: string
+                realName:
+                  type: string
+              additionalProperties: true
+              description: sxtAccount/sxtPassword 等凭据会被服务忽略。
+            record:
+              type: object
+              required:
+              - idCard
+              - manaDoctorId
+              - manaUnitId
+              - regionCode
+              properties:
+                idCard:
+                  type: string
+                  description: 身份证件号，普通日志不得记录原文。
+                personName:
+                  type: string
+                manaDoctorId:
+                  type: string
+                manaUnitId:
+                  type: string
+                regionCode:
+                  type: string
+              additionalProperties: true
+              description: 完整 PHIS record 字段及映射规则见 docs/04 §14。
+      additionalProperties: false
+    HealthRecordUpsertOutcome:
+      type: object
+      required:
+      - status
+      - action
+      properties:
+        status:
+          type: string
+          enum:
+          - done
+          - retry
+          - failed
+          - manual_review
+        action:
+          type: string
+          enum:
+          - none
+          - create
+          - update
+          - skip
+        reason:
+          type: string
+        serviceId:
+          type: string
+          example: JKDA00003
+        responseCode:
+          type: string
+          example: '01'
+        phrIdHint:
+          type: string
+          description: 脱敏档案编号，仅保留末四位。
+          example: '****1234'
+    HealthRecordUpsertError:
+      type: object
+      required:
+      - error
+      - retrySafe
+      properties:
+        error:
+          type: string
+          example: health record upsert failed
+        retrySafe:
+          type: boolean
+          description: false 表示 CHIS 可能已完成写入，禁止重放整个 upsert。
+        outcome:
+          $ref: '#/components/schemas/HealthRecordUpsertOutcome'
     ErrorResponse:
       type: object
       required: