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