增加重构文档

2026-03-12 14:23:15 +08:00
parent 0ae2db1808
commit 758b1c4f77
16 changed files with 1626 additions and 15 deletions
@@ -0,0 +1,127 @@
+# Material 领域重构指南
+
+## 1. 范围
+
+本文档只做 Material 主表梳理。
+
+当前优先关注：
+
+- `material.material_type`
+- `material.status`
+- `material.supply_status`
+- `material.approval_party`
+
+## 2. 字段盘点
+
+### 2.1 `material_type`
+
+当前实现：
+
+- 本地没有独立 enum 类
+- 主要来源是 `contract_product_type_list`
+- 模型里是 `String`
+- 创建 schema 里是 `str`
+- 同步 schema 里也是 `str`
+
+当前使用：
+
+- 是物资主类型字段
+- schema 示例和业务逻辑都直接依赖 `contract_product_type_list`
+
+项目侧取值范围：
+
+- 当前本地明确值：`TY`、`ZJ`、`NB`、`XB`、`ZB`、`GS`、`CN`、`DL`、`XT`、`CBJDB`、`SX`、`ECXT`、`QT`
+
+集团侧差异：
+
+- 集团侧 `enum_config.Material.material_type` 是按项目类型变化的
+- 光伏下有：`ZJ`、`TY`、`NB`、`XB`、`ZB`、`GS`、`CN`、`QT`
+- 陆风/海风下有：`FJ`、`TT`、`XB`、`ZB`、`GS`、`CN`、`QT`
+- 项目侧当前使用的本地列表明显偏光伏，且代码里还存在命名差异：例如本地用 `XT` / `CBJDB` / `SX` / `ECXT`，集团侧常见的是 `35KV` / `CYJD` / `SVG` / `ECPG`
+- 同步 schema 里 `material_type` 仍是 `str`
+
+结论：
+
+- 应迁到 `field_config`
+- 不能继续只靠本地 `contract_product_type_list`
+
+### 2.2 `status`
+
+当前实现：
+
+- 模型里是 `SmallInteger`
+- 同步 schema 里是 `Optional[int]`
+
+项目侧取值范围：
+
+- 当前未看到单独 enum 类
+- 现有注释和使用都表明它是数值状态字段
+
+集团侧差异：
+
+- 集团侧 `enum_config.Material.status` 给的是 `-1`、`0`、`1`
+- 项目侧没有在 material 模块里沉成统一常量
+
+结论：
+
+- 应统一正式状态定义源
+
+### 2.3 `supply_status`
+
+当前实现：
+
+- 模型里是 `SmallInteger`
+- 本地有 `SupplyStatus` enum：`-1`、`0`、`1`、`None`
+
+项目侧取值范围：
+
+- `-1`
+- `0`
+- `1`
+- `None`
+
+集团侧差异：
+
+- 集团侧 Material.status 也是按 `-1`、`0`、`1` 表达进度状态
+- 项目侧存在 `status` 和 `supply_status` 两个相近字段，语义有重叠
+
+结论：
+
+- 需要明确 `status` 和 `supply_status` 哪个才是正式推送字段
+
+### 2.4 `approval_party`
+
+当前实现：
+
+- 模型里是 `String`
+- schema 里是 `str`
+- 当前示例值是 `jiagong`、`yigong`
+
+项目侧取值范围：
+
+- `jiagong`
+- `yigong`
+
+集团侧差异：
+
+- 当前没看到集团侧 `enum_config` 对这个字段给出正式候选项
+- 同步 schema 里也没有这个字段
+
+结论：
+
+- 先保留本地代码级候选项
+- 后续如需推送再决定是否外提
+
+## 3. 重点结论
+
+- `material_type` 是标准的 `field_config` 候选字段，不能再继续绑死在本地光伏型列表上。
+- `status` 与 `supply_status` 当前语义重叠，必须先定正式推送字段。
+- `approval_party` 暂时还是本地专有字段，不需要现在就硬并到集团侧。
+
+## 4. 待修改项清单
+
+1. 将 `material_type` 正式迁到 `field_config`。
+2. 按项目类型重建 `material_type` 候选项，不再只用本地光伏型列表。
+3. 统一 `35KV/XT`、`CYJD/CBJDB`、`SVG/SX`、`ECPG/ECXT` 这类命名差异。
+4. 明确 `status` 与 `supply_status` 的职责边界。
+5. 为 `material_type` 在 schema 层增加统一校验入口。