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。
• 第二节(开机先读)与第三节(回写协议)是硬纪律,每次都执行。

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

当前任务: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)一起提交到该仓库。

八、临时文件

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