crm_project/Project Handover Document.md

---
创建时间: 2026-02-27T15:07
更新时间: 2026-02-27T15:13
tags:
  - WebApp
  - work
---
# 项目现状与后端开发交接说明书 (Project Handover Document)

## 1. 项目概况与技术栈 (Project Overview & Tech Stack)

**业务背景**： 本项目为专为**润滑油行业**深度定制的 B2B 企业级 ERP/CRM 综合系统。业务链路完整覆盖了“客（客户与客情）、货（产品与库存）、单（订单与发货）、财（发票与智能报销）、权（组织与权限）”五大核心中后台数字化流转。

**技术栈要求**：

- **前端 (已完成 UI 占位)**：Vue 3 (Composition API), TypeScript, Element Plus, Vite.
    
- **后端 (即将开发，请 AI 注意)**：[⚠️请在此处填入你期望的后端语言，如：Node.js (NestJS) / Java (Spring Boot) / Python (FastAPI)] + MySQL/PostgreSQL 关系型数据库 + Redis (用于 Token 鉴权与缓存)。
    

## 2. 已完成的前端模块全景图 (Completed Frontend Modules)

现阶段已完成全套核心前台视图（UI/UX）搭建与交互逻辑封皮，主要包含以下独立路由模块：

- **`/` 及基础框架 (Layout)**：基于 `el-container` 的经典折叠侧边栏与顶部面包屑导航，预留多级路由。
    
- **`/customers` (客户管理大盘)**：涵盖高级检索，实现 A/B/C 三级高净值客户的标签化表格总览。
    
- **`/customers/detail` (客户详情)**：深度整合 AI。左侧档案卡+AI客情健康度；右侧/下方搭载沉浸式时间轴（Timeline），及弹窗式 `AI 拜访简报生成器`。
    
- **`/products` (产品与库存)**：采用“左树右表”布局。左侧分类树，右侧精细管理多包装规格 SKU，内置双抽屉查看详情及【出入库流水账】。
    
- **`/orders` (订单管理)**：业务极度复杂的交易枢纽。含【客户专属历史定价自动带出】逻辑，精准追踪发货状态（待/部分/已发货）及付款进度（进度条跟踪）。
    
- **`/shipping` (物流发货记录)**：与订单强关联，支持【一笔订单分批发货】，追踪承运方与物流单号。
    
- **`/finance` (财务发票与报销中心)**：
    
    - **大一统票据池**：上传即刻 OCR 提取，底层实行软删除（作废）。
        
    - **智能报销申请 (草稿体系)**：左侧票据池拉取，右侧购物车封装（内置费用描述及两级票据类型转换），实时合计。
        
    - **专属 A4 打印**：利用 CSS `@media print` 穿透重绘出带大写金额转化、极高信噪比的定制版报销单。
        
- **`/settings` (系统设置与权限)**：标准 RBAC 控制台。左树（部门）右表（员工）；角色池分配极细粒度的“数据横向穿透权限”（全部/本部门/仅本人）及菜单按钮权限。
    

## 3. 核心业务数据结构 (Core Data Structures / API Contracts)

_注：这是后端建立 SQL Schema 的绝对契约基准。_

**1. 客户与日志实体 (Customer & FollowUp)**

- **Customer**: `id`, `name`, `level`, `industry`, `contact`, `phone`, `aiScore`, `address`, `status`
    
- **FollowUpLog**: `id`, `customerId`, `salespersonId`, `content`, `emotionType`, `nextVisitTime`, `createTime` (用于生成 AI 简报的底层饲料)
    

**2. 产品库存实体 (Product SKU & InventoryFlow)**

- **ProductSku**: `id`, `categoryId`, `skuCode`, `name`, `spec` (如 200L/桶), `standardPrice`, `stockQty`, `warningThreshold`, `status`
    
- **InventoryFlow**: `id`, `skuCode`, `changeQty` (+/-), `reason` (进货/出库/损耗), `operatorId`, `createTime`
    

**3. 订单交易实体 (Order)**

- **OrderMain**: `orderNo`, `customerId`, `totalAmount`, `shippingState` (pending/partial/shipped), `paymentState` (unpaid/partial/cleared), `createTime`
    
- **OrderItem**: `id`, `orderNo`, `skuCode`, `qty`, `unitPrice`, `subTotal`
    

**4. 独立发货单实体 (Shipping - 承接分批发货)**

- **ShippingRecord**: `shippingNo`, `orderNo`, `carrier` (如德邦), `trackingNo`, `status` (transit/delivered), `shipDate`
    
- **ShippingItem**: `id`, `shippingNo`, `skuCode`, `shippedQty` (本次实际发货量)
    

**5. 财务及报销实体 (Invoice & Expense)**

- **InvoicePool** (票据池): `id`, `uploaderId`, `fileUrl`, `merchantName`, `amount`, `invoiceDate`, `type` (客户发票/报销发票), `is_deleted` (防物理篡改)
    
- **ExpenseRecord** (报销总单): `systemNo`, `applicantId`, `totalAmount`, `status` (draft/pending/approved/rejected)
    
- **ExpenseDetail** (报销明细行): `id`, `systemNo`, `invoiceId`, `expenseDesc`, `originalType` (油费/招待), `offsetType` (冲顶类型), `amount`
    

**6. 权限角色实体 (Role & Setup)**

- **User**: `userId`, `deptId`, `roleId`, `username`, `passwordHash`, `status`
    
- **Role**: `roleId`, `roleName`, `dataScope` (all/dept_and_sub/self), `menuKeys`
    

## 4. 下一阶段开发规划 (Next Phase Planning)

前端 UI 及交互体验已接近完全体（目前皆由 `ref/reactive` 驱动的纯本地响应式黑盒）。开启新一轮对话进入后端主导阶段，强烈建议按以下顺位破冰：

1. **确定后端框架与建库方案**：
    
    - 优先依据上述实体契约搭建关系型数据库模型（含 ER 关联图设计）。
        
    - 注意：所有财务与流水表强制引入 `is_deleted` 及 `update_time` 等审计字段。
        
2. **鉴权与 RBAC 拦截栈基座开发**：
    
    - 开发 JWT Token 签发与认证体系。
        
    - 核心难点预警：必须在底层封装针对 `dataScope` 的 SQL 动态拼接过滤器，严防数据越权访问。
        
3. **消除前端 Mock 层联调**：
    
    - 配置前端代理环境。
        
    - 开发通用 CRUD 接口，逐步替换 Vue 文件中的 Mock 数据。
        
4. **复杂流体业务 API 攻坚**：
    
    - 开发“历史专享价”带出接口。
        
    - 开发“分批发货关联扣减订单待发数量”的事务一致性逻辑。
        
    - 开发“购物车报销合单”的长事务锁定逻辑。