增加项目侧重构文档

2026-03-12 14:54:48 +08:00
parent 758b1c4f77
commit 84b3b7652a
16 changed files with 1485 additions and 458 deletions
@@ -114,3 +114,79 @@
 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 明确报错。
+