erp / tax-agent · Commits

Commit 45aab328d4302a25dfb6c35017e5c612a03bfe22

Authored by zhangmeiyang
1 parent 7d1419db
build: skipped

docs(tax-agent): 添加TaxAgent系统设计文档 

- 创建完整的系统设计文档，涵盖架构、模块设计、数据模型等
- 详细描述各模块功能及核心组件，包括tax-boot、tax-central等六大模块
- 提供系统核心流程说明，如消息处理、责任链模式应用
- 定义系统核心概念，如租户、账套、文档、映射和代理
- 描述与金蝶K3 Cloud的集成方式及API调用机制
- 说明配置管理机制，支持多租户、多账套灵活配置
- 添加异常处理机制和错误码定义
- 提供部署架构、安全设计和监控日志方案
- 规划未来功能扩展方向和性能优化策略
Inline Side-by-side
Showing 2 changed files with 813 additions and 0 deletions
doc/TaxAgent系统设计文档.md 0 → 100644
  View file @45aab32
  1 +# TaxAgent 系统设计文档
  2 +
  3 +## 版本信息
  4 +| 版本 | 修订日期 | 作者 | 说明 |
  5 +|------|----------|------|------|
  6 +| 1.0 | 2025-11-11 | AI助手 | 基于项目代码分析生成的完整设计文档 |
  7 +| 1.1 | 2025-11-12 | AI助手 | 根据最新代码更新文档内容 |
  8 +| 1.2 | 2025-11-14 | AI助手 | 根据最新代码更新文档内容，增加业务配置管理功能 |
  9 +
  10 +## 1. 系统概述
  11 +
  12 +TaxAgent 是一个税务代理系统，用于处理不同业务系统与财务系统（如金蝶K3 Cloud）之间的数据传输和转换。系统采用模块化设计，通过责任链模式处理业务流程，支持多租户、多账套的配置管理。
  13 +
  14 +系统主要处理四种业务单据类型：
  15 +- 客户信息 (BD_Customer)
  16 +- 收款单 (AR_RECEIVE_BILL)
  17 +- 应收单 (AR_RECEIVABLE)
  18 +- 退款单 (AR_REFUND_BILL)
  19 +
  20 +### 1.1 设计目标
  21 +
  22 +TaxAgent系统旨在提供一个统一的平台，实现业务系统与财务系统之间的数据自动同步。系统通过以下方式实现设计目标：
  23 +
  24 +1. **解耦业务系统与财务系统**：通过中间件方式，降低业务系统与财务系统之间的耦合度
  25 +2. **提高数据传输效率**：批量处理和异步传输机制，提高数据处理效率
  26 +3. **增强系统可靠性**：通过异常处理和重试机制，确保数据传输的可靠性
  27 +4. **支持多租户架构**：支持多个租户同时使用系统，实现资源隔离
  28 +5. **灵活的配置管理**：通过配置化管理，适应不同客户的业务需求
  29 +
  30 +### 1.2 系统架构
  31 +
  32 +系统采用模块化架构设计，主要包含以下模块：
  33 +
  34 +- **tax-boot**: 系统启动模块，负责整合其他模块并启动Spring Boot应用
  35 +- **tax-central**: 核心模块，包含基础类、接口定义、工具类等
  36 +- **tax-doc**: 文档处理模块，负责将原始数据转换为标准文档对象
  37 +- **tax-map**: 映射转换模块，将文档对象转换为财务系统所需的映射对象
  38 +- **tax-proxy**: 代理发送模块，负责与外部财务系统通信
  39 +- **tax-storage**: 存储模块，负责数据持久化和配置管理
  40 +
  41 +### 1.3 技术栈
  42 +
  43 +TaxAgent系统采用现代化的技术栈构建：
  44 +
  45 +- **核心框架**：Spring Boot 3.x、Spring Cloud
  46 +- **ORM框架**：MyBatis-Plus
  47 +- **消息队列**：RabbitMQ
  48 +- **配置中心**：Nacos
  49 +- **数据库**：MySQL 8.x
  50 +- **连接池**：HikariCP
  51 +- **JSON处理**：Jackson
  52 +- **日志框架**：Logback
  53 +- **构建工具**：Maven
  54 +
  55 +### 1.4 核心流程
  56 +
  57 +系统采用责任链模式处理业务流程：
  58 +1. **初始化处理** (InitializeProcessor): 解析原始消息，构建标准文档对象
  59 +2. **映射转换** (MappingProcessor): 将文档对象转换为映射对象
  60 +3. **代理发送** (ProxyProcessor): 发送映射对象到目标系统
  61 +
  62 +整个处理流程中，系统会进行数据映射记录和错误处理：
  63 +- 成功处理的数据会被记录到 tax_pipeline_mapping 表中
  64 +- 处理失败的数据会被记录到 tax_mapping_error 表中
  65 +
  66 +### 1.5 核心概念
  67 +
  68 +在深入了解系统设计之前，需要理解以下核心概念：
  69 +
  70 +- **租户(Tenant)**：系统中的独立客户或组织单位，具有独立的配置和数据空间
  71 +- **账套(Pipeline)**：财务系统中的独立核算单位，对应财务系统中的具体账套
  72 +- **文档(Document)**：业务系统中的原始业务数据，如客户信息、应收单等
  73 +- **映射(Mapping)**：将文档对象转换为财务系统所需的格式
  74 +- **代理(Proxy)**：负责与外部财务系统通信的组件
  75 +
  76 +## 2. 模块详细设计
  77 +
  78 +### 2.1 tax-boot 模块
  79 +
  80 +#### 2.1.1 功能说明
  81 +系统启动模块，整合所有组件并提供消息接收处理能力。该模块是整个系统的入口点，负责初始化Spring Boot应用并配置核心组件。
  82 +
  83 +#### 2.1.2 核心组件
  84 +- **TaxApplication**: Spring Boot启动类，配置ProcessorChain
  85 +- **TaxAutoPush**: RabbitMQ队列配置
  86 +- **TaxReceiver**: RabbitMQ消息接收器，处理外部传入的消息
  87 +- **TaxReceiveService**: 消息处理服务，负责消息预处理和结果记录
  88 +
  89 +#### 2.1.3 消息处理流程
  90 +
  91 +TaxAgent系统通过RabbitMQ接收来自业务系统的消息，处理流程如下：
  92 +
  93 +1. **消息接收**：TaxReceiver.receiveMessage()方法接收来自RabbitMQ的消息
  94 +2. **消息预处理**：TaxReceiveService.messagePreHandle()方法对消息进行预处理，包括：
  95 + - 验证租户信息
  96 + - 验证系统类型与文档类型的匹配性
  97 + - 获取租户账套配置
  98 +3. **责任链处理**：调用processorChainMap.get(SystemType).startProcess()启动处理链，依次执行：
  99 + - InitializeProcessor（初始化处理）
  100 + - MappingProcessor（映射转换）
  101 + - ProxyProcessor（代理发送）
  102 +4. **结果记录**：TaxReceiveService.recordMapping()方法记录处理结果到数据库
  103 +
  104 +```java
  105 +// 消息接收处理流程
  106 +1. TaxReceiver.receiveMessage() 接收消息
  107 +2. TaxReceiveService.messagePreHandle() 预处理消息
  108 +3. 调用 processorChainMap.get(SystemType).startProcess() 启动处理链
  109 +4. 依次执行 InitializeProcessor -> MappingProcessor -> ProxyProcessor
  110 +5. TaxReceiveService.recordMapping() 处理结果记录到数据库
  111 +
  112 +// 异常处理流程
  113 +1. 消息处理过程中出现异常会被捕获
  114 +2. 系统会记录错误信息到 tax_mapping_error 表
  115 +3. 即使出现异常，消息也会被确认消费（手动ACK）以避免重复处理
  116 +```
  117 +
  118 +### 2.2 tax-central 模块
  119 +
  120 +#### 2.2.1 功能说明
  121 +核心模块，包含系统的基础类定义、枚举类型、异常处理、工具类等。该模块是整个系统的基础，为其他模块提供公共的类和接口定义。
  122 +
  123 +#### 2.2.2 核心类设计
  124 +
  125 +##### 2.2.2.1 基础领域对象
  126 +- **BaseDocument**: 所有文档对象的基类，包含业务系统传入的原始数据
  127 +- **BaseMapping**: 所有映射对象的基类，包含 verifyInformation 和 returnKeys 字段用于验证和查询
  128 +- **BaseProxy**: 所有代理对象的基类，包含发送到财务系统的响应数据
  129 +- **MessageContext**: 消息上下文，贯穿整个处理流程，包含处理过程中的所有数据
  130 +
  131 +##### 2.2.2.2 枚举类型
  132 +- **SystemType**: 系统类型枚举（如金蝶K3 Cloud），定义了系统支持的文档类型
  133 +- **DocumentType**: 文档类型枚举（客户信息、应收单、退款单等）
  134 +- **StatusType**: 处理状态枚举
  135 +- **ProcessType**: 流程类型枚举
  136 +- **MappingStateType**: 映射状态类型枚举（已同步、同步失败、同步重试）
  137 +- **AuditType**: 审核类型枚举
  138 +- **SettingFieldType**: 配置字段类型枚举（固定值、动态映射、远程调用）
  139 +- **FieldType**: 字段类型枚举，定义了各种业务字段
  140 +
  141 +##### 2.2.2.3 处理器接口
  142 +- **Processor**: 处理器接口，定义处理方法
  143 +- **AbstractProcessor**: 抽象处理器实现，提供通用处理逻辑
  144 +- **ProcessorChain**: 处理器链，实现责任链模式，按顺序执行各个处理器
  145 +
  146 +##### 2.2.2.4 转换器
  147 +- **IConverter**: 字段转换器接口，用于简单字段的转换
  148 +- **ISubConverter**: 子对象转换器接口，用于复杂对象列表的转换
  149 +- **@Converter**: 字段转换注解，用于标注需要转换的字段
  150 +- **@SubConverter**: 子对象转换注解，用于标注需要转换的复杂对象列表
  151 +
  152 +转换器是TaxAgent系统中非常重要的组件，通过注解方式实现对象间的自动转换。系统支持三种配置方式：
  153 +1. 固定值配置：直接使用预设的固定值
  154 +2. 动态映射：通过键值对映射实现值的转换
  155 +3. 远程调用：通过HTTP调用外部服务获取值
  156 +
  157 +#### 2.2.3 上下文管理
  158 +- **TenantStorageContext**: 租户存储上下文，管理租户配置信息，在系统启动时加载所有启用的账套配置
  159 +- **ConnectionContext**: 连接上下文，管理不同系统的连接信息，如金蝶系统的连接参数
  160 +- **ConverterContext**: 转换器上下文，管理所有字段转换器实例
  161 +- **DocumentContext**: 文档上下文，管理所有文档构建器
  162 +- **MappingContext**: 映射上下文，管理所有映射转换器
  163 +- **ProxyContext**: 代理上下文，管理所有数据发送器
  164 +
  165 +### 2.3 tax-doc 模块
  166 +
  167 +#### 2.3.1 功能说明
  168 +文档处理模块，负责将原始JSON消息转换为标准文档对象。该模块是处理流程的第一步，将业务系统传入的JSON数据转换为系统内部使用的标准Java对象。
  169 +
  170 +#### 2.3.2 核心组件
  171 +- **InitializeProcessor**: 初始化处理器，处理流程的第一步，继承自AbstractProcessor，@Order(1)
  172 +- **DocumentContext**: 文档上下文，管理所有文档构建器，在系统启动时初始化
  173 +- **Builder**: 文档构建器抽象类，定义构建文档对象的接口
  174 + - **CustomerBuilder**: 客户信息构建器，处理客户信息文档
  175 + - **ReceiptBuilder**: 收款单构建器，处理收款单文档
  176 + - **ReceivableBuilder**: 应收单构建器，处理应收单文档
  177 + - **RefundBuilder**: 退款单构建器，处理退款单文档
  178 +
  179 +#### 2.3.3 处理流程
  180 +
  181 +InitializeProcessor处理流程：
  182 +1. 从DocumentContext.CONTEXT根据documentTypeEnum获取对应的Builder
  183 +2. 调用builder.build()方法构建文档对象
  184 +3. 将文档对象设置到MessageContext中
  185 +
  186 +Builder处理逻辑：
  187 +1. 解析msgBody中的JSON数据构建具体文档对象
  188 +2. 如果存在对应的配置，则应用默认配置（固定值、动态映射或远程调用）
  189 +3. 查询数据库中是否已存在映射记录，如果存在则设置customerId等字段
  190 +
  191 +```java
  192 +// InitializeProcessor处理流程
  193 +1. 从DocumentContext.CONTEXT根据documentTypeEnum获取对应的Builder
  194 +2. 调用builder.build()方法构建文档对象
  195 +3. 将文档对象设置到MessageContext中
  196 +
  197 +// Builder处理逻辑
  198 +1. 解析msgBody中的JSON数据构建具体文档对象
  199 +2. 如果存在对应的配置，则应用默认配置
  200 +3. 查询数据库中是否已存在映射记录，如果存在则设置customerId等字段
  201 +```
  202 +
  203 +### 2.4 tax-map 模块
  204 +
  205 +#### 2.4.1 功能说明
  206 +映射转换模块，将文档对象转换为财务系统所需的映射对象。该模块是处理流程的第二步，负责将内部标准文档对象转换为财务系统（如金蝶K3 Cloud）所需的格式。
  207 +
  208 +#### 2.4.2 核心组件
  209 +- **MappingProcessor**: 映射处理器，处理流程的第二步，继承自AbstractProcessor，@Order(2)
  210 +- **MappingContext**: 映射上下文，管理所有转换器，在系统启动时初始化
  211 +- **Transformer**: 映射转换器抽象类，定义文档对象到映射对象的转换接口
  212 + - **CustomerTransformer**: 客户信息转换器，处理客户信息文档到映射的转换
  213 + - **ReceiptTransformer**: 收款单转换器，处理收款单文档到映射的转换
  214 + - **ReceivableTransformer**: 应收单转换器，处理应收单文档到映射的转换
  215 + - **RefundTransformer**: 退款单转换器，处理退款单文档到映射的转换
  216 +
  217 +#### 2.4.3 处理流程
  218 +
  219 +MappingProcessor处理流程：
  220 +1. 从MappingContext.CONTEXT根据documentTypeEnum获取对应的Transformer
  221 +2. 调用transformer.transform()方法转换文档对象
  222 +3. 将映射对象设置到MessageContext中
  223 +4. 将映射对象转换为Map格式用于日志输出
  224 +
  225 +Transformer处理逻辑：
  226 +1. 使用MappingUtils.convertValue将BaseDocument转换为BaseMapping
  227 +2. 设置verifyInformation和returnKeys用于后续的重复性校验和查询
  228 +3. verifyInformation用于在发送前验证数据是否已存在，避免重复发送
  229 +4. returnKeys用于指定查询返回的字段
  230 +
  231 +```java
  232 +// MappingProcessor处理流程
  233 +1. 从MappingContext.CONTEXT根据documentTypeEnum获取对应的Transformer
  234 +2. 调用transformer.transform()方法转换文档对象
  235 +3. 将映射对象设置到MessageContext中
  236 +4. 将映射对象转换为Map格式用于日志输出
  237 +
  238 +// Transformer处理逻辑
  239 +1. 使用MappingUtils.convertValue将BaseDocument转换为BaseMapping
  240 +2. 设置verifyInformation和returnKeys用于后续的重复性校验和查询
  241 +3. verifyInformation用于在发送前验证数据是否已存在，避免重复发送
  242 +4. returnKeys用于指定查询返回的字段
  243 +```
  244 +
  245 +### 2.5 tax-proxy 模块
  246 +
  247 +#### 2.5.1 功能说明
  248 +代理发送模块，负责与外部财务系统通信，发送处理后的数据。该模块是处理流程的第三步，也是最后一步，负责将映射对象发送到目标财务系统（如金蝶K3 Cloud）。
  249 +
  250 +#### 2.5.2 核心组件
  251 +- **ProxyProcessor**: 代理处理器，处理流程的第三步，继承自AbstractProcessor，@Order(3)
  252 +- **ProxyContext**: 代理上下文，管理所有发送器，在系统启动时初始化
  253 +- **Sender**: 数据发送器抽象类，定义映射对象到代理对象的发送接口
  254 + - **CustomerSender**: 客户信息发送器，处理客户信息映射到代理的发送
  255 + - **ReceiptSender**: 收款单发送器，处理收款单映射到代理的发送
  256 + - **ReceivableSender**: 应收单发送器，处理应收单映射到代理的发送
  257 + - **RefundSender**: 退款单发送器，处理退款单映射到代理的发送
  258 +- **KingDeeHelper**: 金蝶系统API调用助手类，封装与金蝶系统的API交互
  259 +
  260 +#### 2.5.3 处理流程
  261 +
  262 +ProxyProcessor处理流程：
  263 +1. 从ConnectionContext.CONNECTION_MAP根据systemTypeEnum获取对应的AbstractConnectionManager
  264 +2. 通过AbstractConnectionManager获取系统连接信息（如金蝶系统的认证信息）
  265 +3. 从ProxyContext.CONTEXT根据documentTypeEnum获取对应的Sender
  266 +4. 调用sender.send()方法发送数据到目标系统
  267 +5. 将返回的代理对象设置到MessageContext中
  268 +
  269 +Sender处理逻辑：
  270 +1. 首先通过querySend查询是否已存在相同数据，避免重复发送
  271 +2. 调用KingDeeHelper.auditSend方法发送数据到金蝶系统
  272 +3. 处理返回结果，提取thirdPartyId和thirdPartyCode
  273 +
  274 +```java
  275 +// ProxyProcessor处理流程
  276 +1. 从ConnectionContext.CONNECTION_MAP根据systemTypeEnum获取对应的AbstractConnectionManager
  277 +2. 通过AbstractConnectionManager获取系统连接信息（如金蝶系统的认证信息）
  278 +3. 从ProxyContext.CONTEXT根据documentTypeEnum获取对应的Sender
  279 +4. 调用sender.send()方法发送数据到目标系统
  280 +5. 将返回的代理对象设置到MessageContext中
  281 +
  282 +// Sender处理逻辑
  283 +1. 首先通过querySend查询是否已存在相同数据，避免重复发送
  284 +2. 调用KingDeeHelper.auditSend方法发送数据到金蝶系统
  285 +3. 处理返回结果，提取thirdPartyId和thirdPartyCode
  286 +```
  287 +
  288 +### 2.6 tax-storage 模块
  289 +
  290 +#### 2.6.1 功能说明
  291 +存储模块，负责数据持久化和配置管理。该模块基于MyBatis-Plus实现数据访问，提供租户、账套、配置和映射数据的存储功能。
  292 +
  293 +#### 2.6.2 核心实体
  294 +- **TaxTenant**: 租户信息，包含租户的基本信息（名称、组、实体等）
  295 +- **TaxPipeline**: 账套信息，包含账套的基本信息和连接参数
  296 +- **TaxPipelineFieldType**: 账套字段配置信息，定义账套中各字段的配置类型
  297 +- **TaxPipelineFixedConfig**: 账套固定值配置，存储字段的固定值配置
  298 +- **TaxPipelineDynamicConfig**: 账套动态映射配置，存储字段的动态映射关系
  299 +- **TaxPipelineRemoteConfig**: 账套远程调用配置，存储字段的远程调用参数
  300 +- **TaxPipelineMapping**: 账套映射信息，记录已处理的业务数据映射关系
  301 +- **TaxMappingError**: 映射错误信息，记录处理失败的业务数据
  302 +- **TaxPipelineFieldVerify**: 字段验证配置，用于配置哪些字段用于重复性校验
  303 +- **TaxPipelineFieldVerifyReturn**: 返回字段配置，用于配置查询时返回的字段
  304 +- **TaxPipelineBusiness**: 账套业务信息，用于配置账套支持的业务类型
  305 +- **TaxPipelineBusinessConfig**: 账套业务配置，用于配置业务支持的文档类型
  306 +- **TaxPipelineBusinessExt**: 账套业务扩展信息，用于配置业务的扩展字段
  307 +- **TaxPipelineBusinessExtData**: 账套业务扩展数据，用于配置业务扩展字段的默认值
  308 +
  309 +#### 2.6.3 核心服务
  310 +- **TaxTenantService**: 租户服务，提供租户的增删改查功能
  311 +- **TaxPipelineService**: 账套服务，提供账套的增删改查功能
  312 +- **TaxPipelineFieldConfigService**: 账套字段配置服务，提供字段配置的增删改查功能
  313 +- **TaxPipelineMappingService**: 账套映射服务，提供映射数据的增删改查功能
  314 +- **TaxMappingErrorService**: 映射错误服务，提供错误记录的存储功能
  315 +- **DynamicTaxPipelineMappingService**: 动态账套映射服务，提供动态表操作功能
  316 +- **TaxPipelineFieldVerifyService**: 字段验证服务，提供验证字段配置的增删改查功能
  317 +- **TaxPipelineBusinessConfigService**: 业务配置服务，提供业务配置的增删改查功能
  318 +
  319 +#### 2.6.4 核心功能
  320 +1. 租户管理：创建、更新、查询租户信息
  321 +2. 账套管理：创建、更新、启用/禁用账套
  322 +3. 配置管理：管理账套的各项配置参数，支持固定值、动态映射和远程调用三种配置方式
  323 +4. 映射管理：维护系统间数据的映射关系
  324 +5. 错误管理：记录和查询处理失败的数据
  325 +6. 动态表管理：为每个租户创建独立的映射数据表
  326 +7. 验证管理：配置用于数据重复性校验的字段和返回字段
  327 +8. 业务配置管理：管理账套支持的业务类型及其配置
  328 +
  329 +## 3. 数据模型设计
  330 +
  331 +### 3.1 核心实体关系图
  332 +
  333 +```mermaid
  334 +erDiagram
  335 + TaxTenant ||--o{ TaxPipeline : has
  336 + TaxPipeline ||--o{ TaxPipelineFieldType : has
  337 + TaxPipelineFieldType ||--o{ TaxPipelineFixedConfig : has
  338 + TaxPipelineFieldType ||--o{ TaxPipelineDynamicConfig : has
  339 + TaxPipelineFieldType ||--o{ TaxPipelineRemoteConfig : has
  340 + TaxPipeline ||--o{ TaxPipelineFieldVerify : has
  341 + TaxPipeline ||--o{ TaxPipelineFieldVerifyReturn : has
  342 + TaxPipeline ||--o{ TaxPipelineBusiness : has
  343 + TaxPipelineBusiness ||--o{ TaxPipelineBusinessConfig : has
  344 + TaxPipelineBusiness ||--o{ TaxPipelineBusinessExt : has
  345 + TaxPipelineBusinessExt ||--o{ TaxPipelineBusinessExtData : has
  346 + TaxTenant ||--o{ TaxPipelineMapping : has
  347 + TaxTenant ||--o{ TaxMappingError : has
  348 +
  349 + TaxTenant {
  350 + bigint id PK
  351 + varchar name
  352 + varchar group
  353 + varchar entity
  354 + int state
  355 + datetime created_time
  356 + datetime modified_time
  357 + }
  358 +
  359 + TaxPipeline {
  360 + bigint id PK
  361 + bigint tenant_id FK
  362 + varchar system_code
  363 + varchar name
  364 + varchar code
  365 + json params
  366 + int state
  367 + datetime created_time
  368 + datetime modified_time
  369 + }
  370 +
  371 + TaxPipelineFieldType {
  372 + bigint id PK
  373 + bigint pipeline_id FK
  374 + varchar document_type
  375 + varchar config_key
  376 + int setting_field_type
  377 + datetime created_time
  378 + datetime modified_time
  379 + }
  380 +
  381 + TaxPipelineFixedConfig {
  382 + bigint id PK
  383 + bigint pipeline_field_type_id FK
  384 + varchar config_value
  385 + datetime created_time
  386 + datetime modified_time
  387 + }
  388 +
  389 + TaxPipelineDynamicConfig {
  390 + bigint id PK
  391 + bigint pipeline_field_type_id FK
  392 + varchar config_value
  393 + varchar config_map_value
  394 + datetime created_time
  395 + datetime modified_time
  396 + }
  397 +
  398 + TaxPipelineRemoteConfig {
  399 + bigint id PK
  400 + bigint pipeline_field_type_id FK
  401 + varchar fixed_params
  402 + varchar field
  403 + varchar remote_address
  404 + varchar data_path
  405 + datetime created_time
  406 + datetime modified_time
  407 + }
  408 +
  409 + TaxPipelineFieldVerify {
  410 + bigint id PK
  411 + bigint pipeline_id FK
  412 + varchar document_type
  413 + varchar config_verify_field
  414 + datetime created_time
  415 + datetime modified_time
  416 + }
  417 +
  418 + TaxPipelineFieldVerifyReturn {
  419 + bigint id PK
  420 + bigint pipeline_id FK
  421 + varchar document_type
  422 + varchar config_return_field
  423 + datetime created_time
  424 + datetime modified_time
  425 + }
  426 +
  427 + TaxPipelineBusiness {
  428 + bigint id PK
  429 + bigint pipeline_id FK
  430 + varchar business_code
  431 + varchar business_name
  432 + datetime created_time
  433 + datetime modified_time
  434 + }
  435 +
  436 + TaxPipelineBusinessConfig {
  437 + bigint id PK
  438 + bigint tax_pipeline_business_id FK
  439 + varchar document_type
  440 + datetime created_time
  441 + datetime modified_time
  442 + }
  443 +
  444 + TaxPipelineBusinessExt {
  445 + bigint id PK
  446 + bigint tax_pipeline_business_id FK
  447 + varchar ext_name
  448 + varchar ext_code
  449 + varchar ext_default_data
  450 + datetime created_time
  451 + datetime modified_time
  452 + }
  453 +
  454 + TaxPipelineBusinessExtData {
  455 + bigint id PK
  456 + bigint tax_pipeline_business_ext_id FK
  457 + varchar ext_data
  458 + datetime created_time
  459 + datetime modified_time
  460 + }
  461 +
  462 + TaxPipelineMapping {
  463 + bigint id PK
  464 + bigint tenant_id FK
  465 + bigint pipeline_id FK
  466 + varchar document_type
  467 + varchar system_data_id
  468 + varchar pipeline_data_id
  469 + json origin_data
  470 + int state
  471 + datetime created_time
  472 + datetime modified_time
  473 + }
  474 +
  475 + TaxMappingError {
  476 + bigint id PK
  477 + varchar group
  478 + varchar entity
  479 + varchar pipeline_code
  480 + varchar document_type
  481 + varchar system_type
  482 + varchar system_data_id
  483 + json origin_data
  484 + int state
  485 + varchar error_message
  486 + datetime created_time
  487 + datetime modified_time
  488 + }
  489 +```
  490 +
  491 +### 3.2 业务文档模型
  492 +
  493 +TaxAgent系统支持四种主要的业务文档类型，每种类型都有对应的文档类、映射类和代理类。
  494 +
  495 +#### 3.2.1 客户信息 (StandardCustomer)
  496 +继承关系：BaseCustomer -> BaseDocument
  497 +
  498 +主要字段：
  499 +- systemDataId: 系统数据ID
  500 +- customerId: 客户ID
  501 +- customerCode: 客户编码
  502 +- customerName: 客户名称
  503 +- customerShortName: 客户简称
  504 +- customerInvoiceTitle: 客户发票抬头
  505 +- legalPerson: 法人姓名
  506 +- idNumber: 证件号
  507 +- country: 国家
  508 +- provincial: 区域组织
  509 +- address: 地址
  510 +- registerAddress: 注册地址
  511 +- customerGroup: 客户分组
  512 +- customerCreateOrg: 创建组织
  513 +- customerUseOrg: 使用组织
  514 +- contacts: 联系人列表
  515 +
  516 +#### 3.2.2 收款单 (ReceiptBill)
  517 +继承关系：BaseBill -> BaseDocument
  518 +
  519 +主要字段：
  520 +- createTime: 创建时间
  521 +- businessType: 业务类型
  522 +- settleOrg: 结算组织
  523 +- saleOrg: 销售组织
  524 +- saleDept: 销售部门
  525 +- payOrg: 支付组织
  526 +- currency: 货币
  527 +- remark: 备注
  528 +- businessCardNumber: 业务卡号
  529 +- settleCurrency: 结算货币
  530 +- contactType: 往来单位类型
  531 +- contact: 往来单位
  532 +- payContactType: 付款单位类型
  533 +- payContact: 付款单位
  534 +- receiptItems: 收款项目列表
  535 +
  536 +#### 3.2.3 应收单 (ReceivableBill)
  537 +继承关系：BaseBill -> BaseDocument
  538 +
  539 +主要字段：
  540 +- createTime: 创建时间
  541 +- businessType: 业务类型
  542 +- settleOrg: 结算组织
  543 +- saleOrg: 销售组织
  544 +- saleDept: 销售部门
  545 +- payOrg: 支付组织
  546 +- currency: 货币
  547 +- settleMethod: 结算方法
  548 +- remark: 备注
  549 +- businessCardNumber: 业务卡号
  550 +- customer: 客户
  551 +- receiver: 收货方
  552 +- orderer: 订货方
  553 +- payer: 付款人
  554 +- settleName: 结算人名称
  555 +- standardCurrency: 标准货币
  556 +- receivableItems: 应收项目列表
  557 +
  558 +#### 3.2.4 退款单 (RefundBill)
  559 +继承关系：BaseBill -> BaseDocument
  560 +
  561 +主要字段：
  562 +- createTime: 创建时间
  563 +- businessType: 业务类型
  564 +- settleOrg: 结算组织
  565 +- saleOrg: 销售组织
  566 +- saleDept: 销售部门
  567 +- payOrg: 支付组织
  568 +- currency: 货币
  569 +- remark: 备注
  570 +- businessCardNumber: 业务卡号
  571 +- settleCurrency: 结算货币
  572 +- receiveContactType: 收款单位类型
  573 +- receiveContact: 收款单位
  574 +- contactType: 往来单位类型
  575 +- contact: 往来单位
  576 +- refundItems: 退款项目列表
  577 +
  578 +## 4. 系统集成设计
  579 +
  580 +### 4.1 与金蝶K3 Cloud集成
  581 +
  582 +#### 4.1.1 连接管理
  583 +通过KingDeeConnectionManager管理金蝶系统的连接信息，连接参数存储在TaxPipeline的params字段中。系统使用金蝶官方提供的K3CloudApi SDK与金蝶K3 Cloud系统进行交互。
  584 +
  585 +#### 4.1.2 API调用
  586 +使用KingDeeHelper工具类封装与金蝶系统的API交互：
  587 +- **nonAuditSend**: 无需审核的保存操作，适用于客户联系人等基础信息
  588 +- **auditSend**: 需要审核的保存操作，适用于业务单据
  589 +- **unAuditSend**: 反审核操作，用于更新已审核的单据
  590 +- **querySend**: 查询操作，用于验证数据是否已存在
  591 +
  592 +API调用异常处理：
  593 +- 所有金蝶系统API调用异常都会被封装为TaxAgentServiceException抛出
  594 +- 异常信息会被记录到日志中
  595 +- 根据异常类型返回相应的错误码给调用方
  596 +
  597 +#### 4.1.3 数据发送流程
  598 +1. 根据DocumentType获取对应的Sender
  599 +2. 构造金蝶系统所需的映射对象
  600 +3. 处理特殊字段（如联系人信息）
  601 +4. 调用KingDeeHelper发送数据
  602 +5. 处理返回结果
  603 +
  604 +#### 4.1.4 重复数据处理
  605 +系统通过verifyInformation和returnKeys字段实现重复数据检测：
  606 +- verifyInformation: 包含用于验证数据是否已存在的查询条件
  607 +- returnKeys: 指定查询返回的字段
  608 +
  609 +在发送数据前，系统会先调用querySend方法检查数据是否已存在，避免重复发送。
  610 +
  611 +### 4.2 消息队列集成
  612 +
  613 +系统通过RabbitMQ接收外部消息：
  614 +- 队列名称: tax-agent.queue
  615 +- 交换机: tax-agent.exchange
  616 +- 路由键: tax-agent.routing.process
  617 +
  618 +消息格式为JSON字符串，包含以下字段：
  619 +- pipelineCode: 账套编码
  620 +- group: 租户组
  621 +- entity: 租户实体
  622 +- msgBody: 消息体（业务数据）
  623 +- systemType: 系统类型
  624 +- documentType: 文档类型
  625 +- systemDataId: 系统数据ID，用于唯一标识业务数据
  626 +
  627 +系统采用手动ACK机制确保消息的可靠处理，即使在处理过程中发生异常，也会确认消息以避免重复处理。
  628 +
  629 +## 5. 配置管理
  630 +
  631 +TaxAgent系统提供灵活的配置管理功能，支持多种配置方式。
  632 +
  633 +### 5.1 租户配置
  634 +通过TaxTenant实体管理租户信息，包含group和entity两个维度。租户是系统中的独立客户或组织单位，具有独立的配置和数据空间。
  635 +
  636 +### 5.2 账套配置
  637 +通过TaxPipeline实体管理账套信息，关联具体的系统类型和连接参数。账套是财务系统中的独立核算单位，对应财务系统中的具体账套。
  638 +
  639 +### 5.3 字段配置
  640 +系统支持三种字段配置方式：
  641 +
  642 +1. **固定值配置**：通过TaxPipelineFixedConfig实体管理，直接使用预设的固定值
  643 +2. **动态映射**：通过TaxPipelineDynamicConfig实体管理，通过键值对映射实现值的转换
  644 +3. **远程调用**：通过TaxPipelineRemoteConfig实体管理，通过HTTP调用外部服务获取值
  645 +
  646 +配置按文档类型进行分类管理，通过TaxPipelineFieldType实体关联具体的配置类型。
  647 +
  648 +### 5.4 数据映射配置
  649 +通过TaxPipelineMapping实体管理不同系统间数据的映射关系，记录已处理的业务数据。
  650 +
  651 +### 5.5 验证字段配置
  652 +通过TaxPipelineFieldVerify和TaxPipelineFieldVerifyReturn实体管理验证字段配置：
  653 +- TaxPipelineFieldVerify: 配置用于验证数据是否已存在的字段
  654 +- TaxPipelineFieldVerifyReturn: 配置查询时返回的字段
  655 +
  656 +### 5.6 业务配置管理
  657 +通过TaxPipelineBusiness、TaxPipelineBusinessConfig和TaxPipelineBusinessExt实体管理业务配置：
  658 +- TaxPipelineBusiness: 配置账套支持的业务类型
  659 +- TaxPipelineBusinessConfig: 配置业务支持的文档类型
  660 +- TaxPipelineBusinessExt: 配置业务的扩展字段及默认值
  661 +
  662 +## 6. 异常处理机制
  663 +
  664 +### 6.1 异常类型
  665 +- **TaxAgentServiceException**: 系统业务异常，继承自RuntimeException
  666 +- **全局异常处理器**: GlobalExceptionHandler统一处理系统异常，提供统一的异常响应格式
  667 +
  668 +### 6.2 异常码定义 (TaxSystemType)
  669 +- UNKNOWN_ERROR: 未知错误
  670 +- MISSING_BUSINESS_INFORMATION: 缺少业务信息
  671 +- BUSINESS_MATCHES_ARE_INCORRECT: 业务匹配不正确
  672 +- NO_MATCHING_SET_OF_ACCOUNTS_FOUND: 未找到匹配的账套
  673 +- NO_TENANT_INFORMATION_FOUND: 未找到租户信息
  674 +- REMOTE_SERVICE_CALLS_ARE_EXCEPTIONAL: 远程服务调用异常
  675 +- REPEAT_SENDING: 重复发送
  676 +- INCORRECT_BUSINESS_PROCESSES: 业务流程不正确
  677 +- ABNORMAL_PARAMETERS: 参数异常
  678 +- INVALID_HTTP_REQUEST_PARAMS: HTTP请求参数无效
  679 +
  680 +系统通过GlobalExceptionHandler统一处理各类异常，确保向客户端返回一致的错误格式。
  681 +
  682 +## 7. 系统扩展性设计
  683 +
  684 +TaxAgent系统设计时充分考虑了扩展性，支持多种方式的扩展。
  685 +
  686 +### 7.1 多系统支持
  687 +通过SystemType枚举和对应的ConnectionManager实现支持不同财务系统。目前系统已实现对金蝶K3 Cloud的支持，可以通过扩展AbstractConnectionManager来支持其他财务系统。
  688 +
  689 +### 7.2 多文档类型支持
  690 +通过DocumentType枚举和对应的Builder、Transformer、Sender实现支持不同文档类型。系统目前已支持客户信息、应收单、收款单和退款单四种文档类型，可以通过实现相应的抽象类来扩展新的文档类型。
  691 +
  692 +### 7.3 字段转换扩展
  693 +通过Converter和SubConverter机制支持灵活的字段转换配置。系统提供了IConverter和ISubConverter接口，可以通过实现这些接口来支持自定义的字段转换逻辑。
  694 +
  695 +### 7.4 处理器链扩展
  696 +通过ProcessorChain实现责任链模式，可以方便地添加新的处理步骤到处理流程中。
  697 +
  698 +## 8. 性能优化考虑
  699 +
  700 +### 8.1 缓存机制
  701 +- 使用ConcurrentHashMap缓存租户配置信息，在系统启动时加载所有启用的账套配置
  702 +- 使用ConcurrentHashMap缓存各类处理器、转换器和发送器
  703 +- 通过RestoreTenantEvent事件机制实现缓存的动态刷新
  704 +
  705 +### 8.2 连接池管理
  706 +- 使用K3CloudApi提供的连接管理机制
  707 +- 数据库连接使用HikariCP连接池
  708 +
  709 +### 8.3 异步处理
  710 +- 消息处理采用手动ACK机制
  711 +- 异常处理独立进行，不影响消息队列的正常消费
  712 +- 数据库操作使用事务管理确保数据一致性
  713 +
  714 +### 8.4 数据库优化
  715 +- 为TaxPipelineMapping表设计了租户独立的表结构，提高查询性能
  716 +- 为常用查询字段添加了索引
  717 +
  718 +## 9. 部署架构
  719 +
  720 +### 9.1 依赖组件
  721 +- MySQL: 数据存储
  722 +- RabbitMQ: 消息队列
  723 +- Nacos: 配置中心和服务发现
  724 +
  725 +### 9.2 部署配置
  726 +- application.properties: 应用配置
  727 +- logback-spring.xml: 日志配置
  728 +
  729 +### 9.3 部署方式
  730 +系统采用Spring Boot应用方式部署，可以通过以下方式启动：
  731 +```bash
  732 +# 使用Maven插件启动
  733 +./mvnw spring-boot:run
  734 +
  735 +# 构建jar包并运行
  736 +./mvnw clean package
  737 +java -jar tax-boot/target/tax-boot.jar
  738 +```
  739 +
  740 +## 10. 安全设计
  741 +
  742 +### 10.1 数据安全
  743 +- 敏感信息（如数据库密码）进行编码存储
  744 +- 通过Nacos配置中心管理敏感配置
  745 +- 数据库访问使用参数化查询防止SQL注入
  746 +
  747 +### 10.2 通信安全
  748 +- 与金蝶系统通信采用HTTPS协议
  749 +- 数据传输采用JSON格式
  750 +- 消息队列使用认证机制确保消息安全
  751 +
  752 +### 10.3 应用安全
  753 +- 使用Spring Security框架提供认证和授权功能
  754 +- 对外暴露的REST API使用JWT进行认证
  755 +- 敏感操作进行权限验证
  756 +
  757 +## 11. 监控和日志
  758 +
  759 +### 11.1 日志管理
  760 +- 使用Logback作为日志框架
  761 +- 支持控制台和文件双输出
  762 +- 按时间和大小滚动日志文件
  763 +- 支持不同环境（dev、test、pre、prod）的日志级别配置
  764 +- 对数据库操作有专门的DEBUG级别日志配置
  765 +- 重要业务操作有详细日志记录
  766 +
  767 +### 11.2 监控指标
  768 +- 消息处理成功/失败统计
  769 +- 系统响应时间监控
  770 +- 异常信息记录和报警
  771 +- API调用成功率统计
  772 +- 数据库操作性能监控
  773 +
  774 +### 11.3 健康检查
  775 +- 提供应用健康检查接口
  776 +- 数据库连接状态监控
  777 +- 消息队列连接状态监控
  778 +- 外部服务可用性检查
  779 +
  780 +## 12. 测试策略
  781 +
  782 +### 12.1 单元测试
  783 +针对各个模块的核心功能编写单元测试，使用JUnit 5作为测试框架。
  784 +
  785 +### 12.2 集成测试
  786 +测试与外部系统的集成，包括金蝶K3 Cloud和RabbitMQ。
  787 +
  788 +### 12.3 性能测试
  789 +测试系统在高并发情况下的处理能力。
  790 +
  791 +### 12.4 测试环境
  792 +- 开发环境（dev）：用于功能开发和调试
  793 +- 测试环境（test）：用于功能测试和集成测试
  794 +- 预生产环境（pre）：用于性能测试和用户验收测试
  795 +- 生产环境（prod）：正式运行环境
  796 +
  797 +## 13. 未来规划
  798 +
  799 +### 13.1 功能扩展
  800 +- 支持更多财务系统（如用友、SAP等）
  801 +- 增加更多的业务文档类型
  802 +- 提供更丰富的配置管理功能
  803 +- 增加业务配置管理API，支持远程获取业务配置信息
  804 +
  805 +### 13.2 性能优化
  806 +- 引入缓存机制（如Redis）提升查询性能
  807 +- 实现消息的批量处理提升吞吐量
  808 +- 优化数据库索引和查询语句
  809 +
  810 +### 13.3 监控完善
  811 +- 集成Prometheus和Grafana实现可视化监控
  812 +- 增加更详细的业务指标监控
  813 +- 实现自动告警机制
0 \ No newline at end of file 814 \ No newline at end of file
doc/customerAsync.xlsx 0 → 100644
View file @45aab32
No preview for this file type