3. 传递单模型设计：数据结构与字段定义
传递单是审查意见驱动流程的核心载体，其数据结构设计直接决定了接口调用的效率与变更记录的完整性。本节将定义传递单的字段规范，并给出符合企业级集成要求的模型设计。
3.1 核心字段定义
传递单模型包含以下关键字段，每个字段均对应明确的业务语义与接口约束：
| 字段名 | 类型 | 长度/格式 | 必填 | 说明 |
|---|---|---|---|---|
| ID | UUID / 自增整数 | 36 字符 / 64 位 | 是 | 全局唯一标识，用于接口幂等与追溯 |
| 标题 | 字符串 | 1~200 字符 | 是 | 传递单摘要，如“API 接口变更-订单模块” |
| 状态 | 枚举 | DRAFT / PENDING / APPROVED / REJECTED / CLOSED | 是 | 驱动流程流转的核心状态机 |
| 发起人 | 字符串 | 用户 ID 或工号 | 是 | 创建传递单的责任人 |
| 接收人 | 字符串 | 用户 ID 或工号 | 是 | 当前待办或最终审批人 |
| 审查意见列表 | 数组 | 每个元素包含：意见ID、审查人、时间、内容、结论 | 否 | 按时间排序的审查记录集合 |
设计要点： 审查意见列表采用嵌入式数组而非独立表，是为了在单次接口调用中完整返回审查链路，减少跨表 JOIN 带来的性能开销。当意见数量超过 100 条时，建议启用分页加载。
3.2 状态机与流转规则
传递单的状态变更遵循严格的有限状态机模型，每个状态转换均需触发对应的审查意见记录：
- DRAFT → PENDING： 发起人提交传递单，系统自动生成初始审查意见占位。
- PENDING → APPROVED： 接收人审查通过，意见列表追加“同意”记录。
- PENDING → REJECTED： 接收人驳回，意见列表追加驳回原因，传递单返回 DRAFT。
- APPROVED → CLOSED： 变更执行完毕，系统自动关闭传递单。
- REJECTED → DRAFT： 发起人修改后重新提交，状态重置。
接口设计提示： 每次状态变更必须同时写入审查意见列表，确保“状态 + 意见”在同一个事务中完成，避免数据不一致。
3.3 传递单数据结构（JSON 示例）
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "订单查询接口字段变更",
"status": "PENDING",
"initiator": "zhang.san",
"receiver": "li.si",
"review_comments": [
{
"comment_id": "c001",
"reviewer": "li.si",
"timestamp": "2025-03-21T10:30:00Z",
"content": "字段命名需符合驼峰规范，建议将 order_id 改为 orderId。",
"conclusion": "REJECTED"
},
{
"comment_id": "c002",
"reviewer": "zhang.san",
"timestamp": "2025-03-21T11:00:00Z",
"content": "已按规范修改，请重新审查。",
"conclusion": "REVISE"
}
]
}3.4 传递单模型架构图
下图展示了传递单模型的核心结构及其与审查意见列表的关系：
3.5 审查意见列表的详细结构
审查意见列表中的每个元素包含以下子字段，确保审查过程可追溯：
| 子字段 | 类型 | 说明 |
|---|---|---|
| comment_id | UUID | 意见唯一标识，用于后续引用或回复 |
| reviewer | 字符串 | 审查人工号或用户名 |
| timestamp | ISO 8601 | 审查时间，精确到毫秒 |
| content | 文本 | 审查意见正文，支持 Markdown 格式 |
| conclusion | 枚举 | APPROVED / REJECTED / REVISE / COMMENT |
注意事项： 审查意见列表的
conclusion 字段与传递单主状态必须保持逻辑一致。例如，当传递单状态为 APPROVED 时，最后一条审查意见的结论必须为 APPROVED，否则视为数据异常。
3.6 模型设计原则总结
- 原子性： 传递单与审查意见列表在同一个聚合根内，确保事务一致性。
- 可追溯： 每次状态变更均生成审查意见记录，形成完整的审计轨迹。
- 可扩展： 审查意见列表支持追加、分页查询，未来可扩展附件或标签字段。
- 接口友好： 单次 GET 请求即可获取传递单全貌，减少接口调用次数。