Etusivu Tutki Apua
Rekisteröidy Kirjaudu sisään
huangjie
/
aivfo-tl-3.0
1
0
Fork 0
Tiedostot Ongelmat 0 Pull-pyynnöt 0 Wiki
Haara: main
Haarat Tagit
aivfo-tl-3.0
/
项目文档
/
项目背景与上手指南.md

项目背景与上手指南.md 9.4 KB
Pysyvä linkki Historia Raaka

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

给接手本任务的 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 完成后拆计划)