01：当前 CRM 工程与模块边界

1. 正式工程不是一个单体 Demo

当前项目根目录：

hc-crm-center/
├── pom.xml                         # 父 POM、模块聚合、公司私服配置
├── hc-crm-center-api/              # 可被其他服务依赖的接口契约
└── hc-crm-center-service/          # 真正启动和运行的业务服务

它是 Java 8 + Maven 多模块 + Spring Boot + MyBatis-Plus 的企业服务。Service 模块还依赖公司内部 Starter、认证、租户、流程、文件、系统等服务。

你的 Demo 是单模块工程，故意删掉了这些企业依赖，目标是让你先掌握核心后端编程。

2. API 模块的职责

路径：hc-crm-center-api/src/main/java/com/hc/crm/

api/       # 跨服务接口或 Feign 契约
enums/     # 枚举，例如跟进阶段、是否海外客户
form/      # Controller 接收的请求对象
vo/        # Controller 返回给前端的对象

API 模块只放“别人可以依赖的稳定协议”，不放数据库访问和复杂业务实现。

例如客户新增入参在：

com.hc.crm.form.CustomerInfoAddForm

客户详情返回值在：

com.hc.crm.vo.CustomerInfoVo

3. Service 模块的职责

路径：hc-crm-center-service/src/main/java/com/hc/crm/

controller/      # HTTP 接口入口
converter/       # Form、DTO、Entity、VO 的转换
dto/             # 复杂业务过程中的数据对象
entity/          # 数据库表映射
service/         # 业务接口
service/impl/    # 业务实现
mapper/          # Mapper 接口
provider/        # 动态 SQL，常用于分页和联表
component/       # 调认证、租户、流程、系统等外部能力
handler/         # 类型转换器
imports/         # Excel 导入
job/             # 定时任务
util/            # 本服务内部工具

4. 客户模块的真实调用链

以客户资料为例：

flowchart TD
    A["前端 POST /crm/web/client/customerInfo/save"] --> B["CustomerInfoController"]
    B --> C["CustomerInfoAddForm + @Valid"]
    C --> D["CustomerInfoConverter"]
    D --> E["CustomerInfoDto"]
    E --> F["CustomerInfoService"]
    F --> G["CustomerInfoServiceImpl"]
    G --> H["CustomerInfoMapper / MyBatis-Plus"]
    H --> I[("customer_info")]
    G --> J["地区、工商、跟进、开票、银行等子表"]

对应源码入口：

controller/web/client/CustomerInfoController.java
service/CustomerInfoService.java
service/impl/CustomerInfoServiceImpl.java
mapper/CustomerInfoMapper.java
provider/CustomerInfoProvider.java
entity/CustomerInfo.java

5. 为什么不能让 Controller 直接查数据库

错误写法：

Controller -> Mapper -> Database

这样一旦要增加名称去重、权限、日志、多个表保存、事务回滚，所有 Controller 都会变乱。

正确分层：

Controller：HTTP、参数校验、调用 Service
Service：业务规则、事务、调用多个 Mapper 或远程服务
Mapper：只做数据读写
Provider：只生成 SQL，不放业务判断
Entity：只表达表结构

6. Demo 与正式工程的差异

项目点	Demo	正式 CRM
Maven 结构	单模块	api + service 多模块
Web 注解	@RestController	内部 @WebClientRestController
响应包装	自建 Result	内部 com.hc.core.api.Result
分页模型	自建 QueryModel / Resolver	@QueryPage、PageInfo、QueryResultUtil
数据库	本机 MySQL	依赖公司环境与配置中心，需确认实际连接配置
权限/租户	不接入	数据权限、用户上下文、租户上下文
写操作	一张表	主表与多个子表、日志、规则、远程调用

这不是 Demo 的缺陷，而是学习顺序：先掌握共通部分，再学习公司封装。

7. 本章练习

1. 打开正式工程根目录的 pom.xml，找到两个 module。
2. 打开 CustomerInfoController，找出 save、edit、findById、query/page、del、del/batch 六类接口。
3. 打开 Demo 的 CustomerInfoController，确认它现在只有分页接口。
4. 用自己的话写下：下一章你要在 Demo 中补齐哪些层。

完成后继续阅读环境章节，不要急着复制正式项目 1000 多行的 CustomerInfoServiceImpl。