82 lines
4.9 KiB
Markdown
82 lines
4.9 KiB
Markdown
# 供应商新增工商与合作信息字段 — 设计文档
|
||
|
||
**日期**：2026-04-24
|
||
**范围**：在 `Factory`（供应商）模型上新增 3 个业务字段，并在前端列表、表单、详情页同步展示/编辑。
|
||
|
||
## 目标
|
||
|
||
满足供应商资料登记的新业务要求：
|
||
1. 工商注册信息 — 本期仅记录**统一社会信用代码**（其余工商字段本期不做）
|
||
2. **交互能力** — 包含最大月供量、常规库存量、生产周期、运输方式、应急供货响应时间等信息（本期先用单个大文本框承载）
|
||
3. **合作模式** — 厂家直供 / 授权代理商 二选一
|
||
|
||
## 新增字段
|
||
|
||
| 字段 | DB 类型 | DB 约束 | 表单必填 | 校验规则 |
|
||
|---|---|---|---|---|
|
||
| `unified_social_credit_code` 统一社会信用代码 | `CharField(max_length=18)` | `null=True, blank=True` | ✅ 必填 | 正则 `^[0-9A-Z]{18}$` — 长度 18，仅数字 + 大写字母 |
|
||
| `interaction_capability` 交互能力 | `TextField` | `null=True, blank=True` | 选填 | 无；前端 textarea 的 placeholder 提示："最大月供量 / 常规库存量 / 生产周期 / 运输方式 / 应急供货响应时间" |
|
||
| `cooperation_mode` 合作模式 | `CharField(max_length=20, choices=COOPERATION_MODE_CHOICES)` | `null=True, blank=True` | ✅ 必填 | choices: `direct='厂家直供'`, `authorized='授权代理商'` |
|
||
|
||
### 存量数据策略
|
||
|
||
三个字段在数据库层均允许为空（`null=True, blank=True`），用以兼容已有的供应商记录。前端表单和后端 serializer 在新增/编辑时强制校验"必填"字段。
|
||
|
||
对用户行为的影响：
|
||
- 历史供应商记录在列表/详情页展示为 `-`
|
||
- 用户第一次编辑历史供应商时，两个"必填"字段必须补齐才能保存，否则前/后端都会拦截
|
||
|
||
### 校验位置
|
||
|
||
| 校验点 | 统一社会信用代码 | 合作模式 | 交互能力 |
|
||
|---|---|---|---|
|
||
| 前端 `el-form rules` | 必填 + 正则 | 必填（在 choices 内） | 无 |
|
||
| 后端 `serializer.validate_*` | 必填 + 正则 | 必填（在 choices 内） | 无 |
|
||
|
||
后端 `null=True, blank=True` 的字段在序列化器层面仍然通过 `required=True` 覆盖为必填。
|
||
|
||
## 改动清单
|
||
|
||
### 后端 `backend/apps/factory/`
|
||
|
||
- **`models.py`**：
|
||
- 在 `Factory` 模型上新增 3 个字段
|
||
- 新增常量 `COOPERATION_MODE_CHOICES = [('direct', '厂家直供'), ('authorized', '授权代理商')]`
|
||
- **`migrations/0005_add_business_info.py`**：新增 3 字段的 Django migration
|
||
- **`serializers.py`**：
|
||
- `FactorySerializer.Meta.fields` 追加 3 个字段
|
||
- `FactorySerializer` 新增 `cooperation_mode_display` 只读字段（`source='get_cooperation_mode_display'`）
|
||
- `FactorySerializer` 新增 `validate_unified_social_credit_code` 方法做正则校验 + 必填
|
||
- `FactorySerializer` 对 `unified_social_credit_code` 和 `cooperation_mode` 显式 `required=True, allow_null=False, allow_blank=False` 覆盖模型的 null/blank
|
||
- `FactoryListSerializer.Meta.fields` 追加 `cooperation_mode` 和 `cooperation_mode_display`
|
||
|
||
### 前端 `frontend/src/views/`
|
||
|
||
- **`FactoryManage.vue`**：
|
||
- 列表在"经销商"列之后新增「合作模式」列（`min-width: 120`，显示 `cooperation_mode_display`）
|
||
- dialog 表单新增 3 个表单项：
|
||
- 统一社会信用代码 — `<el-input>`，含 form rules（必填 + 正则）
|
||
- 合作模式 — `<el-select>`（厂家直供 / 授权代理商），含 form rules（必填）
|
||
- 交互能力 — `<el-input type="textarea">`，提示语 placeholder，3~6 行高度
|
||
- `form` reactive 对象新增 3 个字段；`resetForm()` 同步新增
|
||
- `onSubmit` 前走 `formRef.validate()`；新增 form rules 定义
|
||
- **`FactoryDetail.vue`**：
|
||
- `<el-descriptions>` 新增 3 行：统一社会信用代码、合作模式（使用 `cooperation_mode_display`）、交互能力
|
||
- 交互能力内容可能较长，需保持换行（`white-space: pre-wrap`）
|
||
|
||
## 非目标（YAGNI）
|
||
|
||
- 工商注册信息中的注册资本/注册地址/法人代表/营业期限/实缴资本/认缴资本等字段本期不做
|
||
- 资质证书（生产许可证、安全生产许可证、绿色建材认证、ISO 三体系等）本期不做
|
||
- 交互能力本期不拆分为结构化子字段（如独立的月供量/库存量/生产周期字段）。后续如有按字段检索/对比的需求再演进
|
||
- 统一社会信用代码本期不做末位校验码算法验证
|
||
- 文件上传、附件管理本期不涉及
|
||
|
||
## 验收
|
||
|
||
- [ ] 新建供应商：填完所有必填字段（含新增的 2 个必填）能成功保存；任一必填字段留空或格式错时，前/后端都拦截
|
||
- [ ] 编辑历史供应商（历史字段为空）：必须补齐两个必填字段后才能保存
|
||
- [ ] 列表页展示「合作模式」列，值为中文标签（"厂家直供"/"授权代理商"），历史数据显示 `-`
|
||
- [ ] 详情页展示三个新字段；历史数据显示 `-`
|
||
- [ ] 统一社会信用代码校验：长度非 18 或含小写字母/非字母数字字符被拦截
|