Skip to content

gap_analysis_and_stories.md

Latest commit

 

History

History
127 lines (98 loc) · 7.61 KB

gap_analysis_and_stories.md

File metadata and controls

127 lines (98 loc) · 7.61 KB

RustRoute 计划与现状差异分析及可执行故事

文档目的：对齐现有代码与计划文档的差距，明确后续迭代方向，并为工程师提供可执行的 user story 与验收标准。

1. 范围决策（Scope Decision）

项目当前存在两条可选路线：

  1. 按原计划补齐功能：持续实现计划文档中承诺的 WebSocket 实时管理、完整 RIP/RIPng 协议、认证与安全体系、自动化测试等能力。
  2. 收敛到真实范围并更新文档：如果阶段性目标调整为“轻量级、仅本地使用的简化 RIP 工具”，需同步更新所有对外文档、版本号以及 README，避免夸大能力。

建议：结合团队资源与时间，先决定方向；若继续兑现计划功能，可参照下文的 P0/P1/P2 优先级故事；若缩减范围，请先执行 P0 故事中的“文档与版本对齐”。

2. 现状问题域分析

问题域 现状 & 影响 关键阻碍 推荐改进
文档与版本脱节 计划文档宣称 v0.3.0、企业级特性【FEATURE_ENHANCEMENT_SUMMARY.md:5-38】，Cargo.toml 仍是 v0.2.0，许多文档不存在【Cargo.toml:1-3】【docs/screenshots/README.md:1-24】 对外沟通失真、影响团队协作 统一版本号与计划；列出真实特性；补齐或删除缺失文档
RIP 核心循环缺失 Router::new 仅安装直连路由无动态同步，未驱动 network/protocol 模块【src/router.rs:109-147】 无法测试、无法展示真实路由功能 实现定时器、报文收发、邻居维护，接入 network::NetworkInterface 与 protocol::RipPacket
配置结构不一致 AuthConfig 使用 jwt_secret 等字段【src/auth.rs:10-33】，实际配置为 secret_key【rust-route-web.json:35-40】 运行时报错或绕过认证，热重载载入失败 重构配置 schema，提供迁移策略；确保默认配置与代码一致
测试与基准失效 集成测试/基准仍引用旧 riper API，编译失败【tests/integration_tests.rs:1-35】【benches/routing_benchmarks.rs:1-33】；run_tests 仅做样板断言【src/main.rs:202-279】 CI 无法反映真实质量 清理旧代码，编写可执行单元/集成测试，补充基准基于真实路由流程
Web 实时能力缺失 前端依赖 WebSocket 推送【web/static/js/dashboard.js:12-47】，后端无 /ws 路由，仅支持 REST【src/web.rs:176-194】 仪表板无法实时刷新，计划目标未达成 新增 WebSocket/SSE 服务，复用 Metrics 和路由事件推送
认证不可用 认证默认启用且警告默认密码，但 Web API 未验证 token【src/web.rs:176-194】 管理界面完全裸奔 对接 JWT 中间件、开启 RBAC、要求修改默认密码
配置热重载不足 仅文件监听并整体覆盖，无差异对比/回滚/版本审计【src/config_manager.rs:175-198】 易引入错误配置，难以排查 增加 diff 输出、快照列表、回滚 API；记录版本元数据
IPv6 & 网络发现停留在样板 代码仅返回固定值或记录日志【src/ipv6.rs:120-182】【src/network_discovery.rs:214-289】 与计划严重不符 若继续开发：实现最小可测版本并接入主流程；若暂不实现，需在文档说明为未来路线
日志/监控宣传过度 计划宣传“85% 覆盖率、自动审计”等【PROJECT_COMPLETION_SUMMARY.md:76-105】 影响可信度 待真实实现后再宣称，或在文档中标记为“计划中”

3. 可执行故事（User Stories）

P0 — 强制优先

  1. 文档与版本对齐

    • 角色：项目维护者
    • 目标：更新 README、计划文档，将未交付项改为“规划中”，同步 Cargo.toml 与 src/main.rs banner 版本
    • 验收：README.md 核心特性与代码一致，Cargo.lock/Cargo.toml 版本统一，旧文档引用删除或补齐

  2. RIP 核心循环上线

    • 角色：网络工程师
    • 目标：实现周期性更新（发送、老化、垃圾回收）、邻居学习，至少支持静态拓扑互通
    • 依赖：P2 配置对齐
    • 验收：
      1. 可运行两个实例，通过 UDP 广播学习互相路由
      2. Metrics 中的报文计数随事件变化【src/metrics.rs:86-119】
      3. 新增单元/集成测试覆盖 Router::rebuild_routing_table 和邻居清理逻辑

  3. 测试与基准修复

    • 角色：开发者
    • 目标：替换不可用测试，CI 能执行
    • 验收：
      1. cargo test、cargo bench 不再引用 riper，均能通过
      2. CI 工作流增加对新测试的执行【.github/workflows/ci.yml:33-87】
      3. 新增最小集成测试验证两个路由器之间的路由同步（可使用 tokio 的 UDP loopback）

P1 — 高优先

  1. Web 实时能力恢复

    • 角色：运维用户
    • 目标：提供 WebSocket 或 Server-Sent Events 接口，推送系统状态、路由变化、活动日志
    • 依赖：P0 RIP 核心循环
    • 验收：
      • /ws 端点存在，前端 RustRouteDashboard 的实时回调得到数据【web/static/js/dashboard.js:12-48】
      • Dashboard 可以实时更新路由数量与活动日志，无需刷新

  2. 认证接入与配置同步

    • 角色：安全负责人
    • 目标：修正配置 schema，给 Web API 加上 JWT 鉴权和 RBAC
    • 依赖：P2 配置对齐
    • 验收：
      1. 默认配置能正确加载（字段一致）
      2. 管理接口默认要求登陆 token，AuthManager 的 RBAC 生效【src/auth.rs:115-205】
      3. UI 强制修改默认密码，安全警示记录在日志中

  3. 配置热重载增强

    • 角色：运维人员
    • 目标：对 ConfigManager 增加差异分析、历史快照、回滚
    • 依赖：P2 配置对齐
    • 验收：
      • 热更新时输出差异摘要
      • 提供 API 列出历史版本并支持回滚
      • 失败时自动回滚并告警

P2 — 中优先

  1. 配置结构对齐与迁移工具

    • 角色：平台开发者
    • 目标：统一配置字段、给出迁移脚本或向下兼容
    • 验收：旧配置可通过命令行/脚本自动迁移；默认配置、用户模板、代码结构完全一致

  2. IPv6 & 网络发现最小可用版

    • 角色：网络工程师
    • 目标：选择继续实现或改为“实验特性”
    • 验收（若继续实现）：能与 IPv4 一样通过简单拓扑测试；对外标记为 Beta

  3. 文档刷新

    • 角色：文档作者
    • 目标：根据最终交付情况更新 Feature Summary、Completion Summary、用户手册
    • 验收：文档中所有表述均可在代码中找到对应实现，计划项明确标注“未完成/进行中”

4. 开发与协作建议

  • 短期冲刺目标：先完成 P0 任务，确保项目能在 CI 中稳定运行，并具备基础路由能力。
  • 代码整洁度：遇到与现有实现冲突的旧文件（例如 tests/integration_tests.rs），优先重写或删除，避免误导。
  • 日志与追踪：在实现 RIP 核心循环和 WebSocket 时，抓取关键指标（邻居数、触发次数）并写入日志，后续便于排查。
  • 安全策略：在认证上线前，强制要求修改默认密码，可在 CLI 启动时提示或直接阻断。
  • 文档更新策略：若阶段目标调整，先修改 README 与计划文档，再发布公告；避免在功能实现后才回补文档。

5. 附录

  • 核心文件参考：
    • src/router.rs:79-146
    • src/web.rs:176-218
    • src/auth.rs:10-205
    • src/config_manager.rs:16-198
    • web/static/js/dashboard.js:12-104
  • 相关计划文档：
    • FEATURE_ENHANCEMENT_SUMMARY.md
    • PROJECT_COMPLETION_SUMMARY.md