# 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)一起提交到该仓库。

## 八、临时文件
- 临时文件放到 `临时文件/` 目录。