andy/by-crm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
60c416e553
by-crm/CLAUDE.md
andy 60c416e553 初始化项目
2026-01-23 17:20:52 +08:00

5.4 KiB
Raw Blame History

  • 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（后端）

    项目结构

    by-crm/
├── backend/                 # Spring Boot 工程
│   ├── src/main/com/bycrm/
│   │   ├── controller/      # Web 层，RESTful API
│   │   ├── service/         # 业务层
│   │   ├── mapper/          # MyBatis DAO
│   │   ├── entity/          # PO / DTO / VO
│   │   ├── config/          # 跨域、MyBatis、Swagger 等配置
│   │   └── ByCrmApplication.java
│   ├── src/main/resources/
│   │   ├── mapper/*.xml     # SQL 映射
│   │   └── application.yml  # 数据源、MyBatis、JWT、有效期等配置
│   └── pom.xml
├── frontend/                # Vue 3 工程
│   ├── src/
│   │   ├── api/             # 接口封装（axios）
│   │   ├── views/           # 页面级组件
│   │   ├── components/      # 通用组件
│   │   ├── router/          # Vue Router
│   │   ├── stores/          # Pinia 状态
│   │   ├── types/           # TypeScript 类型
│   │   └── utils/           # 权限、请求拦截、日期格式化
│   ├── vite.config.ts
│   └── package.json
├── sql/
│   └── init.sql             # 客户表、报备表、经销商表、字典表
└── docs/
    └── api.md               # Swagger 导出文档

    开发命令

    后端

    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-保护中。

    后续迭代方向

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

    API 接口说明

    认证接口

    • POST /api/auth/login - 用户登录
    • GET /api/auth/user/info - 获取当前用户信息
    • POST /api/auth/logout - 用户退出

    客户接口

    • GET /api/customer/page - 分页查询客户
    • GET /api/customer/{id} - 获取客户详情
    • POST /api/customer - 创建客户
    • PUT /api/customer/{id} - 更新客户
    • DELETE /api/customer/{id} - 删除客户
    • GET /api/customer/search - 搜索客户（用于客户唯一性校验）

    报备接口

    • GET /api/report/page - 分页查询报备
    • GET /api/report/{id} - 获取报备详情
    • POST /api/report - 创建报备
    • PUT /api/report/{id}/audit - 审核报备
    • DELETE /api/report/{id} - 撤回报备

    经销商接口（仅管理员）

    • GET /api/dealer/list - 查询所有经销商
    • GET /api/dealer/{id} - 获取经销商详情
    • POST /api/dealer - 创建经销商
    • PUT /api/dealer/{id} - 更新经销商
    • DELETE /api/dealer/{id} - 删除经销商

    默认测试账号

    • 管理员：admin / admin123
    • 经销商用户1：user001 / admin123
    • 经销商用户2：user002 / admin123
    • 经销商用户3：user003 / admin123