Domů Procházet Nápověda
Registrovat se Přihlásit se
huangjie
/
aivfo-tl-3.0
1
0
Rozštěpit 0
Soubory Úkoly 0 Pull Requesty 0 Wiki
Strom: e0e986671c
Větve Značky
aivfo-tl-3.0
/
CLAUDE.md

CLAUDE.md 9.0 KB
Historie Surový

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 定位;调试级(串口/相机原始细节)走本地文件、按模块/按舱热开。

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 关键列:id/trace_id/op_time/project/module/operation/operator/input/output/result/error/elapsed_ms/house_sn/well_sn/tl_sn。常用查询:

  • 最近 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。

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

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

八、临时文件

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

九、编译与重启

  • 但凡是你需要编译后重启、编译前关闭停止进程、关闭软件，你自己执行，不能让我重启、关闭软件。