📚 课程目录第4章数据模型设计

4、数据模型设计：CAPA整改任务的数据结构、字段映射、状态枚举定义

CAPA（Corrective and Preventive Action）整改任务在追溯平台与OA系统之间同步时，核心难点在于双方数据模型的差异。本章定义一套标准化的中间数据模型，作为接口交互的契约，确保字段映射清晰、状态流转一致。

4.1 CAPA整改任务核心数据结构

下表定义了CAPA整改任务在接口传输中的标准字段结构，包含字段名称、类型、长度、必填标识及说明。

字段名	类型	长度	必填	说明
capaId	String	64	是	追溯平台CAPA唯一编号
title	String	256	是	整改任务标题
description	String	2000	是	问题描述与整改要求
sourceType	String	32	是	来源类型：audit / complaint / deviation / recall
sourceId	String	64	否	来源单据编号（如审核报告ID）
priority	Integer	2	是	优先级：1-紧急，2-高，3-中，4-低
assignee	String	64	是	责任人OA账号
deadline	DateTime	-	是	整改截止时间（ISO 8601格式）
status	String	32	是	当前状态枚举值
attachments	Array	-	否	附件文件URL列表
createdTime	DateTime	-	是	创建时间
updatedTime	DateTime	-	是	最后更新时间

设计要点：字段长度预留充分，description 支持 2000 字符以容纳详细整改要求；attachments 使用数组结构，便于扩展多文件场景。

4.2 字段映射：追溯平台 → OA系统

追溯平台与OA系统的字段命名和结构存在差异，必须建立明确的映射关系。下表列出关键字段的映射规则。

追溯平台字段	OA系统字段	映射规则
capaId	externalId	直接映射，作为OA侧外部关联ID
title	subject	直接映射
description	content	直接映射，OA侧自动追加来源标识
sourceType	category	枚举转换：audit→审核整改，complaint→投诉处理，deviation→偏差处理，recall→召回处理
priority	urgency	数值映射：1→紧急，2→重要，3→普通，4→低
assignee	responsiblePerson	直接映射，需确保OA账号存在
deadline	expectFinishTime	直接映射，格式统一为 yyyy-MM-dd HH:mm:ss
status	workflowStatus	状态枚举映射（详见4.3节）
attachments	fileList	URL列表转换为OA附件对象数组

    映射注意事项：category 字段在OA侧为下拉选择，必须确保枚举值精确匹配；deadline 字段需注意时区转换，统一使用北京时间（UTC+8）。

4.3 状态枚举定义与流转

CAPA整改任务的状态枚举是接口同步的核心，双方必须严格对齐。下表定义标准状态枚举及其含义。

枚举值	中文名称	说明	OA侧映射
PENDING	待接收	任务已创建，等待责任人接收	待处理
IN_PROGRESS	进行中	责任人已接收，正在整改	处理中
COMPLETED	已完成	整改措施已执行完毕	已完成
VERIFIED	已验证	整改效果已通过验证	已关闭
REJECTED	已驳回	整改不通过，需重新整改	退回
CANCELLED	已取消	任务被取消或关闭	已作废

状态流转遵循以下规则，确保追溯平台与OA系统状态同步一致。

正向流转：PENDING → IN_PROGRESS → COMPLETED → VERIFIED
逆向流转：IN_PROGRESS / COMPLETED → REJECTED → IN_PROGRESS
终止流转：PENDING / IN_PROGRESS → CANCELLED
禁止跳转：不允许从 PENDING 直接跳转到 VERIFIED 或 CANCELLED 以外的状态

状态同步风险：当OA侧状态为“退回”时，追溯平台必须将状态更新为 REJECTED，并触发重新整改流程；若状态映射错误，将导致双方数据不一致，影响CAPA闭环。

4.4 接口数据模型示例（JSON）

以下为创建CAPA整改任务时的完整请求体示例，展示字段结构与枚举值的实际使用。

{
  "capaId": "CAPA-2025-00123",
  "title": "供应商A批次20250315微生物超标整改",
  "description": "2025年3月15日来料检验发现微生物指标超标，要求供应商在7个工作日内完成原因分析并提交整改报告。",
  "sourceType": "audit",
  "sourceId": "AUDIT-2025-0089",
  "priority": 2,
  "assignee": "zhangsan@supplier.com",
  "deadline": "2025-03-28T18:00:00+08:00",
  "status": "PENDING",
  "attachments": [
    "https://trace.example.com/files/2025/03/report_001.pdf",
    "https://trace.example.com/files/2025/03/photo_002.jpg"
  ],
  "createdTime": "2025-03-19T10:30:00+08:00",
  "updatedTime": "2025-03-19T10:30:00+08:00"
}

接口设计建议：建议在接口文档中明确枚举值的全大写格式，避免因大小写不一致导致解析失败；deadline 字段统一使用带时区的 ISO 8601 格式，消除时区歧义。

4.5 数据校验规则

为确保接口数据质量，定义以下校验规则，在接收端进行强制验证。

必填校验：capaId、title、description、sourceType、priority、assignee、deadline、status 字段不可为空
枚举校验：sourceType 必须在 [audit, complaint, deviation, recall] 范围内；status 必须在 [PENDING, IN_PROGRESS, COMPLETED, VERIFIED, REJECTED, CANCELLED] 范围内
格式校验：deadline 必须符合 ISO 8601 格式；assignee 必须为有效的OA账号格式（邮箱或工号）
长度校验：title 不超过256字符；description 不超过2000字符；capaId 不超过64字符
业务校验：deadline 必须大于当前时间；priority 值必须在1-4之间

    校验失败处理：当校验不通过时，接口应返回明确的错误码和错误描述，例如：{"code": "INVALID_PARAM", "message": "status 枚举值无效，允许值：PENDING, IN_PROGRESS, COMPLETED, VERIFIED, REJECTED, CANCELLED"}，便于调用方快速定位问题。