# 项目背景与上手指南（新会话第一篇先读我）

> 给接手本任务的 Claude:**先完整读这一篇**,再按下面「阅读顺序」去读仓库里的详细文档。本篇是总入口,不重复抄细节——细节都在被指向的文档里。
> 同一仓库,你能直接读到下面提到的所有文档与代码。仓库根:`aivfo-tl-3.0/`。

---

## 一、这是什么项目

**时差培养箱(IVF 胚胎培养)软件系统**。一句话:培养箱 7×24 自动培养胚胎,定时拍照记录胚胎发育延时影像,数据上传服务器供医生查看打分。

系统有**三个 C# / .NET 6 桌面程序 + 一套 Java 微服务后端**:

| 程序 | 目录 | 角色 | 跑在哪 |
|---|---|---|---|
| **operate** | `ivf_tl_operate_2.0/` | 培养箱**本机操作界面**(舱室/调试/对焦/配置/监控) | 培养箱机器上 |
| **control** | `ivf_tl_operate_2.0/control/`(现为类库,被 operate 进程内托管) | **机器驱动大脑**:串口控制下位机、拍照、换气补气、自动对焦、图片上传 | 培养箱机器上 |
| **front** | `aivfo-front-manament-2.0/` | **管理端/医生工作站**:患者管理、胚胎打分、出报告 | 医生办公电脑 |
| Java 微服务 | `aivfo-gateway/`、`aivof-tl-control/`、`aivfo-business-manage/`、`aivfo-data-transmission/`、`aivfo-oplog/` 等 | 网关/业务/数据传输/操作日志 | 服务器(本机开发时跑在 108 + 本机) |

> 历史:做过一次"三项目合并"(M0–M8)。**被合并进 `ivf_tl_operate_2.0` 解决方案的三个原始项目是:operate(→`ivf_tl_Operate`)+ control(→`control/` 子树)+ AutoFocusTool 自动对焦工具(→`control/IvfTl.AutoFocus` 对焦库)**;合并把 control 的代码塞进了 operate 进程内托管运行,把 AutoFocusTool 重构成 control 的对焦类库。**注意:front 不在本次合并内**——它始终是独立的第四个桌面程序(`aivfo-front-manament-2.0/`),只是同属一个产品。**合并代码完成,但真机验收整体未做、且有 operate 侧功能降级遗留**(见 `进度/待验证清单.md` M-01~M-07 与 `需求文档/操作端逻辑与配置全景.md` §八);旧文档在重建时清空归档。

---

## 二、当前任务(你要做的)

**operate / control 双进程拆分。**

把 control 从 operate 进程内**剥离回独立常驻进程**,核心诉求:

- **control 必须 7×24 常驻驱动机器**(胚胎培养不能中断),哪怕 operate 关了它也要继续跑(继续采集/换气/拍照/上传)。
- **operate 只是 UI**,用户想开就开、想关就关,关掉不能影响 control。
- **用户/装机视角仍是一个软件**:只装、只启动 operate;control 由 operate 在后台自动拉起,用户无感。绝不能回到"手动开两个 exe"。

为什么要拆:合并成一个进程后,operate 关 UI 进程退不掉(control 的常驻线程撑着→残留进程)、重开又起一套 control 抢串口;监控页只能同进程直读、内容不全;调试时串口被 control 占用。这些都是单进程塞两个生命周期相反的东西导致的。

**范围红线**:**只动 operate / control,front 完全不动**。control 的采集/换气/对焦/上传**业务逻辑零改动**,只动"进程边界 + 进程间本地通信"。

---

## 三、已定的架构(关键决策,已与用户逐项确认,勿推翻重议)

1. **进程模型**:operate / control 两个独立进程。代码仍在一个解决方案里管理,装机是一个软件。
2. **进程间通信**:**control 开本地 HTTP 小服务**(`127.0.0.1:38080`,.NET 自带 HttpListener),operate 调它的接口读状态/借串口/停止。
3. **谁拉起 control**:**operate 按需拉起**(登录后探活,不在则 Process.Start)+ **operate 开机自启** + **control 用 Mutex 保证全程单实例**。control 是管理员、operate 也是管理员,拉起不弹 UAC。
4. **调试让串口**:operate 调 `/serial/pause`+`/serial/resume`,**复用现有 HouseGate 闸门**(现是同进程内,改成跨进程喊),control 不死、其他舱照常、调完自动恢复。
5. **整体停止 control**:control 起来后默认**不能随便停**(防误操作中断培养)。只有监控页一个**受护栏按钮**(二次确认 + 工程师口令 `tl13579`)→ `/shutdown` 安全停机。
6. **监控页补全**:operate 的服务监控页改为跨进程读 control 的 `/status`,补三块:各舱实时活动(拍照/对焦/换气)、后台线程健康/心跳、串口借用/占用状态。
7. **分三阶段实现**:① control 独立进程骨架(能起/能连/operate关了续命)② 监控补全 + 调试借串口 + 受护栏停止 ③ 清理老壳 + 装机收尾。

---

## 四、阅读顺序(按序读完即可开工,不靠任何对话记忆)

1. **本篇**(项目全貌 + 当前任务 + 架构决策)。
2. `项目文档/进度/进度状态.yaml` —— **轻断点**:现在干到哪、下一步、阶段概览。
3. `项目文档/进度/工作计划表.md` —— 阶段真实状态 + 续接指南。
4. `项目文档/需求文档/specs/2026-06-22-operate-control-双进程拆分-design.md` —— **架构设计全文**(9 章:背景/决策/拓扑图/HTTP 接口契约/生命周期/监控补全/老壳处置/分阶段/风险)。**动手前必读。**
5. `项目文档/开发计划/2026-06-22-阶段1-control独立进程骨架.md` —— **阶段1 实现计划**:7 个 bite-sized 任务,每步带完整代码/命令/预期。**照着做。**
6. `项目文档/需求文档/control-逻辑与配置全景.md` —— **现状基线/接手全图**:control 全部逻辑(采集主循环/服务器双向交互/启动硬件层/缓冲瓶/数据库)+ 全部配置参数,均标 `file:line`。改 control 前查它。
7. `项目文档/进度/交接卡.md` 末尾 —— 最近一次工作细节。
8. `项目文档/进度/待验证清单.md` —— 真机门控项。
9. `CLAUDE.md`(仓库根)—— 项目铁律:全程中文、用 codegraph 检索、回写协议、编译/重启自己执行等。

---

## 五、技术栈与环境要点

- **桌面端**:C# / .NET 6(`net6.0-windows`)/ WPF。MVVM(CommunityToolkit.Mvvm)。JSON 用 Newtonsoft.Json。单测用 xUnit(见 `control/IvfTl.AutoFocus.Tests`)。
- **构建**:`dotnet build`;JDK11 + Maven3.9.9 @ `C:\TLData\tools`(Java 微服务用)。operate/control 解决方案:`ivf_tl_operate_2.0/ivf_tl_Operate.sln` 与 `control/ivf_tl_Control.sln`。
- **代码检索**:仓库已建 **codegraph 索引**(`.codegraph/`)。理解/定位代码**优先用 codegraph**(`codegraph_explore` / `codegraph_node`,或 shell `codegraph explore "..."`),别上来就 grep/读文件。增删文件后跑 `codegraph sync`。
- **运行依赖**:control 启动要连本机 gateway(`127.0.0.1:10010`)登录、连 108 的 MySQL/Kafka/MQTT/Nacos。起微服务集群:`bash 项目文档/开发环境/start-all.sh`。详见 `开发环境/`。
- **权限**:operate / control 都要求 `requireAdministrator`(串口/相机/盘符)。

---

## 六、已知坑(务必知道,踩过的)

1. **operate 有两个 build 行为不同**:Debug 版 `AppData.cs:91-111` 有 `#if DEBUG` 块**顺序覆盖**服务器地址,**最终生效写死成测试网关 `test-gateway.aivfo.com:36000` / `211.149.139.131`**(中途出现的 192.168.0.207 等会被后续行覆盖,既非最终值也不是公网)——**真机/本机验证必须用 Release 版**(走 App.config 的 127.0.0.1/108)。
2. **operate / control 是管理员进程**:非交互 shell 里 RunAs 提权可能弹不出(杀不掉/起不来高权限进程)。开关软件相关操作见 CLAUDE.md 第九节。
3. **control 启动依赖一堆运行时文件**:`DependFile`(SQLite 库/相机原生 DLL)、App.config(连接+换气参数)。拆独立进程部署时这些要随 control.exe 到位,否则 StartRun 失败。清单见 control 全景文档 §八。
4. **两套并行的串口/相机栈**(旧 `ivf_tl_Entity/ComEntitys` + HAL 包装栈 `IvfTl.Hardware`),是迁移期现状,排障要分清当前走哪条。详见全景文档 §六。
5. **本地 SQLite 多数表须预置**:`aivfoTL.db` 须预置文件;但 `house_autofocus_calibration` 一表例外,由 `DBService` 启动时 `CodeFirst.InitTables` 自动建(`CREATE TABLE IF NOT EXISTS`),勿当缺表 bug 排查。
6. **老壳 `ivf_tl_ControlTest`**:是合并前 control 的独立 exe,但混了测试代码、命名乱(三命名空间)、已被 operate 旁置不引用。**别改造它**;新 control 启动器基于干净的 `ivf_tl_Control` 类库新建(阶段1),老壳阶段3 退役删。

---

## 七、开工方式(用户已定)

- **子代理驱动开发**(superpowers:subagent-driven-development):每个 Task 派全新子代理实现 + 两阶段审查(spec 合规 → 代码质量),主线收结论。
- **先建 feature 分支**(勿在 main 直接改代码)。
- **阶段1 的 Task1–6 是纯编码**(可独立完成),**Task7 是真机验证**(真机已连,由 Claude 自主跑完、无需用户在场/配合;仅「水平电机」「垂直 Z 电机」运动范围需守安全区间,参考 `临时文件/相关参数.html`,其余下位机控制无风险)。
- 每完成一步按 CLAUDE.md 第三节回写:`进度状态.yaml`(断点)+ `交接卡.md`(追加)+ 工作计划表 + 进度数据.js。提交边界 = 文档已同步。

---

## 八、当前进度(交接时点)

- ✅ 需求梳理(control 全景 + 全配置参数)
- ✅ 架构设计(双进程方案,9 章设计文档)
- ✅ 阶段1 实现计划(7 任务,可执行)
- ✅ 文档体系重建(本篇 + 总纲 + 续接三件套 + CLAUDE.md 对齐)
- ☐ **阶段1 代码实现 —— 这是你要开始的**(从开发计划阶段1 Task1 起)
- ☐ 阶段2 / 阶段3(待阶段1 完成后拆计划)