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

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

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

## 二、开机先读这些(无缝衔接引擎,按顺序)
> **当前任务:operate / control 双进程拆分**(旧任务 M0-M8 三项目合并:**代码完成、真机验收整体未做、有 operate 侧降级遗留〔见 `进度/待验证清单.md` M-01~M-07〕**;旧文档已清空,本体系为新任务重建)。
每次新会话 / 关机重启后,严格按此顺序读,读完即可接着干(**本节为续接顺序的唯一权威**,`项目背景与上手指南.md §四` / `00-需求总览.md §六` 应与本节对齐):
1. `项目文档/项目背景与上手指南.md` —— **总入口·新会话第一篇**:项目全貌(三桌面程序 + Java 微服务)/当前任务/已定架构/技术栈/已知坑,一篇读懂"在做什么"。
2. `项目文档/进度/进度状态.yaml` —— **轻断点**:当前断点 / 下一步 / 阶段概览(读这个就知道现在干到哪、下一步干啥)。
3. `项目文档/进度/工作计划表.md` —— **阶段真实状态 + 顶部「全局概览·续接指南」**(阶段1/2/3 干到哪、文档三层结构、续接三件套一览)。
4. `项目文档/开发计划/2026-06-22-阶段1-control独立进程骨架.md` —— **当前阶段实现计划**(7 个 bite-sized 任务,标注哪些受真机门控)。
5. `项目文档/进度/交接卡.md` —— **拉到最后一段** = 最近一次工作的细节。
6. 按需再读:架构看 `需求文档/specs/2026-06-22-operate-control-双进程拆分-design.md`;现状基线看 `需求文档/control-逻辑与配置全景.md`(control 全图)+ `需求文档/操作端逻辑与配置全景.md`(operate 全图,含**§八 合并降级登记**);验证进度看 `进度/待验证清单.md`;全局背景看 `00-需求总览.md`(总纲,勿删)。

⚠ 环境/账号信息以 `项目文档/开发环境/服务器测试环境.md`(**当前实际部署 = 108 原生环境,权威**)+ `连接配置清单-换服务器必读.md` 与用户实际部署为准;`环境与账号清单.md` 描述的是**本机 Docker 备用环境**(compose `tl-mw`),非当前运行环境,勿据它定连接信息。

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

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

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

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

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

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

## 四、文档地图(`项目文档/` 下,按需深入查)
> 当前任务 = operate/control 双进程拆分。旧任务(M0-M8)文档已清空。
- `项目背景与上手指南.md`   ★**新会话第一篇总入口**(项目全貌/当前任务/已定架构/技术栈/已知坑);开机先读顺序见第二节。
- `00-需求总览.md`            新任务总纲(为什么拆/目标/范围/关键决策,勿删)。
- `需求文档/`              *做什么*:`specs/2026-06-22-operate-control-双进程拆分-design.md`(架构设计,9章含拓扑/HTTP契约/生命周期/分阶段)+ `control-逻辑与配置全景.md`(control 现状基线)+ `操作端逻辑与配置全景.md`(operate 现状基线:启动/业务模块/交接面/HTTP/配置 + **§八 合并降级登记**,标 file:line)。
- `开发计划/`              *怎么做*:`2026-06-22-阶段1-control独立进程骨架.md`(阶段1 七任务,可执行)。阶段2/3 待拆。
- `系统业务流程详图.html`  ★开发上手总文档(单页可视化,浏览器打开):汇总背景/架构/两份全景/阶段1计划/降级登记,读一篇即懂「为什么改→改成什么样→现在什么样→接下来改什么→怎么上手」。
- `进度/`              续接回写文件(进度状态.yaml=断点 / 工作计划表.md=阶段状态 / 交接卡.md=追加历史 / 待验证清单.md=真机门控)+ `进度数据.js` / `监控面板.html`(实时面板)。
- `开发环境/`            `服务器测试环境.md`——**当前实际中间件部署(108 原生环境,权威·编译部署先查这里)**;`连接配置清单-换服务器必读.md`——换服务器逐项改 IP/端口/账号;`环境与账号清单.md`——本机环境/版本/账号凭证/Docker 备用环境排障记录;`start-all.sh`(一键起微服务集群)。

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

### 5.1 两层日志(互补,别只看一层)
- **动作层**(`OperationLogger.Begin`,各端逐方法埋点 G3-1/G3-2 + HTTP/串口/相机单点收口 P3b):带 **输入/输出/结果/报错/耗时**,module 如 `舱室设置/对焦调试/皿管理/胚胎操作/串口/相机/HTTP`。**定位失败靠这层**(读 `result=失败` 那条的 input+error)。
- **点击层**(`module=界面点击`,operate+front 各有 `Helpers/ClickTrailLogger.cs` 全局 Button 点击拦截):记 **"哪个页面·点了哪个按钮"** 的导航/意图轨迹(含"进入舱室调试"这类纯导航),`operation="页面类名 · 按钮文字"`。只记点击瞬间、**不含结果**。已跳过软键盘按键(防泄露密码)与滚动条 RepeatButton。
- **关层(怎么操作 §10 配置)**:每个程序**各有自己的 `oplog-config.json`**,源在项目根、随 exe 部署到其**输出目录(exe 同目录)**,改部署目录那份并保存,**≤15s 自动热加载、免重启**(已在两端 `App.xaml.cs InitOperationLog` 接 `o.ConfigFilePath = BaseDirectory + oplog-config.json`;监听器启动即读一次+轮询)。
  - operate:源 `ivf_tl_operate_2.0/ivf_tl_Operate/oplog-config.json`(模块:界面点击/HTTP/串口/相机/舱室设置/对焦调试/对焦设置/缓冲瓶调试/皿管理/胚胎操作)。
  - front:源 `aivfo-front-manament-2.0/ivf_tl_Manage/oplog-config.json`(模块仅 界面点击/HTTP——front 只有点击层+HTTP 单点收口,无业务动作埋点)。
  - 格式:`{ "enabled":true, "globalLevel":"Info", "modules":{ "界面点击":{"enabled":false}, "HTTP":{"enabled":false} } }`。把模块 `enabled` 设 `false` 即停记;`modules` 没列的默认全开;顶层 `enabled=false` 一键全关;文件不存在=全开(开发默认)。生效后该程序日志有"操作日志配置已热加载"。

### 5.2 怎么让日志真入库(运行期前置)
1. **中间件全在 108 服务器**(MySQL `log` 库:3306 / Kafka:9092 / Nacos:8848)。换服务器见 `项目文档/开发环境/连接配置清单-换服务器必读.md`。
2. **起 `aivfo-oplog` 消费端**(本机,默认 profile=local 全连 108;**机器重启即停需重起**):
   `C:/TLData/tools/jdk-11/bin/java -Xmx256m -jar aivfo-oplog/target/aivfo-oplog-1.0.0-SNAPSHOT.jar`(或整集群 `bash 项目文档/开发环境/start-all.sh`)。日志看 `临时文件/run-oplog.log`,出现 `Subscribed to ... tl-oplog` + `HikariPool ... Start completed` 即就绪。
3. operate/front 的 `App.config` `kfkaIP=192.168.0.108`、topic=`tl-oplog`,产消息端就绪。**不起 oplog 则消息只堆 Kafka 不入库**(这是"没记录"的最常见原因)。

### 5.3 怎么查库(本机无 mysql 客户端时,用 JDK11 + 驱动直查)
驱动:`C:/TLData/tools/maven-repo/mysql/mysql-connector-java/8.0.28/mysql-connector-java-8.0.28.jar`;库:`jdbc:mysql://192.168.0.108:3306/log`(root/root)。写个单文件 `临时文件/Q.java` 用 `java -cp <驱动> 临时文件/Q.java` 跑。`operation_log` 实测 **19 列**:`id/trace_id/parent_id/op_time/project/module/operation/operator/input/output/result/error/elapsed_ms/level/house_sn/well_sn/tl_sn/host/create_time`(`parent_id`=父子调用串联、`create_time`=入库时间、`level`=日志级、`host`=来源主机)。常用查询:
- 最近 N 条:`SELECT id,op_time,project,module,operation,result FROM operation_log ORDER BY id DESC LIMIT 20`
- 拉一次操作跨端时间线:`... WHERE trace_id='xxx' ORDER BY op_time`
- 只看失败:`... WHERE result='失败' ORDER BY id DESC LIMIT 20`(读对应 input+error)
- 按模块/排除噪声:`... WHERE module<>'HTTP' ...` 或 `WHERE module='界面点击'`
- 终端里中文显示乱码是控制台编码问题,库里是正确 UTF-8。

## 六、编译环境(若需本地编译)
- **C#/.NET(当前任务 operate/control/front 用这套)**:目标框架 `net6.0-windows`(仅 `control/IvfTl.AutoFocus.Tests` 为 net8.0;本机装 .NET 8.0.x SDK,可编 net6.0)。解决方案:`ivf_tl_operate_2.0/ivf_tl_Operate.sln`(operate,含 control 子树)/ `ivf_tl_operate_2.0/control/ivf_tl_Control.sln`(control 类库)/ `aivfo-front-manament-2.0/ivf_tl_Manage.sln`(front)。编译 `dotnet build <csproj|sln> -c Debug|Release`;**真机/连内网必须 Release**(Debug 的 `#if DEBUG` 覆写服务器地址到 test-gateway 外网,见 operate 全景 §十 / 待验证清单 M-07);operate.exe 正运行会锁 DLL 报 MSB3021,先关 operate 再编。
- **Java 微服务**:JDK 11.0.25 + Maven 3.9.9 @ `C:\TLData\tools`;本地仓库 `C:\TLData\tools\maven-repo`。Nexus 私服凭证已配在 `~/.m2/settings.xml`(admin);详细环境/账号见 `项目文档/开发环境/环境与账号清单.md`。
- ★Java 本地多仓构建顺序:先 `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)一起提交到该仓库。

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

##  九、工作方式约束
- 真机已连接,所有测试/验证由你自己跑完,不要中途让我配合(不要让我点界面、看数据、启停程序/进程)。
- 业务不清楚时,查合并前的老代码和现有系统的代码自行判断,不要让我确认。
- 遇到问题穷尽手段自己定位结论,默认我不在旁边盯着。