by-crm/CLAUDE.md

• CLAUDE.md

  此文件为 Claude Code (claude.ai/code) 在此仓库中工作时提供指导。

  项目名称

  经销商管理系统

  项目概述

  经销商管理系统是一款面向企业渠道管理的CRM系统，核心解决“客户报备冲突”与“保护期归属”问题。系统通过唯一有效报备机制与自动到期释放机制，确保同一客户在同一时间只能被一个经销商跟进，并在保护期结束后自动回归可报备池，避免长期占坑，提升渠道效率与公平性。

  技术栈

  • 前端：Vue 3 + TypeScript + Vite + Element Plus
  • 后端：Spring Boot 2.7 + MyBatis + MySQL 8
  • 架构模式：前后端分离，MVC 分层
  • 构建工具：Maven（后端）、pnpm（前端）
  • 代码规范：ESLint + Prettier（前端）、SpotBugs + Checkstyle（后端）

  开发命令

  后端

  cd backend
  mvn spring-boot:run          # 本地启动（端口 8080）
  mvn test                     # 单元测试
  mvn spotbugs:check           # 静态检查
  

  前端

  cd frontend
  pnpm install
  pnpm dev                     # 本地启动（端口 5173）
  pnpm build                   # 生成 dist
  pnpm lint                    # ESLint 检查
  

  核心业务流程（供编码时参考）

  1. 客户唯一性校验：新建客户时先模糊匹配名称，命中则禁止重复创建。
  2. 报备申请：经销商选择客户 → 填写简要说明 → 提交。
  3. 防撞单：提交瞬间校验该客户是否已存在“有效”报备，存在则直接提示冲突。
  4. 审核：管理员在后台查看待审核列表 → 通过（生成保护期）/ 驳回（填写原因）。
  5. 保护期：通过后自动计算到期日（默认 90 天，可配置），到期凌晨定时任务将状态置为“已失效”，客户重新变为“可报备”。
  6. 数据可见性：经销商仅看“自己的客户 + 自己的报备”；管理员可看全部。

  关键配置项

  • application.yml 中的 crm.report.ttl-days 控制保护期天数。
  • crm.report.allow-overlap 仅用于测试开关，生产必须保持 false。
  • Vue 全局拦截器统一注入 JWT（登录后返回），权限粒度到按钮级。

  数据库命名规范

  • 表名：全小写，下划线分割，如 customer, report, dealer,以 crm_ 开头。
  • 字段：全小写，下划线，主键 id，不需要外键，外键由程序控制，时间 created_at, updated_at。
  • 字典：使用 tinyint 并配套枚举类，如 customer_status 0-可报备 1-保护中。

  后续迭代方向

  • 微信小程序端提交报备
  • 客户公海池与主动分配
  • 报备延期申请流程
  • 报表：经销商活跃度、客户转化率`