aivfo-tl-3.0/CLAUDE.md

aivfo-tl-3.0 — 时差培养箱合并改造项目

路径约定:下文所有 项目文档/... 均相对仓库根目录 aivfo-tl-3.0/。 本文件两台引擎:第二节(开机先读) 保证重启后无缝衔接;第三节(回写协议) 保证文档不滞后。

一、沟通约定(最先生效)

• 全程用中文回复。
• 代码/文件检索、定位优先用 codegraph(MCP codegraph_explore / codegraph_node,或 shell codegraph explore "..."),而非 grep/读文件。
• 代码理解优先用 codegraph_explore —— 一次返回相关符号源码 + 调用链。
• 增删改文件后跑 codegraph sync(增量同步索引,保持最新);仅在索引异常/需全量重建时才用 codegraph init。
• 第二节(开机先读)与第三节(回写协议)是硬纪律,每次都执行。

二、开机先读这些(无缝衔接引擎,按顺序)

每次新会话 / 关机重启后,严格按此顺序读,读完即可接着干:

1. 项目文档/进度/进度状态.yaml —— 轻断点:当前断点 / 下一步 / 紧前阻塞(只读这个就知道现在干到哪、下一步干啥)。
2. 项目文档/进度/工作计划表.md —— 里程碑真实状态 + 顶部「全局概览·续接指南」(各里程碑干到哪、文档三层结构、续接三件套一览)。
3. 项目文档/开发计划/2026-06-20-当前开发计划.md —— 剩余工作(5 组任务 G1 串口收尾 / G2 UI / G3 日志 / G4 对焦数据 / G5 业务回归,标注哪些受真机门控)。
4. 项目文档/进度/交接卡.md —— 拉到最后一段 = 最近一次工作的细节。
5. 按需再读:验证进度看 待验证清单.md;全局背景看 00-需求总览.md(总纲,勿删)。

⚠ 环境/账号信息以 项目文档/开发环境/环境与账号清单.md 与用户实际部署为准。

三、回写协议 —— 硬纪律(文档不滞后引擎)

3.1 轻断点规则

进度状态.yaml 的 当前任务 只保留当前断点(正在做什么 + 下一步 + 阻塞),控制在约 5 行内。每推进一步覆盖更新它,不在这里堆历史——历史细节一律进 交接卡.md。

3.2 交接卡 = 追加式历史

每完成一步或暂停,在 交接卡.md 末尾追加一段,格式:## 日期 时间 · 一句话标题,下列「改动 / 核实 / 踩坑 / 下一步」。只追加,绝不覆盖。

3.3 回写矩阵 —— 什么事发生,就更新哪些文件

触发事件	必须回写的文件
完成一步 / 暂停	进度状态.yaml(覆盖断点)+ 交接卡.md(追加)+ 进度数据.js(让 监控面板.html 反映)
任务状态变化(开始 / 完成 / 待验证)	工作计划表.md
真机验证了一条	待验证清单.md 对应 V-xxx
设计 / 方案改了	对应 需求文档/NN-*.md + 00-需求总览.md(若动总纲)+ 受影响的 开发计划/*.md
新增源码文件 / 删除文件	改完跑 codegraph sync(增量同步索引)

3.4 提交边界 = 文档已同步(强约束)

一个任务做完、准备 git 提交时,先把上表中该任务牵动的所有文件一次性同步到位,再提交。 「git 提交 = 文档已和代码对齐」 —— 不允许只提交代码而不更新文档。

四、文档地图(项目文档/ 下,按需深入查)

• 00-需求总览.md 总纲(勿删)。
• 需求文档/01-14 各专题方案(无 11):01架构合并 / 02业务闭环 / 03自动对焦 / 04微服务改造 / 05通讯监控 / 06配置统一 / 07UI改造 / 08影响范围 / 09计划验收 / 10术语契约 / 12计划表+对焦数据 / 13硬件访问层接口 / 14全量操作日志。
• 开发计划/ 2026-06-20-当前开发计划.md(当前剩余工作 G1-G5)+ 已完成归档/(M1-M5/M8 历史子计划,参考用)。
• 进度/ 续接回写文件(进度状态.yaml / 工作计划表.md / 交接卡.md / 待验证清单.md)+ 进度数据.js / 监控面板.html(实时面板)+ 历史报告/(旧审计报告归档)。
• 开发环境/ 环境与账号清单.md——本机环境、版本、账号/凭证、Docker 排障记录(编译与部署先查这里)。

五、排障利器:全量操作日志(M8,设计见 14 号)

• 系统做了"全量操作日志":C#/Java 所有操作记 谁/功能/输入/输出/报错/结果,经 Kafka→日志微服务 aivfo-oplog→log 库 operation_log 表,跨端共用 trace_id。
• 排障第一步:拿到 trace_id,把一次操作的跨端日志拉成时间线,找 result=失败 那条读 input+error 定位;调试级(串口/相机原始细节)走本地文件、按模块/按舱热开。

六、编译环境(若需本地编译)

• JDK 11.0.25 + Maven 3.9.9 @ C:\TLData\tools;本地仓库 C:\TLData\tools\maven-repo。
• Nexus 私服凭证已配在 ~/.m2/settings.xml(admin);详细环境/账号见 项目文档/开发环境/环境与账号清单.md。
• ★本地多仓构建顺序:先 mvn -DskipTests install 装 aivfo-framework(底座,提供 com.aivfo SNAPSHOT),再编译依赖它的各微服务,否则报 Could not find artifact。

七、Git(改动可追溯/可回退)

• 仓库:http://git.aivfo.com:36000/huangjie/aivfo-tl-3.0,主分支 main,仓库名 aivfo-tl-3.0。
• 每做完一个任务,把该任务牵动的代码与已同步的文档(见 3.4)一起提交到该仓库。

八、临时文件

• 临时文件放到 临时文件/ 目录。