19 KiB
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_infoCREATE) -
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.vuepanelTitleBarTextRules如需竖条则登记「主体危化品能力」 -
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。
执行方式二选一:
- Subagent-Driven(推荐) — 每 Task 开新子代理,Task 间复查
- Inline Execution — 本会话按 executing-plans 连续做完
选哪种?