ecm_sync_system/docs/enum_refactor/contract_settlement.md

Contract Settlement 领域重构指南

1. 范围

本文档对应 backend 的 contract_settlement 主表。

当前优先关注：

• contract_settlement.contract_type
• contract_settlement.status
• contract_settlement.payment_method

2. 字段盘点

2.1 contract_type

当前实现：

• 模型里是 String
• 没有单独 enum 类型绑定到模型

项目侧取值范围：

• 当前主要跟随关联合同的 contract_type
• 代码现状至少包含：product、service、project

集团侧差异：

• 集团侧 enum_config.ContractSettlement.contract_type 当前只有 product、service
• 项目侧如果继续沿用 project，会比集团侧多一个值
• 当前仓库里没有 standalone 的同步 schema 来收紧这个字段

结论：

• 先与合同主表 contract_type 保持一致
• 再确认结算领域是否允许 project

2.2 status

当前实现：

• 模型里是 SmallInteger
• 默认值 0

项目侧取值范围：

• 当前没有独立 enum 类
• 从集团侧和现有语义看，应至少覆盖 -1、0、1

集团侧差异：

• 集团侧 enum_config.ContractSettlement.status 明确给出 -1、0、1
• 项目侧模型没有沉成统一常量或 enum

结论：

• 应补统一状态定义源

2.3 payment_method

当前实现：

• 本地 PaymentMethod enum 有两个值：node_payment、progress_payment
• 模型里仍是 String
• SettlePaymentMethodsSelect 手动校验合法值

当前使用：

• 合同结算服务会按 payment_method 分支校验和处理

项目侧取值范围：

• node_payment
• progress_payment

集团侧差异：

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

结论：

• 保留为本地代码 enum
• 需要把“手动 validator”提升为统一 schema / service 约束

3. 重点结论

• contract_settlement 里最稳定的枚举字段是 payment_method，应继续保留为代码 enum。
• contract_type 不能单独拍板，必须跟合同主表一起决定是否保留 project。
• status 当前只是模型整数，没有正式定义源，需要补齐。

4. 待修改项清单

1. 明确 contract_settlement.contract_type 是否允许 project。
2. 为 status 补正式常量或 enum 定义。
3. 将 payment_method 的合法值校验统一沉到正式 schema/enum，而不是只在个别 schema 手动校验。
4. 明确结算主表与合同主表在 contract_type 上是否必须同源。

5. 按本轮要求的改造落点

contract_settlement 领域不属于项目初始化第一批重点，但它直接涉及“写死下拉改动态”这件事。

5.1 初始化

本领域当前没有独立的项目初始化候选项链路。

contract_type 主要跟随合同主表，payment_method 主要出现在结算业务选择和后续分支处理中。

5.2 Create / 业务校验

当前 payment_method 的合法值主要靠：

• PaymentMethod enum
• SettlePaymentMethodsSelect schema 里的手动 validator

而 service payment_methods_select() 本身没有再做额外校验。

本轮目标是：

• 保留 payment_method 的固定语义 enum 属性
• 但在业务层入口也要能通过统一 config 工具或统一 enum 工具做显式校验
• 不把校验只留在 schema 里

5.3 下拉列表

当前支付方式只有选择接口，没有正式的动态下拉接口。

因此这轮要补的不是“替换已有动态接口”，而是：

• 把现有写死支付方式候选项明确收口
• 如果前端需要单独下拉接口，应改成动态返回，而不是继续依赖前端或 schema 写死

同理，payment_type、advance_type 这类当前靠本地 enum 固定的候选项，也应按同样思路处理。

5.4 清理项

本轮 contract_settlement 领域完成后，应避免继续保留：

• 只存在于 schema validator、但没有统一出口的支付方式候选项定义
• 前端和后端各自写死一份支付方式列表

6. 测试关注点

contract_settlement 领域 service 层集成测试至少覆盖：

1. payment_method 合法值更新成功，非法值明确报错。
2. 如果补了下拉接口，下拉返回是否与 service 校验同源。
3. contract_type 跟随合同主表时，不出现与合同主表不一致的脏数据。