Files
shanxia2.0/docs/superpowers/plans/2026-07-26-crm-supplier-hazard-capability.md
T
2026-07-26 21:06:09 +08:00

19 KiB
Raw Blame History

CRM 主体危化品能力配置与选品限制 — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 配置安庆山峡/安徽云栋等主体能否做易制毒、易制爆产品,并在报价单、合同选品与保存时按主体能力限制产品。

Architecture: 在 crm_supplier_info 增加 allow_toxic / allow_explosive;共享纯函数判定选品合法性;产品 list 支持按 supplierId 过滤;报价/合同保存做后端校验;切换主体时前端自动剔除冲突明细并提示。合同管理下挂「主体危化品能力」配置页。

Tech Stack: FastAPI + SQLAlchemy + Pydantic v2;Vue 3 + Element Plus;MySQL 5.7

Spec: docs/superpowers/specs/2026-07-26-crm-supplier-hazard-capability-design.md


文件结构

文件 职责
backend/scripts/migrate_20260726_crm_supplier_hazard_capability.sql 增量 DDL + 菜单 seed
docs/sql/shanxia2.0.sql 同步 crm_supplier_info / sys_menu
backend/app/models/crm_models.py CrmSupplierInfo 两字段
backend/app/schemas/crm/supplier_info.py Create/Update/响应字段
backend/app/crud/crm/supplier_info.py _row_to_dict / create / update
backend/app/services/crm_supplier_hazard.py product_allowed + 校验明细
backend/tests/test_crm_supplier_hazard.py 纯函数单测
backend/app/schemas/crm/product.py ProductListBody.supplierId
backend/app/crud/crm/product.py list 按主体能力过滤
backend/app/api/crm.py 透传 supplierId
backend/app/crud/crm/quote.py create/update 校验
backend/app/crud/crm/contract.py create/update 校验
web-admin/src/utils/crm-supplier-hazard.ts 前端同名判定 + 剔除 helper
web-admin/src/api/crm/supplierInfo/index.ts VO/Form 增加字段
web-admin/src/api/crm/product.ts list 可传 supplierId(已通用)
web-admin/src/views/crm/supplier-hazard/index.vue 配置页
web-admin/src/router/modules/sqxp.ts 路由
web-admin/src/views/crm/quote/components/ProductSelector.vue 传 supplierId
web-admin/src/views/crm/contract/components/ProductSelector.vue 传 supplierId
web-admin/src/views/crm/quote/components/QuoteFormPanel.vue 改主体剔除 + 打开选品前校验
web-admin/src/views/crm/contract/components/ContractFormDialog.vue 同上
web-admin/src/views/crm/contract/form.vue 同上(若仍在用)

Task 1: 共享判定函数 + 单测(后端)

Files:

  • Create: backend/app/services/crm_supplier_hazard.py

  • Create: backend/tests/test_crm_supplier_hazard.py

  • Step 1: 写失败单测

# backend/tests/test_crm_supplier_hazard.py
from app.services.crm_supplier_hazard import product_allowed


def test_plain_always_allowed():
    assert product_allowed(is_toxic=0, is_explosive=0, allow_toxic=0, allow_explosive=0) is True


def test_toxic_only_requires_allow_toxic():
    assert product_allowed(1, 0, allow_toxic=1, allow_explosive=0) is True
    assert product_allowed(1, 0, allow_toxic=0, allow_explosive=1) is False


def test_explosive_only_requires_allow_explosive():
    assert product_allowed(0, 1, allow_toxic=0, allow_explosive=1) is True
    assert product_allowed(0, 1, allow_toxic=1, allow_explosive=0) is False


def test_dual_requires_both():
    assert product_allowed(1, 1, allow_toxic=1, allow_explosive=1) is True
    assert product_allowed(1, 1, allow_toxic=1, allow_explosive=0) is False
    assert product_allowed(1, 1, allow_toxic=0, allow_explosive=1) is False
  • Step 2: 跑测确认失败

Run: cd backend && source venv/bin/activate && pytest tests/test_crm_supplier_hazard.py -v
Expected: FAIL(模块不存在)

  • Step 3: 实现
# backend/app/services/crm_supplier_hazard.py
"""主体危化品能力:产品是否允许选择/落库。"""

from __future__ import annotations

from typing import Any, Dict, Iterable, List, Optional, Tuple

from sqlalchemy.orm import Session

from app.crud.crm.product import get_product  # 若无 get_product,用 db.query(CrmProduct)
from app.crud.crm.supplier_info import get_supplier_info


def product_allowed(
    is_toxic: int,
    is_explosive: int,
    *,
    allow_toxic: int,
    allow_explosive: int,
) -> bool:
    toxic = int(is_toxic or 0) == 1
    explosive = int(is_explosive or 0) == 1
    if not toxic and not explosive:
        return True
    if toxic and explosive:
        return int(allow_toxic or 0) == 1 and int(allow_explosive or 0) == 1
    if toxic:
        return int(allow_toxic or 0) == 1
    return int(allow_explosive or 0) == 1


def get_supplier_hazard_flags(
    db: Session,
    supplier_id: Optional[str],
    *,
    tenant_no: str,
) -> Tuple[int, int]:
    """返回 (allow_toxic, allow_explosive);无主体时视为 (0, 0)。"""
    if not supplier_id:
        return 0, 0
    row = get_supplier_info(db, str(supplier_id), tenant_no=tenant_no)
    if not row:
        return 0, 0
    return int(getattr(row, "allow_toxic", 0) or 0), int(getattr(row, "allow_explosive", 0) or 0)


def assert_products_allowed_for_supplier(
    db: Session,
    *,
    tenant_no: str,
    supplier_id: Optional[str],
    products: Iterable[Dict[str, Any]],
) -> None:
    """不合规则 raise ValueError,文案列出产品名。"""
    allow_toxic, allow_explosive = get_supplier_hazard_flags(db, supplier_id, tenant_no=tenant_no)
    blocked: List[str] = []
    for p in products or []:
        pid = str(p.get("productId") or p.get("product_id") or "").strip()
        if not pid:
            continue
        prod = get_product(db, pid, tenant_no=tenant_no)  # 按现有 CRUD 签名调整
        if not prod:
            continue
        is_toxic = int(getattr(prod, "is_toxic", 0) or p.get("isToxic") or 0)
        is_explosive = int(getattr(prod, "is_explosive", 0) or p.get("isExplosive") or 0)
        if not product_allowed(is_toxic, is_explosive, allow_toxic=allow_toxic, allow_explosive=allow_explosive):
            name = getattr(prod, "product_name", None) or p.get("productName") or pid
            blocked.append(str(name))
    if blocked:
        raise ValueError(
            "当前主体不具备以下产品的危化品经营能力,请移除后重试:" + "、".join(blocked)
        )

实现时核对 get_product / get_supplier_info 真实签名;若无 get_product,用 db.query(CrmProduct).filter(...).first()。

  • Step 4: 跑测通过

Run: pytest tests/test_crm_supplier_hazard.py -v
Expected: PASS

  • Step 5: Commit(仅在用户要求提交时执行)
git add backend/app/services/crm_supplier_hazard.py backend/tests/test_crm_supplier_hazard.py
git commit -m "$(cat <<'EOF'
feat(crm): add supplier hazard product_allowed helper and unit tests

EOF
)"

Task 2: DB 字段 + Model + Supplier CRUD/Schema

Files:

  • Create: backend/scripts/migrate_20260726_crm_supplier_hazard_capability.sql(本 Task 先写 ALTER,菜单放 Task 5)

  • Modify: docs/sql/shanxia2.0.sql(crm_supplier_info CREATE)

  • Modify: backend/app/models/crm_models.py

  • Modify: backend/app/schemas/crm/supplier_info.py

  • Modify: backend/app/crud/crm/supplier_info.py

  • Step 1: 迁移 SQL(字段部分)

-- backend/scripts/migrate_20260726_crm_supplier_hazard_capability.sql
ALTER TABLE `crm_supplier_info`
  ADD COLUMN `allow_toxic` smallint(6) NOT NULL DEFAULT 0 COMMENT '是否允许易制毒产品(0否1是)' AFTER `bank_account`,
  ADD COLUMN `allow_explosive` smallint(6) NOT NULL DEFAULT 0 COMMENT '是否允许易制爆产品(0否1是)' AFTER `allow_toxic`;

在本地/测试库执行该 ALTER。同步修改 docs/sql/shanxia2.0.sql 中 CREATE TABLE crm_supplier_info,在 bank_account 后加入同两列。

  • Step 2: Model

在 CrmSupplierInfo(status 之前)增加:

allow_toxic = Column(SmallInteger, nullable=False, default=0, comment="是否允许易制毒产品(0否1是)")
allow_explosive = Column(SmallInteger, nullable=False, default=0, comment="是否允许易制爆产品(0否1是)")
  • Step 3: Schema

SupplierInfoCreateBody / SupplierInfoUpdateBody 增加:

allow_toxic: Optional[int] = Field(default=0, alias="allowToxic", description="是否允许易制毒(0/1)")
allow_explosive: Optional[int] = Field(default=0, alias="allowExplosive", description="是否允许易制爆(0/1)")

UpdateBody 默认用 None 表示不改:

allow_toxic: Optional[int] = Field(default=None, alias="allowToxic")
allow_explosive: Optional[int] = Field(default=None, alias="allowExplosive")
  • Step 4: CRUD _row_to_dict + create/update

_row_to_dict 增加:

"allowToxic": int(row.allow_toxic or 0),
"allowExplosive": int(row.allow_explosive or 0),

create_supplier_info / update_supplier_info 写入 allow_toxic / allow_explosive(update 仅当 kwargs 含该键时设置)。

  • Step 5: 手动冒烟

调用 listAll 供方接口,确认返回含 allowToxic/allowExplosive(默认 0)。


Task 3: 产品 list 按主体过滤

Files:

  • Modify: backend/app/schemas/crm/product.py — ProductListBody

  • Modify: backend/app/crud/crm/product.py — list_products

  • Modify: backend/app/api/crm.py — products list 透传

  • Step 1: Schema

supplier_id: Optional[str] = Field(default=None, alias="supplierId", description="报价/合同主体ID,传入则按危化品能力过滤")
  • Step 2: list_products

增加参数 supplier_id: str = None。在 status 过滤之后、count 之前:

if supplier_id:
    from app.services.crm_supplier_hazard import get_supplier_hazard_flags, product_allowed
    allow_toxic, allow_explosive = get_supplier_hazard_flags(db, supplier_id, tenant_no=tenant_no)
    # 内存过滤:先查出候选再 filter;若数据量大可改为 SQL OR 条件

推荐 SQL 条件(与 product_allowed 等价):

# 普通: (is_toxic!=1 AND is_explosive!=1)
# 或 仅毒且 allow_toxic
# 或 仅爆且 allow_explosive
# 或 双属性且两项都开
from sqlalchemy import and_, or_, not_

conds = [
    and_(
        or_(CrmProduct.is_toxic.is_(None), CrmProduct.is_toxic != 1),
        or_(CrmProduct.is_explosive.is_(None), CrmProduct.is_explosive != 1),
    )
]
if allow_toxic == 1:
    conds.append(and_(CrmProduct.is_toxic == 1, or_(CrmProduct.is_explosive.is_(None), CrmProduct.is_explosive != 1)))
if allow_explosive == 1:
    conds.append(and_(CrmProduct.is_explosive == 1, or_(CrmProduct.is_toxic.is_(None), CrmProduct.is_toxic != 1)))
if allow_toxic == 1 and allow_explosive == 1:
    conds.append(and_(CrmProduct.is_toxic == 1, CrmProduct.is_explosive == 1))
q = q.filter(or_(*conds))
  • Step 3: API 透传 body.supplier_id → list_products(..., supplier_id=...)

  • Step 4: 冒烟

  • 不传 supplierId:产品管理列表条数不变

  • 传仅开毒的主体:不含「仅爆」「双属性」产品


Task 4: 报价 / 合同保存校验

Files:

  • Modify: backend/app/crud/crm/quote.py — create_quote / update_quote

  • Modify: backend/app/crud/crm/contract.py — create/update 写产品处

  • Step 1: quote

在 create_quote / update_quote 解析出 supplier_id 与 product_rows 后、落库前:

from app.services.crm_supplier_hazard import assert_products_allowed_for_supplier

assert_products_allowed_for_supplier(
    db,
    tenant_no=tenant_no,
    supplier_id=str(supplier_id) if supplier_id else None,
    products=product_rows or [],
)

update_quote 仅在本次请求带了 products/productList 时校验;若只改头不改明细,应用库中现有明细 + 新 supplier_id 再校验(防只改主体留下冲突品)。

  • Step 2: contract

在合同 create/update 写入 crm_contract_product 前调用同一 assert_products_allowed_for_supplier,supplier_id 取合同交易主体。

  • Step 3: 冒烟

用 API 保存含冲突产品的报价 → 期望业务错误文案含产品名。


Task 5: 菜单 + 配置页 + 路由

Files:

  • Append: backend/scripts/migrate_20260726_crm_supplier_hazard_capability.sql(菜单)

  • Modify: docs/sql/shanxia2.0.sql(sys_menu INSERT)

  • Create: web-admin/src/views/crm/supplier-hazard/index.vue

  • Modify: web-admin/src/router/modules/sqxp.ts

  • Modify: web-admin/src/api/crm/supplierInfo/index.ts

  • Step 1: 菜单 SQL

合同 order_num=6,客户 order_num=7。将 order_num >= 7 的 CRM 子菜单 +1,再插入本菜单 order_num=7:

UPDATE `sys_menu`
SET `order_num` = `order_num` + 1
WHERE `parent_id` = 'CRM00000000000000000000000000001'
  AND `order_num` >= 7
  AND `del_flag` = 0;

INSERT INTO `sys_menu` (
  `id`, `menu_name`, `parent_id`, `menu_type`, `path`, `component`, `perms`,
  `is_frame`, `visible`, `status`, `tenant_no`, `order_num`, `remark`,
  `create_by`, `create_dept_id`, `create_time`, `update_by`, `update_time`, `del_flag`
) VALUES (
  'CRM3000000000000000000000000025',
  '主体危化品能力',
  'CRM00000000000000000000000000001',
  'C',
  'supplier-hazard',
  '/crm/supplier-hazard/index',
  'crm:supplierHazard:list',
  1, '1', '1', 'shanxia2.0', 7,
  '配置主体是否允许易制毒/易制爆产品',
  'system', '', NOW(), NULL, NOW(), 0
);

-- 按钮权限(编辑)
INSERT INTO `sys_menu` (
  `id`, `menu_name`, `parent_id`, `menu_type`, `path`, `component`, `perms`,
  `is_frame`, `visible`, `status`, `tenant_no`, `order_num`, `remark`,
  `create_by`, `create_dept_id`, `create_time`, `update_by`, `update_time`, `del_flag`
) VALUES (
  'CRM3000000000000000000000000026',
  '主体危化品能力编辑',
  'CRM3000000000000000000000000025',
  'F',
  '', NULL,
  'crm:supplierHazard:edit',
  1, '0', '1', 'shanxia2.0', 1, NULL,
  'system', '', NOW(), NULL, NOW(), 0
);

给相关角色(至少超管)分配新菜单(按项目现有 sys_role_menu 习惯补 INSERT,或登录后在角色管理勾选)。

  • Step 2: 前端 API 类型

SupplierInfoVO / SupplierInfoForm 增加 allowToxic?: number、allowExplosive?: number。

  • Step 3: 路由

在 sqxp.ts 合同路由附近增加:

{
  id: 'CRM3000000000000000000000000025',
  name: 'CrmSupplierHazard',
  path: 'supplier-hazard',
  component: '/crm/supplier-hazard/index',
  meta: { title: '主体危化品能力', keepAlive: true, menuCode: 'crm:supplierHazard:list' }
},
  • Step 4: 配置页

新建 web-admin/src/views/crm/supplier-hazard/index.vue:

  • 结构对齐 CRM 列表:panel-top 标题「主体危化品能力」+ listAllSupplierInfo / 分页 list

  • 列:主体名称、编码、允许易制毒(el-switch)、允许易制爆(el-switch)、状态 Tag、更新时间

  • switch @change 调 updateSupplierInfo({ id, allowToxic, allowExplosive, supplierName })(update 若要求名称,带上当前行名称)

  • 按钮带图标;状态/类型用 el-tag

  • App.vue panelTitleBarTextRules 如需竖条则登记「主体危化品能力」

  • Step 5: 浏览器

打开 /#/crm/supplier-hazard,切换开关后刷新仍保持。


Task 6: 前端选品过滤 + 改主体剔除

Files:

  • Create: web-admin/src/utils/crm-supplier-hazard.ts

  • Modify: quote/contract ProductSelector.vue

  • Modify: QuoteFormPanel.vue

  • Modify: ContractFormDialog.vue(及 form.vue 若仍入口)

  • Step 1: 工具函数

// web-admin/src/utils/crm-supplier-hazard.ts
export function productAllowedByHazard(
  isToxic: number | undefined,
  isExplosive: number | undefined,
  allowToxic: number,
  allowExplosive: number
): boolean {
  const toxic = Number(isToxic || 0) === 1
  const explosive = Number(isExplosive || 0) === 1
  if (!toxic && !explosive) return true
  if (toxic && explosive) return allowToxic === 1 && allowExplosive === 1
  if (toxic) return allowToxic === 1
  return allowExplosive === 1
}

export function removeProductsNotAllowedByHazard<T extends { productId?: string | number; productName?: string; isToxic?: number; isExplosive?: number }>(
  products: T[],
  allowToxic: number,
  allowExplosive: number
): { kept: T[]; removedNames: string[] } {
  const kept: T[] = []
  const removedNames: string[] = []
  for (const p of products) {
    if (productAllowedByHazard(p.isToxic, p.isExplosive, allowToxic, allowExplosive)) {
      kept.push(p)
    } else {
      removedNames.push(p.productName || String(p.productId || ''))
    }
  }
  return { kept, removedNames }
}

注意:明细行可能没有 isToxic/isExplosive。改主体时若缺失,应先用当前 supplierList 能力 + 必要时批量查产品详情,或在加入明细时把 hazard 快照进行。实现约定: handleProductConfirm 写入行时带上 isToxic/isExplosive(从选中产品对象拷贝);改主体剔除依赖行上快照。

  • Step 2: ProductSelector

增加 prop supplierId?: string | number。fetchProductList 请求体带 supplierId。无 supplierId 时父组件不应打开弹窗(或弹窗内提示先选主体)。

  • Step 3: QuoteFormPanel

  • 打开选品前:无 form.supplierId → ElMessage.warning('请先选择报价主体')

  • handleSupplierChange:取新主体 allowToxic/allowExplosive,removeProductsNotAllowedByHazard,写回 form.products,若有 removedNames → ElMessage.warning(\当前主体不支持以下产品,已自动移除:${removedNames.join('、')}`)`

  • <ProductSelector :supplier-id="form.supplierId" ... />

  • Step 4: ContractFormDialog / form.vue

同样处理交易主体变更与 ProductSelector。

  • Step 5: 手工验收

按 spec「测试要点」1–6 走一遍。


Task 7: 收尾

  • 跑 pytest tests/test_crm_supplier_hazard.py -v
  • 若改了字段一致性相关实体,按需跑 python scripts/check_field_consistency.py(供方)
  • ./scripts/update-graph.sh backend 与 frontend(若脚本可用)
  • 更新 design spec 状态为「已实现」日期(实现完成后)

Spec 覆盖自检

Spec 项 Task
allow_toxic / allow_explosive 字段 Task 2
双属性须两项都开 Task 1
配置菜单「主体危化品能力」 Task 5
报价/合同选品过滤 Task 3 + 6
改主体自动剔除并提示 Task 6
保存后端校验 Task 4
存量不回溯 无额外任务(只读历史天然满足)
产品管理不受过滤 Task 3(不传 supplierId)

执行说明

Plan 已保存。实现前请先在目标库执行 Task 2/5 的 SQL。

执行方式二选一:

  1. Subagent-Driven(推荐) — 每 Task 开新子代理,Task 间复查
  2. Inline Execution — 本会话按 executing-plans 连续做完

选哪种?