bsp

IHD 产品组业务数据导入对接规范

项目	说明
适用对象	各产品组研发、架构、实施
文档目的	统一正式表导入对接方式，防止循环依赖，指导业务数据迁移接入
核心原则	IHD 通过前端配置的 REST 地址调用产品组；产品组不要在 api 层引用 `hisihd-api` / 继承 Feign
关联代码	`IhdDataSaveClient`、`IhdSaveRequest`、`ImportDataServiceImpl#sendJsonRequest`
编写背景	病案号等迁移场景中出现 `mrm-api` 依赖 `hisihd-api`、Feign 继承 `IhdDataSaveClient` 引发依赖方向争议

1. 正确依赖方向（必读）

1.1 推荐链路

源库 / Excel
    ↓
IHD 迁移服务（hisihd）读临时表、做字段/字典对照
    ↓  HTTP REST（业务配置里的 importClass URL）
产品组业务服务（如 mrm / opar / ipar / 医生站）落正式表
    ↓
产品组返回每条成功/失败（id / status / errorMsg）
    ↓
IHD 记正式导入进度与失败明细日志
（临时表 status / new_id：现状由产品组更新，见 §3.4）

1.2 依赖方向红线

允许	禁止
IHD core-biz 用 `RestTemplate` 调产品组 Controller HTTP	产品组 `xxx-api` 依赖 `hisihd-api`
产品组 biz / controller 实现与前台一致的导入落库逻辑	产品组 Feign 接口 `extends IhdDataSaveClient`
产品组按需引用 DTO 约定（或自建等价 JSON 结构）	api 依赖 api、形成编译期环或「迁移工具被业务反向依赖」
IHD 配置产品组完整 REST URL	指望 IHD 编译期注入各产品组 Feign Client

一句话：
迁移工具应调用业务；不应让业务模块（尤其 api）反向依赖迁移工具的 Feign 契约。

1.3 为何禁止 Feign 继承 `IhdDataSaveClient`

历史写法类似：

@FeignClient(name = "mrm-mediway-server", path = "...")
public interface BspIhdInPatmrnoClient extends IhdDataSaveClient<BspIhdMaMrInpatmrnoPO> {
    @PostMapping("save")
    BaseResponse<List<...>> save(@RequestBody IhdSaveRequest<...> request);
}

问题：

产品组 xxx-api 的 pom 会引入 hisihd-api / hisihd-biz-model → 依赖倒置（业务依赖迁移工具）。
多产品组都这样做时，hisihd-api 被大量业务模块编译依赖，耦合面爆炸（runner 依赖树中可见）。
IHD 正式导入实际走的是 RestTemplate + 配置 URL，并不需要这些 Feign；Feign 继承是多余且有害的。
IhdDataSaveClient 上的 @FeignClient / @PostMapping 已注释，本身就不是给产品组继承用的运行契约。

IhdDataSaveClient 仅可视为「方法签名示意」，不要作为产品组 api 的父接口。

2. 标准对接方式：前端配置 REST

2.1 在 IHD 业务配置中填写

正式导入时，IHD 读取业务配置：

配置项	含义	示例
`importClass`	产品组完整 HTTP URL（POST）	`http://{网关或服务}/xxx/context/mrm/api/trans/ihd/save`

实施在 IHD 前台「业务配置」中维护，改地址不必改 IHD 代码、不必让产品组发 Feign 包给 IHD。

2.2 IHD 侧实际调用方式

ImportDataServiceImpl
  → 组包 JSON（configObj + ihdMiddleTablePos）
  → restTemplateIhd.exchange(importClass, POST, ...)
  → 解析 BaseResponse<List<BaseResponseTempDTO>>

请求头携带：Content-Type: application/json，access-token: <当前令牌>。

3. 产品组需要提供什么

3.1 提供 Controller（与前台同逻辑）

推荐做法（医生站等已验证路径）：

提供 HTTP Controller，逻辑与业务前台导入/保存一致（或复用同一 Service）。
不要为 IHD 单独再维护一套「仅 Feign 可用」的 api 继承链。
若历史上 api 里已有 extends IhdDataSaveClient：删除继承，改为普通 Controller；api 模块 去掉对 hisihd-api 的依赖。

示例形态（示意）：

@RestController
@RequestMapping("/mrm/api/trans/ihd")  // 与配置到 IHD 的 URL 路径一致
public class XxxIhdImportController {

    @PostMapping("/save")
    public BaseResponse<List<BaseResponseTempDTO>> save(@RequestBody Map<String, Object> body) {
        // 1. 解析 configObj、ihdMiddleTablePos
        // 2. 落正式表（与前台相同 Service）
        // 3. 按条回写结果：id / status / errorMsg
        // 4. 中间表 status 由 IHD 根据返回结果处理，或按双方约定由产品组更新——见 3.3
        return BaseResponse.success(resultList);
    }
}

3.2 请求体约定（与 `IhdSaveRequest` 对齐）

IHD 发出的 JSON 结构等价于：

{
  "configObj": {
    "业务参数code": "业务参数value"
  },
  "ihdMiddleTablePos": [
    {
      "id": 123,
      "temp_id": 123,
      "...中间表字段（已字典对照后的值）...": "..."
    }
  ]
}

说明：

configObj：来自 IHD「业务参数配置」，产品组用于默认科室、默认类型等。
ihdMiddleTablePos：一批中间表行；含主键 id（回写结果时必须能对应）。
字段名以中间表 / 对照后驼峰或下划线为准，双方联调时固定样例 JSON。

参考类型（仅作契约说明，产品组勿强制依赖 jar）：

com.mediway.his.ihd.biz.model.dto.IhdSaveRequest
中间表基类字段：newId、status（1 成功 / 非 1 未成功）等见 IhdMiddleTablePO

3.3 响应体约定（IHD 强依赖）

IHD 按如下结构解析：

{
  "success": true,
  "code": "200",
  "msg": "ok",
  "data": [
    {
      "id": "123",
      "status": "1",
      "errorMsg": ""
    },
    {
      "id": "124",
      "status": "0",
      "errorMsg": "证件号已存在"
    }
  ]
}

字段	要求
外层 `BaseResponse`	`success=true` 表示本批接口可解析；业务行失败放在 `data` 行内
`data[].id`	对应中间表行 id，必填
`data[].status`	`"1"` = 该行导入成功；其它 = 失败
`data[].errorMsg`	失败原因，便于 IHD 写正式导入明细

参考：BaseResponseTempDTO（id / status / errorMsg）。

3.4 中间表 status 由谁更新（现状 vs 目标）

现状（以当前 ImportDataServiceImpl#saveDataByFormal 为准）：

产品组 HTTP 返回后，IHD 只做：

统计成功/失败条数
失败行写入正式导入明细日志 bs_bsp_ihd_formal_itm_log

不会根据返回结果去 UPDATE 临时表的 status / new_id。

因此现场能把 status 置为 '1'、避免重复导入的，实际是 产品组在落库成功时自行更新中间表（这也是部分组曾想引用 hisihd-api 的原因之一）。

步骤	现状责任方
读临时表、对照、调产品组	IHD
写正式业务表	产品组
更新临时表 `status` / `new_id`	产品组
正式导入主表/明细日志	IHD

目标约定（规范推荐，待 IHD 补齐回写后切换）：

步骤	目标责任方
读临时表、对照、调产品组	IHD
写正式业务表	产品组
根据返回 `data[].id/status` 更新临时表 `status`/`new_id`、记正式导入日志	IHD

切换前：产品组可继续更新中间表，但不要为此让 xxx-api 依赖 hisihd-api；直接用本库 SQL/JdbcTemplate 更新约定中间表即可。
切换后：产品组只返回结果，中间表状态统一由 IHD 回写。

4. 产品组落地检查清单

接入一个新业务正式导入前，产品组自检：

已提供 POST Controller，URL 可配置进 IHD importClass
请求/响应符合第 3 节约定，并用 Postman/前台同等包体联调通过
xxx-api 的 pom 未依赖 hisihd-api
无 extends IhdDataSaveClient 的 Feign

5. 反例与正例

5.1 反例（禁止）

mrm-api
  ├── depends on hisihd-api
  ├── Feign: XxxClient extends IhdDataSaveClient
  └── 声称「给 IHD 导入用」

问题：依赖方向反了；且 IHD 根本不走该 Feign。

5.2 正例（推荐）

mrm-biz / mrm Controller
  └── POST /.../ihd/save   （与前台同 Service）

hisihd 业务配置
  └── importClass = https://网关/.../ihd/save

hisihd-core-biz
  └── RestTemplate POST → 上述 URL

bsp