strepsiades
202 lines
5.5 KiB
Markdown
202 lines
5.5 KiB
Markdown
# 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 层增加统一校验入口。
|
||
|
||
## 5. 按本轮要求的改造落点
|
||
|
||
material 是本轮最需要针对性改造的领域之一，因为它当前同时存在：
|
||
|
||
- 初始化来源分叉
|
||
- create 校验分叉
|
||
- 下拉来源分叉
|
||
|
||
### 5.1 初始化
|
||
|
||
当前 material 初始化不是单源：
|
||
|
||
- 候选项来自 `contract_config` 里的 product 合同
|
||
- 单位和部分展示信息来自 `material_contract_{project_type}` dict
|
||
|
||
而且 `unit` 现在还挂在 dict `remark` 上。
|
||
|
||
本轮目标是：
|
||
|
||
- 明确 `material.material_type` 的正式配置来源
|
||
- 把 `label`、`unit`、`parts` 等附属字段纳入正式 config 结构
|
||
- 去掉“从 dict remark 补单位”这种不适当用法
|
||
|
||
### 5.2 Create 校验
|
||
|
||
当前 create 路径里：
|
||
|
||
- `material_type` 入参本身没有正式 config 校验
|
||
- `show_name`、`unit` 由 `contract_product_type_list` 反查
|
||
- 随后又会调用合同创建，由合同 service 再做一层 code 白名单校验
|
||
|
||
这说明 material create 现在不是单一入口校验。
|
||
|
||
本轮目标是：
|
||
|
||
- 在 `MaterialService.create()` 开头基于 config 校验 `material_type`
|
||
- 用 `get_field_option_map()` 之类的方法直接拿 `label`、`unit`、`parts`
|
||
- 不再依赖 `contract_product_type_list` 和默认兜底值
|
||
|
||
### 5.3 下拉列表
|
||
|
||
当前物资下拉已经部分走 config：
|
||
|
||
- `/material/material-types` 读 `material_types`
|
||
- `/material-detail/contract-product-type/list` 也读 `material_types`
|
||
|
||
但模块里仍保留了旧的硬编码路径：
|
||
|
||
- `get_material_info_by_code()`
|
||
- `get_kit_options()`
|
||
- `contract_product_type_list`
|
||
|
||
本轮目标是：
|
||
|
||
- 让物资类型和部件列表统一从新的 config 工具返回
|
||
- 下拉、初始化、create 校验全部围绕同一套 `material_type` 配置
|
||
|
||
### 5.4 清理项
|
||
|
||
material 领域这轮改造完成后，应优先清理：
|
||
|
||
- `material_contract_*` 中用 `remark` 承载单位的旧逻辑
|
||
- `contract_product_type_list` 里只服务于 `material_type` 真源的旧定义
|
||
- `get_material_info_by_code()` 这类旧反查入口
|
||
|
||
## 6. 测试关注点
|
||
|
||
material 领域 service 层集成测试至少覆盖：
|
||
|
||
1. 初始化：项目初始化后 material 的 `material_type`、`show_name`、`unit` 是否来自目标 config。
|
||
2. 下拉：物资类型和部件列表是否来自同一 config，且与初始化同源。
|
||
3. Create：合法 `material_type` 能创建，非法 `material_type` 明确报错，不再依赖默认兜底。
|
||
|