# 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` 跟随合同主表时，不出现与合同主表不一致的脏数据。