docs: 补充流水标签详细日志设计
This commit is contained in:
@@ -0,0 +1,412 @@
|
||||
# 项目流水标签后端详细日志设计
|
||||
|
||||
## 概述
|
||||
|
||||
本次设计面向“项目流水标签”后端链路补充详细日志提醒能力，覆盖手动重算、自动触发、项目级互斥、规则级执行、参数解析、结果落库和自动补跑全过程。
|
||||
|
||||
目标同时满足两类需求：
|
||||
|
||||
- 排障：出现“没有触发”“任务卡住”“规则没执行”“结果为 0”“自动补跑未生效”等问题时，能够通过日志快速定位断点
|
||||
- 审计：能够追踪是谁在什么时间，对哪个项目、哪个模型发起了手动重算，以及本次重算的结果摘要
|
||||
|
||||
本次设计只补应用日志，不调整数据库表结构，不新增前端展示，不引入 AOP、链路追踪框架或独立审计表。
|
||||
|
||||
## 已确认范围
|
||||
|
||||
- 日志面向“排障 + 审计”双目标
|
||||
- 日志保存位置沿用现有后端应用日志
|
||||
- 记录手动重算与自动触发两类入口
|
||||
- 记录项目级互斥、补跑标记、补跑消费过程
|
||||
- 记录任务级摘要、规则级执行、结果清理和结果写入
|
||||
- 记录规则参数解析来源和结果
|
||||
- 阈值参数值允许打印
|
||||
- 身份证号、账号、`objectKey` 等敏感字段不打印明文
|
||||
- 不打印 SQL 明细
|
||||
- 命中明细不按条展开到 `info`
|
||||
|
||||
## 现状问题
|
||||
|
||||
当前与流水标签相关的主要代码位于：
|
||||
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankTagServiceImpl.java`
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/ProjectBankTagRebuildCoordinator.java`
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/BankTagRuleConfigResolver.java`
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiFileUploadServiceImpl.java`
|
||||
|
||||
现状上，“文件上传 / 拉取本行信息”链路已有较多日志，但“流水标签重算”核心链路日志不足，主要存在以下问题：
|
||||
|
||||
1. 手动重算和自动触发进入标签链路后，缺少统一入口日志
|
||||
2. 项目级互斥和 `needRerun` 标记逻辑几乎不可观测
|
||||
3. 标签任务开始、结束、失败都没有清晰摘要
|
||||
4. 单条规则执行的耗时、命中数、阈值来源无法定位
|
||||
5. 结果清理和批量写库缺少过程确认
|
||||
|
||||
这会导致问题发生时难以区分：
|
||||
|
||||
- 是入口未触发
|
||||
- 是被项目级互斥拦截
|
||||
- 是规则没有命中
|
||||
- 是规则执行失败
|
||||
- 是结果写库失败
|
||||
- 是补跑标记了但未真正再次执行
|
||||
|
||||
## 方案对比
|
||||
|
||||
### 方案一：在现有方法中直接补日志
|
||||
|
||||
- 在现有类中按节点直接补 `info / debug / warn / error`
|
||||
- 不做统一模板
|
||||
|
||||
优点：
|
||||
|
||||
- 改动最小
|
||||
- 落地最快
|
||||
- 与当前项目写法最接近
|
||||
|
||||
缺点：
|
||||
|
||||
- 日志字段格式容易分散
|
||||
- 后续继续扩展时容易重复和漂移
|
||||
|
||||
### 方案二：统一字段格式的轻量日志设计
|
||||
|
||||
- 在现有类中补日志
|
||||
- 统一核心上下文字段和文案结构
|
||||
- 允许通过少量私有辅助方法减少重复
|
||||
|
||||
优点：
|
||||
|
||||
- 兼顾快速落地和长期可检索性
|
||||
- 同时适合排障和审计
|
||||
- 不引入额外框架，风险较低
|
||||
|
||||
缺点：
|
||||
|
||||
- 比方案一多一点整理成本
|
||||
|
||||
### 方案三：日志之外再做持久化审计摘要
|
||||
|
||||
- 除应用日志外，再把关键摘要落到任务表或独立审计表
|
||||
|
||||
优点：
|
||||
|
||||
- 审计能力最强
|
||||
- 不依赖日志平台
|
||||
|
||||
缺点：
|
||||
|
||||
- 超出本次“补详细日志提醒”的范围
|
||||
- 会引入表结构或数据模型变更
|
||||
|
||||
## 最终方案
|
||||
|
||||
采用方案二：统一字段格式的轻量日志设计。
|
||||
|
||||
具体原则如下：
|
||||
|
||||
1. 只在现有后端类补日志，不改数据库结构
|
||||
2. `info` 负责任务摘要和关键里程碑
|
||||
3. `debug` 负责规则参数、命中数量、批处理细节
|
||||
4. `warn` 负责互斥、降级、参数缺失、无命中等非致命异常
|
||||
5. `error` 负责任务失败、规则异常、写库失败、触发失败
|
||||
6. 日志字段尽量统一，保证同一任务可以通过 `projectId/taskId` 串起来
|
||||
|
||||
## 日志等级设计
|
||||
|
||||
### info
|
||||
|
||||
用于记录：
|
||||
|
||||
- 手动重算入口
|
||||
- 自动触发入口
|
||||
- 获取项目锁成功
|
||||
- 任务创建成功
|
||||
- 规则加载完成
|
||||
- 历史结果清理开始
|
||||
- 单规则开始和结束摘要
|
||||
- 结果批量写入摘要
|
||||
- 任务成功摘要
|
||||
- 自动补跑开始和结束
|
||||
|
||||
### debug
|
||||
|
||||
用于记录：
|
||||
|
||||
- 规则阈值参数
|
||||
- 参数来源项目
|
||||
- 规则命中明细数量
|
||||
- 无需写库时的空结果分支
|
||||
- 补跑标记消费细节
|
||||
|
||||
### warn
|
||||
|
||||
用于记录：
|
||||
|
||||
- 手动重算被运行中任务拒绝
|
||||
- 自动触发命中运行中任务，仅标记 `needRerun`
|
||||
- 自动触发被跳过
|
||||
- 规则参数缺失
|
||||
- 规则执行结果为空或无命中
|
||||
|
||||
### error
|
||||
|
||||
用于记录：
|
||||
|
||||
- 任务整体失败
|
||||
- 单规则执行异常
|
||||
- 结果写库异常
|
||||
- 参数解析过程中出现不可恢复异常
|
||||
- 自动触发或补跑异常
|
||||
|
||||
## 统一上下文字段
|
||||
|
||||
建议所有流水标签日志尽量带上以下字段：
|
||||
|
||||
- `projectId`
|
||||
- `taskId`
|
||||
- `modelCode`
|
||||
- `triggerType`
|
||||
- `operator`
|
||||
- `ruleCode`
|
||||
- `costMs`
|
||||
- `hitCount`
|
||||
|
||||
其中：
|
||||
|
||||
- 任务创建前无法取得 `taskId` 的场景允许缺省
|
||||
- 与单规则无关的日志可以不打印 `ruleCode`
|
||||
- 与耗时无关的日志可以不打印 `costMs`
|
||||
|
||||
## 脱敏规则
|
||||
|
||||
本次日志遵循以下脱敏边界：
|
||||
|
||||
- 允许打印阈值参数编码和值
|
||||
- 不打印身份证号明文
|
||||
- 不打印账号明文
|
||||
- 不打印完整 `objectKey`
|
||||
- 不打印规则 SQL
|
||||
- 不在 `info` 级别展开逐条命中结果
|
||||
|
||||
若后续需要定位对象级命中，可在 `debug` 级别打印脱敏后的对象标识摘要，例如前 3 位加后 2 位，但本次设计不要求默认展开。
|
||||
|
||||
## 打点设计
|
||||
|
||||
### 1. 入口层
|
||||
|
||||
涉及类：
|
||||
|
||||
- `CcdiBankTagController`
|
||||
- `CcdiFileUploadServiceImpl`
|
||||
|
||||
目标：
|
||||
|
||||
- 明确日志是从手动入口还是自动入口进入
|
||||
- 对自动触发链路补“已触发 / 已跳过”判断
|
||||
|
||||
建议日志：
|
||||
|
||||
```text
|
||||
【流水标签】收到手动重算请求: projectId={}, modelCode={}, operator={}
|
||||
【流水标签】批处理完成，准备触发自动重算: projectId={}, triggerType={}, anySuccess={}
|
||||
【流水标签】跳过自动重算: projectId={}, triggerType={}, reason=all_records_failed
|
||||
```
|
||||
|
||||
### 2. 协调层
|
||||
|
||||
涉及类：
|
||||
|
||||
- `ProjectBankTagRebuildCoordinator`
|
||||
|
||||
目标：
|
||||
|
||||
- 观测项目级互斥
|
||||
- 区分“任务丢失”和“任务被合并补跑”
|
||||
- 记录锁获取、锁释放、补跑消费全过程
|
||||
|
||||
建议日志：
|
||||
|
||||
```text
|
||||
【流水标签】手动重算开始排队: projectId={}, modelCode={}, operator={}
|
||||
【流水标签】项目已有运行中任务，拒绝手动重算: projectId={}, modelCode={}, operator={}
|
||||
【流水标签】项目正在重算，已标记完成后补跑: projectId={}, runningTaskId={}, triggerType={}
|
||||
【流水标签】获取项目重算锁成功: projectId={}
|
||||
【流水标签】检测到需要补跑，准备再次执行: projectId={}, previousTaskId={}
|
||||
【流水标签】未检测到补跑标记，结束自动重算: projectId={}, taskId={}
|
||||
【流水标签】释放项目重算锁: projectId={}
|
||||
```
|
||||
|
||||
### 3. 执行层
|
||||
|
||||
涉及类：
|
||||
|
||||
- `CcdiBankTagServiceImpl`
|
||||
|
||||
目标：
|
||||
|
||||
- 形成任务级生命周期日志
|
||||
- 形成规则级执行和写库摘要
|
||||
|
||||
建议日志：
|
||||
|
||||
```text
|
||||
【流水标签】任务创建成功: taskId={}, projectId={}, modelCode={}, triggerType={}, operator={}
|
||||
【流水标签】加载启用规则完成: taskId={}, projectId={}, modelCode={}, ruleCount={}
|
||||
【流水标签】开始清理历史结果: taskId={}, projectId={}, modelCode={}
|
||||
【流水标签】规则开始执行: taskId={}, projectId={}, ruleCode={}, resultType={}
|
||||
【流水标签】规则执行参数: taskId={}, ruleCode={}, thresholds={}
|
||||
【流水标签】规则执行完成: taskId={}, projectId={}, ruleCode={}, hitCount={}, costMs={}
|
||||
【流水标签】规则无命中: taskId={}, projectId={}, ruleCode={}, costMs={}
|
||||
【流水标签】批量写入标签结果: taskId={}, projectId={}, resultCount={}
|
||||
【流水标签】任务执行成功: taskId={}, projectId={}, modelCode={}, triggerType={}, ruleCount={}, hitCount={}, costMs={}
|
||||
【流水标签】任务执行失败: taskId={}, projectId={}, modelCode={}, triggerType={}, error={}
|
||||
```
|
||||
|
||||
### 4. 参数解析层
|
||||
|
||||
涉及类：
|
||||
|
||||
- `BankTagRuleConfigResolver`
|
||||
|
||||
目标：
|
||||
|
||||
- 说明阈值从项目默认配置还是项目专属配置解析而来
|
||||
- 在参数缺失时明确记录缺了哪些编码
|
||||
|
||||
建议日志：
|
||||
|
||||
```text
|
||||
【流水标签】解析规则参数: projectId={}, effectiveProjectId={}, ruleCode={}, requiredParams={}
|
||||
【流水标签】规则参数解析结果: projectId={}, ruleCode={}, thresholdValues={}
|
||||
【流水标签】规则参数缺失: projectId={}, ruleCode={}, missingParams={}
|
||||
```
|
||||
|
||||
## 关键异常场景设计
|
||||
|
||||
### 手动重算被拒绝
|
||||
|
||||
当项目已经存在运行中任务时：
|
||||
|
||||
- 抛出原有业务异常
|
||||
- 额外补 `warn`，明确项目、模型、操作人和拒绝原因
|
||||
|
||||
目的：
|
||||
|
||||
- 便于区分“接口未进来”和“接口进来了但被互斥挡住”
|
||||
|
||||
### 自动重算被合并
|
||||
|
||||
当批量上传或拉取本行触发自动重算时，如果项目已在运行中：
|
||||
|
||||
- 不再直接丢弃
|
||||
- 通过 `markNeedRerun` 标记补跑
|
||||
- 日志明确说明当前触发未丢失，而是等待本轮完成后自动重跑
|
||||
|
||||
### 参数缺失但继续执行
|
||||
|
||||
当前规则参数解析器未对所有缺失参数直接抛错，部分规则可能按空值或 `0` 继续执行。
|
||||
|
||||
此场景需要：
|
||||
|
||||
- `warn` 记录缺失参数编码
|
||||
- `debug` 记录实际解析到的阈值集合
|
||||
- 文案中说明本次按当前默认值继续执行
|
||||
|
||||
### 单规则执行失败
|
||||
|
||||
当某条规则在查询或结果构造过程中抛异常时：
|
||||
|
||||
- `error` 记录 `taskId/projectId/ruleCode`
|
||||
- 保留原有失败传播语义
|
||||
- 由任务级失败日志补充整任务摘要
|
||||
|
||||
### 结果写库失败
|
||||
|
||||
当历史结果已清理但新结果写入失败时：
|
||||
|
||||
- `error` 记录失败发生在“结果写入”阶段
|
||||
- 日志中带上准备写入的结果条数
|
||||
|
||||
这样可以避免误判为“规则无命中”。
|
||||
|
||||
### 自动补跑消费
|
||||
|
||||
自动重算完成后如果检测到 `needRerun=1`：
|
||||
|
||||
- `info` 记录上一轮任务 ID 和将进入补跑
|
||||
- `debug` 记录补跑标记消费结果
|
||||
|
||||
如果没有检测到补跑标记，也应记录收尾日志，避免看到“开始”却看不到“结束”。
|
||||
|
||||
## 建议实现方式
|
||||
|
||||
为控制改动范围，本次不新增独立日志组件，优先采用以下实现策略：
|
||||
|
||||
1. 在相关类中直接补充结构统一的日志
|
||||
2. 对重复字段较多的场景，可增加少量私有辅助方法拼接摘要
|
||||
3. 不为了日志而引入 ThreadLocal、MDC、AOP 或统一切面
|
||||
|
||||
这样可以把改动集中在当前标签链路相关类中，降低回归风险。
|
||||
|
||||
## 验证策略
|
||||
|
||||
本次重点验证“行为分支可被覆盖”，不建议编写对日志文本本身高度耦合的脆弱断言。
|
||||
|
||||
建议关注以下测试：
|
||||
|
||||
### 协调器测试
|
||||
|
||||
- 已有运行中任务时，手动重算被拒绝
|
||||
- 自动触发时命中运行中任务并标记 `needRerun`
|
||||
- 自动触发完成后成功消费补跑标记
|
||||
|
||||
### 标签服务测试
|
||||
|
||||
- 启用规则数为 0
|
||||
- 规则执行有命中且成功写库
|
||||
- 规则执行无命中时不写库
|
||||
- 单规则抛异常导致任务失败
|
||||
|
||||
### 参数解析测试
|
||||
|
||||
- 使用默认项目参数
|
||||
- 使用项目专属参数
|
||||
- 存在参数缺失时返回缺失状态
|
||||
|
||||
## 非目标
|
||||
|
||||
本次设计不包含以下内容：
|
||||
|
||||
- 新增数据库表或审计表
|
||||
- 前端页面展示任务执行日志
|
||||
- 接入链路追踪系统
|
||||
- 打印规则 SQL
|
||||
- 打印对象或账号明细
|
||||
- 调整标签任务执行策略或线程池模型
|
||||
|
||||
## 预期效果
|
||||
|
||||
落地后，开发和运维应能够通过日志快速回答以下问题：
|
||||
|
||||
- 手动重算是否真正进入后端
|
||||
- 自动触发是否提交成功，还是因为整批失败而跳过
|
||||
- 项目当前是否被互斥锁住
|
||||
- 自动触发是否被合并为补跑
|
||||
- 本次任务创建了哪个 `taskId`
|
||||
- 加载了多少条规则
|
||||
- 哪条规则执行最慢、命中多少
|
||||
- 参数是否来自默认配置，是否存在缺失
|
||||
- 结果是否已删除旧数据并完成新写入
|
||||
- 任务最终成功还是失败，失败在哪个阶段
|
||||
|
||||
## 落地范围
|
||||
|
||||
建议本次代码改动控制在以下文件附近：
|
||||
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiBankTagController.java`
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiBankTagServiceImpl.java`
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/ProjectBankTagRebuildCoordinator.java`
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/BankTagRuleConfigResolver.java`
|
||||
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiFileUploadServiceImpl.java`
|
||||
|
||||
如需进一步实现，可在此设计基础上继续拆分为具体实现计划。
|
||||
Reference in New Issue
Block a user