11：业务全景：领域、接口、表与交互关系

本章是当前 CRM 的业务地图。后续每个业务章节都从这里的“领域 → 接口 → Service → 表”关系展开。

1. 当前项目真正管理的是什么

它不是只有“客户 CRUD”的项目，而是一条从商机到成交的 CRM 业务链：

flowchart LR
    A["客户主资料"] --> B["客户-产品跟进"]
    B --> C["跟进记录、联系人、保护期"]
    C --> D["项目评估"]
    C --> E["试单申请"]
    D --> F["合同"]
    E --> F
    F --> G["合同审批结果"]
    G --> H["客户成交日期与跟进截止时间联动"]

    B --> I["到期、转移、分享、公海、认领"]
    I --> B

主线的核心不是客户本身，而是 客户 + 产品 的 customer_product_follow。同一个客户可以由不同商务跟进不同产品；产品跟进的状态、保护期限和成交阶段决定后续能否创建项目评估、试单和合同。

2. 业务域清单

业务域	核心 Controller / Service	关键表	主要动作
客户主资料	CustomerInfoController / CustomerInfoServiceImpl	customer_info	新增、编辑、详情、删除、导入、工商信息查询
客户附属资料	联系人、地区、工商、发票、银行各 Service	customer_contact、customer_region、customer_business_info、customer_invoice、customer_bank_info	客户资料补全与变更审计
产品跟进	CustomerProductFollowController / CustomerProductFollowServiceImpl	customer_product_follow	新增跟进、转移、分享、保护期、截止时间规则
跟进记录	CustomerFollowRecordController / CustomerFollowRecordServiceImpl	customer_follow_record、customer_follow_record_comment	沟通记录、附件、评论、刷新保护期
公海	CustomerProductPublicPoolServiceImpl、PublicPoolJob	customer_product_public_pool、customer_product_claim_log	到期入公海、认领、冻结、已成交降级
保护规则	两个 Protect 配置 Service	customer_protect_configuration、customer_protect_special_config	各阶段期限、容量、特殊客户规则
项目评估	ProjectEvaluationController / ProjectEvaluationServiceImpl	project_evaluation + 6 张明细表	评估、风险、结算、保险、附件、审批
合同	ContractController / ContractServiceImpl	contract + 6 张明细表	合同编号、客户/联系人/规则/垫资、审批与回调
试单	TrialOrderApplicationController / Service	trial_order_application、trial_order_product	试单产品、审批、跟进期限联动
基础资料	品牌、产品、行业、地区、岗位、结算规则 Service	customer_brand、product、industry_dict 等	下拉选项、关联配置、分页维护
文件/审计/导入	SysFileServiceImpl、变更日志、Import Processor	sys_file、customer_info_change_log、import_record	附件、字段变更、Excel 批量写入

3. Controller 的访问前缀

绝大部分客户端接口由 @WebClientRestController 生成 /crm/web/client/... 前缀；少数 Controller 直接使用 @RequestMapping("/web/client/...")。不要凭文件名猜 URL，应先看 Controller 注解。

典型入口：

/crm/web/client/customerInfo/*
/web/client/customerProductFollow/*
/crm/web/client/customerFollowRecord/*
/crm/web/client/projectEvaluation/*
/crm/web/client/contract/*
/crm/web/client/trialOrderApplication/*

每个 Controller 的职责是把 Form 转 DTO、调用 Service、返回 Result<T>；业务顺序必须到 ServiceImpl 中看。

4. 数据库脚本与实际表

当前仓库同时保留：

src/main/resources/sql/init.sql    # MySQL 方言
src/main/resources/sql/pginit.sql  # PostgreSQL 方言

两份脚本表达同一批核心业务表。实际使用哪种数据库必须以环境配置和团队说明为准；不要将 Demo 的 MySQL 建表语句直接用于正式环境。

核心表按关系分组：

客户：customer_info
  ├─ customer_region
  ├─ customer_business_info
  ├─ customer_contact
  ├─ customer_invoice
  ├─ customer_bank_info
  └─ customer_info_change_log

客户-产品：customer_product_follow
  ├─ customer_product_follow_contact
  ├─ customer_product_follow_contact_relation
  ├─ customer_follow_record
  │   └─ customer_follow_record_comment
  ├─ customer_follow_deadline_log
  ├─ customer_product_claim_log
  ├─ customer_transfer_log
  └─ customer_product_public_pool

项目评估：project_evaluation
  ├─ project_evaluation_risk_content
  ├─ project_evaluation_service_requirement
  ├─ project_evaluation_settlement_rule
  ├─ project_evaluation_personnel_type
  ├─ project_evaluation_advance_payment_purpose
  └─ project_evaluation_insurance_instruction

合同：contract
  ├─ contract_contact
  ├─ contract_customer_relation
  ├─ contract_settlement_rule
  ├─ contract_advance_payment_purpose
  ├─ contract_business_model
  └─ contract_number_sequence

5. 一条数据从前端到数据库的真实形态

以项目评估新增为例：

ProjectEvaluationAddForm（API 模块）
  -> ProjectEvaluationConverter
  -> ProjectEvaluationDto（Service 模块）
  -> ProjectEvaluationServiceImpl.insertProjectEvaluation
  -> project_evaluation 主表
  -> 6 张项目评估明细表
  -> sys_file 附件表
  -> SaasBpmModelServer.startFlow
  -> 回写 flow_id / flow_status

这就是为什么企业项目不能只看 Controller：一个“保存”按钮可能导致多张表写入和一次远程流程调用。

6. 你在 Demo 的实现顺序

不要直接复制全部 46 张表。按正式业务链的最小子集做：

第一层：demo_customer
第二层：demo_customer_product_follow
第三层：demo_follow_record
第四层：demo_project_evaluation
第五层：demo_contract

每增加一层，都必须先写清：

1. 主键和外键关系；
2. 允许的状态；
3. 创建前置条件；
4. 保存时哪些表必须放在同一事务；
5. 状态变化后要更新哪些字段或日志。

7. 阅读当前源码的固定方法

对任何业务域都执行以下四步：

1. Controller：找到 URL、Form、调用的 Service 方法
2. Form / DTO：找到前端能传哪些字段
3. ServiceImpl：找到校验、事务、子表、远程调用、状态回写
4. Entity + init.sql / pginit.sql：核对真正写到哪张表、字段和索引

后续九章严格按这个方法拆解。