JNetApplet/docs/project-review.md

JNetApplet 项目审查清单

审查日期：2026-07-22 审查范围：全部源码（C++ 后端 + QML 前端 + 构建脚本 + 文档）

---

一、缺陷（Bug / 逻辑错误）

🔴 高优先级

1. 速度计算假设定时间隔严格为 1 秒 ✅ 已修复 calculateSpeed() 直接用 currentRxBytes - m_lastRxBytes 作为 bytes/sec，未除以实际流逝时间。系统负载高或定时器抖动时，速度值会失真。 已改为记录上次采样的毫秒时间戳 m_lastTimestampMs，按真实流逝时间 delta_bytes / elapsed_seconds 计算速度；速度存储由 qint64 改为 double 保留精度；elapsedSec > 0 守卫避免除零。

2. 计数器回绕/重置产生负速度 ✅ 已修复 网卡重启、/proc/net/dev 计数器溢出或接口重置时，currentRxBytes - m_lastRxBytes 可能为负。代码无任何兜底，QML 会显示负速度。 已在 calculateSpeed() 中对 rxDelta / txDelta 钳制为 0，计数器回绕/接口重置/网卡重启时不再产生负速度。

3. "总量统计"语义有误导 ✅ 已修复 m_totalDownload = currentRxBytes 只存储活动接口的当前计数器值，并非真正的累计流量。 已改为累加会话增量 m_totalDownload += rxDeltaClamped，"总计"语义从"活动接口计数器值"变为"本次会话累计流量"：从 0 开始增长，切换网卡不再跳变，网卡重启不归零。跨重启持久化属于 #18 的范畴。

4. 独立窗口不支持深色模式 ✅ 已修复 AboutWindow.qml、SettingsWindow.qml、TextColorPicker.qml、TrafficChartWindow.qml 全部硬编码浅色，不随系统主题适配。 已为 4 个独立窗口新增 isDarkMode 属性（由 networkview.qml 检测后注入），各窗口定义深/浅双色方案切换。深色模式检测改用 DTK.palette.window.hslLightness < 0.5（原 DockPalette.iconTextPalette 不随系统主题变化）。同时修复 networkview.qml 任务栏图标和 NetworkPopup 弹窗的颜色基：从 DockPalette.iconTextPalette 改为 DTK.palette.windowText，解决深色模式黑底黑字问题。

5. detectInterfaces() 过滤规则与 readNetworkStats() 不一致 ✅ 已修复 init() 先调 detectInterfaces()（仅过滤 lo），再调 readNetworkStats()（过滤 lo/veth/docker/br-），首次刷新前 docker/veth 接口短暂出现造成 UI 闪烁。 已将 detectInterfaces() 的过滤规则统一为与 readNetworkStats() 一致（lo/veth*/docker*/br-*）。

🟡 中优先级

6. setActiveInterface() 不校验接口有效性 ✅ 已修复 可传入不存在的接口名，会被持久化到配置文件，当前会话期间速度恒为 0。 已在方法入口增加 m_interfaceList.contains(interface) 校验，无效接口名直接忽略。

7. 速度历史仅记录活动接口 ✅ 已修复 m_speedHistory 每秒只给 m_activeInterface 追加采样点，非活动接口永不采集，切换到新接口时趋势图为空。 已新增 m_lastRxBytesByIface / m_lastTxBytesByIface 跟踪所有接口的字节基线，calculateSpeed() 遍历所有接口采集速度历史。切换接口时趋势图立即有数据。

8. 窗口居中未考虑多显示器 ✅ 已修复 AboutWindow、SettingsWindow、TrafficChartWindow 用 Screen.width/height 居中，frameless 窗口在多屏环境下可能出现在非预期屏幕。 已加 Screen.virtualX / Screen.virtualY 偏移，窗口在任务栏所在屏幕内居中而非虚拟桌面原点。

9. SPDX 版权归属为占位符 ✅ 已修复 所有文件头 SPDX-FileCopyrightText: 2024 MyCompany，"MyCompany" 是模板占位符。 已将 8 个源文件的版权头改为 SPDX-FileCopyrightText: 2026 Jokul。

10. version() 无兜底 ✅ 已修复 若 pluginMetaData().value("Version") 返回空（元数据未加载），AboutWindow 版本行显示空白。 已在 version() 中加兜底：元数据返回空时回退到编译时版本号 PROJECT_VERSION 宏。CMakeLists.txt 新增 target_compile_definitions 将 project(VERSION) 暴露为编译宏。

---

二、代码质量 / 可维护性

11. 大量重复代码跨组件复制 ✅ 已修复 networkview.qml 和 NetworkPopup.qml 中重复颜色定义、isPhysicalIf、formatSpeed、formatTotal 等，formatSpeed 还在 TrafficChartWindow.qml 中第三份拷贝。 已新建 package/components/NetCommon.qml 聚合所有公共颜色与函数。3 个文件删除重复定义改为引用 common.xxx，净删除 91 行重复代码。downloadValueColor 由属性绑定改为函数（调用方传速度值）。

12. 死代码：interfaceStats 属性未被使用 ✅ 已修复 networkview.qml 绑定了 interfaceStats 属性但从未读取，C++ 侧的 interfaceStats() 函数和 Q_PROPERTY 也是死代码。 已删除 Q_PROPERTY、interfaceStats() 实现、statsChanged 信号、QML 属性绑定。

13. 死代码：refresh() Q_INVOKABLE 从未被 QML 调用 ✅ 已修复 C++ 侧的 Q_INVOKABLE void refresh() 从未被 QML 调用。 已移除 Q_INVOKABLE 标记。refresh() 函数本身保留（是 m_refreshTimer 每秒回调），仅不再暴露给 QML。

14. interfaceStats 暴露的数据不完整 ✅ 随 #12 一并解决 NetworkInterface 结构体解析了 rxErrors/txErrors/rxDropped/txDropped，但 interfaceStats() 输出时丢弃了这些字段。 interfaceStats() 已随 #12 整体删除，不再有不完整的输出。结构体字段保留供未来使用。

15. README.md 和 AGENTS.md 严重过时 ✅ 已修复 项目结构只列 AboutWindow.qml，功能特性未提及设置窗口/字体颜色/流量波动图/IPv6/深色模式，README 写"从弹窗卸载"实际在设置窗口。 已更新 README.md 和 AGENTS.md 的功能特性列表、项目结构（补全 6 个组件）、C++ Backend 属性列表（移除 interfaceStats，新增 ipv6Address/version/textColor/speedHistory 等）。

16. qsTr() 源字符串为中文，无翻译基础设施 ✅ 已修复 QML 中 qsTr() 以中文为源串，无 .ts 翻译文件、无 lupdate/lrelease 构建步骤、C++ 无翻译加载逻辑。 已将全部 44 处 qsTr 源串改为英文，新建 translations/jnetapplet_zh_CN.ts 中文翻译文件。CMake 增加 LinguistTools + qt_add_translation 编译 .ts -> .qm，init() 中按系统语言加载 .qm 并安装到 qApp。

17. C++ 后端无单元测试 项目无任何测试。calculateSpeed、readNetworkStats 的正则解析、isPhysicalInterface、niceCeil（QML）等纯逻辑函数适合且应该有单元测试覆盖。

---

三、可开发的新需求 / 功能增强

🟢 推荐开发

#	需求	说明	价值
18	日/月流量统计持久化	将每日累计流量写入 settings.ini，重启后保留。弹窗/设置窗口展示今日/本月用量	解决缺陷 #3，核心功能提升
19	深色模式适配	AboutWindow/SettingsWindow/TextColorPicker/TrafficChartWindow 改用 DTK 主题色或 DockPalette 派生色	解决缺陷 #4，视觉一致性
20	公共代码抽取	颜色/格式化/排序逻辑抽取为共享文件，消除 3 处重复	解决 #11，降低维护成本
21	文档同步	更新 README + AGENTS.md 的项目结构、功能列表、组件说明	解决 #15，新人/AI 接手必备
22	网络断连检测	活动接口 operState != Up 或 IP 丢失时，任务栏显示断连图标 + tooltip 提示	用户体验提升
23	全接口持续采样	后台为所有接口采集速度历史，切换接口时趋势图立即有数据	解决缺陷 #7
24	速度单位切换	设置中可选 KB/s（二进制）或 Mbps（十进制），或智能自动切换	国际化/习惯适配

🔵 可选增强

#	需求	说明
25	刷新间隔可配置	设置中可选 1s/2s/5s 刷新频率，降低低端设备 CPU 占用
26	流量超限通知	设置阈值，下载/上传超限时发送系统通知
27	趋势图时间窗口可选	流量波动图支持 5min / 30min / 1h 切换（需持久化历史数据）
28	多接口聚合速度	任务栏可选显示所有接口合计速度，而非仅活动接口
29	HiDPI 适配	独立窗口使用相对尺寸而非固定像素，适配高分辨率屏幕
30	i18n 翻译基础设施	源串改英文 + 添加中文 .ts + lrelease 构建集成
31	DTK 原生窗口框架	独立窗口改用 DWindow / DTK 窗口装饰，获得原生 deepin 标题栏、圆角、阴影
32	导出流量数据	将流量统计导出为 CSV/JSON，便于分析
33	C++ 后端单元测试	为速度计算、正则解析、接口检测添加 Qt Test 单元测试
34	丢包/错误率展示	弹窗中展示 rxErrors/rxDropped，网络质量诊断
35	开机自启保障	确保 dde-shell 启动时插件自动加载（可能需 dde-shell 配置）

---

优先级建议

第一优先级（影响正确性）：#1 速度计算间隔、#2 负速度、#5 接口过滤不一致

第二优先级（影响体验）：#4 深色模式、#3 总量语义、#7 历史采样、#15 文档过时

第三优先级（工程质量）：#11 重复代码、#12-14 死代码、#17 测试缺失

第四优先级（功能扩展）：#18 日/月统计、#22 断连检测、#26 流量通知