跳转到正文

UmiUDI 后端 API 补全与扩展实施方案 ​

🎯 方案概述 ​

为了将现有的 UmiUDI - API 从“单一支付与基础查询接口”升级为面向全业务域的高性能微服务体系,我们针对 Models 层现存的 42 个核心数据库实体,制定了本套 API 接口补全与系统扩展实施方案。

本方案旨在补全涵盖 UDI DI 基础库、生产登记(SCD)、质检合规(ZJ)、仓储出入库(CK)以及 ERP 第三方同步在内的核心业务 API,并提供标准化的企业级规范,作为后续开发和技术交接的权威技术文档。


📡 核心技术栈与开发标准 ​

  1. 宿主框架:ASP.NET Core on .NET 9 (高并发、跨平台)
  2. 数据访问:Entity Framework Core 结合 umi_basicContext(已自动映射全部 42 张业务表),复杂与统计查询选用 Linq 或 Dapper 执行高效只读检索。
  3. 输出规范:采用统一响应封装器 ReturnCodes 规范 JSON 输出结构。
  4. 接口安全:生产环境(Production)默认关闭 Swagger 文档;内部接口采用 JWT Bearer Token / API Key 进行调用鉴权。

🛠️ API 控制器补全路线图与设计 ​

根据现有的 42 个实体模型的业务关联度,我们将 API 补全计划划分为 5 个专有业务控制器域:

mermaid
graph TD
    API[UmiUDI - API] --> DI[DiController - P0]
    API --> SCD[UdiScdController - P0]
    API --> ZJ[UdiZjController - P1]
    API --> CK[CkController - P1]
    API --> ERP[ErpController - P2]

1. DiController (DI 信息与药监同步域 - 🥇 P0) ​

  • 覆盖模型:di、di_csdm、di_status、di_gen、di_download、di_yjj_draft、di_yjj_publish 等。
  • 业务描述:用于管理医疗器械唯一标识的产品标识(DI)主数据,提供新增、属性维护、包装层级关联、以及与国家药监局(NMPA)数据中心对接的桥梁。
  • 接口规约:
    • GET /api/di:分页拉取本企业登记的 DI 主数据列表(支持商品名称、规格型号模糊检索)。
    • POST /api/di:首次录入器械 DI 编码与属性信息。
    • PUT /api/di/{id}:修改现有 DI 属性(触发 di_status.update_time 时效更新)。
    • POST /api/di/sync-yjj:将本地 DI 数据同步至国家药监局申报草稿表(di_yjj_draft)或正式发布表(di_yjj_publish)。
    • GET /api/di/download:拉取或比对药监局下发的产品标识主数据(di_download vs 本地 di),自动诊断信息一致性。

2. UdiScdController (生产首次登记与追溯域 - 🥇 P0) ​

  • 覆盖模型:udi_scd、udi_scd_detail、udi_scd_review。
  • 业务描述:生产首次登记(SCD)是 UDI 追溯的起点。用于记录生产批号、有效期、序列号等 PI 信息,并绑定生成的 UDI 完整条码。
  • 接口规约:
    • GET /api/scd:分页查询生产登记总表(含生产日期、操作人)。
    • POST /api/scd:批量上传生产首次赋码关系(保存至主表 udi_scd 与明细表 udi_scd_detail)。
    • GET /api/scd/{scdId}/details:拉取指定生产批次下所有的单品级 UDI 条码与序列号清单。
    • POST /api/scd/review:提交/保存生产数据的双人审核记录(udi_scd_review),以满足 GMP 附录中对关键控制点“双人复核并电子签名”的严苛合规要求。

3. UdiZjController (条码打印与质量控制域 - 🥈 P1) ​

  • 覆盖模型:udi_cj、udi_cj_review、udi_dy、udi_dy_detail、udi_dy_review 等。
  • 业务描述:处理条码打印(DY)、采集检验(CJ)和质量控制。提供条码物理分级报告、缺陷诊断、以及审计审核流。
  • 接口规约:
    • GET /api/zj/print-jobs:查询标签打印作业记录(udi_dy)及打印明细(udi_dy_detail)。
    • POST /api/zj/records:保存质检仪采集上报的条码验证记录(物理反射率、调制比、对比度、符号等级,写入 udi_cj)。
    • GET /api/zj/defect-report:分析条码缺陷,自动过滤识别出符号等级低于 C 级的低劣条码,提供预警。
    • POST /api/zj/review:对条码首检、巡检与出厂放行批次执行多级主管审核(udi_cj_review / udi_dy_review),写入数字审核戳。

4. CkController (智能仓储与扫码出入库域 - 🥈 P1) ​

  • 覆盖模型:ck_inout、ck_inout_detail、ck_inout_review、ck_inout_detail_review。
  • 业务描述:仓储管理是 UDI 动态合规流通的关键。该控制器负责扫码出库、入库、退货入库的记录上报与追溯。
  • 接口规约:
    • GET /api/ck/inout:分页获取仓库出入库历史记录总表。
    • POST /api/ck/inout:保存客户端扫码枪上传的批量出入库 UDI 条码包,并向明细表 ck_inout_detail 差量写入关联的数据。
    • GET /api/ck/trace/{udi}:正向追溯——通过单品 UDI 直接反查其出入库流向及当前所在的物理库位。
    • POST /api/ck/review:记录出入库单据的终审、盘点复核人员电子签名链(ck_inout_review 与 ck_inout_detail_review)。

5. ErpController (第三方 ERP 同步与业务流转域 - 🥉 P2) ​

  • 覆盖模型:erp_scdd(生产订单)、erp_sclld(领料单)、erp_scrkd(入库单)、erp_xsckd(销售出库)、erp_xsthd(销售退货)等。
  • 业务描述:作为与外部 ERP 接口(如 SAP, 用友, 金蝶)双向同步的统一总线,拉取上游单据作为赋码依据,并将赋码 UDI 结果回写外部系统。
  • 接口规约:
    • POST /api/erp/sync-scdd:从 ERP 拉取/同步最新下达的生产计划订单(erp_scdd),作为系统打印条码的任务源。
    • POST /api/erp/sync-sclld:同步原材料/半成品生产领料单(erp_sclld),建立 UDI 单品与原材料批次的血统追溯。
    • POST /api/erp/xsckd:同步销售发货出库单(erp_xsckd),记录每个客户发货关联的精确 UDI 单品条码。
    • POST /api/erp/xsthd:同步退货入库单(erp_xsthd),防范未赋码及假冒伪劣退货器械进入合法流通链。

🔒 统一规范与安全设计 ​

1. 统一响应格式 ​

所有新扩展的 API 必须通过通用包装器返回,确保客户端能够高效解析并提供友好提示:

json
{
  "code": 200,          // 200-成功, 400-请求错误, 401-未授权, 500-服务器错误
  "success": true,
  "message": "操作成功",
  "data": { ... }       // 具体的数据体或分页明细
}

2. 审计追踪与日志规范 ​

针对所有修改、删除 DI 及 UDI 核心数据的 API,必须在切面(AOP Filter)中拦截并自动向操作日志表中记录:

  • 操作人 ID (sys_user.id)、操作时间、客户端 IP、操作类型(增/删/改)
  • 变更前后的实体快照(方便药监飞检时一键导出审计追踪日志)。

3. Swagger 文档受控与生产防暴露 ​

  • 硬性隔离:如已在 Program.cs 中实现,Swagger UI 仅在 Development 环境启用。
  • 分级授权:在开发环境下访问 Swagger UI 时,涉及核心 ERP 同步与敏感支付校验的接口,必须在 Swagger 顶部的 Authorize 锁图标中填入合规的开发者鉴权 Token。

UmiUDI & Drug 医疗器械与药品唯一标识全生命周期追溯系统