chis_osi/docs/superpowers/plans/2026-07-16-health-record-upsert.md

PHIS Health Record Upsert Implementation Plan

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: Convert one PHIS health-record task into a validated CHIS JKDA write request, then provide a reusable query-first upsert application service.

Architecture: source owns the PHIS JSON contract and strips credentials, mapping performs pure PHIS-to-CHIS conversion, contract owns the JKDA write shape, and pipeline orchestrates query/create/update through injected interfaces. HTTP exposure and persistent retry/report stores remain in T-204 and Phase 3.

Tech Stack: Go 1.24 standard library, existing contract/mapping/osi packages, table-driven tests.

---

Task 1: T-212 PHIS DTO and source identity

Files:

• Create: source/health_record.go

• Create: source/health_record_test.go

• Create: source/testdata/health_record.json

• Create: docs/decisions/001-phis-health-record-source-key.md

• Write failing tests that decode the PHIS envelope, retain archId/businessId/empiId/phrId, expose only doctor ID/name, and reject a missing archId.

• Run go test ./source -count=1 and verify failure because the package/API does not exist.

• Implement the DTO and DecodeHealthRecordTask; use archId as the health-record source key and retain businessId only for tracing.

• Run go test ./source -count=1 and verify pass.

• Record the source-key evidence and compatibility decision in the ADR.

Task 2: T-212 complete mapping and write contract

Files:

• Modify: contract/jkda.go

• Modify: contract/jkda_test.go

• Modify: mapping/health_record.go

• Modify: mapping/health_record_test.go

• Modify: mapping/health_record_baseline_test.go

• Modify: mapping/checkid.go

• Write failing contract/mapping tests for all PHIS direct fields, adressNumber to addressNumber, stable checkId across updateTime, past-history nodes, four history arrays, conditional familyMiddle, required/date/length/code validation, and per-record operateUser.

• Run targeted go test ./contract ./mapping -count=1 and verify expected failures.

• Expand only fields supplied by PHIS and implement pure conversion helpers; normalize multi-select separators and preserve explicit no-history codes.

• Run targeted tests until green, then run go test ./contract ./mapping -count=1.

Task 3: T-212 per-record operation context

Files:

• Modify: osi/jkda.go

• Modify: osi/jkda_test.go

• Modify: cache/dictionary.go

• Modify: cache/dictionary_test.go

• Write failing tests proving a mapped doctor ID survives as manageInfo.operateUser, while DSFMC/operateUnit still come from trusted client config; add doctor-ID membership validation to dictionary snapshots.

• Run targeted tests and verify expected failures.

• Implement minimal request-context merge and dictionary membership lookup.

• Run go test ./cache ./osi ./mapping -count=1 and verify pass.

Task 4: Complete and commit T-212

Files:

• Modify: tasks.md

• Modify: progress.md

• Modify: docs/current-state.md

• Modify: docs/04-字段与接口映射.md

• Update mapping documentation, mark T-212 DONE, append RED/GREEN/full validation evidence, and set T-213 as next.

• Run gofmt, go test ./..., go build ./..., and git diff --check.

• Commit T-212 as one logical commit.

Task 5: T-213 query-first upsert service

Files:

• Create: pipeline/health_record_upsert.go

• Create: pipeline/health_record_upsert_test.go

• Write failing tests for zero-result create, one-result update, multiple/cross-unit/inactive manual review, query failure without create fallback, create/update failure classification, idempotent skip, and PHIS/report events.

• Run go test ./pipeline -count=1 and verify expected failure because the service does not exist.

• Implement HealthRecordUpsertService with injected OSI, converter, idempotency, report, and PHIS status interfaces; keep persistence and retry scheduling out of scope.

• Run go test ./pipeline -count=1 and then go test ./....

Task 6: Complete and commit T-213

Files:

• Modify: tasks.md

• Modify: progress.md

• Modify: docs/current-state.md

• Modify: docs/03-目标架构设计.md

• Document the reusable application-service boundary and mark T-213 DONE; leave T-204 TODO and T-215 BLOCKED.

• Run gofmt, go test ./..., go build ./..., and git diff --check.

• Commit T-213 as a second logical commit.