docs: 登记 T-301 体检查询契约与字段清单

- docs/04 §11 体检 ~260 字段清单（7 节点）供将来 create 用
- docs/01 §5.2 标注各体检接口联调状态（单查未部署）
- tasks T-301 DONE；gitignore 收敛为 scripts/*.py

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -44,9 +44,10 @@ config.local.yaml
 scripts/*.json
 # 账号/凭据（userName/密码/主机/代理）——只本地留存
 /docs/账号.txt
-# 本地联调脚本（硬编码了 ask/orgCode/身份证等真实值）——只本地留存
+# 本地联调探针脚本（硬编码了 ask/orgCode/身份证等真实值）——只本地留存
-/scripts/query_health_record.py
+/scripts/*.py
 /query_health_record.bat
+/dev.bat
 # 本地工作区文件
 /agent-session.txt
 /chis_osi.code-workspace

docs/01-OSI接口规范分析.md

@@ -132,15 +132,15 @@
 
 ### 5.2 健康体检（JKTJ）
 
-| 业务 | 路径 | serviceId |
+| 业务 | 路径 | serviceId | 联调状态 |
-| --- | --- | --- |
+| --- | --- | --- | --- |
-| 创建 | `/osi/api/jktj/create` | `JKTJ00001` |
+| 创建 | `/osi/api/jktj/create` | `JKTJ00001` | 待写入授权 |
-| 查询 | `/osi/api/auto/jktj/query` | `JKTJ00002` |
+| 查询（单条） | `/osi/api/auto/jktj/query` | `JKTJ00002` | ⚠ 实测"没有url的接口配置"（**未部署**）；`auto/jktj/find` 待确认 |
-| 更新 | `/osi/api/jktj/update` | `JKTJ00003` |
+| 更新 | `/osi/api/jktj/update` | `JKTJ00003` | 待写入授权 |
-| 已检/待检人员列表 | `/osi/api/auto/jktjlist/query` | `JKTJLIST00002` |
+| 已检/待检人员列表 | `/osi/api/auto/jktjlist/query` | `JKTJLIST00002` | 路径登记；入参待确认 |
-| 最近一次体检 | `/osi/api/auto/jktjlscx/query` | `JKTJLSJL00002` |
+| 最近一次体检 | `/osi/api/auto/jktjlscx/query` | `JKTJLSJL00002` | ✅ 联调可用（T-301） |
 
-> 体检报文体量大（hcData/lsData/exaData/aeData 等数十~上百字段），是字段映射工作量最大的一块。
+> 体检报文体量大（实测最近一次约 260 字段，分 4 object + 3 array 子节点），是字段映射工作量最大的一块。响应结构与字段清单见 `docs/04 §11`。
 
 ### 5.3 老年人（LNR）
 

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

@@ -250,3 +250,44 @@ T-206 已建立本地契约与客户端方法，真实写入验收暂未执行
 - `mapping.BuildHealthRecordCreate` 负责把 `MappedHealthRecord` 组装成 `contract.HealthRecordCreate`，保留确定性 `checkId`，并由 `manaDoctorId/manaUnitId` 派生 `createUser/createUnit`。
 
 真实 create/update 联调完成后，需要在本节补回平台返回样本、`phrId` 字段确认、同一 `checkId` 重复 create 的幂等语义。
+
+---
+
+## 11. JKTJ 健康体检查询 · 联调实测契约（T-301）
+
+> 来源：2026-07 沙箱"最近一次体检"一次成功查询（`code="01"`）。**脱敏结构**，真实值只在本地样本、不入库。
+> 这是体检查询的事实基线，也是将来体检 **create 映射**的字段清单来源。
+
+### 11.1 接口与状态
+
+| 业务 | serviceId | 路径 | 状态 |
+| --- | --- | --- | --- |
+| 最近一次体检 | `JKTJLSJL00002` | `/auto/jktjlscx/query` | ✅ 实测可用（`osi.LastHealthCheck`） |
+| 已检/待检列表 | `JKTJLIST00002` | `/auto/jktjlist/query` | 路径已登记；入参（机构/日期/分页）待厂家确认 |
+| 单条按体检 id 查 | `JKTJ00002` | docx 标 `/auto/jktj/query` | ⚠ 实测返回"没有url的接口配置"（**未部署**）；`/auto/jktj/find` 待确认，见 docs/06 B5 |
+
+- 请求信封同档案（`serviceId` + `uploadinfo{baseInfo, manageInfo}`）；查询按 `idCard`/`phrid`/`empiId` 之一。
+- **两处与档案不同的坑**：① 最近一次的 `data` 是**单个对象**（档案 find 是数组）；② 体检身份证字段是小写 **`idcard`**（档案是 `idCard`）。
+
+### 11.2 记录结构与主键
+
+- 体检记录主键 = **`checkId`**（体检自身流水，**注意**与档案 §5 我方生成的幂等 `checkId` 同名不同义）。
+- 各子节点用 **`healthCheck`** 外键指向主键（值 = checkId）；子节点各有自己的 id：`healthAssessment.assessmentId`、`accessoryExamination.recordId`、`inhospitalSituations[].situationId`。
+
+### 11.3 字段清单（实测约 260 项，供体检 create 建模用）
+
+> 查询侧只强类型化定位字段（`contract.HealthCheckSummary`：checkId/healthCheck/idcard/personName/checkDate），完整内容由 `osi.Result.Raw` 保留。
+> 全量字段的强类型建模留到体检 create 任务——写入映射才需要逐字段建模，届时以本清单 + 联调 create 样本为准，不照 docx 猜类型（本样本大量字段为 null，类型不可判）。
+
+| 节点 | 类型 | 字段数 | 说明 |
+| --- | --- | --- | --- |
+| （顶层标量） | - | 39 | 体征与主诉：身高体重 `height/weight/bmi`(float)、血压 `constriction/diastolic(_l)`、`temperature/pulse/breathe/waistline`、`symptom/healthstatus/selfcare/cognitive/emotion` 及各类疾病标志 |
+| `healthAssessment` | object | 24 | 健康评价：`abnormality1..8`、`riskfactorsControl`、`assessmentId` + create/lastModify 审计字段 |
+| `examination` | object | 52 | 一般查体：皮肤/淋巴结/心肺/腹部/肝脾/乳腺/妇科等 `*` + `*Desc` 描述对 |
+| `lifestySituation` | object | 43 | 生活方式：吸烟 `wehtherSmoke/beginSmokeTime`、饮酒 `drinkingFrequency`、运动、职业暴露 `occupational/dust/ray/chemicals` |
+| `accessoryExamination` | object | 84 | 辅助检查（最大）：血常规 `wbc/hgb/platelet`、生化 `alt/ast/glu/fbs/hba1c/tc/tg/hdl/ldl/cr/bun/tbil`、尿常规、心电 `ecg`、胸片 `x`、视力听力 `recordId` |
+| `inhospitalSituations` | array | 19/项 | 住院/家庭病床：`type`、`inhospitalDate/outhospitalDate`、`situationId`，多含 `*_text` 中文回显 |
+| `nonimmuneInoculations` | array | - | 非免疫规划预防接种（本样本空，结构待样本） |
+| `medicineSituations` | array | - | 用药情况（本样本空，结构待样本） |
+
+> 命名坑点：`constriction`=收缩压、`diastolic`=舒张压（`_l` 疑为左侧）；辅助检查用大量医学缩写。建 create 映射时逐字段加中文注释。

docs/current-state.md

@@ -88,9 +88,9 @@ python3 scripts/query_health_record.py
 
 > 读先行调整（2026-07-08）：写入（T-206/T-204）被厂家授权锁死，先推其余业务线查询。
 
-1. **T-301 体检查询打通**（`contract/jktj.go` + `osi/jktj.go`，JKTJ00002 / JKTJLSJL00002），响应字段记入 docs/04 —— 当前可领。
+1. ✅ T-301 体检查询打通（`osi.LastHealthCheck` JKTJLSJL00002；字段清单 docs/04 §11）——待 `go test ./...` 复验。
-2. T-302 体检 HTTP 查询端点（复用 T-208 handler 模式）。
+2. **T-302 体检 HTTP 查询端点**（复用 T-208 handler 模式）——当前可领。
-3. 并行催厂家（docs/06 ★ 优先催办）：写入授权+测试档案、缺失列表 serviceId、checkId/完整度规则。
+3. 并行催厂家（docs/06 ★ 优先催办）：写入授权+测试档案、缺失列表/单查 serviceId、checkId/完整度规则。
 4. 授权到位后回到 T-206 真实 create 验收 → T-204。
 
 ## 维护规则

progress.md

@@ -200,3 +200,12 @@
 - 变更：`tasks.md` 新增 Phase Q2（其余业务线查询：T-301 体检查询 / T-302 体检端点 / T-303 老年人查询 / T-304 列表查询），把写入 T-206(BLOCKED)/T-204 明确降到 Q2 之后；里程碑加 M4=体检查询、M5=创建闭环。`docs/06` 顶部加"★ 当前批次优先催办"，把写入授权(D3)+缺失 serviceId(B1/B2/B4)+写入规则(C1/C2) 归拢成一封邮件一起催。`docs/current-state.md` 下一步改为 T-301 起。
 - 决策（全栈分析）：真实 create 被厂家写入授权外部锁死，垂直切片走不通；改按读/写横切、读先行——读路径不被授权阻塞、只读零风险、且各查询响应是将来写入映射的事实侦察。T-206 创建代码保留不作废，授权到位再验收。
 - 下一步：T-301 体检查询打通。
+
+## 2026-07-08 T-301 体检查询打通（最近一次）
+
+- 状态：DONE
+- 变更：新增 `contract/jktj.go`（HealthCheckSummary 定位字段）、`osi/jktj.go`（`LastHealthCheck` JKTJLSJL00002）、`osi/jktj_test.go`（脱敏假数据测路径/解码/Raw/idcard 小写映射/单键校验）；`osi/codes.go` 登记 JKTJLSJL00002 + JKTJLIST00002 路由；`docs/04` 新增 §11 体检字段清单（~260 项/7 节点），`docs/01 §5.2` 标注各体检接口联调状态。
+- 验证：真实"最近一次体检"查询已通（用户侧 Python 脚本 code=01，返回单个体检对象）。Go 侧因本环境离线无工具链未复跑，需用户 `go test ./...` 确认编译与单测。
+- 发现：① 单条 JKTJ00002 `auto/jktj/query` 平台实测"没有url的接口配置"（未部署），`auto/jktj/find` 待确认 → docs/06 B5。② 体检 data 为单对象（档案 find 是数组）。③ 体检身份证字段小写 `idcard`（档案 `idCard`）。④ 体检主键 `checkId`（与档案幂等 checkId 同名不同义），子节点 `healthCheck` 外键指向它。
+- 决策：查询只强类型化定位字段，完整内容留 `Result.Raw`；~260 全量字段建模留到体检 create（写入才需逐字段，避免照单样本猜 null 类型）。
+- 下一步：T-302 体检 HTTP 查询端点（复用 T-208 handler 模式）；或按 docs/06 催厂家确认单查/列表接口。

tasks.md

@@ -73,7 +73,7 @@
 
 | ID | 任务 | 依赖 | 验收要点 | 状态 |
 | --- | --- | --- | --- | --- |
-| T-301 | 体检查询打通：`contract/jktj.go` + `osi/jktj.go`（单条 JKTJ00002 / 最近一次 JKTJLSJL00002） | T-004 | 真实请求拿到 `code="01"` 与体检数据；响应字段（hcData/lsData/exaData/aeData…）记入 docs/04 | TODO |
+| T-301 | 体检查询打通：`contract/jktj.go` + `osi/jktj.go`（最近一次 JKTJLSJL00002） | T-004 | 真实请求拿到 `code="01"` 与体检数据；响应字段（~260 项/7 节点）记入 docs/04 §11 | DONE（单条 JKTJ00002 平台未部署，见 §11） |
 | T-302 | 体检 HTTP 查询端点（复用 T-208 handler 模式） | T-301 | server 模式 curl 返回体检完整 JSON；默认仅绑本机 | TODO |
 | T-303 | 老年人查询打通：自理 LNRZLPG / 体质 LNRZYTZ（查询 serviceId 部分待确认） | T-004 | 真实请求打通；缺失 serviceId 先向厂家确认（docs/06 B4） | TODO（部分待 B4） |
 | T-304 | 列表类查询（档案/体检/老年人/中医指导列表） | T-004 | 各列表路径+serviceId 到位后返回分页数组 | BLOCKED（待 docs/06 B1/B2 厂家回填） |