Files
shanxia2.0/docs/superpowers/plans/2026-05-30-crm-iteration1-product.md
T
2026-06-01 08:21:21 +08:00

18 KiB
Raw Blame History

CRM 迭代 1:产品分类 + 产品管理 + Excel 导入导出 实施计划

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.

设计文档: docs/superpowers/specs/2026-05-30-crm-migration-design.md §4.1 范围: 产品分类(树形 CRUD)、产品管理(列表+弹窗)、Excel 导入导出、附件上传、字典数据迁移

迁移规则: 严格遵循 OpenSpec coding-conventions 中的「已有系统迁移的蔓延控制」规则,仅实现 CRM 源系统已有的功能,不做功能膨胀。


已排除功能(用户确认)

功能 排除原因
产品定价(crm_product_price) 用户确认无此业务
价格历史(crm_product_price_history) 用户确认无此业务
库存日志(crm_product_stock_log) 用户确认无此业务
产品标签(crm_product_tag + tag_relation) 用户确认无此业务
复制产品 用户确认无此业务
拖拽排序 用户确认暂时不需要,使用排序号

File Map

Backend — 新建文件

文件 职责
backend/app/models/crm_models.py CRM SQLAlchemy 模型(迭代 1:CrmProductCategory + CrmProduct + SysOss 共 3 个)
backend/app/schemas/crm/product.py 产品/分类的 Pydantic CreateBody/UpdateBody/Response schemas
backend/app/crud/crm/product.py 产品/分类的 CRUD 操作
backend/app/api/crm.py CRM API 路由(迭代 1:产品分类 + 产品管理 + 导入导出)

Backend — 修改文件

文件 变更
backend/app/api/__init__.py 导入 crm_router
backend/app/main.py include_router(crm_router)

Frontend — 新建文件

文件 职责
web-admin/src/api/crm/product.ts 产品/分类 API 调用函数
web-admin/src/views/crm/product/index.vue 产品列表页(含导入导出)
web-admin/src/views/crm/product/ProductFormDialog.vue 产品新增/编辑弹窗
web-admin/src/views/crm/product/ProductViewDialog.vue 产品查看弹窗
web-admin/src/views/crm/product-category/index.vue 产品分类管理(树形)
web-admin/src/views/crm/product-category/CategoryFormDialog.vue 分类新增/编辑弹窗

Frontend — 修改文件

文件 变更
web-admin/src/router/modules/sqxp.ts 新增「CRM 管理」一级菜单及子菜单路由
backend/app/api/menu.py 新增 CRM 菜单节点到 STATIC_MENU_TREE

SQL — 已完成

文件 状态
docs/sql/crm_product_tables.sql ✅ 已生成(DDL:crm_product_category + crm_product + sys_oss)
docs/sql/crm_dict_data_migration.sql ✅ 已生成(85 dict_type + 371 dict_data)

注意: crm_product_tables.sql 需更新,移除 crm_product_price、crm_product_price_history、crm_product_stock_log、crm_product_tag、crm_product_tag_relation 共 5 张表的 DDL,只保留 crm_product_category、crm_product、sys_oss 共 3 张表。


Tasks

Task 1: 更新 DDL 脚本并创建数据库表

文件: docs/sql/crm_product_tables.sql

  • 更新脚本:移除 5 张不需要的表(price、price_history、stock_log、tag、tag_relation),只保留 3 张表
    • crm_product_category — 产品分类(树形)
    • crm_product — 产品主表
    • sys_oss — 统一附件表
  • 在 MySQL 中执行 DDL,确认 3 张表创建成功

验证: SHOW TABLES LIKE 'crm_product%'; + SHOW TABLES LIKE 'sys_oss'; 确认 3 张表存在。


Task 2: 创建 SQLAlchemy 模型

文件: backend/app/models/crm_models.py

  • 创建文件,导入 Base 和 Column 类型
  • 实现 CrmProductCategory 模型(树形结构:parent_id, category_name, category_code, level, status + 公共字段)
  • 实现 CrmProduct 模型(product_no, product_name, category_id, category_name, model, unit, price, cost_price, status, description, package_spec + 公共字段)
  • 实现 SysOss 模型(统一附件表:id, tenant_no, biz_type, biz_id, file_name, original_name, file_suffix, url, file_size, file_type, attach_type, sort_order, service, ext1 + 公共字段)
  • 确保所有模型都有完整公共字段(参照 models.py 中 SysUser 的字段模式)
  • 在 backend/app/main.py 中添加 from app.models import crm_models # noqa: F401

参考模式:

# 参照 backend/app/models/models.py 中的 BizLeaveRequest / BizAttachment 模式
from app.core.database import Base
from sqlalchemy import Column, String, DateTime, Integer, SmallInteger, Text, DECIMAL, CHAR
from datetime import datetime

class CrmProduct(Base):
    __tablename__ = "crm_product"
    id = Column(String(64), primary_key=True, comment="主键ID")
    product_no = Column(String(50), nullable=False, comment="产品编号")
    # ... 业务字段 ...
    # 公共字段
    tenant_no = Column(String(64), nullable=False, default="zkxw", comment="租户编号")
    order_num = Column(Integer, nullable=True, comment="排序号")
    # ... 其余公共字段参照 SysUser ...

验证: cd backend && source venv/bin/activate && python -c "from app.models.crm_models import CrmProduct; print(CrmProduct.__tablename__)" 无报错。


Task 3: 创建 Pydantic Schemas

文件: backend/app/schemas/crm/__init__.py, backend/app/schemas/crm/product.py

  • 创建 backend/app/schemas/crm/ 目录
  • 创建 __init__.py 空文件
  • 定义 ProductCategoryCreateBody(category_name 必填, parent_id, category_code, level, status, order_num, remark)
  • 定义 ProductCategoryUpdateBody(同 CreateBody,所有字段 optional,含 id)
  • 定义 ProductCreateBody(product_no, product_name, category_id, model, unit, price, cost_price, status, description, package_spec, order_num, remark)
  • 定义 ProductUpdateBody(同 CreateBody,所有字段 optional,含 id)
  • 定义 ProductImportRow(Excel 导入行对应 schema,字段映射到产品属性)

参考模式: 参照 backend/app/schemas/ 中已有的 Pydantic v2 schema 模式(BaseModel, ConfigDict, Field)。

验证: python -c "from app.schemas.crm.product import ProductCreateBody; print(ProductCreateBody.model_fields)" 无报错。


Task 4: 创建 CRUD 操作

文件: backend/app/crud/crm/__init__.py, backend/app/crud/crm/product.py

  • 创建 backend/app/crud/crm/ 目录和 __init__.py
  • 实现 ProductCategoryCRUD(继承 CRUDBase)
    • get_tree(db, tenant_no) — 查询所有分类,返回树形结构
    • get_by_code(db, category_code, tenant_no) — 按编码查询
    • check_has_children(db, category_id, tenant_no) — 检查是否有子分类(删除前校验)
    • check_has_products(db, category_id, tenant_no) — 检查是否有产品引用(删除前校验)
  • 实现 ProductCRUD(继承 CRUDBase)
    • get_list(db, tenant_no, filters, page, page_size) — 分页列表(含分类名筛选、状态筛选、关键字搜索)
    • get_by_no(db, product_no, tenant_no) — 按编号查询(唯一性校验)
  • 实现 SysOssCRUD(继承 CRUDBase)
    • get_by_biz(db, biz_type, biz_id, tenant_no) — 按业务类型+ID 查询附件
    • batch_save(db, attachments, tenant_no) — 批量保存附件

参考模式: 参照 backend/app/crud/user.py、backend/app/crud/role.py 使用 CRUDBase 的方式。

关键:

  • 所有查询 必须 过滤 del_flag == 0
  • 所有查询 必须 过滤 tenant_no == current_user.tenant_no
  • 删除操作使用软删除 del_flag = 1
  • 产品编号自动生成逻辑(参考 CRM 原规则)

验证: python -c "from app.crud.crm.product import ProductCRUD; print('OK')" 无报错。


Task 5: 创建 API 路由(统一 POST + Excel 导入导出)

文件: backend/app/api/crm.py

重要:遵循 OpenSpec api-conventions 的「统一 POST 接口」规范,所有业务接口使用 @router.post(),URL 通过路径语义区分操作,ID 通过请求体传入。

  • 创建文件,定义 router = APIRouter(prefix="/web/crm", tags=["CRM管理"])
  • 实现产品分类 API(统一 POST):
    • POST /web/crm/product-categories/tree — 树形列表(请求体可选筛选)
    • POST /web/crm/product-categories/add — 新增分类
    • POST /web/crm/product-categories/update — 修改分类
    • POST /web/crm/product-categories/delete — 删除分类(校验:有子分类/有产品则拒绝)
  • 实现产品管理 API(统一 POST):
    • POST /web/crm/products/list — 分页列表(请求体:page, pageSize, keyword, categoryId, status)
    • POST /web/crm/products/detail — 详情(请求体:id)
    • POST /web/crm/products/add — 新增(自动生成编号、分类名称冗余写入)
    • POST /web/crm/products/update — 修改
    • POST /web/crm/products/delete — 删除(请求体:id 或 ids)
    • POST /web/crm/products/options — 下拉选项(其他模块选择产品用)
  • 实现 Excel 导入导出 API:
    • POST /web/crm/products/import — Excel 导入(FormData: file,字段校验、重复检测、批量插入)
    • POST /web/crm/products/export — Excel 导出(请求体筛选条件,返回 xlsx 文件流)
    • POST /web/crm/products/import-template — 下载导入模板(返回 xlsx 文件流)
  • 注册路由到 app/api/__init__.py 和 app/main.py

Excel 导入导出参考:

  • Python 端使用 openpyxl 或 pandas
  • 导入字段映射:产品名称、产品编号、分类名称、规格型号、单位、标准单价、状态
  • 导出字段与列表表格列一致
  • 导入时需校验:必填字段、分类是否存在、编号唯一性
  • 导出文件名格式:产品列表_YYYYMMDD.xlsx

参考模式: 参照 backend/app/api/admin.py 的路由模式:

  • 使用 Depends(require_admin_or_super_admin) 获取当前用户
  • 使用 Depends(get_db) 获取数据库会话
  • 返回 success_response(data) 或 error_response(msg)
  • 所有路由使用 @router.post()(新规范)

注册步骤:

  1. backend/app/api/__init__.py: 添加 from app.api.crm import router as crm_router 和 __all__ 中加入 "crm_router"
  2. backend/app/main.py: import 行添加 crm_router,include 行添加 app.include_router(crm_router, prefix=settings.API_V1_PREFIX)

验证: 启动后端 ./start-local.sh,访问 /docs 确认 CRM 分组下的 API 端点可见。测试 POST /api/web/crm/products/list 返回空列表。


Task 6: 创建前端 API 模块

文件: web-admin/src/api/crm/product.ts

  • 创建 web-admin/src/api/crm/ 目录
  • 实现 API 调用函数:
import request from '@/utils/http'

// 产品分类(统一 POST)
export function fetchCategoryTree(data?: any) {
  return request.post({ url: '/web/crm/product-categories/tree', data })
}
export function fetchCreateCategory(data: any) {
  return request.post({ url: '/web/crm/product-categories/add', data })
}
export function fetchUpdateCategory(data: any) {
  return request.post({ url: '/web/crm/product-categories/update', data })
}
export function fetchDeleteCategory(data: { id: string }) {
  return request.post({ url: '/web/crm/product-categories/delete', data })
}

// 产品管理(统一 POST)
export function fetchProductList(data: any) {
  return request.post({ url: '/web/crm/products/list', data })
}
export function fetchProductDetail(data: { id: string }) {
  return request.post({ url: '/web/crm/products/detail', data })
}
export function fetchCreateProduct(data: any) {
  return request.post({ url: '/web/crm/products/add', data })
}
export function fetchUpdateProduct(data: any) {
  return request.post({ url: '/web/crm/products/update', data })
}
export function fetchDeleteProduct(data: { id: string } | { ids: string[] }) {
  return request.post({ url: '/web/crm/products/delete', data })
}
export function fetchProductOptions(data?: any) {
  return request.post({ url: '/web/crm/products/options', data })
}

// Excel 导入导出
export function fetchImportProducts(file: File) {
  const formData = new FormData()
  formData.append('file', file)
  return request.post({ url: '/web/crm/products/import', data: formData, headers: { 'Content-Type': 'multipart/form-data' } })
}
export function fetchExportProducts(data: any) {
  return request.post({ url: '/web/crm/products/export', data, responseType: 'blob' })
}
export function fetchImportTemplate() {
  return request.post({ url: '/web/crm/products/import-template', responseType: 'blob' })
}

参考模式: 参照 web-admin/src/api/admin.ts 的 request 调用方式。

验证: pnpm build 无 TS 报错。


Task 7: 创建产品分类页面(树形)

文件: web-admin/src/views/crm/product-category/index.vue, CategoryFormDialog.vue

  • 创建 web-admin/src/views/crm/product-category/ 目录
  • 实现 index.vue:
    • 参考模板页:树形模板 src/views/system/category/index.vue
    • 左侧树 + 右侧编辑面板布局
    • 树节点展示分类名称,选中节点显示详情/编辑
    • 工具栏:新增分类、展开/折叠
    • 操作按钮:编辑、删除、新增子分类
    • 使用 <el-tag> 展示状态(启用/停用)
    • 按钮带 <el-icon> 图标
    • 排序使用 order_num 排序号
  • 实现 CategoryFormDialog.vue:
    • label-position="top" 表单
    • .dialog-form-layout + .form-grid-2 布局
    • 字段:分类名称(必填)、分类编码、父级分类(树形选择)、状态、排序号、备注
    • 使用 Fresh Mint 色板

验证: pnpm dev 访问 /#/crm/product-category,页面正常渲染,CRUD 操作正常。


Task 8: 创建产品管理页面(含导入导出)

文件: web-admin/src/views/crm/product/index.vue, ProductFormDialog.vue, ProductViewDialog.vue

  • 创建 web-admin/src/views/crm/product/ 目录
  • 实现 index.vue:
    • 参考模板页:复杂列表 src/views/system/order/index.vue
    • 搜索栏:产品名称(回车搜索)、产品分类(树形下拉)、状态筛选
    • 表格列:产品编号、产品名称、分类名称、规格型号、单位、标准单价、状态(el-tag)、排序号、创建时间
    • 状态列用 <el-tag> 语义色(上架=success、下架=info)
    • 操作列 fixed="right" min-width ≥ 260px
    • 工具栏按钮:新增(primary)、导入、导出、下载导入模板
    • 支持分页
    • 导入:el-upload 选择 Excel 文件,调用导入接口,显示导入结果(成功/失败条数)
    • 导出:调用导出接口,下载 xlsx 文件
  • 实现 ProductFormDialog.vue:
    • 新增/编辑共用弹窗
    • .dialog-form-layout + .form-grid-2
    • 字段:产品编号(新增时自动生成/可编辑)、产品名称(必填)、产品分类(树形下拉)、规格型号、单位、标准单价、成本价、状态、包装规格、描述(textarea)、排序号、备注
    • 附件上传:使用 sys_oss,biz_type='crm_product'
  • 实现 ProductViewDialog.vue:
    • 只读查看弹窗
    • 展示产品详情 + 附件列表

验证: pnpm dev 访问 /#/crm/product,列表渲染、搜索筛选、新增/编辑/删除/查看、导入导出全部正常。


Task 9: 注册前端路由和后端菜单

文件: web-admin/src/router/modules/sqxp.ts, backend/app/api/menu.py

  • 在 sqxp.ts 中添加 CRM 管理一级菜单:
// CRM 管理
{
  id: 'CRM0000000000000000000000000001',
  name: 'CrmManagement',
  path: '/crm',
  component: '/index/index',
  meta: {
    title: 'CRM 管理',
    icon: 'ri:contacts-line',
    keepAlive: false,
    roles: ['admin']
  },
  children: [
    {
      id: 'CRM0000000000000000000000000002',
      name: 'CrmProductCategory',
      path: 'product-category',
      component: '/crm/product-category/index',
      meta: { title: '产品分类', keepAlive: true, menuCode: 'crm:productCategory:list' }
    },
    {
      id: 'CRM0000000000000000000000000003',
      name: 'CrmProduct',
      path: 'product',
      component: '/crm/product/index',
      meta: { title: '产品管理', keepAlive: true, menuCode: 'crm:product:list' }
    },
    // 后续迭代会在此添加更多子菜单
  ]
}
  • 在 menu.py 的 STATIC_MENU_TREE 中添加对应的 CRM 菜单节点

验证: 刷新页面,侧边栏出现「CRM 管理」菜单,点击「产品分类」「产品管理」可进入对应页面。


Task 10: 执行字典数据迁移脚本

文件: docs/sql/crm_dict_data_migration.sql(已生成)

  • 在测试环境 MySQL 中执行脚本
  • 执行验证 SQL 确认数据正确插入

验证:

SELECT dict_type, COUNT(*) as cnt FROM sys_dict_data WHERE dict_type LIKE 'crm_%' OR dict_type LIKE 'cw_%' GROUP BY dict_type ORDER BY dict_type;
SELECT dict_type, dict_name FROM sys_dict_type WHERE dict_type LIKE 'crm_%' OR dict_type LIKE 'cw_%' ORDER BY dict_type;

Task 11: 整体验证

  • 后端:启动 ./start-local.sh,确认无启动错误
  • 后端:访问 /docs,确认 CRM API 分组下的所有端点可见
  • 后端:测试产品分类 CRUD 全流程(创建→查询→修改→删除)
  • 后端:测试产品 CRUD 全流程(创建→查询→修改→删除→下拉选项)
  • 后端:测试 Excel 导入(上传文件→校验→入库)
  • 后端:测试 Excel 导出(筛选→下载文件)
  • 前端:pnpm build 成功(无 TS 错误)
  • 前端:pnpm dev 启动,访问 CRM 菜单
  • 前端:产品分类页面 — 树形展示、增删改查、排序号
  • 前端:产品管理页面 — 列表、搜索、新增、编辑、查看、删除、导入、导出
  • 字典数据迁移脚本已执行并验证
  • 所有新增代码无 lsp_diagnostics 错误

Commit Strategy

feat(crm): update product DDL — keep only category, product, sys_oss tables
feat(crm): add SQLAlchemy models for CRM product module (3 models)
feat(crm): add Pydantic schemas and CRUD for CRM product
feat(crm): add CRM product API routes with Excel import/export
feat(crm): add frontend API module for CRM product
feat(crm): add product category page (tree with sort order)
feat(crm): add product management page with import/export
feat(crm): add CRM menu entries in router and menu.py
chore(crm): update dict migration SQL script