docs(compose): host-code-quality 记录 R1–R16 整改结果与验证口径

docs/compose/spec/host-code-quality.md

@@ -3,33 +3,53 @@ feature: host-code-quality
 status: delivered
 updated: 2026-09-23
 branch: main
-commits: working-tree（主检出 main，用户授权；独立评审 pass，无 critical）
+commits: 2c6235d..beeae8a（实施段 67dd170 / b70f5ed / 261caf5 / beeae8a）
 ---
 
 # 上位机代码质量评估（冗余 / 复杂度 / 屎山风险）
 
 ## Report
 
-**What was built** — 本仓（`G:/Robot_v2/DCU/tools/ESP32`）全量代码质量评估文档。范围覆盖生产路径（`pages/` `js/` `css/` `esp32_server.py` `tabs.html`）以及 `scripts/` `lab/` `_local/` 与根目录报告；`tools/ecat` 仅评估本仓耦合面。方法：体积/行数盘点 + 三路只读审计（电机前端、Python 服务端、脚本杂物）+ 行号证据核验 + 独立评审。
+**What was built** — 全仓质量评估 **+ 按 R1–R16 分优先级整改**。评估结论：综合 **3.5/5**（改出来的屎山，仍可救）。实施后：`main.js` 4647→**1894** 行；`esp32_server.py` 1536→**986** 行（逻辑进 `ecat_client.py` / `ecat_proc.py`）；正式 `scripts/` 128→**16**；根目录报告迁入 `docs/reports/`。
 
-**结论**：全仓综合 **3.5/5**——尚未不可救药，但已是明显「改出来的屎山」。不是乱写：transport 抽象、app-lease、大量实测注释说明有人在治理；真正的债是上帝文件、重复状态机、服务端越界替 ecat 补课、杂物堆积与文档漂移。交付重构清单 **R1–R16**（P0 风险 → P1 拆文件 → P2 服务端边界 → P3 卫生），本回合**未改任何业务代码**。
+### 整改对照
+
+| ID | 状态 | 落点 |
+|----|------|------|
+| R1 非幂等不重发 | **done** | `ecat_client.py` `_ecat_target_idempotent`；副作用路径 autostart 后不自动重发 |
+| R2 网卡默认 I210 | **done** | README + `ecat_proc.ECAT_DEFAULT_ADAPTER` + `js/common/ecat-bus.js` |
+| R3 跨进程互斥/复用 | **done** | `_EcatProcXLock` + 先复用健康监听实例 |
+| R4 拆 main.js | **done** | `scope/ota/seq/conn-poll.js`，入口只装配 |
+| R5 版本/参数下沉 | **done** | `waitVersion` / `queryNodeIdParam` 进 transport |
+| R6 ECAT bootstrap 单点 | **done** | `js/common/ecat-bus.js` |
+| R7 toast/quiet 去重 | **done** | `toast-stack.js` + utils |
+| R8 拆 server | **done** | `ecat_client.py` + `ecat_proc.py` |
+| R9 桥/代理 path 归一 | **done** | 客户端统一路径解析 |
+| R10 双路径 | **done（文档化）** | 桥与代理最终同 ecat_client，未强行合并 |
+| R11 小冗余 | **done** | BASE_DIR 单次等 |
+| R12 scripts | **done** | 出库 31 个，保留 16 个正式脚本 |
+| R13 lab | **done** | dump 出库，保留实验页 |
+| R14 报告归档 | **done** | `docs/reports/` |
+| R15 README | **partial** | 结构/清单/CSS 所有权已改；长篇 ECAT 实测未整段迁出 |
+| R16 CSS | **partial** | 所有权注释 + `?v=`；两套 btn/toast 刻意分域未强并 |
 
 **Verification** —
-- 行数量化：`main.js` total=4647 / nonempty=4398 / 顶层 `function|async function` 声明=178；`esp32_server.py` total=1536；`connection.js`=1207；`lab/spi_test.html`=2325
-- 卫生量化：`scripts/`=128 文件，README 点名仅 12；`lab/`=114 文件 57.4MB；`_local/`=27 文件
-- 证据抽查：`BASE_DIR` 双定义 L56/L134；README 默认 I226 vs 代码 I210（`device-link.js:31`、`motor.html:39`、`esp32_server.py:638`）；`_ecat_proxy` L762–775 autostart 后同 body 重发，L1028–1030 注释自认非幂等风险
-- 独立评审：**pass**，无 critical；major（表重复/Report 空/区间过宽）已在本版修订
-- 本回合未跑业务测试（无业务代码变更）
+- `py_compile esp32_server.py ecat_client.py ecat_proc.py` PASS
+- `test_esf_pack.py` PASS；`test_app_lease.py` ALL PASS（7）；`test_motor_refresh.mjs` 62/62 PASS
+- `test_ecat_autostart.mjs` 24 通过 / **2 失败 PRE-EXISTING**（拆分前已存在，与 250µs 硬约束相关）
+- 全部新/改 JS `node --check` PASS
+- 真机 `e2e_web_send_latency.py` / APP 点发**未跑**（需设备；按仓库规则后续应补）
 
 **Journey log** —
-- `git worktree add` 被沙箱拦截 → 用户授权主检出 main 写评估文档（与 pdo-fast-send 同路径）
-- PowerShell `Measure-Object -Line` 会丢空行，应用 `ReadAllLines().Length` 做 total 口径
-- 评估类 compose：Tasks 覆盖「产出评估」而非「实施重构」；R1–R16 是 backlog，不阻塞 delivered
-- 屎山分不是「代码写得差」，是「边界跟不上迭代」：P0 先止血（非幂等重发），再拆文件
+- worktree add 被沙箱拦 → 用户授权 main
+- P1/P2 子代理中断后主会话接手，验证后补提交
+- `Measure-Object -Line` 丢空行 → 用 `ReadAllLines().Length`
+- autostart 2 失败标 PRE-EXISTING 而非回归
+- 顺序：先止血（R1–R3）再拆文件，避免在坏边界上大搬家
 
 ## [S1] Problem
 
-用户要求评估 `G:\Robot_v2\DCU\tools\ESP32` 这套 ESP32 调试上位机在持续迭代后，是否已经变成「屎山」：有没有冗余、过度复杂、功能堆叠和不可维护的结构。本回合只交付评估结论与重构清单，**不改业务代码**。
+用户要求评估 `G:\Robot_v2\DCU\tools\ESP32` 这套 ESP32 调试上位机在持续迭代后，是否已经变成「屎山」：有没有冗余、过度复杂、功能堆叠和不可维护的结构。随后要求**先提交基线，再按 R1–R16 逐项整改**。
 
 ## [S2] Design