RuView代码规范指南：构建高质量WiFi姿态估计系统

为什么规范对WiFi姿态估计系统至关重要？

在RuView这样的复杂系统中，代码规范不仅仅是代码风格的统一，更是系统可靠性和可维护性的基石。该项目通过商用WiFi设备实现穿墙人体姿态估计，涉及CSI信号处理、神经网络推理和实时跟踪等关键技术。规范的代码能够:

• 降低系统风险：在信号处理和姿态估计算法中，一致的错误处理机制可减少因数据异常导致的系统崩溃
• 提高开发效率：清晰的命名和文件组织让开发者能快速定位关键模块，如rust-port/wifi-densepose-signal/src/ruvsense/中的信号处理代码
• 优化性能：遵循性能规范的代码能确保实时姿态估计达到10 FPS以上的处理速度
• 促进协作：统一的编码风格降低了团队成员间的沟通成本

✅ 最佳实践：将代码规范纳入CI流程，通过自动化工具确保所有提交都符合项目标准

如何组织代码以支持复杂的信号处理流程？

RuView采用模块化架构设计，将复杂的WiFi姿态估计系统分解为逻辑清晰的组件。合理的文件组织能够反映系统架构，使新开发者快速理解代码结构。

推荐的目录结构

rust-port/wifi-densepose-rs/
├── crates/                  # 功能独立的Rust crate
│   ├── wifi-densepose-core/ # 核心数据结构和接口
│   ├── wifi-densepose-signal/ # CSI信号处理
│   ├── wifi-densepose-nn/   # 神经网络推理
│   └── wifi-densepose-mat/  # 多天线跟踪算法
├── data/                    # 训练数据和模型
└── examples/                # 示例应用

⚠️ 注意事项：每个模块应遵循单一职责原则，例如信号处理模块不应包含UI渲染代码

文件组织正反例

// ❌ 不推荐：混合多种职责的文件结构
src/
├── main.rs  // 包含CSI处理、神经网络推理和UI代码

// ✅ 推荐：职责分离的文件结构
src/
├── csi_processor.rs  // 仅处理CSI信号
├── pose_estimator.rs // 仅处理姿态估计
└── ui/
    └── dashboard.rs  // 仅处理UI渲染

如何通过命名传达代码意图？

在WiFi信号处理和姿态估计这样的专业领域，精准的命名能够大幅提高代码可读性，减少理解成本。

核心命名规则

• 模块/文件：使用kebab-case，如signal-processing.rs
• 结构体/枚举：使用PascalCase，如CsiFrame、PoseEstimator
• 函数/方法：使用snake_case，如process_phase_data
• 常量：使用SCREAMING_SNAKE_CASE，如MAX_CSI_BUFFER_SIZE

命名正反例

// ❌ 不推荐：模糊不清的命名
fn process_data(input: &[f32]) -> Vec<f32> {
    // 处理逻辑...
}

// ✅ 推荐：清晰表达意图的命名
/// 对原始CSI相位数据进行标准化处理
/// 消除噪声和硬件差异带来的误差
fn normalize_phase_data(raw_phase: &[f32]) -> Vec<f32> {
    // 处理逻辑...
}

✅ 最佳实践：在rust-port/wifi-densepose-signal/src/csi_processor.rs中，所有函数都遵循"动词+名词"的命名模式，如filter_noise、calculate_amplitude

如何确保代码质量和可靠性？

WiFi姿态估计系统需要处理噪声信号和复杂场景，代码质量直接影响系统准确性和稳定性。RuView采用多层次质量保障机制。

测试策略

RuView的测试体系分为三个层级：

1. 单元测试：测试独立功能，如CSI相位校正算法
2. 集成测试：验证模块间交互，如信号处理到姿态估计的流程
3. 性能测试：确保实时处理性能，如references/densepose_performance_chart.png所示

不同配置下的性能对比，展示了WiFi信号与图像-based姿态估计的准确率差异，指导性能优化方向

测试代码示例

// [rust-port/wifi-densepose-signal/tests/validation_test.rs]
#[test]
fn test_phase_sanitization() {
    // 准备包含噪声的测试数据
    let raw_phase = vec![0.1, 2.5, 1.3, 5.8, 3.2];
    let expected = vec![0.1, 2.5, 1.3, 5.8 - 2.0*PI, 3.2];
    
    // 执行测试
    let result = phase_sanitizer::sanitize(&raw_phase);
    
    // 验证结果
    assert!(result.iter().zip(expected.iter())
        .all(|(a, b)| (a - b).abs() < 1e-6));
}

代码审查要点

代码审查时应重点关注：

• 信号处理算法的数值稳定性
• 神经网络推理的内存使用
• 实时处理的性能瓶颈
• 错误处理的完整性

如何高效协作开发WiFi感知功能？

RuView作为开源项目，需要清晰的协作流程来协调分布式开发。

分支策略

• main：保持可部署状态的生产代码
• develop：开发分支，包含下一个版本的功能
• feature/csi-optimization：功能分支，如CSI处理优化
• hotfix/connection-issue：紧急修复分支

提交规范

遵循Conventional Commits规范：

<类型>[可选作用域]: <描述>

[可选正文]

[可选脚注]

示例：

feat(signal): 添加自适应相位噪声过滤算法

实现基于Hampel滤波器的自适应噪声过滤，
在低信噪比环境下将姿态估计准确率提升12%。

Closes #42

常见类型：

• feat：新功能，如添加多人体跟踪
• fix：错误修复，如修复CSI数据解析 bug
• perf：性能优化，如加速神经网络推理
• refactor：代码重构，不改变功能

如何设计可扩展的WiFi感知系统？

优秀的架构设计是系统长期可维护的关键，尤其对于RuView这样需要持续演进的WiFi感知系统。

核心设计模式

1. 策略模式：在rust-port/wifi-densepose-signal/src/csi_processor.rs中用于不同信号处理算法的切换
2. 观察者模式：用于处理实时数据流，如UI更新和数据记录
3. 状态模式：管理系统不同运行状态，如校准、正常运行、错误状态

系统架构展示了从WiFi信号到姿态估计的完整流程，包括CSI相位处理和模态转换网络两个核心步骤

性能优化实践

1. 内存管理：使用适当的数据结构减少内存分配，如rust-port/wifi-densepose-core/src/types.rs中定义的高效数据类型
2. 并行处理：利用多线程处理多天线数据，如rust-port/wifi-densepose-mat/src/tracking/中的并行跟踪实现
3. 算法优化：选择计算效率高的算法，平衡精度和性能

常见问题解答

Q: 如何处理不同硬件的CSI数据差异？

A: 使用rust-port/wifi-densepose-hardware/src/esp32_parser.rs中的硬件归一化模块，消除不同设备间的系统误差。

Q: 如何平衡实时性能和估计精度？

A: 通过rust-port/wifi-densepose-signal/src/subcarrier_selection.rs实现动态子载波选择，在弱信号环境下自动降低精度以保证帧率。

Q: 代码规范是否适用于固件开发？

A: 是的，固件代码同样遵循这些规范。例如firmware/esp32-csi-node/main/csi_collector.c中的C代码采用类似的命名和结构原则。

规范如何随项目演进？

代码规范不是一成不变的，需要随着项目发展而更新。RuView采用以下机制管理规范演进：

1. 版本控制：规范文档本身纳入版本控制，每个主要版本更新时评审规范
2. 提案流程：通过ADR（架构决策记录）提出规范变更，如docs/adr/ADR-001-wifi-mat-disaster-detection.md
3. 定期审查：每季度审查规范执行情况，根据实际开发需求调整

✅ 实践建议：所有规范变更都应通过Pull Request进行，确保团队共识并留下变更记录

总结

本指南涵盖了RuView项目开发的核心规范，从代码组织到协作流程，从质量保障到架构设计。遵循这些规范将帮助团队构建可靠、高效的WiFi姿态估计系统。记住，规范的目的不是限制创造力，而是提供共同的基础，让团队能够专注于解决复杂的技术问题而非纠结于代码风格。

RuView系统实时姿态检测界面，展示了规范代码实现的实际效果，包括骨架绘制和性能指标监控