docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案

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