增加重构文档

docs/enum_refactor/contract.md

@@ -0,0 +1,116 @@
+# Contract 领域重构指南
+
+## 1. 范围
+
+本文档只做 Contract 领域的项目侧梳理。
+
+当前优先关注：
+
+- `contract.contract_type`
+- `contract.code`
+- `contract.currency`
+
+## 2. 字段盘点
+
+### 2.1 `contract_type`
+
+当前实现：
+
+- `app/modules/contract/enums.py` 定义了 `ContractType`
+- 取值：`product`、`service`、`project`
+- `Contract` 模型里是 `String`
+- `ContractCreate` 里是 `str | None`
+- 同步 schema `schemas/contract/contract.py` 里也是 `str`
+
+当前使用：
+
+- 是合同主表核心分类字段
+- 合同结算服务里会按 `contract_type == "project"` 分支处理工程类合同
+
+项目侧取值范围：
+
+- `product`
+- `service`
+- `project`
+
+集团侧差异：
+
+- 集团侧 `enum_config.Contract.contract_type` 当前只有 `product`、`service`
+- 项目侧比集团侧多一个 `project`
+- 同步 schema 当前没有把它收紧成 enum
+
+结论：
+
+- 保留为代码 enum
+- 先统一“是否正式保留 `project`”
+
+### 2.2 `code`
+
+当前实现：
+
+- 模型里是普通 `String`
+- 没有本地正式 enum
+- 初始化侧实际依赖 `contract_config` / `contract_code_dict` / `supply_chain_group`
+
+当前使用：
+
+- 初始化合同时，`code` 承担业务子类型编码职责，例如 `EPC`、`PC`、`KY`、`JL`
+- 不是单纯的“自由合同编号”
+
+项目侧取值范围：
+
+- 当前无法从单一代码 enum 列出权威全集
+- 本地已明确出现的典型值包括：`EPC`、`PC`、`PF`、`CG`、`OSC`、`KY`、`JL`、`E`、`SCYW`、`ZJ`、`TY`、`NB`、`XB`、`ZB`、`GS`、`CN`、`QT`
+
+集团侧差异：
+
+- 集团侧 `enum_config.Contract.code` 已明确把这类值当成正式候选项，并且按项目类型变化
+- 同步 schema 里的 `code` 仍是普通 `str`
+- 项目侧现在没有把这组值沉成统一的字段配置或正式 enum
+
+结论：
+
+- 不建议继续当自由字符串处理
+- 更适合迁到 `field_config`，或至少统一走配置表来源
+
+### 2.3 `currency`
+
+当前实现：
+
+- 模型里是 `String`
+- 默认值 `CNY`
+- schema 里是普通字符串
+
+当前使用：
+
+- 当前主要是合同基础信息字段
+- 没看到复杂分支逻辑
+
+项目侧取值范围：
+
+- 当前代码里唯一明确值是默认值 `CNY`
+
+集团侧差异：
+
+- 当前没看到集团侧 `enum_config` 对这个字段给出正式候选项
+- 同步 schema 里也是 `str`
+
+结论：
+
+- 先保持字符串字段
+- 如果未来真的出现多币种，再决定是否需要正式枚举
+
+## 3. 重点结论
+
+- `contract_type` 应保留为代码 enum，但要先明确是否保留 `project`。
+- `code` 当前实际上承担合同业务子类型职责，不应继续当自由字符串处理。
+- `currency` 当前没有足够证据说明要做枚举化。
+
+## 4. 待修改项清单
+
+1. 统一 `ContractType` 的正式定义源。
+2. 确认 `contract_type=project` 是否继续作为正式值保留。
+3. 为 `contract_type` 在 schema 层补 enum 校验。
+4. 把 `contract.code` 从“自由字符串”改成统一配置来源。
+5. 评估 `contract.code` 是否直接迁到 `field_config`。
+6. 区分清楚 `contract.code` 与“合同编号/contract_sn”的职责，避免一个字段同时承担两层语义。