docs: 全项目优化路线图 v2 - #108
Conversation
pikachuren
left a comment
There was a problem hiding this comment.
🙏 感谢 @suantea 提交！
🤖 AI 自动审核声明：本评审报告由 AI 自动生成，当前使用 DeepSeek-V4.1-Flash 模型进行分析。
评审范围：
PR-108.own.diff（1 文件 / +98 −0，新增ROADMAP.md），base =dc2877b(origin/main)，head =60a43d0。
行号以新增文件ROADMAP.md的行号为准。核查方式：对照 origin/main 实际代码与本仓库 open PR 列表。
📖 PR #108 — docs: 全项目优化路线图 v2
🎯 结论
结论：🔄 Request Changes（文档本身有价值，不建议关掉；建议补充"验收标准"、收敛既有规划文档、并把在途 PR 标注为"待合并"）
评分：功能 ⭐⭐⭐⭐ | 最小改动 ⭐⭐⭐⭐ | 前向兼容 ⭐⭐⭐⭐ | 方案设计 ⭐⭐⭐
变更：1 文件（+98 / −0）
整体方案：一份"五波次 + 长期池"的全项目路线图，共 38 项待办，每项带代码证据（文件:行）与量级估算（S/M/L），并给出 4 条执行原则（安全项插队、先基建后铺开、每波次以 PR 交付、WIP 分支先合并或先废弃）。结构清楚、优先级明确、可据此直接开工，明显优于"罗列式"路线图。主要短板是可执行性止于"定位"：没有验收标准，且把尚未合并的 PR 成果当作既成事实，容易在两周内过期。
核心改动清单
- 第一波 S1–S9 安全止血（
PUT /system/config收进 admin 组、宿主机级写操作统一鉴权、WireGuard hook 风险提示、SMB 注入、SFTP 沙箱、Secret 契约执行、登录防爆破、CORS/SQLite 权限、CI 门禁）。 - 第二波 Q1–Q6 稳定性与资源边界（日志 writer 改造、无界表保留策略、优雅关闭、handler 三件套统一、main 组装整理、SystemConfig 键注册表）。
- 第三/四/五波 A1–A7（新用户上手）、B1–B8（穿透质量）、E1–E8（工程化基建）。
- 长期池 + 关键原则 + 调研数据基线。
问题清单
-
[P1]
ROADMAP.md:15、:104— 文档以既成事实的口吻描述未合并 PR 的成果："穿透模块的 6 条断链已在 PR #107 修复"、"P0 断链修复：PR #107"，同时又声明"执行进度以本文件为唯一权威清单"（:11）。但 #107 当前尚未合并（本批评审亦给出 Request Changes）。一旦 #107 需要返工或调整范围，这份"唯一权威清单"立即失真。建议改为"PR #107（在途，待合并）"，并在 :104 标注核实时间。同理:48A1"两分支前后端已完整，缺入口接线"、:90"feat/remote-lines=feat/frpmaster=feat/mtls内容重叠"都是对分支状态的强断言，建议标明核对时间/依据（或改为"据分支查看"）。 -
[P1] 与仓库既有 3 份规划/状态文档职责重叠：
DEMANDS（需求原文）、PLANNER（开发计划与清单）、ISSUE_FIX_STATUS.md（问题修复状态报告）都已存在，再引入一份自称"唯一权威清单"的 ROADMAP.md 会产生"多处真相"。建议二选一：(a) 明确分工——ROADMAP.md 只保留未完成项，ISSUE_FIX_STATUS.md只作为历史完成记录，PLANNER保留架构/目录规划；(b) 直接并入PLANNER的后续章节。无论哪种，建议在 README 里建立互链，并在 ROADMAP.md 顶部写明与另两份文档的边界。 -
[P1] 缺少验收标准/完成定义。每项只有"证据 + 量级（S/M/L）"，没有"做完之后怎么验证"。例如 S1 的验收可以是"表驱动测试锁住鉴权矩阵"、S5 可以是"存在越权读取 RootPath 之外的负向用例"、E6 可以是"install.sh 校验失败时中止安装"。对单人维护的仓库，"负责人"可以省略，但 38 项待办没有验收口径时，很容易长期停在"看起来做了"的状态。是否考虑把表头从「# | 事项 | 证据 | 量级」调整为「# | 事项 | 证据 | 验收标准 | 量级」？另外可以给每个波次补一个可检查的里程碑（如"第一波合并后
gosec高危为 0"）。 -
[P2] 部分证据行号/路径需核对（我抽查了两处，其余定位基本准确）：
:23S1 用middleware/auth.go:59-75说明"legacyadmin_password明文登录路径"——该文件实际路径是backend/api/middleware/auth.go，而 59-75 行是JWTAuth的 token 解析；legacy 明文登录在backend/api/handlers/auth.go:59-75（admin_password查询在handlers/auth.go:65）。建议修正路径。:23"同一遗留概念散落 7 文件"——实测后端admin_password出现在 5 个文件（handlers/auth.go、handlers/admin.go、handlers/init.go、handlers/system.go、model/models.go）。数字是否要按"文件"重算一下？- 我另外抽查的 S4（SMB 注入
storage/manager.go:316-351）、S6（model/secret.go:48-50）、S8（CORSmiddleware/auth.go:158-160）、S1 主体（router.go中auth.PUT("/system/config")未进 admin 组）均与 main 一致 ✓。
-
[P2] 数据基线（
:101-103）口径需注明"含在途 PR"：后端 15 个测试文件—— main 实为 12 个_test.go，15 应是"含 #107 新增的 3 个测试文件"；627 处 any我按\bany\b粗算超过 700，口径（是否含注释/字符串）建议注明；54 处 goroutine与我用go ...前缀粗算的口径也不一致。建议在基线标题里补一句"统计口径 + 是否含未合并分支"，否则读者对不上数会更不信任文档。 -
[P2] 措辞建议：
:15"存在 5 个高危安全缺口（含一条真实提权路径）"——在公开仓库里这句自我披露对贡献者很有价值，但建议同时在 issue 里跟踪细节，避免文档长期挂着"高危"却无对应 issue；且"真实提权路径"这类绝对化表述，建议附上触发前提（例如"具备任意已登录账号"）。
产品视角评估：从产品经理视角看，这份文档的价值在"把散落的债务变成可排序、可开工的清单"，尤其是"安全项插队"和"每个波次以 PR 交付、合并一个再开下一个"这两条原则，直接针对当前 30+ open PR、长分支反复腐化的痛点，非常务实。它的短板是把"定位"误当成了"可执行"：有证据、有优先级、有量级，但没有验收标准，也没有收敛到单一入口，还提前把在途 PR 记成已完成。最小可用的 MVP 版本是：只保留两张表——"未完成项（含验收标准）"与"在途 PR/分支状态"，把现状描述里的量化断言移到附注一节。这样文档既能长期维护，也能在合并后立即被人信任。
兼容性/迁移风险：无代码影响（纯文档，1 文件 +98），不需要迁移脚本。唯一"风险"是文档权威性与实际状态的偏差（见 P1），建议在合并时同步一次标题/日期，并约定"每波次合并后更新本文件"的维护责任——否则第 5 波之前它就会过时。
值得肯定的点
- 每项都附
文件:行证据而非空泛罗列（抽查定位基本正确），可以直接照单开工，这在"AI 贡献者批量提 PR"的场景下尤其有用。 - 显式区分"波次顺序"与"量级"，并单列"安全项永远插队"的例外规则，比单纯的优先级排序更贴近真实执行方式。
- 主动记录仓库治理问题（fork 与上游 main 已分叉、
feat/remote-lines/feat/frpmaster/feat/mtls内容重叠需先决策取舍），并明确"WIP 分支先合并或先废弃"——这对维护者减少并行分支是有实际帮助的。
建议操作理由：文档方向正确、证据扎实、优先级清晰，建议补充验收标准 + 与既有 3 份文档收敛边界 + 把在途 PR 标注为待合并后合并；不必关掉。
基于 2026-09 四轮全项目深度调研（穿透链路、后端架构、前端工程健康度、安全运维）的系统性优化计划：
PUT /system/config提权路径、WireGuard hook/ SMB 注入、SFTP 沙箱、登录防爆破、Secret 契约执行等 9 项每项附代码证据定位与量级估算，长期池单列。此文档作为后续执行的权威清单。
🤖 Generated with ZCode