# 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. 明确结算明细审批状态与通用审批体系的正式映射。