docs: CLAUDE.md 瘦身——§五排障细节拆出独立文档 + 新增§3.5任务收尾提醒/clear

降每会话固定 token 开销:CLAUDE.md 97→82 行(净省 15 行)。
- §五 全量操作日志的细节(两层日志/热开关/入库/查库/19列/SQL)整段搬到
  项目文档/排障/全量操作日志-排障指南.md,正文只留"能力+排障第一步"2行指路
- §四 文档地图补 1 行指向新文件
- 新增 §3.5:每完成任务回写完文档后,主动提醒用户 /clear(软提醒,状态已落盘不丢)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CLAUDE.md

@@ -9,6 +9,7 @@
 - 代码**理解**优先用 `codegraph_explore` —— 一次返回相关符号源码 + 调用链。
 - 增删改文件后跑 `codegraph sync`(增量同步索引,保持最新);仅在索引异常/需全量重建时才用 `codegraph init`。
 - 第二节(开机先读)与第三节(回写协议)是**硬纪律**,每次都执行。
+- 我不太懂技术，所以和我沟通以及输出的文档尽量大白话一些，当然前提是claude能看懂，因为都是靠claude编程。
 
 ## 二、开机先读这些(无缝衔接引擎,按顺序)
 > **当前任务:operate / control 双进程拆分**(旧任务 M0-M8 三项目合并:**代码完成、真机验收整体未做、有 operate 侧降级遗留〔见 `进度/待验证清单.md` M-01~M-07〕**;旧文档已清空,本体系为新任务重建)。
@@ -44,6 +45,11 @@
 一个任务做完、**准备 `git` 提交时**,先把上表中该任务牵动的**所有**文件一次性同步到位,**再提交**。
 **「git 提交 = 文档已和代码对齐」** —— 不允许只提交代码而不更新文档。
 
+### 3.5 任务收尾主动提醒 /clear(省 token)
+每完成一个任务、**回写完文档(并提交)后**,主动对用户说一句:
+**"✅ 这步完了、文档已同步,断点都落在 `进度状态.yaml`/`交接卡.md` 里,建议现在 `/clear` 再继续下一步(省 token)。"**
+理由:状态已落盘,清空对话不丢任何东西,下个会话照常续接。这是**提醒、非强制**——由用户决定清不清。
+
 ## 四、文档地图(`项目文档/` 下,按需深入查)
 > 当前任务 = operate/control 双进程拆分。旧任务(M0-M8)文档已清空。
 - `项目背景与上手指南.md`   ★**新会话第一篇总入口**(项目全貌/当前任务/已定架构/技术栈/已知坑);开机先读顺序见第二节。
@@ -53,32 +59,11 @@
 - `系统业务流程详图.html`  ★开发上手总文档(单页可视化,浏览器打开):汇总背景/架构/两份全景/阶段1计划/降级登记,读一篇即懂「为什么改→改成什么样→现在什么样→接下来改什么→怎么上手」。
 - `进度/`              续接回写文件(进度状态.yaml=断点 / 工作计划表.md=阶段状态 / 交接卡.md=追加历史 / 待验证清单.md=真机门控)+ `进度数据.js` / `监控面板.html`(实时面板)。
 - `开发环境/`            `服务器测试环境.md`——**当前实际中间件部署(108 原生环境,权威·编译部署先查这里)**;`连接配置清单-换服务器必读.md`——换服务器逐项改 IP/端口/账号;`环境与账号清单.md`——本机环境/版本/账号凭证/Docker 备用环境排障记录;`start-all.sh`(一键起微服务集群)。
+- `排障/`              `全量操作日志-排障指南.md`——全量操作日志的细节(两层日志/热开关/入库/查库/SQL),从 §五 拆出,需排障时再读。
 
-## 五、排障利器:全量操作日志(运行期能力,旧任务遗留、仍有效)
-- 系统做了"全量操作日志":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#/Java 全操作记 谁/功能/输入/输出/报错/结果,经 Kafka→`aivfo-oplog`→`log` 库 `operation_log` 表,跨端共用 `trace_id`。**排障第一步**:拿 `trace_id` 拉跨端时间线,找 `result=失败` 那条读 input+error。
+- **细节(两层日志 / 热开关配置 / 怎么入库 / 怎么查库 / 19 列字段 / 常用 SQL)→ 读 `项目文档/排障/全量操作日志-排障指南.md`,需要排障时再看。**
 
 ## 六、编译环境(若需本地编译)
 - **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 再编。

项目文档/排障/全量操作日志-排障指南.md

@@ -0,0 +1,28 @@
+# 排障利器:全量操作日志(运行期能力,旧任务遗留、仍有效)
+
+> 这是从 `CLAUDE.md §五` 拆出来的细节文档。CLAUDE.md 正文只留"有这能力 + 排障第一步"的指路,**需要排障时再读本文件**。
+
+- 系统做了"全量操作日志":C#/Java 所有操作记 谁/功能/输入/输出/报错/结果,经 Kafka→日志微服务 `aivfo-oplog`→`log` 库 `operation_log` 表,跨端共用 `trace_id`。
+- **排障第一步**:拿到 `trace_id`,把一次操作的跨端日志拉成时间线,找 `result=失败` 那条读 input+error 定位;调试级(串口/相机原始细节)走本地文件、按模块/按舱热开。
+
+## 一、两层日志(互补,别只看一层)
+- **动作层**(`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` 一键全关;文件不存在=全开(开发默认)。生效后该程序日志有"操作日志配置已热加载"。
+
+## 二、怎么让日志真入库(运行期前置)
+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 不入库**(这是"没记录"的最常见原因)。
+
+## 三、怎么查库(本机无 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。