mongodb-log

AI 二次改写指南

1．用途

本文用于把当前项目交给 AI 继续开发、修复、重构或改写文档。目标不是让 AI 一次性重写整个仓库，而是让它在充分理解现状和约束后，做范围明确、可验证、可回退的修改。

适用任务包括：

• 新增或调整 Log 分析能力。
• 新增或调整 FTDC 指标组、解析和查询能力。
• 修复后端、前端、存储或竞态问题。
• 在不改变行为的前提下做局部重构。
• 根据源码更新项目文档。
• 审查某项实现是否违反内存、统计、隐私或兼容性约束。

2．AI 开始前的必读顺序

AI 不应只读取用户点名的单个文件。推荐按以下顺序建立上下文：

1. CLAUDE.md：项目硬约束、红线和验证要求。
2. ROADMAP.md：当前阶段、已完成事项、阻塞和最近验证。
3. docs/design.md：系统结构、功能设计和当前权衡。
4. 与任务直接相关的源码和测试。
5. README.md 与 docs/user-guide.md：外部功能口径和用户行为。

发生冲突时，以源码和测试为当前事实，以 CLAUDE.md 为不可降低的约束。文档与源码冲突时，先指出差异，再判断应该改代码还是改文档，不能静默选择。

3．项目速查

3.1 运行模型

• 后端：Java 17、Spring Boot、MongoDB BSON。
• 前端：Vue 3、Vite、Element Plus、ECharts。
• 存储：本地 JSON／JSONL、FTDC 源副本、blocks.idx。
• 交付：前端打进 Spring Boot 可执行 JAR。
• 部署假设：本机单用户，默认 127.0.0.1:18080。

3.2 代码路由

任务	优先查看
Log 上传、队列、状态	task/TaskService.java、task/TaskRunner.java、task/AnalysisTask.java
结构化日志	parser/StructuredLogParser.java、对应测试
旧版日志	parser/LegacyLogParser.java、BalancedDocumentExtractor.java、对应测试
查询模式	parser/QueryPatternNormalizer.java
慢查询统计	analysis/AnalysisAccumulator.java、DurationDistribution.java、TopSlowQueryCollector.java
运行诊断	analysis/diagnostics/DiagnosticAccumulator.java、LogDiagnostics.java
Log 持久化	storage/FileTaskRepository.java
Markdown 报告	report/MarkdownReportService.java
Log REST	web/TaskController.java、GlobalExceptionHandler.java
FTDC 上传与建索引	task/ftdc/FtdcTaskService.java、FtdcTaskRunner.java
FTDC 格式解析	parser/ftdc/
FTDC 索引	storage/ftdc/FtdcIndexWriter.java、FtdcIndexReader.java
FTDC 查询和降采样	analysis/ftdc/FtdcSeriesService.java、FtdcMetricDecoder.java
FTDC 分组	analysis/ftdc/FtdcMetricGroups.java
FTDC REST	web/FtdcTaskController.java
全局清理和内存	task/ApplicationMaintenanceService.java、web/SystemController.java
Log 前端	web/src/App.vue、web/src/components/、web/src/api/tasks.js
Metric 前端	web/src/components/ftdc/、web/src/api/ftdcTasks.js
前端竞态	web/tests/task-races.test.js、web/tests/ftdc-races.test.js

3.3 当前公开功能与内部组件

AI 必须先判断目标属于「公开能力」还是「内部代码」。当前产品公开：

• Log 任务、汇总、诊断、Top 5000 明细、散点、单条详情和 Markdown 报告。
• FTDC 任务、指标组目录和指标组序列。
• JVM 堆内存和全量数据清理。

以下代码存在且有测试，但没有 REST 路由和前端入口：

• FTDC 单指标序列查询。
• FTDC 原始值分页。
• FTDC GZip CSV 导出。

除非用户明确要求发布这些能力，否则不要顺手暴露接口或添加页面。

4．不可破坏的设计不变量

4.1 Log 不变量

• 日志必须逐行流式处理，禁止整文件读入内存。
• 结构化和旧版日志可以混合出现在同一任务。
• Top 5000 必须从全部慢查询中精确选取。
• 八档耗时分布必须基于全部慢查询，不能从 Top 5000 推算。
• Top 50 模式按 Namespace + 操作 + 归一化模式 分组。
• Top 50 每组的最慢样本独立于全局 Top 5000。
• 缺失字段不能当成零。
• 无效耗时不能进入慢查询统计，但解析错误必须计数。
• 普通日志原文不能持久化。
• 运行诊断不得改变 summary.json 和旧 API 的统计口径。
• 诊断事件、时间线、高基数计数和样本必须有界。

4.2 FTDC 不变量

• 外层 BSON 按文档读取，一次只解压当前 Block。
• 文件按内容验证，不依赖扩展名。
• 单任务最多 20 个非空文件。
• 建索引、查询和内部导出共用公平串行许可。
• 产品查询只开放指标组接口。
• 单组最多 200 个指标，每指标最多返回 1,200 个图表点。
• 未选中的指标列不能被完整恢复或缓存。
• 解压字节数、样本数和「指标数 × 样本数」必须在分配前校验。
• min、max、avg 和全零判断基于全部有效点。
• 降采样必须保留首尾和桶内极值。
• 时间断裂处必须用 null 断线。
• 多文件重复时间戳以更早上传的文件为准。
• 查询前必须校验源副本大小和 SHA-256。
• 不保存全量展开时间序列。

4.3 存储与删除不变量

• JSON、JSONL、catalog 和索引使用临时文件发布。
• 应用重启后不能继续使用中断任务的半成品。
• 活动任务不可删除。
• 删除只能作用于应用托管目录，不能跟随符号链接。
• 清空全部数据必须先确认所有任务均为终态，再开始删除。
• 失败删除要保留任务记录，允许用户修复环境后重试。

4.4 隐私不变量

• 不自动发送任何输入或结果到外部服务。
• 报告不能包含完整命令、完整 attributes 或普通原始日志。
• URI、IP、邮箱、用户身份和密钥字段必须经过脱敏。
• 日志和报告仍可能包含业务 Namespace、文件名和模式，不能宣称完全匿名。

4.5 前端不变量

• 图表和数据表在同一区块互斥显示，避免重复渲染。
• 零值和缺失值必须分开显示。
• 旧请求不能覆盖新任务、新指标组或新详情选择。
• 多指标组按用户选择顺序串行请求，并逐组增量渲染。
• 单组失败不能中断剩余组。
• 页面不能从降采样点间距自行推断时间断裂。
• 解读文字只能基于实际字段，不能自动断言根因。

5．把用户请求转换为可验证目标

AI 在动手前应把自然语言请求写成以下结构：

目标：用户最终能观察到什么变化。
范围：允许修改哪些模块和文档。
不变项：哪些统计、接口、存储或隐私行为不能改变。
输入：正常输入、无效输入和边界输入。
输出：成功结果、错误结果和历史兼容行为。
验证：新增哪些测试，运行哪些命令，如何确认结果。

示例：

目标：Log 结果页新增按客户端筛选 Top 5000 的能力。
范围：慢查询分页接口、前端筛选表单、相关测试和文档。
不变项：Top 5000 选取规则、summary.json、报告和历史任务格式不变。
输入：空筛选、IPv4、IPv6、大小写差异和无匹配值。
输出：在已保留的 Top 5000 内筛选，页数和 total 与筛选结果一致。
验证：Controller 集成测试、前端交互测试、全量后端与前端测试。

6．标准改写流程

6.1 第一步：只读调查

在修改前完成：

1. 读取项目规范和路线图。
2. 查看 git status，区分用户已有改动和本次任务。
3. 精确定位相关类、组件、接口和测试。
4. 用现有测试或最小输入复现当前行为。
5. 记录文档口径与源码是否一致。

不要在调查阶段顺手格式化、升级依赖或重构相邻代码。

6.2 第二步：确认最小修改面

按数据流从入口向下列出改动点：

用户操作
→ 前端组件
→ API 封装
→ Controller 参数和响应
→ Service／Runner
→ Parser／Analysis
→ Repository／持久化
→ 自动化测试
→ 用户文档与设计文档

没有经过这条链路的层不要默认修改。只改后端而不检查前端，或只改模型而不检查历史 JSON 兼容，都属于不完整方案。

6.3 第三步：先写失败验证

修 bug 或改变行为时，优先添加能稳定复现问题的测试：

• 解析规则：添加最小日志行或 FTDC fixture。
• 聚合规则：使用可手工复算的小数据集。
• API：使用 Controller 集成测试核对状态码和 JSON。
• 前端：模拟请求、竞态、空值和交互。
• 文件系统：使用临时目录，不操作真实 data。

如果只是文档修正，不需要为了形式新增业务测试，但必须核对源码、相对链接和文档内部一致性。

6.4 第四步：最小实现

• 优先修改已有职责明确的类。
• 不为一次性规则创建通用框架。
• 不引入第二套同类库。
• 不改变无关 API、JSON 字段或 UI 布局。
• 不添加用户未要求的配置项和兼容层。
• 新增边界必须在循环或内存分配前校验。
• 新增错误必须映射为清晰、稳定的 API 消息。

6.5 第五步：分层验证

推荐从快到慢运行：

1. 目标单元测试。
2. 相关包或相关前端测试文件。
3. 全量 mvn test。
4. 全量 npm test -- --run。
5. npm run build。
6. 交付相关改动再运行 mvn clean package。
7. 涉及真实交互时启动 JAR 做浏览器验收。

验证失败时修根因，不能注释测试、降低断言或添加跳过标记让结果变绿。

6.6 第六步：同步文档和路线图

代码、接口、限制、数据目录或用户操作变化时，检查：

• README.md
• README.en.md
• docs/user-guide.md
• docs/user-guide.en.md
• docs/design.md
• docs/ai-rewrite-guide.md
• CLAUDE.md

只有已经实现并验证的事项才能写入 ROADMAP.md 的「已完成」或「最近验证」。尚未验证的内容写「待确认」，不能用推测补齐。

7．按任务类型的修改指南

7.1 修改结构化日志解析

检查清单：

• 新字段是日志信封字段还是 attr 字段。
• MongoDB 缺失该字段时的行为。
• 零值、负值、字符串数字、浮点值和超大值。
• 是否影响慢查询认定、模式归一化或诊断覆盖率。
• 旧版日志是否需要对应能力。
• ParsedLogEntry 变化是否破坏历史 JSON 读取。
• 详情、报告和前端解释是否需要同步。

禁止只根据 MongoDB 版本号启用字段；应按字段实际存在和类型能力解析。

7.2 修改旧版日志解析

检查清单：

• 日志头、命令主体和耗时是否来自明确位置。
• 嵌套文档、字符串花括号和 BSON 构造器是否仍安全。
• getMore 是否需要读取 originatingCommand。
• 新正则是否会把普通消息误判为慢查询或心跳失败。
• 解析不完整时应返回 PARTIAL、FAILED 还是 SKIPPED。

不要用宽泛正则从任意文本中猜耗时或命令字段。

7.3 修改慢查询统计

先回答四个问题：

1. 统计对象是全部慢查询还是已保留明细。
2. 是否要求精确结果。
3. 内存上限如何保证。
4. 历史任务缺失新字段时如何展示。

以下口径不能混用：

• 全部慢查询：耗时分布、总数、总耗时、聚合统计。
• 固定容量明细：全局 Top 5000。
• 按频次选择后独立保留：Top 50 模式样本。
• 有界近似：诊断中的应用、Driver 等高基数 Top 值。

7.4 修改运行诊断

• 新事件必须有稳定分组键。
• 事件种类、样本数和时间线必须继续有界。
• 新线索必须能从实际字段直接复算。
• 阈值需要写入测试和设计文档。
• 线索文案不能表达为确定根因。
• 不能把诊断字段塞入旧 summary.json 改变兼容口径。
• 报告只输出脱敏后的诊断结果。

7.5 修改 FTDC 解析或索引

这是高风险区域，必须逐层核对：

1. BSON 文档长度和文件偏移。
2. zlib 声明长度、实际长度和尾随数据。
3. baseline 长度与属性数量。
4. uvarint 和 RLE 边界。
5. Schema 路径与 baseline 列顺序。
6. blocks.idx 写入和读取字段顺序。
7. 源文件大小和 SHA-256。
8. 数组分配前的规模校验。

索引格式字段发生变化时，必须明确是否升级 magic／version，以及旧任务如何失败或兼容。不能让旧索引被错误解释成新格式。

7.6 修改 FTDC 查询或降采样

至少覆盖：

• 单文件和多文件。
• 时间范围无数据。
• 重复时间戳和上传顺序优先级。
• 某指标在部分 Schema 缺失。
• raw 和 delta。
• 点数刚好等于上限和超过上限。
• 首点、尾点、尖峰、低谷和时间断裂。
• 完整点统计与降采样展示的差异。
• 全零、全负值和 long 边界。

不能为了图表方便先把全部点存入 List<Long>，再做二次处理。

7.7 修改前端异步逻辑

每个请求都要回答：

• 用户切换任务后，旧响应会怎样。
• 用户关闭详情或重新选择后，旧响应会怎样。
• 定时器是否可能产生重叠请求。
• 组件卸载后是否取消定时器和请求。
• 部分失败是否保留已经成功的结果。
• 错误后是否有清晰重试路径。

新增请求时优先复用现有的版本号、pending 和 AbortController 模式，不引入新的全局状态库。

7.8 修改持久化或删除

• 所有写入先到同目录临时文件。
• 检查原子移动不受支持时的回退。
• 中断后不能发布半成品。
• 删除前校验 ID、根目录、目标目录、普通文件和符号链接。
• 文件删除与索引更新的失败顺序必须可恢复或可重试。
• 测试只能使用隔离临时目录。

7.9 修改报告

• 报告只读取持久化结果，不重新扫描原日志。
• 新增字段先判断是否可能包含身份、地址、凭据或命令字面值。
• 所有用户可控文本经过 Markdown 表格转义和敏感值遮盖。
• 历史任务缺失字段时明确标注，不补零。
• 时间继续使用 UTC。
• 更新 MarkdownReportServiceTest 中的正向内容和禁止出现内容。

8．测试选择矩阵

改动范围	最低验证	建议追加
纯 Markdown 文档	相对链接、路径、git diff --check	与源码关键常量交叉检索
单个 Log 解析规则	对应 Parser 测试	mvn test
Log 聚合或报告	对应 Analysis／Report 测试	Controller 集成测试、mvn test
FTDC 格式或索引	Parser／Index 测试	Series、集成、真实样本条件测试
FTDC 查询或降采样	FtdcSeriesServiceTest	Controller 集成测试、真实样本条件测试
后端 API	Controller 集成测试	前端 API／组件测试、mvn test
前端展示	相关 Vitest 文件	全量前端测试和生产构建
前端竞态	race 测试	浏览器快速切换手工验收
构建／发布	全量测试	mvn clean package 和 JAR 启动
删除／清理	临时目录集成测试	权限和符号链接边界

9．常见错误模式

9.1 把 Top 5000 当作全量数据

错误结果：耗时分布、平均值或模式频次只基于保留明细。

正确做法：聚合在流式读取阶段完成，Top 5000 只影响持久化明细。

9.2 把缺失字段显示成零

错误结果：用户无法区分「指标确实为零」和「日志没有提供」。

正确做法：后端使用可空字段，前端显示「日志未提供」或 —。

9.3 用服务器版本号判断字段

错误结果：混合版本日志、版本缺失或字段提前／延后出现时统计错误。

正确做法：按字段存在、类型和可解析性判断，版本号只做数据质量信息。

9.4 为 FTDC 查询展开全部列

错误结果：大文件或多文件任务内存随「指标数 × 样本数」增长。

正确做法：索引定位 Block，只解码时间列和选中组的列。

9.5 用降采样点算统计值

错误结果：尖峰、低谷、平均值和全零判断失真。

正确做法：遍历全部点计算统计，同时只把有界代表点写入响应。

9.6 在前端推断时间断裂

错误结果：极值降采样造成不规则时间间距，被误判为真实断裂。

正确做法：后端基于完整时间序列判断并插入 null，前端只负责渲染。

9.7 把内部类当成已发布功能

错误结果：README 或用户指南声称支持单指标分页或 CSV 导出，但用户没有入口。

正确做法：以 Controller 路由和前端入口共同判断公开能力。

9.8 只改源码不更新进度源

错误结果：ROADMAP.md 与仓库实际状态不一致。

正确做法：实现、验证完成后同步路线图；未验证事项不能标为完成。

10．提供给 AI 的任务上下文模板

复制以下模板，并用本次任务信息替换占位内容：

项目：MongoDB Log & Metric Analyzer

目标：
<用户可观察的最终结果>

当前行为：
<如何复现，实际结果是什么>

期望行为：
<正常输入、边界输入、错误输入分别是什么结果>

允许修改：
<文件或模块范围>

禁止改变：
- Log 全量聚合与 Top 5000／Top 50 的口径。
- FTDC 流式、有界、串行和源文件完整性约束。
- 本地离线与隐私边界。
- 未点名的公开 API 和存储格式。

必读：
- CLAUDE.md
- ROADMAP.md
- docs/design.md
- 与任务相关的源码和测试

验证：
<必须运行的目标测试、全量测试、构建或浏览器验收>

交付：
<代码、测试、文档、ROADMAP 更新和汇报格式>

11．可直接使用的提示词

11.1 Bug 修复

先读取 CLAUDE.md、ROADMAP.md 和 docs/design.md，再调查这个问题。先用现有输入或最小测试稳定复现，给出根因和最小修改面；确认属于实现任务后，先补失败测试，再做最小修复。不要修改无关代码，不要改变现有统计口径、FTDC 资源边界、存储格式或公开 API。修复后运行相关测试和全量测试，并只在验证通过后更新 ROADMAP.md。最终汇报根因、改动文件、验证结果和仍存在的边界。

问题：<粘贴问题>

11.2 新功能

先读取 CLAUDE.md、ROADMAP.md、docs/design.md 和相关测试，把需求转换成可验证目标。列出用户流程、输入边界、接口变化、持久化影响、内存上限、历史兼容和隐私影响。只实现明确要求的最小功能，先写失败测试，不增加未要求的依赖、配置和兼容层。完成后同步用户文档、设计文档和 ROADMAP.md，并运行相关全量验证。

需求：<粘贴需求>

11.3 局部重构

这是行为保持型重构。先读取 CLAUDE.md、ROADMAP.md 和 docs/design.md，明确当前可观察行为和现有测试覆盖。只重构指定模块，不改变 REST 路由、JSON 字段、排序、错误消息、存储格式、资源上限和 UI 行为。先运行重构前测试建立基线，再小步修改，每步复跑目标测试。若发现必须改变行为，停止并单独说明，不要把行为变更混入重构。

范围：<粘贴类或组件>
目的：<粘贴维护性问题>

11.4 文档更新

先读取 CLAUDE.md、ROADMAP.md、docs/design.md，并从 Controller、Service、核心常量、前端入口和测试交叉核对事实。只记录当前已经实现的行为，明确区分公开功能、内部组件、精确统计和近似统计。以当前源码和测试为准，不要根据类名猜功能。完成后检查所有相对链接、文件路径、接口路径、数值上限和中英文口径；运行 git diff --check，并在验证通过后更新 ROADMAP.md。

文档目标：<粘贴目标>

11.5 代码审查

按 CLAUDE.md 和 docs/design.md 审查本次 diff。优先寻找会导致统计错误、全量物化、内存无界、竞态覆盖、半成品发布、越界删除、敏感信息泄露、历史任务不兼容和公开能力误判的问题。每条问题必须指出具体文件和行、可复现条件、实际影响和最小修复方向。没有证据的问题不要写成结论。只做审查，不直接改代码。

12．AI 完成任务前的自检

12.1 范围

• 每行改动都能追溯到用户请求。
• 没有顺手重构、升级依赖、格式化无关文件或发布内部能力。
• 用户已有未提交改动被保留。

12.2 正确性

• 正常、无效和边界输入都有明确行为。
• 精确统计没有被固定容量明细替代。
• 缺失值没有变成零。
• 排序、去重和时间语义保持稳定。
• 历史任务缺失新字段时不会崩溃或伪造结果。

12.3 资源

• Log 仍逐行处理。
• FTDC 仍逐文档、逐 Block、按需列处理。
• 新 Map、List、数组和缓存有清晰上限或规模依据。
• 校验发生在大内存分配前。

12.4 安全和隐私

• 没有新增外部请求。
• 没有把凭据、完整命令或普通原始日志写入结果。
• 文件路径仍被限制在托管根目录内。
• 删除逻辑不跟随符号链接。

12.5 验证和文档

• 新行为有自动化测试或说明无法自动验证的原因。
• 相关测试和构建已实际运行，不凭历史结果宣称通过。
• README、用户指南、设计文档和 API 口径一致。
• ROADMAP.md 只记录已经验证的完成项。
• git diff --check 通过。

13．AI 最终汇报模板

结论：<任务是否完成，用户现在得到什么>

改动：
- <文件或模块>：<具体变化及原因>

验证：
- <命令>：<通过数量或关键结果>
- <未执行项>：<原因和影响>

边界：
- <仍然不支持或需要用户注意的事项>

汇报只写已发生的事实。不要把「应该通过」「理论上可用」写成「已验证」。

This site is open source. Improve this page.