strepsiades
193 lines
5.1 KiB
Markdown
193 lines
5.1 KiB
Markdown
# 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”的职责，避免一个字段同时承担两层语义。
|
|
|
|
## 5. 按本轮要求的改造落点
|
|
|
|
contract 领域本轮要直接收口 3 条链路：
|
|
|
|
- 初始化
|
|
- create 校验
|
|
- 下拉列表
|
|
|
|
### 5.1 初始化
|
|
|
|
当前合同初始化已经走 `contract_config`。
|
|
|
|
因此这轮初始化改造的核心不是重做合同初始化，而是：
|
|
|
|
- 把 `contract.code` 明确成正式字段级配置来源
|
|
- 后续让合同初始化、物资初始化、前端下拉都围绕这套配置工作
|
|
|
|
`contract_type` 继续保留为代码 enum，不迁到 `field_config`。
|
|
|
|
### 5.2 Create 校验
|
|
|
|
当前 `ContractService.create()` 的校验主要依赖：
|
|
|
|
- `contarct_type_dict`
|
|
- `contract_code_dict`
|
|
- service / product 的硬编码白名单
|
|
|
|
这和初始化使用的 `contract_config` 不是同一真源。
|
|
|
|
本轮目标是：
|
|
|
|
- `contract_type` 继续按代码 enum 校验
|
|
- `contract.code` 改成通过新的 config 工具校验
|
|
- 避免继续新增 `if contract_type == ... and code in [...]` 这种硬编码白名单
|
|
|
|
### 5.3 下拉列表
|
|
|
|
当前合同下拉接口：
|
|
|
|
- `/contract/type/list`
|
|
- `/contract/sub-type/list`
|
|
|
|
其中：
|
|
|
|
- `type/list` 直接读代码字典
|
|
- `sub-type/list` 先写死过滤列表，再读代码字典
|
|
|
|
这和初始化 `contract_config` 不一致。
|
|
|
|
本轮目标是：
|
|
|
|
- 合同类型列表继续由代码 enum 提供
|
|
- 合同子类型列表改为动态读取 config
|
|
- 保证前端看到的 code 列表和初始化、create 校验同源
|
|
|
|
### 5.4 清理项
|
|
|
|
本轮 contract 领域改造完成后，应清理：
|
|
|
|
- 只用于 `contract.code` 下拉和校验的旧硬编码 code 白名单
|
|
- 只承担旧合同子类型翻译的代码字典入口
|
|
|
|
但下面这些不应误删：
|
|
|
|
- `ContractType` enum
|
|
- 其它真正稳定的固定语义 enum
|
|
|
|
## 6. 测试关注点
|
|
|
|
contract 领域 service 层集成测试至少覆盖：
|
|
|
|
1. 初始化：`contract_config` 能正确初始化合同，并继续驱动下游结算/物资链路。
|
|
2. 下拉：合同子类型下拉是否来自目标 config，且与初始化 code 集一致。
|
|
3. Create：合法 `contract_type + code` 创建成功，非法 code 明确报错。
|
|
|