18 KiB
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()(新规范)
注册步骤:
backend/app/api/__init__.py: 添加from app.api.crm import router as crm_router和__all__中加入"crm_router"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