CRM 系统开发规范

本仓库为 CRM 系统多模块单仓库工程。crm-base 是所有业务模块的基础包，所有业务模块必须依赖 crm-base 并遵守本文档的规范开发。

1. 技术栈

项	版本/选型
JDK	17
Spring Boot	3.3.x（父 pom 统一管理）
ORM	MyBatis-Plus（运行时 CRUD）+ JPA 注解（ddl-auto 自动建表，全环境统一）
认证	Spring Security + JWT（由 crm-auth 模块实现，base 只依赖 spring-security-core）
文件存储	MinIO（对象存储）+ kkFileView（在线预览），由 crm-file 模块实现
缓存	Redis（RedisTemplate 已配置 JSON 序列化）
文档	Knife4j（/doc.html）
工具库	Hutool、Guava、EasyExcel

2. 工程结构与模块命名

crm/                        # 父工程（本仓库根目录），统一管理依赖版本
├── crm-base/               # 基础包，不含任何业务
├── crm-auth/               # 认证与权限：三方扫码登录、JWT、统一用户、部门/角色/菜单、数据权限
├── crm-file/               # 文件模块：直传/三阶段分片上传（MinIO）、下载、kkFileView 预览
├── crm-app/                # 唯一启动入口：聚合全部模块打可执行 jar（其他模块不 repackage）
├── crm-dict/               # 数据字典：两级分组/字典项，业务方按 code 消费
├── crm-rule/               # 线索公海池配置域：公海池/人员/领取规则/区域（crm-lead 的上游）
├── crm-lead/               # 线索业务域：7 状态机 + 四视图 + 领取/分配/反馈/转商机/释放
├── crm-preference/         # 列偏好：用户级列显隐/拖拽排序（与 crm-dict 平行的通用模块）
├── crm-customer/           # （待建）业务模块示例：客户域
└── crm-xxx/                # 业务模块命名规范：crm-{业务域}，小写中划线

• 新增模块时在根 pom.xml 的 <modules> 中登记，并在 <dependencyManagement> 中管理其版本。
• 业务模块依赖版本一律继承父 pom，子模块 pom 中不允许出现 <version> 硬编码（内部模块除外）。

3. 业务模块内包结构（模板）

以客户模块为例，根包 com.crm.customer：

com.crm.customer
├── controller/             # XxxController，只做参数接收/校验/包装 Result，不写业务逻辑
├── service/                # 接口：IXxxService extends IBaseService<Xxx>
│   └── impl/               # 实现：XxxServiceImpl extends BaseServiceImpl<XxxMapper, Xxx>
├── mapper/                 # XxxMapper extends CrmBaseMapper<Xxx>
├── domain/
│   ├── entity/             # 实体 Xxx extends BaseEntity（与表一一对应）
│   ├── dto/                # XxxDTO extends BaseDTO（abstract，出入参双向载体）
│   ├── vo/                 # XxxVO（仅用于视图展示的聚合对象，可选）
│   ├── param/              # XxxParam extends BaseParam（查询入参）
│   └── enums/              # 业务枚举，必须实现 HasValueEnum
├── constant/               # 模块内常量（可选）
└── task/                   # 定时任务（可选，执行前校验 ScheduledTaskProperties.owner）

启动类约定

业务模块的启动类必须扫描到 com.crm 下的全部组件与 Mapper：

@SpringBootApplication(scanBasePackages = "com.crm")
@MapperScan("com.crm.**.mapper")
@EnableJpaRepositories(considerNestedRepositories = false) // 如不用 JPA Repository 可不加
public class CustomerApplication { ... }

建表统一由 JPA 注解 + Hibernate ddl-auto: update 完成（全环境一致，不维护 SQL 脚本；运行时 CRUD 全部走 MyBatis-Plus）。 新增字段的 DEFAULT 值、索引、唯一约束务必通过 columnDefinition / @Table(indexes/uniqueConstraints) 完整声明：

spring:
  jpa:
    hibernate:
      ddl-auto: update

4. 类命名规范

类型	命名	继承/实现	说明
实体	Customer	BaseEntity	与表一一对应，不加后缀
传输对象	CustomerDTO	BaseDTO（abstract）	出入参双向载体，业务类继承白拿 id/createTime/updateTime
视图对象	CustomerVO	-	多表聚合展示时使用
查询参数	CustomerParam	BaseParam	分页/条件查询入参
控制器	CustomerController	-	返回值必须是 Result<T>
服务接口	ICustomerService	IBaseService<Customer>
服务实现	CustomerServiceImpl	BaseServiceImpl<CustomerMapper, Customer>
Mapper	CustomerMapper	CrmBaseMapper<Customer>	自动获得 batchUpsert
枚举	CustomerTypeEnum	HasValueEnum<T>	枚举值常量全大写
异常	XxxException	RuntimeException	优先复用 base 的 4 个异常

5. 数据库规范

• 表名：crm_{模块}_{实体}，全小写下划线，如 crm_customer_info、crm_order_item。
• 字段名：全小写下划线（实体字段驼峰自动映射）。
• 每张表必备公共字段（由 BaseEntity 携带，自动填充，勿手动赋值）：

字段	类型	说明
id	bigint	雪花 ID 主键（IdType.ASSIGN_ID，CustomIdGenerator 生成）
creator_id	varchar(50)	创建用户 id，插入时自动填充
create_time	datetime	创建时间，插入时自动填充
updater_id	varchar(50)	更新用户 id，插入/更新时自动填充
update_time	datetime	更新时间，插入/更新时自动填充
deleted	tinyint NOT NULL DEFAULT 0	逻辑删除位，删除一律走 removeById 系列

• 多实例部署时必须为每个实例配置不同的雪花机器位：

crm:
  snowflake:
    worker-id: 1        # 0~31，实例间互不相同
    datacenter-id: 0    # 0~31

6. 接口规范

• URL：/api/{模块}/{资源}，资源用名词复数或动宾结构，如 POST /api/customer/customers、GET /api/customer/customers/page。
• 返回值统一 Result<T>；分页返回 Result<PageResult<T>>（Result.page(...) 一行包装）。
• HTTP 状态码：业务失败也返回 200，通过 code/success 判断；仅系统异常 500、路径不存在 404、授权拒绝 403。
• 入参校验用 @Valid + jakarta.validation 注解，校验失败由全局异常处理统一返回 40001。
• Long 类型（含雪花 ID）已全局序列化为字符串，前端回传时按字符串传即可。
• 日期时间格式统一 yyyy-MM-dd HH:mm:ss（GMT+8）。

7. 响应码分段（新增须在此登记）

区间	含义	归属
0	成功	base
400xx	参数类错误	base
401xx	认证/身份错误	base / crm-auth
403xx	权限错误	base
404xx	资源不存在	base
405xx	请求方式错误	base
500xx	系统/外部调用错误	base
60001	通用业务错误	base
61001~61999	认证模块（61001 不支持的登录方式 / 61002 三方授权失败 / 61003 账号禁用 / 61004 部门分配参数非法 / 61005 部门不存在 / 61006 部门下仍有成员拒删 / 61007 部门移动非法防环）	crm-auth
62001~62999	文件模块（62001 大小超限 / 62002 类型禁止 / 62003 上传会话不存在 / 62004 分片不完整 / 62005 预览服务不可用 / 62006 分片大小配置错误）	crm-file
63001~63999	数据字典（63001 参数非法 / 63002 分组编码已存在 / 63003 内置字典保护 / 63004 分组下仍有字典项 / 63005 分组不存在或已停用 / 63006 字典编码组内重复 / 63007 字典值同组重复 / 63008 身份字段只读 / 63009 字典项被引用 / 63010 字典项不存在 / 63011 分组不存在 / 63012 仅启用项可设默认）	crm-dict
64001~64999	公海池配置（64001 参数非法 / 64002 池名重复 / 64003 部门已有公海池 / 64004 池不存在 / 64005 池内仍有活跃线索拒删 / 64006 池成员非法 / 64007 区域不存在）	crm-rule
65001~65999	线索业务（65001 线索无效 / 65002 线索不存在 / 65003 起始态不允许迁移 / 65004 非领取人 / 65005 领取规则拒绝 / 65006 日领取上限 / 65007 持有上限 / 65008 转商机失败 / 65009 已转商机不可删改 / 65010 乐观锁 CAS 冲突）	crm-lead

8. 异常与断言规范

• 业务代码不要 try-catch 后自己拼 Result，直接抛异常交给 GlobalExceptionHandlerAdvice：
  • 业务规则不满足 → BusinessErrorException 或 AssertUtils.isTrue/notNull(...)
  • 查不到数据 → service.getByIdOrThrow(id) 或 AssertUtils.exist(...)（返回 40401）
  • 权限不足 → PermissionErrorException
• 日志：业务异常打 warn（无堆栈），系统异常打 error（带堆栈）。禁止 e.printStackTrace()。

9. 日志与链路

• TraceIdFilter 已为每个请求注入 traceId（透传请求头 X-Trace-Id，无则生成），并回写响应头。
• 各模块 logback pattern 必须包含 %X{traceId}：

%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{36} - %msg%n

10. crm-base 能力清单

包	内容
advice	GlobalExceptionHandlerAdvice 全局异常处理
config	CORS、MyBatis-Plus（分页/防全表更新/批量Upsert注入器）、雪花ID、公共字段填充、Jackson（Long→String、日期格式）、Redis 序列化、Knife4j、定时任务属主
constant	CommonConstants（traceId、分页上限、批量条数）
domain	BaseEntity / BaseDTO / BaseParam / Result / PageResult / ResultCodeEnum / HasValueEnum / StatusEnum / 4 个通用异常
filter	TraceIdFilter
mapper	CrmBaseMapper（含 batchUpsert）
security	LoginUser 接口、SecurityUtils（当前用户）、DataVisibility / DataVisibilityContext（数据可见性范围，见 §12）
annotation	@DataScope（实体级数据权限声明，见 §12）
service	IBaseService / BaseServiceImpl（getByIdOrThrow、pageResult、batchUpsert 分批）
utils	AssertUtils、BeanCopyUtils、EnumUtils、ExcelUtil（导入/导出）、PageConverter（防注入排序）、ServletUtils、TreeUtils

11. 典型用法示例

// Controller
@PostMapping("/page")
public Result<PageResult<CustomerDTO>> page(@RequestBody CustomerParam param) {
    PageResult<Customer> page = customerService.pageByParam(param);
    return Result.page(page.convert(e -> e.toDTO(CustomerDTO::new)));
}

// Service 实现
@Service
public class CustomerServiceImpl extends BaseServiceImpl<CustomerMapper, Customer>
        implements ICustomerService {

    @Override
    public PageResult<Customer> pageByParam(CustomerParam param) {
        Page<Customer> page = PageConverter.toMpPage(param);
        lambdaQuery()
                .like(StrUtil.isNotBlank(param.getKeyword()), Customer::getName, param.getKeyword())
                .page(page);
        return new PageResult<>(page);
    }

    @Override
    public void changeOwner(Long customerId, String newOwnerId) {
        Customer customer = getByIdOrThrow(customerId);
        AssertUtils.isFalse(newOwnerId.equals(customer.getOwnerId()), "客户已归属该负责人");
        // ...
    }
}

12. 认证与权限模块（crm-auth）

统一用户 + 三方扫码登录 + 部门/角色/菜单 + 数据权限，业务模块只需依赖 crm-auth 即可获得登录校验与数据权限能力（无需自己配 Security）。

数据模型

表	说明
crm_auth_user	全 CRM 统一用户，业务表里的负责人/创建人等 id 均指向本表；含 dept_id 归属部门（数据权限用）
crm_auth_identity	三方身份绑定，一个用户可绑多个平台身份，唯一约束 (identity_type, union_id)
sys_dept	部门层级（父子关系 + 祖级链）
sys_menu	菜单/按钮资源，目录/菜单/按钮三类型
sys_role	角色，携带数据范围（DataScopeEnum）
sys_role_menu / sys_user_role	角色-菜单、用户-角色多对多关系

首次启动时 DataInitializer 会在 sys_role 为空时初始化管理员角色（数据范围=全部）与系统管理菜单。

登录流程

前端扫码拿 authCode ──▶ POST /api/auth/login/dingtalk {authCode}
   后端: authCode 换三方用户(unionId, mobile...) 
        ├─ 该三方身份已绑定? ─是─▶ 取绑定用户
        ├─ 按手机号匹配已有用户? ─是─▶ 复用(跨平台合一) + 补绑身份
        └─ 都没有 ─▶ 首登自动注册 + 绑定身份
   ──▶ 签发 JWT(存 Redis) ──▶ 返回 {token, userInfo}

• 跨平台身份映射键：手机号。钉钉、企微用同一手机号视为同一 CRM 用户。要拿到手机号，需在三方开放平台为应用开通手机号权限。
• 扩展新渠道（如企微）：实现 ThirdPartyAuthClient 接口并注册为 Bean、在 IdentityTypeEnum 加枚举、Controller 加一个登录入口即可，登录主流程零改动。

会话（JWT + Redis）

• token 放请求头：Authorization: Bearer {token}。
• 双重校验：先验 JWT 签名，再查 Redis（不存在即已下线/过期）；剩余有效期不足一半自动续满（滑动过期）。
• 强制下线：删除对应 Redis key。
• 关键配置（生产用环境变量注入）：

crm:
  auth:
    jwt:
      secret: ${CRM_JWT_SECRET}      # 至少 32 位随机串
      ttl-days: 7
    ignore-urls:                     # 业务模块追加放行路径（默认已放行登录/文档）
      - /api/xxx/callback/**
    dingtalk:
      client-id: ${DINGTALK_CLIENT_ID}
      client-secret: ${DINGTALK_CLIENT_SECRET}

业务模块如何接入

1. pom 依赖 crm-auth（会传递带上 crm-base）。
2. 启动类 @SpringBootApplication(scanBasePackages = "com.crm") + @MapperScan("com.crm.**.mapper")。
3. 若需 Hibernate 自动建 auth 表，启动类加 @EntityScan("com.crm")（各服务独立部署 auth 时无需关心）。
4. 业务代码取当前用户：SecurityUtils.getUserId() / getRequiredUserId()（来自 crm-base）。

菜单/角色/部门管理接口

SystemController 提供 /api/system/**：菜单树 GET /menus/tree（按当前用户角色过滤，前端据此控制路由/UI）、菜单/角色/部门的 save/delete、角色分页 POST /roles/page、分配菜单 POST /roles/assign-menus、分配角色 POST /users/assign-roles 等。

数据权限（行级过滤）

基于 MyBatis 拦截器在 SQL 层自动注入过滤条件，业务代码零侵入：

• 声明：在需要受控的实体类上标 @DataScope(ownerColumn = "owner_id", deptColumn = "dept_id")（crm-base 提供），未标注的表不受影响。
• 生效链路：JWT 认证通过后 PermissionService.initDataScopeContext() 按用户角色取最宽档位、结出部门集合（含子部门档位预先展开子树），整包装入 DataVisibilityContext（ThreadLocal，不跳线程）；读侧 DataScopeInterceptor 拦截 SELECT，把可见范围翻成 WHERE 条件，写侧 MetaObjectFillHandler 取同一份身份填归属字段。
• 档位（DataScopeLevel，取值来自 sys_role.data_scope）：1 仅本人（owner_id=当前用户）/ 2 本部门（dept_id IN 部门集合）/ 3 本部门及下属部门（dept_id IN 展开子树后的部门集合）/ 4 全部（不过滤）。多角色取最宽档，无角色按最窄档。
• fail-closed：按部门档位遇上空部门集合则一律不可见（注入 1=0），不会退化成不过滤；未知档位等脏配置直接让请求失败而不静默放行。详见 ADR-0006。

13. 文件模块（crm-file）

通用文件上传/下载/预览（MinIO + kkFileView），前端接口与后端内部服务共用。领域术语见 crm-file/CONTEXT.md，关键决策见 ADR-0003/0004。

接口与能力

• HTTP（/api/file/**）：直传 POST /upload、详情 GET /info、下载 GET /download（信封例外：成功二进制流，失败 JSON 信封）、预览地址 GET /preview-url、逻辑删除 POST /delete、分片三阶段 POST /multipart/init|upload|complete。
• 内部调用：一律注入 FileApi 门面（流式/byte[] 上传等），业务表只存 fileId 字符串，上传必传业务域 bizDomain。
• 分片上传（中转三阶段，ADR-0004）：init 建会话存 Redis（支持带 uploadId 断点续传）→ 逐片写入 MinIO 临时对象 chunks/{uploadId}/{序号} → complete 校验齐全后 composeObject 合并落库。孤儿分片由 OrphanChunkCleanupTask 定时兜底清理。
• 预览：后端对文件签内网 presigned GET → 拼入 kkFileView onlinePreview 地址返回，浏览器只接触 kkFileView，MinIO 不暴公网。
• 守门校验：扩展名黑名单、直传上限、单文件总大小上限，越界抛 62xxx（见 §7）。

关键配置（前缀 crm.file，生产凭证用环境变量注入）

crm:
  file:
    minio:
      endpoint: http://minio内网地址:9000
      access-key: ${CRM_MINIO_AK}
      secret-key: ${CRM_MINIO_SK}
      bucket: crm                    # 不存在时启动自动创建
    preview:
      kkfileview-url: ${CRM_KKFILEVIEW_URL}   # 必须浏览器可达
      presign-ttl: 10m
    chunk-size: 5MB                  # 硬下限 5MB（composeObject 约束）
    direct-upload-limit: 10MB        # 超过必须走分片
    max-file-size: 1GB
    upload-session-ttl: 24h
    cleanup-cron: 0 0 3 * * ?

14. 线索模块（crm-lead）

线索全生命周期业务域：7 状态机 + 四视图 + 领取/分配/反馈/转商机/释放，以及超时回收与失效两个定时任务。领域术语与决策见 crm-lead/CONTEXT.md，关键决策见 ADR-0018~0022。

依赖方向

单向 crm-lead → crm-rule → (crm-auth / crm-dict)；公海池实体归 crm-rule，本模块只消费。crm-lead 另依赖 crm-preference（列偏好，单向，crm-preference 不得反向引用，见 §16）。

接口与能力

• HTTP（/api/lead/**）：四视图分页 POST /page、详情 GET /detail、历史时间线 GET /history，以及领取/分配/反馈/转商机/释放/激活/关注等命令。
• 四视图（viewType，取值域为 LeadViewType 枚举）：PUBLIC_POOL（公海，status=待领取）/ MY_LEAD（我的线索，owner=当前用户）/ MY_FOLLOW（我的关注）/ MANAGE（线索管理，@DataScope 部门天花板）；空/非法值回落 MANAGE。
• 批量命令非原子、逐条 CAS、部分成功：返回 BatchResult（成功 N / 失败 M + 结构化失败原因 LeadBatchFailReason）。

内部模块（读写分离，ADR-0022）

LeadServiceImpl 已按「深度」拆为三个深模块 + 写侧命令编排：

深模块	藏起的机制	契约要点
LeadTransition	7 状态迁移 + 统一 guard（起始态/持有人）+ 状态 CAS 乐观锁	对 crm-rule/crm-auth 零依赖；声明式 allowedFromStatuses()/requiresOwner()
LeadHistoryRecorder	组装 LeadHistory + kv 明细序列化 JSON + 落库	单方法 record(...)，写侧与迁移侧共用；空 kv 存 null
LeadViewQuery	四视图分页 + 详情 + 历史时间线 + 展示字段拼装	独占读依赖；自持 LeadMapper 用 selectPage

• 状态 CAS：所有写状态的 UPDATE 一律带 AND status IN (合法起始态)，行数=0 即判「已被他人操作」（ADR-0021）。守卫在 CAS 之上给友好前置（非法态 65003 / 非持有人 65004）。
• 转商机端口 OpportunityCreationPort：商机模块尚不存在，本模块只定接口；首个实现须与 crm-lead 同库共享事务（ADR-0020）。

定时任务

超时回收（RECYCLE）与失效（EXPIRE）两个任务，执行前校验 ScheduledTaskProperties.owner；失效任务先于回收任务运行（ADR-0019）。

15. 公海池配置模块（crm-rule）

线索公海池的配置域：公海池实体（归属部门 + 省/市/区）、人员（负责人/协作人/成员）、领取规则、超时回收/失效/领取上限配置、区域字典。领域术语见 crm-rule/CONTEXT.md。

• 依赖方向：单向 crm-rule → (crm-auth / crm-dict)，不得反向依赖 crm-lead——公海池不知道线索存在。公海池表复用 crm-base 数据范围模块。
• HTTP（/api/rule/**）：公海池管理 /api/rule/pool、区域查询 /api/rule/region。
• 对外读服务：ISysRegionService（省市 code→name，供 crm-lead 展示拼装消费）。

16. 列偏好模块（crm-preference）

平台级用户列表列偏好（用户级列显隐 + 拖拽排序），与 crm-dict 平行的通用模块。契约仅 get / save 两法。领域术语见 crm-preference/CONTEXT.md。

• 依赖方向：只依赖 crm-base。业务方（如 crm-lead）单向依赖它；scope_key 由业务方约定的稳定 code（如 lead.public_pool），crm-preference 仅作不透明字符串存储、不持有字段清单语义。
• 每菜单独立：线索域有 4 个 scope（公海 / 我的线索 / 我的关注 / 线索管理），互不同步。候选列清单归业务方定义，本模块只存用户勾选与排序结果（visible_keys / column_order）。
• HTTP：/api/preference/**。