9.4 KiB
CRM 业务明细清单（shanxia2.0 现状）
版本：v1.0
日期：2026-06-10
依据：docs/sql/shanxia2.0.sql、docs/crm-migration/module-status.md、backend/app/api/crm*.py、web-admin/src/views/crm/
源系统：shanxia/crm（Java RuoYi-Vue-Plus + Vue3），门户内 Python 重写
1. 模块定位
CRM 负责山峡化工销售前端主数据与交易链路：线索 → 商机 → 报价 → 合同，并提供产品、客户、公海池等主数据。数据表前缀 crm_*，API 前缀 /api/web/crm（多数为 POST Body 风格，合同列表等部分为 GET）。
与运输计划的关系：合同是计划发起的上游；客户表提供供应商/目的地；产品表提供物料信息（运输计划尚需扩展易制毒/易制爆字段）。
2. 技术实现
| 项 | 说明 |
|---|---|
| 后端入口 | backend/app/api/crm.py、crm_contract_routes.py、crm_contract_sub_routes.py、crm_quote_routes.py |
| 业务层 | backend/app/crud/crm/、backend/app/services/crm/（部分） |
| 前端目录 | web-admin/src/views/crm/、web-admin/src/api/crm/ |
| 路由注册 | web-admin/src/router/modules/sqxp.ts（合同/报价等静态路由） |
| 响应协议 | 门户 success_response 封装（code + data），与地磅/bx 不同 |
| 租户 | 全表 tenant_no，查询默认过滤 |
| 软删除 | del_flag=1 |
3. 数据表清单（23 张，均在 shanxia2.0.sql）
| 表名 | 说明 | 移植状态 |
|---|---|---|
crm_product_category |
产品分类（树形） | ✅ |
crm_product |
产品主数据 | ✅ |
crm_customer |
客户主数据 | ✅ |
crm_contact |
联系人 | ✅ |
crm_customer_follow |
客户跟进记录 | ✅ |
crm_customer_pool |
公海池客户 | ✅ |
crm_customer_pool_rule |
公海池规则 | ✅ |
crm_invoice_info |
客户开票信息 | ✅ |
crm_clue |
线索 | ✅ |
crm_clue_follow |
线索跟进 | ✅ |
crm_opportunity |
商机 | ✅ |
crm_opportunity_follow |
商机跟进 | ✅ |
crm_opportunity_product |
商机产品 | ✅ |
crm_opportunity_stage_log |
商机阶段日志 | ✅ |
crm_quote |
报价单 | ✅ |
crm_quote_product |
报价产品明细 | ✅ |
crm_quote_approval |
报价审批 | ✅ |
crm_quote_share_log |
报价分享日志 | ✅ |
crm_contract |
合同主表 | ✅ |
crm_contract_product |
合同产品明细 | ✅ |
crm_contract_product_price_tier |
框架合同调价区间 | ✅ |
crm_contract_approval |
合同审批 | ✅ |
crm_contract_change |
合同变更 | ✅ |
crm_contract_template |
合同模板 | ✅ |
crm_supplier_info |
供方主体（山峡/云栋等） | ✅ |
原 sx.sql 有、门户未移植：crm_payment*、crm_invoice*、crm_visit*、标签相关表、产品扩展表（附件/价格历史/库存流水）等。
4. 业务模块明细
4.1 产品管理
| 能力 | 说明 |
|---|---|
| 产品分类 | 树形 CRUD，/product-categories/tree |
| 产品列表 | 分页、筛选、上下架 |
| 导入导出 | Excel 导入/导出/模板下载 |
| 产品选项 | /products/options 供下拉使用 |
主字段：product_no、product_name、category_id、model（规格）、unit、price、cost_price、stock、tax_rate、status。
运输计划缺口：尚无 is_precursor（易制毒）、is_explosive（易制爆）字段。
4.2 客户管理
| 能力 | 说明 |
|---|---|
| 客户 CRUD | 列表、详情、新增、编辑、删除 |
| 客户视图 | 我的/待跟进/重点/已成交/本周新增/长期未跟进等 |
| 转移/成交/入池 | 负责人变更、成交标记、放入公海 |
| 导入导出 | Excel |
| 统计 | 概览、来源、级别、行业、趋势、负责人、跟进 |
| 联系人 | 嵌套在客户详情，含主联系人、决策人、生日提醒 |
| 跟进记录 | 客户维度跟进 CRUD + 导出 |
| 开票信息 | 客户维度维护 |
主字段：customer_no、customer_name、level、source、industry、owner_user_id、deal_status、address 等。
运输计划用法：供应商名称、目的地名称从客户表选取；安庆山峡、安徽云栋亦作为客户主体参与单据类别判断。
4.3 公海池
| 能力 | 说明 |
|---|---|
| 公海客户列表 | 可领取、可分配 |
| 领取/分配 | 单人或批量 |
| 公海记录 | 入池历史查询 |
| 公海规则 | 规则 CRUD、启用/停用、手动执行回收 |
4.4 线索管理
| 能力 | 说明 |
|---|---|
| 线索 CRUD | 列表、详情、新增、编辑、删除 |
| 跟进 | 跟进记录维护 |
| 分配/转化/无效 | 转商机或客户、标无效 |
| 导入导出 | Excel |
| 统计页 | 前端有页，统计接口在列表侧隐藏 |
业务链路：线索 →（转化）→ 客户 / 商机。
4.5 商机管理
| 能力 | 说明 |
|---|---|
| 商机 CRUD | 列表、看板、漏斗、统计 |
| 阶段流转 | 变更阶段、批量变更、标记赢单/输单 |
| 跟进 | 商机跟进记录 |
| 产品明细 | 商机关联产品 |
| 分配 | 负责人变更 |
| 导出 | Excel |
业务链路：商机 → 报价 / 合同。
4.6 报价管理
| 能力 | 说明 |
|---|---|
| 报价 CRUD | 列表、表单、详情 |
| 版本 | 新版本、版本历史 |
| 审批 | 提交、审批、撤回 |
| 分享 | 生成分享链接、分享统计 |
| 生成报价 PDF | |
| 转合同 | toContract |
| 接受/拒绝 | 客户侧确认态 |
| 产品子表 | 报价产品明细独立 API |
| 统计 | 概览、状态、趋势 |
API 文件：crm_quote_routes.py（约 30+ 端点，POST 为主）。
4.7 合同管理（核心）
| 能力 | 说明 |
|---|---|
| 合同 CRUD | 列表（多 Tab：我的/全部/待审批/已审批/执行中/已完成/已作废） |
| 创建来源 | 手工新建、从报价创建、从商机创建、续签 |
| 审批流 | 提交/批量提交/撤回、审批、审批流查询 |
| 执行生命周期 | 开始执行、完成、作废、签订 |
| 合同产品 | 多产品明细，含数量、单价、包装规格、送货方式 |
| 框架合同调价 | crm_contract_product_price_tier：按日期区间维护单价 + 调价函附件 letter_oss_ids |
| 模板 | 保存/读取富文本合同模板、PDF 下载 |
| 附件 | 合同文件、分类附件上传 |
| 变更 | 合同变更子模块 |
| 统计 | 概览、状态、类型、趋势、即将到期 |
| 导出 | Excel |
合同类型（字典 crm_contract_type）：销售合同、采购合同、框架合同（framework）等。
合同状态：draft → executing → finished / invalid；并行 approval_status。
合同产品关键字段（计划可带出）：product_id、price、quantity、package_spec、delivery_method、model、unit。
运输计划相关缺口：
- 合同页尚无「发起运输计划」入口；
- 框架合同调价后端已有，计划侧取价规则待建；
- 产品易制毒/易制爆属性待加到
crm_product。
4.8 供方主体（crm_supplier_info）
| 能力 | 说明 |
|---|---|
| 后端 API | 列表、详情、新增、编辑、删除、导出（在 crm.py） |
| 前端页面 | ❌ 无独立菜单页 |
| 用途 | 合同 supplier_id 关联安庆山峡、安徽云栋等签约主体 |
5. 前端菜单（sys_menu 已入库部分）
| 菜单 | 路径 | 权限前缀 |
|---|---|---|
| CRM 管理 | /crm |
— |
| 产品分类 | /crm/product-category |
crm:productCategory:* |
| 产品管理 | /crm/product |
crm:product:* |
| 客户列表 | /crm/customer |
crm:customer:* |
| 公海池 | /crm/customer/pool |
crm:customerPool:* |
| 线索管理 | /crm/clue |
crm:clue:* |
| 商机管理 | /crm/opportunity |
crm:opportunity:* |
说明：合同管理、报价管理页面已在 sqxp.ts 注册，但 shanxia2.0.sql 快照中可能尚未写入对应 sys_menu 行；部署时需补菜单 SQL 或手工配置。
6. 典型业务闭环
线索 ──转化──► 客户
│
商机 ◄──────────┘
│
├──► 报价（版本/审批/分享）
│ │
│ └──► 合同（审批/执行/产品/调价函）
│
└──► 合同（直接从商机创建）
7. 与其他模块集成
| 对接模块 | 集成方式 |
|---|---|
地磅 db_* |
地磅计划/地磅单通过 product_id 关联 crm_product；往来单位存客户名称文本 |
报销 bx_* |
无直接表关联；业务上可附件引用合同/报价 PDF |
运输计划 plan_*（待建） |
从合同发起；读客户/产品/合同价格 |
8. 未完成 / 待验证项
| 项 | 状态 |
|---|---|
| 回款、开票、回访、标签 | ❌ 未移植 |
| 供方主体前端页 | ❌ |
| 合同/报价菜单 SQL | 🟡 需核对生产库 |
| 全模块联调手测 | 🟡 module-status 标记「代码完成，待手测」 |
| 易制毒/易制爆产品属性 | ❌ 运输计划前置改造 |
9. 参考路径
| 文档/代码 | 路径 |
|---|---|
| 移植状态 | docs/crm-migration/module-status.md |
| 合同业务逻辑 | docs/crm-migration/plans/contract/02-business-logic.md |
| SQL 快照 | docs/sql/shanxia2.0.sql |
| 原系统 SQL | docs/sql/sx.sql（对照用） |