26 lines
9.9 KiB
HTML
26 lines
9.9 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>host-code-quality.md 修订附录 2026-10-19</title><style>
|
||
body{font-family:-apple-system,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;margin:0;background:#f5f6f8;color:#1d2330;line-height:1.6}
|
||
.wrap{max-width:1180px;margin:0 auto;padding:28px 24px 60px}
|
||
h1{font-size:26px;margin:0 0 6px}h2{font-size:20px;margin:36px 0 12px;padding-bottom:6px;border-bottom:2px solid #d9dee8}
|
||
h3{font-size:16px;margin:22px 0 8px}
|
||
.meta{color:#5b6476;font-size:13px}
|
||
.card{background:#fff;border:1px solid #e1e5ec;border-radius:10px;padding:16px 18px;margin:12px 0}
|
||
table{border-collapse:collapse;width:100%;background:#fff;font-size:13px;margin:8px 0}
|
||
th,td{border:1px solid #e1e5ec;padding:6px 8px;vertical-align:top;text-align:left}
|
||
th{background:#eef1f6;font-weight:600}
|
||
code{font-family:Consolas,Menlo,monospace;font-size:12px;background:#f0f2f6;padding:1px 4px;border-radius:3px;word-break:break-all}
|
||
.sev{display:inline-block;padding:1px 8px;border-radius:10px;font-size:12px;font-weight:600;color:#fff;white-space:nowrap}
|
||
.s0{background:#b3261e}.s1{background:#e8710a}.s2{background:#3367d6}.s3{background:#5f6b7a}
|
||
.kpis{display:flex;gap:12px;flex-wrap:wrap}.kpi{flex:1;min-width:130px;background:#fff;border:1px solid #e1e5ec;border-radius:10px;padding:12px 14px}
|
||
.kpi b{display:block;font-size:26px}
|
||
.issue{background:#fff;border:1px solid #e1e5ec;border-left:5px solid #ccc;border-radius:8px;padding:12px 16px;margin:10px 0}
|
||
.issue.s0b{border-left-color:#b3261e}.issue.s1b{border-left-color:#e8710a}.issue.s2b{border-left-color:#3367d6}.issue.s3b{border-left-color:#5f6b7a}
|
||
.issue h4{margin:0 0 6px;font-size:15px}.issue dl{margin:0;display:grid;grid-template-columns:72px 1fr;gap:3px 10px;font-size:13px}
|
||
.issue dt{color:#5b6476}.issue dd{margin:0}
|
||
.st{white-space:nowrap;font-weight:600}.st-ok{color:#1e7e34}.st-part{color:#b26a00}.st-open{color:#b3261e}.st-na{color:#5f6b7a}.st-old{color:#6b4fbb}
|
||
pre.arch{background:#1f2430;color:#e6e9ef;padding:14px;border-radius:8px;overflow:auto;font-size:12.5px;line-height:1.45}
|
||
a{color:#2457c5}
|
||
.note{font-size:12.5px;color:#5b6476}
|
||
</style></head><body><div class="wrap"><h1>《host-code-quality.md》修订附录 2026-10-19</h1><div class="meta"><a href="../host-code-quality.md">原报告</a> · 核对基线 commit <code>eac3717</code> · 总评审：<a href="../../../review/DCU_DesktopController_专家评审_2026-10-19.html">DCU_DesktopController_专家评审_2026-10-19.html</a></div><div class="card"><b>原报告：</b>上位机代码质量评估（冗余 / 复杂度 / 屎山风险）<br><b>时间线：</b>status: delivered，2026-09-23（27a8fc1 → 83a035c）<br><b>原结论概要：</b>综合约 3.5/5；P0 服务端风险已落地，电机前端回滚后只外提 scope/seq/ota；R4~R7 部分/未实施。<p class="note">原文件保持不变；本附录逐条记录其结论在当前代码中的状态。</p></div><h2>逐条结论跟踪</h2><table><tr><th>编号</th><th>原结论 / 建议</th><th>当前状态</th><th>证据（文件:行号）</th><th>备注</th></tr><tr><td>HQ-R1</td><td>非幂等不自动重发</td><td class="st st-part">部分修复</td><td><code>ecat_client.py:58-62, 290-299, 418-436</code></td><td>HTTP 代理已遵守；ESF1 快发重试违反同一原则（P-2）</td></tr><tr><td>HQ-R2</td><td>网卡默认 I210</td><td class="st st-ok">已修复</td><td><code>ecat_proc.py:28</code></td><td></td></tr><tr><td>HQ-R3</td><td>跨进程互斥/复用</td><td class="st st-part">部分修复</td><td><code>ecat_proc.py:67-94, 125-140</code></td><td>锁超时/CreateMutexW 失败仍继续执行（P-4）</td></tr><tr><td>HQ-R4</td><td>拆 main.js</td><td class="st st-part">部分修复</td><td><code>js/motor/main.js（3254 行）</code></td><td>仍为上帝文件（M-18）</td></tr><tr><td>HQ-R5</td><td>版本/参数下沉</td><td class="st st-open">仍未实施</td><td><code>—</code></td><td></td></tr><tr><td>HQ-R6</td><td>ECAT bootstrap 单点</td><td class="st st-part">部分修复</td><td><code>js/motor/transport-ecat.js:418-441; js/common/ecat-bus.js:65-75</code></td><td>电机侧仍自算周期并绕过预算（M-6）</td></tr><tr><td>HQ-R7</td><td>toast/quiet 去重</td><td class="st st-open">仍未实施</td><td><code>js/can/send.js:17</code></td><td>CAN 侧还出现 toast 双实例（C-9）</td></tr><tr><td>HQ-R8~R14</td><td>服务端拆分与卫生</td><td class="st st-ok">已修复（大部分）</td><td><code>ecat_client.py; ecat_proc.py; docs/reports/</code></td><td>但 .qoder/.zcode 入库（H-1）</td></tr><tr><td>HQ-R15</td><td>README</td><td class="st st-part">部分修复</td><td><code>README.md:3, 190, 449</code></td><td>个人路径与默认周期描述过时（H-2、H-4）</td></tr></table><h2>相关新问题（详见总评审）</h2><div class="issue s0b" id="P-2"><h4><span class="sev s0">致命</span> [P-2] ESF1 快发在 sendall 成功后出错仍整包重发</h4><dl><dt>模块</dt><dd>主机服务/安全</dd><dt>位置</dt><dd><code>ecat_client.py:247-279</code></dd><dt>现象</dt><dd>_tcp_once 持锁 sendall(body) 后读 8 字节 FSOK；recv 超时/断连抛异常时 attempt 0 会 continue，attempt 1 再发同一 body。与同文件非幂等不重发原则（_ECAT_IDEMPOTENT_TAILS）矛盾。</dd><dt>风险</dt><dd>同一帧运动指令被 native 入队两次，电机执行两次增量/相对命令。</dd><dt>修改建议</dt><dd>仅当 connect 阶段失败时重试；sendall 之后的任何异常直接返回 ok:false（可附 maybe_sent 标记）。</dd></dl></div><div class="issue s1b" id="H-1"><h4><span class="sev s1">严重</span> [H-1] AI 工具目录被提交</h4><dl><dt>模块</dt><dd>仓库卫生/文档</dd><dt>位置</dt><dd><code>.qoder/repowiki/（约 75 个文件）; .zcode/plans/plan-sess_*.md; .gitignore</code></dd><dt>现象</dt><dd>.qoder 自动生成的知识库与 .zcode 个人调试计划（含 G:\ 路径与固件计划）入库，且未列入 .gitignore。</dd><dt>风险</dt><dd>仓库噪声、信息泄露、与真实代码不同步误导读者。</dd><dt>修改建议</dt><dd>移出仓库（需用户决定，本次评审不删除任何文件）并加入 .gitignore。</dd></dl></div><div class="issue s1b" id="M-6"><h4><span class="sev s1">严重</span> [M-6] 「谁可以动总线」红线被多处绕过</h4><dl><dt>模块</dt><dd>电机控制/故障保护</dd><dt>位置</dt><dd><code>js/motor/transport-ecat.js:394-459, 668; js/common/device-link.js:250-287, 322-327</code></dd><dt>现象</dt><dd>transport-ecat.ensureStarted 在 isBusHealthy 为 false（含 unknown）时调用 motor/start，不带 reason、不走 ensureEcatLoopRepair 预算，并重复实现 ecat-bus.resolveEcatStartBody 的周期/DC 逻辑；Owner bootstrapEcatBus 同样无 reason 且把 unknown 当需要启动；repairEcatDc 无间隔/次数预算，pollEcat 每 2 s 与 healthCheck 都可触发。</dd><dt>风险</dt><dd>健康总线被误重启、OTA/刷写期间总线被抢、DC 修复风暴。</dd><dt>修改建议</dt><dd>所有 start/repair 统一经 ecat-bus 单入口（带 reason、预算与 OTA 闸）；unknown 状态不得触发启动；删除 transport-ecat 内重复的周期计算（与 host-code-quality R6 同源）。</dd></dl></div><div class="issue s1b" id="P-4"><h4><span class="sev s1">严重</span> [P-4] 跨进程锁超时或 CreateMutexW 失败仍继续执行</h4><dl><dt>模块</dt><dd>主机服务/安全</dd><dt>位置</dt><dd><code>ecat_proc.py:67-94（尤其 72-81）</code></dd><dt>现象</dt><dd>_EcatProcXLock 未拿到锁（_owned=False）时不中止，后续 kill/拉起照常进行。</dd><dt>风险</dt><dd>多实例并发 kill/start，串行保护失效。</dd><dt>修改建议</dt><dd>未拿到锁时返回失败（503）或只读复用，不做 kill/start。</dd></dl></div><div class="issue s2b" id="C-9"><h4><span class="sev s2">一般</span> [C-9] toast 模块被加载成两个实例</h4><dl><dt>模块</dt><dd>CAN/公共层</dd><dt>位置</dt><dd><code>js/can/send.js:17; js/can.js:19-20, 47</code></dd><dt>现象</dt><dd>send.js 以 ?v= 查询串导入 toast.js，违反 can.js 自身规则，产生两个模块实例，去重与隐藏计时不共享。</dd><dt>风险</dt><dd>重复提示。</dd><dt>修改建议</dt><dd>JS 间 import 去掉 ?v=。</dd></dl></div><div class="issue s2b" id="H-2"><h4><span class="sev s2">一般</span> [H-2] 受版本控制文件含个人绝对路径</h4><dl><dt>模块</dt><dd>仓库卫生/文档</dd><dt>位置</dt><dd><code>scripts/build_mem.bat:21; README.md:3, 449; docs/compose/spec/host-code-quality.md:67</code></dd><dt>现象</dt><dd>G:\Robot_v2\... 等路径。</dd><dt>风险</dt><dd>换机即失效。</dd><dt>修改建议</dt><dd>改为相对路径或环境变量。</dd></dl></div><div class="issue s2b" id="H-4"><h4><span class="sev s2">一般</span> [H-4] 注释/文档与代码不符（默认周期等）</h4><dl><dt>模块</dt><dd>仓库卫生/文档</dd><dt>位置</dt><dd><code>js/motor/transport-ecat.js:37, 166, 416-417, 607; README.md:190</code></dd><dt>现象</dt><dd>注释写 supportsOta=false，实际 :607 为 true；注释与 README 写『默认 4 ms 由后端决定/删键跟随后端』，实际回落 0.25 ms。</dd><dt>风险</dt><dd>误导调参与维护。</dd><dt>修改建议</dt><dd>统一以 ecat-bus.js 常量为准并修正文档。</dd></dl></div><div class="issue s3b" id="M-18"><h4><span class="sev s3">建议</span> [M-18] main.js 约 3250 行，流控逻辑重复</h4><dl><dt>模块</dt><dd>电机控制/故障保护</dd><dt>位置</dt><dd><code>js/motor/main.js:807-948</code></dd><dt>现象</dt><dd>单文件过大、依赖函数提升的闭包顺序；sendBatch 与 sendBurst 流控代码复制。</dd><dt>风险</dt><dd>改动易引入回归。</dd><dt>修改建议</dt><dd>拆分 cmd 编码、流控、UI 绑定、持久化模块；抽公共流控。</dd></dl></div><h2>结论</h2><div class="card">共 9 条：已修复 2、部分修复 5、仍存在/存疑 2、已过时 0、无法在本仓库核实 0。</div></div></body></html>
|