ecm_sync_system/docs/enum_refactor/contract_settlement_detail.md

Contract Settlement Detail 领域重构指南

1. 范围

本文档对应 backend 的 contract_settlement_detail 明细表。

当前优先关注：

• contract_settlement_detail.payment_type
• contract_settlement_detail.advance_type
• contract_settlement_detail.approval_status

2. 字段盘点

2.1 payment_type

当前实现：

• 本地 PaymentType enum 定义在 app/modules/contract/enums.py
• 取值：advance、progress、settlement
• 模型里是 String
• PostDetailData schema 里已使用 PaymentType | None

当前使用：

• 结算服务会按 payment_type 分支处理，例如预付款与进度款逻辑不同

项目侧取值范围：

• advance
• progress
• settlement

集团侧差异：

• 当前没看到集团侧 enum_config 为结算明细单独列出该字段
• 当前仓库也没有 standalone 的同步 schema 对应 contract_settlement_detail

结论：

• 保留为代码 enum
• 这是少数已经在 schema 层显式使用 enum 的字段，应该延续这种做法

2.2 advance_type

当前实现：

• 本地 AdvanceType enum 取值：project、product、service
• 模型里是 String
• PostDetailData schema 里已使用 AdvanceType | None

项目侧取值范围：

• project
• product
• service

集团侧差异：

• 当前没看到集团侧 enum_config 为该字段给出正式候选项
• 当前仓库也没有 standalone 的同步 schema 对照该字段

结论：

• 保留为代码 enum

2.3 approval_status

当前实现：

• 模型依赖 ApprovalMixin
• 结算明细服务强依赖审批流

项目侧取值范围：

• 当前跟随通用审批状态体系
• 本领域自身没有单独 enum 文件

集团侧差异：

• 当前没看到 standalone 的同步 schema 对这个明细领域建模

结论：

• 接入通用审批定义即可

3. 重点结论

• payment_type、advance_type 已经是本地相对成熟的代码 enum，用法比结算主表更收敛。
• 这一层不需要优先迁 field_config，重点是把模型层和 schema 层收口一致。
• approval_status 继续走通用审批定义即可。

4. 待修改项清单

1. 将 payment_type、advance_type 保持为正式 enum，不要退回自由字符串。
2. 评估模型层是否也要收紧，而不只是 schema 层使用 enum。
3. 明确结算明细审批状态与通用审批体系的正式映射。