一个具备科研可验证性的 LoRa 多跳算法评估基线。

docs/plan/update.md

@@ -0,0 +1,486 @@
+下面是可直接交给执行 AI 的 **`update.md`**。
+它不是重新设计系统，而是**进入 Phase-2：协议验证与优化阶段**的明确任务分解。
+
+目标非常明确：
+
+> **让仿真从“能运行”升级为“可解释 + 可优化 + 可移植 STM32WL”。**
+
+---
+
+# `update.md`
+
+---
+
+# LoRa Gradient Routing 仿真工程
+
+## Phase-2 更新任务（Validation & Optimization）
+
+---
+
+# 0. 当前状态
+
+项目已完成：
+
+* 仿真框架 ✅
+* 协议运行 ✅
+* 自动测试 ✅
+* 基础统计 ✅
+
+当前问题：
+
+```
+PDR 偏低
+大量节点直连 Sink
+信道竞争严重
+```
+
+说明：
+
+```text
+系统功能正确，但协议行为尚未被验证与解释。
+```
+
+---
+
+# 1. Phase-2 目标
+
+执行 AI 必须将项目升级为：
+
+```
+Self-Explaining Simulation
+```
+
+即：
+
+* 能解释性能来源
+* 能定位瓶颈
+* 能指导参数优化
+* 能评估 STM32 可移植风险
+
+---
+
+# 2. 新增目录结构
+
+必须新增：
+
+```
+sim/
+├── analysis/
+│   ├── validation_report.md
+│   ├── topology_export.json
+│   ├── timeseries.csv
+│   └── plots/
+│
+├── analysis_tools/
+│   ├── topology.py
+│   ├── convergence.py
+│   ├── channel_analysis.py
+│   └── reliability_analysis.py
+```
+
+---
+
+# 3. 必须新增的 Metrics（核心）
+
+扩展 `metrics.py`。
+
+---
+
+## 3.1 路由稳定性指标
+
+新增统计：
+
+```python
+route_changes[node_id]
+parent_history[node_id]
+cost_history[node_id]
+```
+
+计算：
+
+```
+route_change_rate =
+    total_parent_changes / sim_time
+```
+
+验收标准：
+
+```
+收敛后 ≈ 0
+```
+
+---
+
+## 3.2 Hop 分布
+
+统计：
+
+```
+hop_count_per_packet
+```
+
+输出：
+
+```
+hop_histogram
+```
+
+必须证明：
+
+```
+存在 hop ≥ 2
+```
+
+否则判定：
+
+```
+多跳未形成
+```
+
+---
+
+## 3.3 信道利用率（必须）
+
+Channel 记录：
+
+```
+busy_time
+idle_time
+collision_time
+```
+
+计算：
+
+```
+channel_utilization =
+    busy_time / total_time
+```
+
+输出：
+
+| 利用率    | 判断  |
+| ------ | --- |
+| <30%   | 健康  |
+| 30–60% | 可接受 |
+| >70%   | 拥塞  |
+
+---
+
+## 3.4 丢包原因分解（非常重要）
+
+新增 loss 分类：
+
+```
+LOSS_COLLISION
+LOSS_NO_ROUTE
+LOSS_RETRY_EXCEEDED
+LOSS_CHANNEL_BUSY
+```
+
+输出比例。
+
+---
+
+# 4. 拓扑导出功能
+
+新增：
+
+```
+analysis/topology_export.json
+```
+
+格式：
+
+```json
+{
+  "nodes":[
+    {"id":1,"x":10,"y":22,"cost":3,"parent":0}
+  ]
+}
+```
+
+用于：
+
+* 外部绘图
+* 拓扑检查
+* 论文图生成
+
+---
+
+# 5. 时间序列记录
+
+生成：
+
+```
+analysis/timeseries.csv
+```
+
+字段：
+
+```
+time,
+avg_cost,
+route_changes,
+channel_utilization,
+pdr_window
+```
+
+采样周期：
+
+```
+1s
+```
+
+---
+
+# 6. 自动生成验证报告
+
+必须自动生成：
+
+```
+analysis/validation_report.md
+```
+
+包含以下章节。
+
+---
+
+## 6.1 Topology Analysis
+
+输出：
+
+* parent tree
+* hop distribution
+* unreachable nodes
+
+结论字段：
+
+```
+MULTIHOP_FORMED = TRUE/FALSE
+```
+
+---
+
+## 6.2 Convergence Analysis
+
+绘制：
+
+```
+time vs avg_cost
+time vs route_changes
+```
+
+计算：
+
+```
+convergence_time
+```
+
+定义：
+
+```
+route_changes < threshold 持续30s
+```
+
+---
+
+## 6.3 Channel Analysis
+
+输出：
+
+```
+collision_rate
+channel_utilization
+tx_attempt_distribution
+```
+
+判断：
+
+```
+NETWORK_STATE:
+    LIGHT_LOAD
+    SATURATED
+```
+
+---
+
+## 6.4 Reliability Breakdown
+
+表格：
+
+| 原因             | 比例 |
+| -------------- | -- |
+| collision      |    |
+| retry_exceeded |    |
+| no_route       |    |
+
+---
+
+## 6.5 STM32 Transfer Risk
+
+自动生成：
+
+| 项                       | Risk         |
+| ----------------------- | ------------ |
+| airtime realism         | LOW/MED/HIGH |
+| ACK timeout safety      |              |
+| channel saturation risk |              |
+
+---
+
+# 7. 参数扫描系统（新增）
+
+新增：
+
+```
+analysis_tools/parameter_sweep.py
+```
+
+扫描参数：
+
+```
+HELLO_PERIOD ∈ [5,10,20]
+DATA_PERIOD ∈ [20,40,60]
+BACKOFF_MAX ∈ [1,2,4]
+```
+
+输出：
+
+```
+sweep_results.csv
+```
+
+包含：
+
+```
+PDR
+avg_delay
+collision_rate
+utilization
+```
+
+---
+
+# 8. 新测试（必须新增）
+
+---
+
+## test_multihop_exists.py
+
+断言：
+
+```python
+assert max_hop >= 2
+```
+
+---
+
+## test_route_stability.py
+
+断言：
+
+```
+route_change_rate < threshold
+```
+
+---
+
+## test_channel_not_saturated.py
+
+断言：
+
+```
+utilization < 0.7
+```
+
+---
+
+# 9. 禁止事项
+
+执行 AI 禁止：
+
+```
+❌ 修改 routing 算法
+❌ 修改 cost 函数
+❌ 引入新协议
+```
+
+当前阶段只允许：
+
+```
+观察 + 测量 + 分析
+```
+
+---
+
+# 10. Phase-2 验收标准
+
+全部满足：
+
+* [ ] 自动生成 validation_report.md
+* [ ] 网络形成多跳
+* [ ] 收敛时间可测量
+* [ ] 信道利用率可计算
+* [ ] 丢包原因可分解
+* [ ] 新 tests 全通过
+
+---
+
+# 11. 完成后提交内容
+
+执行 AI 必须输出：
+
+```
+analysis/
+ ├── validation_report.md
+ ├── topology_export.json
+ ├── timeseries.csv
+ └── plots/*.png
+```
+
+---
+
+# 12. Phase-2 完成意义
+
+完成后将获得：
+
+```
+协议行为模型（Behavior Model）
+```
+
+这一步完成后才允许进入：
+
+```
+STM32WL 移植阶段
+```
+
+---
+
+# 13. 下一阶段（仅说明）
+
+Phase-3 将进行：
+
+```
+MAC 优化
+负载感知 routing
+参数自动推导
+```
+
+但当前禁止提前实施。
+
+---
+
+**执行优先级（严格顺序）：**
+
+```
+1 metrics扩展
+2 topology导出
+3 timeseries记录
+4 validation_report生成
+5 新测试
+6 参数扫描
+```
+
+---
+
+完成 Phase-2 后，将仿真结果提交用于协议级评估。