文档源码审核报告.md 16 KB
M0-00 · 文档源码一致性审核报告
审核员：文档审核员（Claude Opus 4.8） · 日期：2026-06-17 审核对象：
项目文档/需求文档/（00-需求总览.md 总纲 + 01–12 子文档）对照 5 个 Java 微服务 + 2 个 .NET 客户端 + autofocustool 源码 审核方式：codegraph MCP（codegraph_explore / codegraph_node）核对符号与文件:行号，辅以 Grep 全局搜索 性质：只读审核，未修改任何源码
维度① 文档-源码一致性（差异清单）
逐项核对 04/03/00-需求总览.md 中"现状 / 文件:行号 / 类名方法名"断言。结论：抽查项 100% 命中，行号精度极高（多数误差 0–2 行），无方法/类不存在的硬错误。
| 文档位置 | 文档声称 | 源码实际 | 影响改造 | 建议 |
|---|---|---|---|---|
| 04 §3/§4.1 | ImageReceiveCompleteEventHandle.java:120-149 focusPointUpdate 整方法 |
方法在 :120-148（结尾 148，doc 写 149 含闭括号，可接受） | 否（删除目标，定位准确） | 行号几乎完美，可直接照删 |
| 04 §3 :143-144 | 选最高分→取位置两行 | :143 max(Comparator.comparing(PictureDAO::getImageScore)).get()；:144 setClearPosition(max.getShootingPosition()) |
否 | EXACT，无需修正 |
| 04 §3/§4.1 :96 | PictureProcessingImpl.java:91-104，:96 JNA getscore 打分 |
方法签名 :91（@Override :90），picture.getscore(...) 在 :96 |
否 | EXACT |
| 04 §4.1 :331 | PictureManage.java:331-355 cutAutofocus 私有方法 |
:331 private CropPictureInfo cutAutofocus(...)，方法体至 :355 |
否 | EXACT。⚠️见下注：存在两个 PictureManage.java |
| 04 §4.1 | AutofocusFeign.java:25-66 整类，唯一调用方 focusPointUpdate |
类在 :25，文件 66 行；codegraph 确认仅被 ImageReceiveCompleteEventHandle 引用 | 否 | "唯一调用方"断言成立，可整类删 |
| 04 §4.1 :55 | CLOUD_SERVER_FOCUS_ALARM 引用随删 |
:55 AlarmTypeKeyEnums.CLOUD_SERVER_FOCUS_ALARM.getValue() |
否 | EXACT |
| 04 §6.2 | ResourceServiceImpl.java:462-481（business-manage），:470 拼分数、:476 max(imageScore) |
方法 :462-481；:470 setImageName(...{}_{}_{}_{}..., getImageScore())；:476 max(Comparator.comparing(A->A.getImageScore())).get().setHighestScore(true) |
是（NPE 点1） | EXACT，核心断言成立 |
| 04 §6.2 | PictureDAOServiceImpl.java:179 getImageScore().compareTo |
:179 c1.getImageScore().compareTo(c2.getImageScore())，所在方法 getFocusBestPicture 起于 :173（doc §6.2 表内写 430-434→179，430-434 是 business-manage 包装层，179 是 data-transmission 实现层） |
是（NPE 点2） | EXACT。两层链路描述准确 |
| 04 §6.2 调用链 | …→ PictureDAOServiceImpl.getLastAutofocusPictureByEmbryoId:241 |
:241 方法存在 | 否 | EXACT |
| 03 §1 :105 | Imaging/Sharpness.cs:105 ÷mean 一次 |
:105 return sumSq / n / mean;，且 :99-104 注释明确记录"原 mean² 选错、改 mean 后峰落 92000" |
否（移植算法依据） | EXACT，注释佐证算法权威性 |
| 03 §1 :181 | Calib/CalibrationEngine.cs:181 CalibrateWell 四步标定 |
:181 public WellCalib CalibrateWell(...)；CoarseFocus/ScanForCenter/ExposureMeter/精对焦四步齐全（:339/:149/:222） |
否 | EXACT |
| 03 §1 移植范围 | "不移植 SelfTest/SmokeTest/Calibrate/CalibWindow 等测试外壳" | autofocustool 下 SelfTest/SmokeTest/Calibrate/CalibTest/ToPng 目录实际仍在 | 否（措辞辨析） | 非错误：03 写的是"不移植"（未来动作）≠"已删"。见下方专项说明 |
| 00-需求总览.md §1.1 | 子系统清单：data-transmission=OpenCV(JNA)/4 表、tl-control=17 表、business=25 表等 | 目录结构、模块分层（controller/service/manage/mapper/...）与表数描述一致，5 个含 lanucher 的微服务均存在 | 否 | 一致，可信 |
⚠️ 关键辨析：autofocustool"已删/仍在"出入
任务点名"文档说已删、实际仍在"。核查结论——需求文档本身没有说错：
- 03 §1 用词是"不移植"（指移植阶段不带这些测试外壳），并非"已删"。目录仍在是预期的。
- 真正声称"已删"的是 autofocustool 自带的内部文档（非本审核范围的需求文档）。此出入需求文档 12 已主动捕获并记录：
12 文档 :142明写"autofocustool 文档称 SelfTest/SmokeTest 等已删，实际仍在"，12 :299进一步定调"按只删高置信度约定保留这些子工程"。 - 即：这是 autofocustool 内部文档 vs 实际的偏差，需求文档已替读者校准。不构成需求文档的可信度问题，反而说明审核机制有效。
注：两个同名 PictureManage.java（潜在歧义，建议补限定）
PictureManage.java 存在两份：
aivfo-data-transmission/.../manage/image/PictureManage.java（本轮删 cutAutofocus 的目标）aivfo-ai-middleware/.../manage/PictureManage.java（AI 侧，不可误改）
04 文档行号正确，但只写"PictureManage.java"易引歧义。建议：04 §4.1 引用处补全模块路径限定。
维度② 业务闭环完整性（NPE 两点 + 闭环连通性）
NPE 两点——均属实，确认会崩
源码层级核对结论：两处都是先 stream 后 get()、未判 null 的真实消费点，t_picture.image_score 列注释即为"图片分数(如果是对焦才有值)"（PictureMapper.xml:25），删打分后 AUTOFOCUS 行该列全 null。
NPE 点1 属实：
ResourceServiceImpl.java:476（business-manage）copy.stream().max(Comparator.comparing(A -> A.getImageScore())).get()——Comparator.comparing对 null 键调compareTo抛 NPE；即便容错，.get()在空流也 NoSuchElement。一打开对焦预览即崩。断言成立。NPE 点2 属实：
PictureDAOServiceImpl.java:179（data-transmission，被 business-managegetFocusBestPicture:430-434经 Feign 调用）c1.getImageScore().compareTo(c2.getImageScore())——getImageScore()返回 null 时.compareTo直接 NPE。"最佳对焦帧"查询触发即崩。断言成立。
两点的调用链（前端
/getAutofocusPictures→ businessResourceServiceImpl:462→ Feign → data-transmissiongetLastAutofocusPictureByEmbryoId:241）与 04 §6.2 描述一致，已逐跳验证。
闭环连通性
- 02 主闭环 9 节点中，④自动对焦/⑤拍照位置来源/⑧对焦预览三处的源码链路真实连通且与文档描述一致。
- 删打分后的替代数据源（本地标定 → 取代 clearPosition → calPhotoPosition 写
t_house_photograph_setting）路径在 tl-control 侧成立：AutofocusUpdateEventHandle:47 → HousePhotographSettingManageImpl.calPhotoPosition:52的 first/else 分支结构与 04 §4.1 描述吻合（else 分支 :69-88 EXACT）。 - 闭环结论：02 闭环图可作验收清单使用，④⑤⑧高危断点标注准确。
维度③ 影响范围全面性（image_score 等全量消费点 + 08 遗漏）
全局搜 image_score / getImageScore / imageScore / highestScore / AutofocusFeign / focusPointUpdate / pictureScore 于 5 个 Java 微服务 + 2 个 .NET 客户端（排除 target/obj/bin）。
全量消费/生产点清单
| # | 位置 | 类型 | 删打分后影响 | 08/04 是否覆盖 |
|---|---|---|---|---|
| 1 | data-transmission ImageReceiveCompleteEventHandle.java:143 |
消费（max 选层） | 删除目标 | ✅ 04/08 覆盖 |
| 2 | business-manage ResourceServiceImpl.java:476 |
消费（max→NPE） | NPE 崩 | ✅ 04§6.2/08§2b |
| 3 | data-transmission PictureDAOServiceImpl.java:179 |
消费（compareTo→NPE） | NPE 崩 | ✅ 04§6.2/08§2b |
| 4 | data-transmission PictureDAOServiceImpl.java:270 |
消费（orderByDesc(getImageScore)，方法 getAutofocusPictureByEmbryoIdAndBatchNumber，正是 focusPointUpdate 调的查询） |
SQL 排序无 NPE，但全 null 后排序失意义 | ⚠️ 未单列 |
| 5 | data-transmission PictureDAOServiceImpl.java:325 |
消费（pageQueryPictures 末位 orderByDesc(getImageScore)） |
SQL 排序无 NPE，分页次序退化 | ⚠️ 未列 |
| 6 | business-manage ResourceServiceImpl.java:333 |
消费（getPictureByDevelopTime AUTOFOCUS 分支 orderByDesc(getImageScore)，挑"按发育时间的最佳对焦帧"） |
SQL 排序无 NPE，但最佳帧静默选错 | ⚠️ 第三个 business-manage 消费点，04"两处"未含 |
| 7 | data-transmission ReceivePictureCroppingMessage.java:226/229/249/252 |
生产（setImageScore(getScore())） |
写入源，随打分链删 | 部分隐含（04 §4.2 buildUpdateDao），未逐行点名 |
| 8 | data-transmission ReceivePictureMessageInfo.java:179 |
生产（setImageScore） |
写入源，随删 | 部分隐含 |
| 9 | data-transmission PictureDAO.java:126-127 / PictureMapper.xml:25 |
字段/列定义 | 列保留停写 | ✅ 04 §5.4 |
| 10 | business-manage FocusPreviewPictureVO.java:72、:78 highestScore |
DTO 字段 | 失去来源 | ✅ 04 §6.2 |
| 11 | front-management AutoFocusWindow.xaml.cs:149（imageScore 拼文件名）、:152 highestScore（高亮背景）、AutoFocusPictureEntity.cs:11/17 |
.NET 消费 | 高亮失效/文件名带 null | ✅ 04 §5.2/08 §2 (D10) |
| 12 | ivf_tl_control_2.0 HouseBin.cs:2446 GetImageScoreAndSaveImage、AivfoHelper.cs:35（P/Invoke native 打分）、picture.cs:150 image_score |
.NET 本地打分（生产侧） | 机旁端自身也有一套打分/评分 native 调用 | ❌ 04/08 完全未提 |
08 / 04 文档遗漏项（建议补登）
遗漏（中）：第 6 项
ResourceServiceImpl.java:333—— 04 §6.2 标题写"business-manage 有两处强依赖 image_score"，实为三处。第三处是 SQLorderByDesc不会 NPE，但属"最佳对焦帧选层判据"，删打分后会静默选错帧（比 NPE 更隐蔽）。建议补入 04 §6.2 表与 08 §2b。遗漏（中）：第 12 项 ivf_tl_control_2.0 的本地打分路径 ——
HouseBin.cs:2446调 nativeGetImageScoreAndSaveImage，picture.cs含image_score字段。文档把"打分"完全归为云端 data-transmission，但机旁 C# 客户端本身已存在一套 native 评分调用。本轮 control 要并入合并端，需确认这套 .NET 打分与云端打分链的关系（是否同源、是否随本地对焦一并替换/删除）。建议登记为待验证项。遗漏（低）：第 4/5 项 data-transmission 两处
orderByDesc(getImageScore)—— 不崩但排序退化。删打分后建议改排序键为 image_time，否则对焦图列表次序无意义。属低优先，宜在 04 §4.2 备注。
不受影响断言复核：ai-middleware / gateway / aivfo-service 全量搜
image_score/getImageScore无匹配，04 §6.4/§6.5"不受影响"成立。
维度④ D5–D10 决策遗留项建议（基于源码现状）
| 决策 | 议题 | 源码现状 | 建议：可拍板 / 仍阻塞 | 理由 |
|---|---|---|---|---|
| 🔶D5 | calPhotoPosition 去留（A 保留接口改输入源 / B 彻底本地下发） |
HousePhotographSettingManageImpl.calPhotoPosition:52 含 first（初始化）/else（更新）两分支，else 用 clearPosition/mattingSuccessNumber 算对焦起点+CCD 位置并写 t_house_photograph_setting。几何换算逻辑完整、与打分解耦（只吃 clearPosition 这个位置值） |
可拍板选 A | 方法只依赖"最清晰位置"这一输入，本地标定算出的 FocusZ 可直接灌入，改动面小、保留云端可追溯记录。B 需重写下发通道、丢失云端记录，风险大。04 §5 已倾向 A，源码支持该选择。 |
| 🔶D6 | 自适应分辨率基准（Surface 实际分辨率 / Viewbox vs 弹性） | 源码无法给出物理屏参数（硬件信息） | 仍阻塞 | 需真机/硬件规格输入，非源码可定。属外部依赖。 |
| 🔶D7 | 退出屏蔽边界（是否留隐藏管理员退出） | 产品策略，源码不决定 | 仍阻塞（但低风险） | 纯产品决策，可与 UI 改造期一并拍板，不阻塞 M3 微服务改造。 |
| 🔶D8 | 配置分层边界（数据库/本地/无网兜底/权限） | 现状四处分散（App.config / TLSetting / EEPROM / calibration.json，见 02 §2.3），需 06 文档展开 | 仍阻塞（需 06 细化） | 需先盘点现有配置项清单再定分层，建议 M5 阶段前出 06 详案，当前不阻塞 M3。 |
| 🔶D9 | 标定结果回写 EEPROM | autofocustool 现状只写 calibration.json、从不回写 EEPROM（03 §4）；写地址读写错配、0x12 回复长度两版矛盾 |
仍阻塞（硬阻塞，真机前置） | 03 §4/§6 明列写地址必须真机验证、回复长度需实测。无真机无法定，是 R4 上线前置条件。 |
| 🔶D10 | 前端对焦预览去留 | 经 business-manage /getAutofocusPictures 取数（非直连 data-transmission），两处 NPE 已确认（维度②）。front AutoFocusWindow 消费 imageScore/highestScore 已确认 |
半拍板：无论去留，先消 NPE 可立即拍板；"去/留"本身可暂缓 | NPE 修复与"预览是否下线"正交——必须先改判据消 NPE（否则患者详情崩），这点现在就能定。预览最终去留可待 UI 期再议。00-需求总览.md §5 D10 描述与源码完全吻合。 |
小结：D5、D10 可基于源码现状当下拍板（D5 选 A、D10 先消 NPE）；D6/D9 是硬阻塞（依赖真机/硬件）；D7/D8 是产品/盘点性决策，不阻塞 M3 微服务改造。
结论
文档整体可信度评估：高（可作为"对着改"的依据）
- 维度①抽查的 13 个关键断言全部命中，行号误差多在 0–2 行，无方法/类不存在的硬错误。03 的算法依据（Sharpness:105 ÷mean、CalibrationEngine:181 四步）与源码注释互证，可信度尤高。
- 维度②两个 NPE 风险点经源码逐跳确认属实，是真实会崩的消费点，非臆测。04 §6.2 是本轮最重要且最准确的章节。
- 文档具备自我校准能力：autofocustool"已删/仍在"的出入，需求文档 12 已主动捕获并定调保留，说明审核机制有效。
动手前必须先修正/补全的文档点
- 04 §6.2 改"两处"为"三处"：补
ResourceServiceImpl.java:333（getPictureByDevelopTimeAUTOFOCUS 分支的orderByDesc(getImageScore)，静默选错最佳帧）。这是最实质的遗漏，不补会漏改。 - 04 §4.1 PictureManage 引用补模块路径限定：避免与 ai-middleware 同名类混淆误删。
- 04/08 补登 ivf_tl_control_2.0 本地打分路径：
HouseBin.cs:2446 GetImageScoreAndSaveImage/AivfoHelper.cs:35/picture.cs:150 image_score——文档把打分纯归云端，机旁 C# 端的 native 评分调用未提，合并改造需厘清其去留。
新发现 · 需登记为待验证的点
- 【待验证 V1】 ivf_tl_control_2.0 的 native 打分（
GetImageScoreAndSaveImage）与云端 data-transmission 打分链是否同源/同 dll？本地对焦化后这套机旁评分是否一并废弃？（影响合并端硬件访问层与对焦集成） - 【待验证 V2】 data-transmission
PictureDAOServiceImpl.java:270/:325两处orderByDesc(getImageScore)删打分后排序键改 image_time 的回归确认。 - 【待验证 V3】
getPictureByDevelopTime:333（business-manage 第三消费点）改判据后，"按发育时间取最佳对焦帧"的临床展示是否仍正确。
阻塞情况
无 BLOCKED。所有点名抽查的关键文件均真实存在、行号吻合，codegraph 索引可用，审核完整执行。