mat/docs/superpowers/specs/2026-04-24-supplier-busines...

4.9 KiB
Raw Blame History

供应商新增工商与合作信息字段 — 设计文档

日期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 方法做正则校验 + 必填
    • FactorySerializerunified_social_credit_codecooperation_mode 显式 required=True, allow_null=False, allow_blank=False 覆盖模型的 null/blank
    • FactoryListSerializer.Meta.fields 追加 cooperation_modecooperation_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">,提示语 placeholder3~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 或含小写字母/非字母数字字符被拦截