外观
UmiUDI 后端 API 补全与扩展实施方案
🎯 方案概述
为了将现有的 UmiUDI - API 从“单一支付与基础查询接口”升级为面向全业务域的高性能微服务体系,我们针对 Models 层现存的 42 个核心数据库实体,制定了本套 API 接口补全与系统扩展实施方案。
本方案旨在补全涵盖 UDI DI 基础库、生产登记(SCD)、质检合规(ZJ)、仓储出入库(CK)以及 ERP 第三方同步在内的核心业务 API,并提供标准化的企业级规范,作为后续开发和技术交接的权威技术文档。
📡 核心技术栈与开发标准
- 宿主框架:ASP.NET Core on .NET 9 (高并发、跨平台)
- 数据访问:Entity Framework Core 结合
umi_basicContext(已自动映射全部 42 张业务表),复杂与统计查询选用 Linq 或 Dapper 执行高效只读检索。 - 输出规范:采用统一响应封装器
ReturnCodes规范 JSON 输出结构。 - 接口安全:生产环境(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_downloadvs 本地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。