包概述

com.legacy.crm.customer 包围绕客户域构建，提供客户档案、联系人、标签与跟进日志的管理能力，并支持客户分级与评分、线索合并去重、批量导入导出以及数据权限控制，支撑销售流程与统计。采用传统三层（Web/Service/DAO）与领域建模结合的结构，基于 Spring MVC + MyBatis 实现，辅以分库分表与读写分离、Redis 与本地二级缓存、binlog 增量同步、Bean Validation、统一错误码、对象转换（MapStruct/Dozer）以及 AOP 审计与灰度开关等技术手段，确保在高并发与复杂业务场景下的性能与一致性。

主要功能

• 客户档案管理
  • 维护 Customer 聚合及其属性、生命周期操作；支持联系人（Contact）、标签（Tag）与跟进日志（FollowUpLog）等关联信息的读写。
• 客户分级与评分
  • 结合 domain.policy 的领域策略进行客户等级与评分计算，支持在服务层对评分结果进行持久化或缓存。
• 线索合并与去重
  • 通过 CustomerDedupService 进行重复检测与合并，消除冗余数据，保持客户唯一性。
• 批量导入与导出
  • ImportExportFacade 提供导入校验、结果汇总与导出能力，支持大批量数据处理。
• 数据权限控制
  • 通过 DataScopeAspect 在控制器或服务层切面织入权限约束，实现基于组织/角色/负责人等维度的数据可见性控制。
• 跟进记录与标签管理
  • 维护客户跟进日志、标签的增删改查，支撑销售过程记录与标注。
• 读写分离与缓存加速
  • 读操作优先从只读库与缓存命中，写操作路由主库并触发缓存更新与增量同步。
• 增量同步
  • BinlogListener 监听数据库变更事件，驱动缓存失效/刷新与下游系统同步，确保数据近实时一致。

核心组件

• com.legacy.crm.customer.web
  • CustomerController
    • 职责：提供页面与 REST API；接收请求、参数校验（Bean Validation）、调用服务层、输出统一错误码规范的响应；结合 DataScopeAspect 实施数据权限。
• com.legacy.crm.customer.service
  • CustomerService
    • 职责：客户域核心业务服务；封装聚合内操作（档案、联系人、标签、跟进日志）、分级评分调用、事务控制与缓存协调。
  • CustomerDedupService
    • 职责：去重策略与合并流程编排；调用仓储与映射层完成重复检测、合并写入及一致性维护。
  • ImportExportFacade
    • 职责：批量导入导出门面；执行数据校验、转换、分片处理与结果汇总；与仓储、缓存和增量同步机制协作。
• com.legacy.crm.customer.domain.model
  • Customer（聚合根）
    • 职责：承载客户核心属性与不变式；聚合内管理联系人、标签、跟进日志等子对象的一致性。
  • Contact（值对象）
    • 职责：客户联系人信息的不可变建模；参与聚合内校验与比较。
  • Tag（标签）
    • 职责：客户标签标注；用于分群与检索。
  • FollowUpLog（日志）
    • 职责：跟进记录条目；承载时间、内容、执行人等信息。
• com.legacy.crm.customer.domain.policy
  • 职责：客户分级、评分等领域策略的接口与实现集合；由服务层在业务流程中调用以产出决策结果。
• com.legacy.crm.customer.dao
  • CustomerRepository（仓储接口）
    • 职责：面向领域的持久化抽象；隐藏 MyBatis 细节，提供聚合级读写能力。
  • CustomerMapper（MyBatis）
    • 职责：SQL 映射与数据访问；支持分库分表与读写分离策略的路由。
• com.legacy.crm.customer.convert
  • Convertor（对象转换）
    • 职责：基于 MapStruct/Dozer 的对象转换抽象；完成 DTO/VO 与领域模型、持久化对象之间的映射。
• com.legacy.crm.customer.config
  • DataScopeAspect（数据权限）
    • 职责：基于 AOP 的数据范围校验与过滤；在控制器/服务方法执行前后实施权限控制。
  • BinlogListener（增量同步）
    • 职责：订阅/监听数据库 binlog；对变更事件进行解析与分发，驱动缓存更新与下游同步。
  • 其他配置（说明）
    • 职责：Spring MVC、MyBatis、数据源（分库分表、读写分离）、Redis、本地缓存、统一错误码、审计与灰度开关等相关配置与切面。

技术特性

• 分层与领域建模结合
  • Web -> Service -> DAO 的依赖单向闭环，Service 以内聚领域模型（Customer 聚合）实现业务规则，DAO 通过仓储接口解耦持久化细节。
• Spring MVC + MyBatis
  • 控制器暴露页面与 API；MyBatis 承担 SQL 映射，结合分库分表策略进行路由；Repository 隐藏 Mapper 细节，维持聚合一致性存取。
• 分库分表与读写分离
  • 写操作路由主库，读操作优先只读库；服务层在事务边界内协调写入与缓存失效，避免脏读。
• 多级缓存
  • Redis 作为分布式一级缓存，本地二级缓存作为热点加速；写路径触发失效或更新，读路径命中失败回源数据库并回填。
• Binlog 增量同步
  • BinlogListener 监听数据库变更，推送缓存刷新并向下游同步，降低强一致开销并提升近实时一致性。
• Bean Validation 与统一错误码
  • 控制器与服务层参数校验统一化；异常到错误码的转换保证对外接口一致性与可观测性。
• 对象转换（MapStruct/Dozer）
  • Convertor 统一对象映射约束，降低层间耦合，保证 DTO/领域/持久化对象的字段一致性。
• AOP 审计与灰度开关
  • 通过切面记录关键操作审计日志；灰度开关控制新策略或新路径的逐步放量，保障变更可控。
• 数据权限控制
  • DataScopeAspect 在执行链路上应用数据范围过滤，确保查询与变更受控。
• 事务与一致性
  • 以服务层为事务边界，通过仓储提交聚合变更；结合缓存失效策略与 binlog 同步降低不一致窗口。

使用场景

• 客户建档与维护
  • CustomerController 接收请求 -> 参数校验 -> 调用 CustomerService -> 更新仓储（主库）-> 失效缓存 -> BinlogListener 推送增量事件。
• 客户分级与评分
  • 服务层装配领域策略（domain.policy），计算等级与分数，并根据策略结果更新持久化与缓存。
• 线索去重与合并
  • CustomerDedupService 基于既定去重规则检测重复，合并聚合数据，统一写入主库并触发缓存与增量同步。
• 批量导入与导出
  • ImportExportFacade 负责文件解析、数据校验、对象转换与分批写入/读取；汇总结果并输出统计。
• 查询与列表检索
  • DataScopeAspect 施加权限过滤；读路径优先本地/Redis 缓存，未命中回源只读库，结果回填缓存。
• 跟进记录与标签管理
  • 在聚合内维护 FollowUpLog 与 Tag，服务层保证聚合约束与事务一致性，DAO/Mapper 持久化相应变更。

包概述

org.toolkit.logging 提供统一的日志抽象与桥接能力，面向库和业务服务形成一致的日志规范。框架通过 SPI 扩展与适配器模式屏蔽底层实现差异，内置基于 Disruptor 的无锁异步写入，提供可插拔的 Appender 与 Encoder，支持 JSON 编码、MDC 上下文传播、按环境与标签的动态路由及级别过滤，并支持 YAML 配置的热加载与启动校验。

包结构与职责概览：

• org.toolkit.logging.api：对外日志门面与工厂等公共 API。
• org.toolkit.logging.core.appender：内置 Appender 实现与相关策略（如文件滚动策略）。
• org.toolkit.logging.core.encoder：内置编码器实现（JSON、Pattern 等）。
• org.toolkit.logging.context：MDC 等上下文管理与传播支持。
• org.toolkit.logging.spi：扩展点绑定与实现发现。
• org.toolkit.logging.bridge：与外部日志框架的桥接适配。

主要功能

• 统一日志抽象与桥接
  • 提供 Logger/LoggerFactory 统一 API，屏蔽底层实现差异。
  • 通过桥接模块与主流日志生态互操作，便于增量迁移与统一接入。
• 高吞吐异步写入
  • 基于 Disruptor 的无锁环形队列进行事件化处理，降低写入端对业务线程的影响。
• 灵活的编码与格式化
  • 支持 JSON 编码与模式化文本编码，满足日志采集、分析与人读友好等多样需求。
• MDC 上下文传播
  • 在线程池与 Web 场景中传播 TraceId、用户标识等上下文，确保跨线程一致性。
• 动态路由与级别过滤
  • 按环境、标签、日志级别等维度路由到不同 Appender；支持细粒度级别阈值控制。
• 可插拔扩展能力
  • Appender、Encoder 等组件通过 SPI 插拔扩展，便于按需定制与集成第三方实现。
• 配置管理
  • YAML 配置热加载；启动阶段配置校验，提前发现缺失或不一致配置。
• 文件归档与滚动
  • 提供文件滚动策略以管理日志文件大小与留存。

核心组件

• Logger
  • 日志门面，提供按级别记录与结构化参数输出，负责采集 MDC 与标签等上下文并生成日志事件。
• LoggerFactory
  • 日志工厂，按名称/类型生成与缓存 Logger；在初始化时装配异步分发器、路由策略与已注册扩展。
• Appender（接口）
  • 日志事件的落地方向抽象，定义追加、启动、关闭等生命周期方法，可挂接编码与过滤逻辑。
• ConsoleAppender
  • 将日志输出至标准输出/错误输出，适用于开发与容器化运行环境。
• FileAppender
  • 将日志输出至文件，配合滚动策略进行归档与留存控制。
• JsonEncoder
  • 将日志事件编码为 JSON 表示，包含时间戳、级别、消息、异常与 MDC/标签等信息。
• PatternEncoder
  • 基于可配置模式将日志事件格式化为文本，便于人读与兼容传统日志格式。
• AsyncDispatcher
  • 异步分发器，基于 Disruptor 接收业务线程提交的日志事件并在独立线程中分发至路由/Appender。
• MdcContext
  • MDC 上下文管理，提供设置/清理 API，并支持在线程池、Web 请求处理链中的上下文传播。
• SpiBinder
  • 扩展绑定与发现入口，用于注册与装配自定义的 Appender、Encoder 等实现。
• Slf4jBridge
  • 与 SLF4J 等日志生态进行桥接，支持在现有代码中统一路由到本框架。
• LogConfig
  • 日志配置模型与加载器，负责从 YAML 读取配置、热加载监听与启动期配置校验。
• RoutingPolicy
  • 路由策略，依据环境、标签、日志级别等维度选择目标 Appender 集合，实现动态路由与过滤。
• RollingPolicy
  • 文件滚动策略，定义滚动触发条件与归档命名/留存规则，供 FileAppender 使用。

组件协作流程（简述）：

• 业务代码通过 Logger 记录日志 -> AsyncDispatcher 异步入队 -> RoutingPolicy 按标签/级别/环境选择 Appender -> Appender 使用 Encoder 编码并落地。
• LoggerFactory 在启动时基于 LogConfig 进行装配，SpiBinder 负责扩展组件的绑定，MdcContext 贯穿事件生成与编码阶段。

技术特性

• 架构模式
  • SPI 扩展机制与适配器模式解耦 API 与实现；Appender/Encoder 等通过约定接口/契约扩展。
• 高性能异步
  • 采用 Disruptor 实现无锁环形队列与事件驱动消费，降低锁竞争与 GC 压力，提升高并发写入吞吐。
• 上下文一致性
  • MDC 跨线程、跨请求传播，确保链路追踪等上下文在异步与回调场景下不丢失。
• 可插拔与可观测
  • Appender 与 Encoder 可按需增删替换；路由与级别过滤可在不改业务代码的情况下动态调整。
• 配置治理
  • YAML 配置支持热加载；启动校验覆盖路由目标存在性、级别阈值有效性、滚动策略配置完整性等。
• 桥接兼容
  • 通过 bridge 模块与现有日志生态互操作，降低迁移成本并避免重复日志。

使用场景

• 库与组件的统一日志门面
  • 对外仅暴露 api，使用者可在不同运行环境中选择具体实现且保持行为一致。
• 高吞吐服务端/微服务
  • 通过 AsyncDispatcher 提升写入吞吐并降低对业务线程的影响；使用 JsonEncoder 便于日志采集与分析。
• 多环境差异化路由
  • 开发环境路由至 ConsoleAppender，生产环境路由至 FileAppender/远端管道；基于标签对关键域进行单独输出。
• Web 与异步任务
  • 使用 MdcContext 传播 traceId/userId 等，实现端到端链路排障。
• 渐进式迁移与整合
  • 利用 Slf4jBridge 与现有生态集成，在不改业务代码的情况下统一日志入口。
• 合规与留存需求
  • 配合 RollingPolicy 管理日志滚动与留存周期，满足审计与合规要求。