`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
8.1 KiB
11-plan — 可观测性:指标定义与日志字段规范
对应
docs/specs/11-observability.md。决策:指标名与日志字段规范先行落地;不引入新监控组件(Micrometer 若已依赖则用,未依赖则手动计数器+日志)。 技术栈:Java 21 + Slf4j +(可选 Micrometer)。
任务 178:日志字段规范落地
所属模块:11 可观测性 依赖:无 预估:8-15 分钟
功能点要求
业务日志统一携带结构化字段:traceId/taskId/moduleType/stage/submissionId/chunkIndex/chunkTotal/jobId/result/errorType;缺失字段用占位;不删现有日志。
测试用例(≥8)
- test_worker_log_has_task_id — Worker 日志含 taskId
- test_worker_log_has_module_type
- test_worker_log_has_stage
- test_result_log_fields — /result 日志字段
- test_heartbeat_log_fields
- test_missing_field_placeholder — 缺字段占位
- test_log_field_names_frozen — 字段名快照
- test_no_log_content_break — 日志内容不破坏
任务 179:禁止记录清单审计
所属模块:11 可观测性 依赖:178 预估:8-15 分钟
功能点要求
审计日志代码:Token/Cookie/完整请求体/文件二进制/用户凭据/敏感 API Key 不入日志;发现问题修正。
测试用例(≥8)
- test_no_token_logged — 无 Token
- test_no_cookie_logged — 无 Cookie
- test_no_full_body_logged — 无完整 body
- test_no_binary_logged — 无二进制
- test_no_credential_logged — 无凭据
- test_no_api_key_logged — 无 API Key
- test_allowed_fields_kept — 允许字段保留
- test_audit_script — 审计脚本可重复
任务 180:Worker 日志字段对齐
所属模块:11 可观测性 依赖:73 预估:8-15 分钟
功能点要求
TaskResultFileJobWorker(04 改造后)日志字段与规范对齐:jobId/taskId/moduleType/stage/errorType;现有 [task-file-job] 前缀保留。
测试用例(≥8)
- test_dispatch_log_fields — dispatch 日志
- test_success_log_fields
- test_failure_log_fields
- test_retry_log_fields
- test_heartbeat_log_fields
- test_stuck_log_fields
- test_field_names_consistent — 与规范一致
- test_no_sensitive — 无敏感
任务 181:task.created/running 指标埋点
所属模块:11 可观测性 依赖:无 预估:8-15 分钟
功能点要求
任务创建(created 计数)与运行中(running gauge)指标;带 moduleType/instanceId 标签;无监控栈时输出日志记录。
测试用例(≥8)
- test_created_incremented — 创建计数
- test_running_gauge — 运行 gauge
- test_module_label — 标签
- test_instance_label — instanceId 标签
- test_created_module_specific — 分模块
- test_counter_persistent — 计数正确性
- test_gauge_update — 更新
- test_metric_name_frozen — 名称快照
任务 182:task.success/failed/cancelled 指标埋点
所属模块:11 可观测性 依赖:181 预估:8-15 分钟
功能点要求
终态计数:success/failed/cancelled 各模块独立计数;与状态迁移一致。
测试用例(≥8)
- test_success_counted
- test_failed_counted
- test_cancelled_counted
- test_module_split — 分模块
- test_no_double_count — 不重复计
- test_terminal_once — 只计一次
- test_failed_then_success — 状态反转不重计
- test_names_frozen
任务 183:task.duration 指标埋点
所属模块:11 可观测性 依赖:182 预估:8-15 分钟
功能点要求
任务耗时(开始→终态)记录;直方图或耗时日志;分模块。
测试用例(≥8)
- test_duration_recorded — 记录
- test_duration_positive — 正值
- test_module_split
- test_short_task — 短任务
- test_long_task — 长任务
- test_duration_bound — 上界
- test_duration_zero_guard — 零保护
- test_name_frozen
任务 184:task.heartbeat.age 指标埋点
所属模块:11 可观测性 依赖:无 预估:8-15 分钟
功能点要求
心跳年龄 gauge:任务最后心跳距今时间;超阈值可观测(日志告警)。
测试用例(≥8)
- test_age_computed — 年龄计算
- test_age_fresh — 新鲜
- test_age_stale — 陈旧
- test_age_threshold_warn — 阈值告警
- test_no_heartbeat — 无心跳处理
- test_age_zero — 刚心跳
- test_age_clock_negative — 时钟负保护
- test_name_frozen
任务 185:file-job.* 指标埋点
所属模块:11 可观测性 依赖:73 预估:8-15 分钟
功能点要求
TaskFileJobWorker 指标:pending/running/success/failed/duration/retry;分 moduleType/instanceId。
测试用例(≥8)
- test_pending_counted
- test_running_counted
- test_success_counted
- test_failed_counted
- test_duration_recorded
- test_retry_counted
- test_module_instance_labels
- test_names_frozen
任务 186:上传耗时/大小指标埋点
所属模块:11 可观测性 依赖:无 预估:8-15 分钟
功能点要求
文件上传:耗时、大小、成功率指标;分 moduleType。
测试用例(≥8)
- test_upload_duration
- test_upload_size
- test_upload_success_rate
- test_module_split
- test_upload_failed
- test_upload_large
- test_size_bound
- test_names_frozen
任务 187:临时磁盘指标埋点
所属模块:11 可观测性 依赖:154 预估:8-15 分钟
功能点要求
临时磁盘容量/占用指标;与 09 告警联动。
测试用例(≥8)
- test_disk_usage_measured
- test_disk_capacity
- test_usage_percent
- test_threshold_warn
- test_empty_dir
- test_measure_failure_grace
- test_name_frozen
- test_no_block
任务 188:指标标签规范
所属模块:11 可观测性 依赖:181-187 预估:8-15 分钟
功能点要求
统一标签:moduleType/instanceId 必带;标签值规范化(null→unknown);不记录用户级数据。
测试用例(≥8)
- test_module_label_all_metrics — 全指标带
- test_instance_label_all
- test_null_module_unknown — null 归一
- test_no_user_label — 无用户级
- test_label_consistent — 命名一致
- test_label_value_clean — 值清洗
- test_cardinality_bounded — 基数有界
- test_spec_frozen — 规范冻结
任务 189:指标命名一致性测试
所属模块:11 可观测性 依赖:188 预估:8-15 分钟
功能点要求
全部指标名与 11 spec §1 标准名一致(aiimage.* 前缀);无拼写漂移。
测试用例(≥8)
- test_prefix_aiimage — 前缀
- test_task_metric_names — 任务族
- test_file_job_metric_names — 文件族
- test_no_typo_drift — 无拼写漂移
- test_snapshot_all_metrics — 全指标快照
- test_new_metric_must_register — 新指标注册
- test_metric_doc_sync — 文档同步
- test_case_consistent — 大小写一致
任务 190:日志脱敏测试
所属模块:11 可观测性 依赖:179 预估:8-15 分钟
功能点要求
敏感值(Token/Key/凭据)即使传入日志调用点也被脱敏(占位符);断言日志输出无原文。
测试用例(≥8)
- test_token_masked
- test_api_key_masked
- test_password_masked
- test_cookie_masked
- test_partial_token_masked — 部分值
- test_url_query_masked — URL 查询参数
- test_masking_consistent — 一致
- test_normal_fields_kept — 正常字段保留
任务 191:双实例指标区分回归
所属模块:11 可观测性 依赖:188-190 预估:8-15 分钟
功能点要求
双实例部署:instanceId 标签区分 server-110/server-121;指标不串;日志含实例标识。
测试用例(≥8)
- test_instance_110_label
- test_instance_121_label
- test_no_cross_instance — 不串
- test_instance_unknown — 未配置
- test_log_has_instance — 日志实例
- test_metric_aggregation_ok — 聚合可用
- test_label_stable — 标签稳定
- test_snapshot_frozen
收尾验证(本模块)
mvn test 相关类全绿;11 spec §2 禁止记录清单逐项对照。