aivfo-tl-3.0/项目文档/给新机Claude的开场文案.md

工作交接 — 时差培养箱合并改造项目

（更新于 2026-06-18；续接用，新机/新会话开场即读本文）

〇、沟通约定（最先生效）

• 全程用中文回复。
• 代码检索/理解优先用 codegraph（项目根已 init .codegraph/；MCP 工具 codegraph_explore / codegraph_node，或 shell codegraph explore "..."），再退而 grep/读文件。
• 每完成一步必回写进度（见第四节），这是硬纪律。

一、先读这些恢复上下文（按顺序）

1. 时差项目源代码/项目文档/进度/进度状态.yaml ← 总入口(机器可解析断点;含"下一步""紧前阻塞")
2. 时差项目源代码/项目文档/进度/交接卡.md（拉到最后一段 = 最近一次工作）
3. 时差项目源代码/项目文档/进度/工作计划表.md（M0–M7 任务级主表;⚠=代码完成待验证）
4. 时差项目源代码/项目文档/进度/待验证清单.md（V-001~V-121，真机照单逐条验）
5. 时差项目源代码/项目文档/进度/SQL与代码一致性核对报告.md 需要全局背景再读 时差项目源代码/项目文档/需求.md（总纲，勿删）。 ⚠ 忽略 项目部署/ 目录(环境/账号信息不准确，以用户实际部署为准)。

二、文档地图（项目文档/ 下，按需深入查）

• 需求.md 总纲。
• 需求文档/01-14 各专题方案：01架构合并 / 02业务闭环 / 03自动对焦 / 04微服务改造 / 05通讯监控 / 06配置统一 / 07UI改造 / 08影响范围 / 09计划验收 / 10术语契约 / 12计划表+对焦数据 / 13硬件访问层接口 / 14全量操作日志。
• 计划/ M1–M5 各里程碑子计划（工作计划表说"子计划另出"即指此）。
• 进度/ 上面第一节那 5 个续接文件 + 进度数据.js / 监控面板.html(实时面板)。

★ 排障利器：全量操作日志（M8，设计见 14 号）

• 系统在做"全量操作日志"：C#/Java 所有操作记 谁/功能/输入/输出/报错/结果，经 Kafka→日志微服务 aivfo-oplog→log 库 operation_log 表，跨端共用 trace_id。
• 排障第一步：拿到 trace_id，把一次操作的跨端日志拉成时间线，找 result=失败 那条读 input+error 定位；调试级(串口/相机原始细节)走本地文件、按模块/按舱热开。
• 现状：设计已定(14 号)、M8 待实现；实现后这是定位问题的首选，别再靠读源码猜。开发规约：以后新写的 C#/Java 代码都要加埋点(强制，见 14 §13)。

三、当前断点（一句话现状）

• 环境已就绪：7 容器中间件(含 MQTT tl-mqtt)、7 库、对焦数据层迁移已应用(V-001)。
• 后端 4 微服务真机起通并注册 Nacos：gateway 10010 / business-pc 10020 / data-transmission 10030 / tl-control 10050。C# operate 真机编译通过、配置本机化(127.0.0.1)、可启动。
• 真机断点：operate 进舱室调试(工程师密码 tl13579)提示"串口失败"(下位机串口/COM 待排查)。
• 进行中：全量操作日志需求(M8)——设计已定(14 号)、项目文档已更新，下一步出实现计划(writing-plans)；串口失败排查暂挂。

四、工作进度实时记录（硬纪律）

• 每完成一步(或暂停时)回写 项目文档/进度/ 的：进度状态.yaml + 交接卡.md(追加勿覆盖) + 进度数据.js(让 监控面板.html 实时反映)。
• 真机验证阶段同步回写 待验证清单.md 对应 V-xxx；任务状态变化时回写 工作计划表.md。

• 设计做了改动、方案做了改动后，“项目文档”相关文件要实时更新，防止文档滞后与代码不一致。

  五、编译环境（若需本地编译）

• JDK 11.0.25 + Maven 3.9.9 @ C:\TLData\tools；本地仓库 C:\TLData\tools\maven-repo。

• Nexus 私服凭证已配在 ~/.m2/settings.xml（admin），401 已解除。

• ★本地多仓构建顺序：先 mvn -DskipTests install 装 aivfo-framework(底座，提供 com.aivfo SNAPSHOT)，再编译依赖它的各微服务，否则报 Could not find artifact。

• bash(Git Bash)进含中文路径目录用正斜杠绝对路径，如 /c/TLData/trae_projects/Project_TL/时差项目源代码/...。

六、Git 状态（改动可追溯/可回退）

• 为了代码安全，“时差项目源代码”下的源代码，项目文件 代码提交到git仓库, 仓库地址 http://git.aivfo.com:36000/huangjie/TL3.0 账号 huangjie 密码huangjie123456