Luckean's blog

Appearance

hc-crm-center：从 Demo 到业务开发实战教程 ​

适用对象：有 Java 基础、但尚未接触 Spring Boot、MyBatis-Plus 和企业后端项目的开发者。
正式项目：/Users/admin/code/hc-project/api-java/hc-crm-center
练习项目：/Users/admin/code/hc-project/api-java/my-center
练习数据库：hc-my-demo

1. 这套教程的目标 ​

完成本教程后，你应当能独立在 Demo 中完成一项简单需求：

text
建表
  -> Entity 映射
  -> Mapper 查库
  -> 分页列表
  -> 详情查询
  -> 新增、编辑、删除
  -> 两张表的事务性保存
  -> 接入简单业务规则和测试

然后你再进入正式 hc-crm-center，能判断一个需求应该改 API 模块、Service 模块、数据库、分页 SQL 还是外部服务调用。

2. 先记住六个词 ​

名词用一句话理解Demo 中的位置
Spring Boot帮你启动 Web 服务、接收 HTTP 请求的框架HcMyDemoApplication
Controller接口入口，负责接收参数和返回 JSONcontroller/CustomerInfoController
Service业务规则所在地，不直接面对 HTTPservice/CustomerPageService
MapperJava 与 SQL/数据库之间的访问层mapper/DemoCustomerMapper
Entity一张数据库表对应的 Java 类entity/DemoCustomer
Form / DTO / VO分别代表接口输入、业务传递、接口输出当前 Demo 后续需要你添加

3. 阅读顺序 ​

不要跳过前面的章节。推荐每完成一章的练习并验证接口后，再进入下一章。

  1. 01-当前CRM工程与模块边界
  2. 02-Demo环境、启动与调试
  3. 03-API模块：Form、VO、枚举与接口契约
  4. 04-Service模块：Controller、Service、DTO、Converter
  5. 05-数据层：数据库、Entity、Mapper、Provider
  6. 06-当前项目同款分页：QueryModel与PageInfo
  7. 07-详情查询：VO与聚合查询
  8. 08-CRUD：新增、编辑、删除与参数校验
  9. 09-业务逻辑：多表事务、日志、权限与远程调用
  10. 10-正式项目需求开发、测试与排错

业务源码实战：按当前 CRM 的真实业务域阅读 ​

下面章节不是通用示例，而是根据当前 hc-crm-center 的 Controller、ServiceImpl、DTO/Form/VO、init.sql 和 pginit.sql 整理。每章都说明实际代码入口、涉及表、状态与交互顺序；你在 Demo 中只实现标注的最小闭环。

  1. 11-业务全景：领域、接口、表与交互关系
  2. 12-客户主资料：创建、编辑、详情、删除与附属资料
  3. 13-产品跟进与跟进记录：真实保存和截止时间规则
  4. 14-保护配置、公海、认领、转移与分享
  5. 15-项目评估：多明细保存与 BPM 审批
  6. 16-合同：编号、关联明细、审批与客户联动
  7. 17-试单申请：产品关联、审批与截止时间联动
  8. 18-基础资料：品牌、产品、行业、地区、岗位和结算规则
  9. 19-附件、变更日志、Excel导入与导入记录
  10. 20-横切能力：租户、数据权限、远程服务、流程和数据库总表
  11. 21-客户端接口交互目录：按Controller定位业务

4. 建议的学习节奏 ​

阶段预计投入产出
第一周4～6 小时能启动 Demo，读懂分页查询并修改一个筛选字段
第二周6～8 小时完成客户详情和单表 CRUD
第三周6～10 小时完成客户 + 联系人的两表事务保存
第四周4～8 小时使用正式 CRM 的目录与接口风格重构 Demo

学习的核心原则：先让接口正确工作，再抽取公共结构；先做单表，再做多表业务。

5. 每次练习的固定动作 ​

每次改代码后，固定执行以下步骤：

bash
cd /Users/admin/code/hc-project/api-java/my-center
mvn test

# 需要运行接口时
export MYSQL_USERNAME=root
export MYSQL_PASSWORD='你的本机密码'
mvn spring-boot:run

然后用 Postman、Apifox 或 curl 调用接口。不要只看“项目启动成功”；必须检查响应 JSON 和数据库数据是否符合预期。

6. 本教程不做的事 ​

  • 不要求你一开始接入公司 Maven 私服、Nacos、网关、租户中心或流程中心；
  • 不让你直接修改正式 CRM 的复杂客户保存逻辑；
  • 不建议把本机数据库密码写入 application.yml 后提交 Git；
  • 不把 Demo 当生产系统：它是用于理解正式项目结构的最小练习场。

7. 完成标准 ​

当你能够不看答案完成下列事情，就可以开始接正式项目的小需求：

  • 新建一张表和对应 Entity；
  • 新建 /query/page 接口，且 page、size 走 URL 参数；
  • 用 Form 校验输入，用 VO 返回详情；
  • 在 ServiceImpl 中实现名称去重、保存、修改、删除；
  • 用 @Transactional 保证主表和子表要么全部保存、要么全部回滚；
  • 至少写一组单元测试或接口测试；
  • 能解释 Controller、Service、Mapper 不能互相乱调的原因。

Lucking

粤ICP备2022078904号-1