feat: publish dbussmsforward refactor

2026-05-08 23:54:03 +08:00
commit 9f1ee9ffe6
77 changed files with 15585 additions and 0 deletions
@@ -0,0 +1,531 @@
+# DbusSmsForward Debian 重构状态报告与下一步落地清单
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** 基于当前仓库实际状态，给出一份 Debian-first 的真实重构进度报告，并列出后续最小可落地的执行清单，避免再把方向带回 OpenWRT。
+
+**Architecture:** 当前仓库处于双轨状态：保留 C# Worker 主线，同时新增 Python 重构线。Python 线已经形成可测试的运行时核心，但 Web 管理层和 Debian 交付闭环尚未完成；C# 线则有 Debian 友好的部分配置改造，但还不是完整的 Web 化交付形态。
+
+**Tech Stack:** Python 3.11、unittest、CLI runtime、ModemManager/DBus 抽象、C# .NET 8 Worker、Systemd-oriented configuration
+
+---
+
+## 一、结论摘要
+
+### 1. 当前方向应明确为 Debian-first
+本项目当前应围绕：
+- Debian 运行
+- ModemManager/DBus 短信接收
+- Web 管理
+- 不要求在 Debian 目标机上编译源码
+
+不应再把“下一步推进目标”描述为 OpenWRT 部署。
+
+### 2. 当前重构不是没进展，但也还没到 Debian Web 成品
+仓库里的 Python 重构线已经完成了“核心运行层”的大量工作：
+- 配置模型
+- 短信来源抽象
+- 文件源/ModemManager 源
+- sender 分发
+- AutmanPush 错误结构化
+- 轮询、去重、fetch issue 统计
+- CLI 基本闭环
+- 自动化测试覆盖
+
+但 **Debian Web 管理版本身尚未完成**，因为还缺：
+- HTTP 服务入口
+- Web API
+- 前端页面
+- 配置读写 API
+- 状态 API
+- systemd/service 交付文件
+- Debian 部署说明与目录规范
+
+### 3. C# 主线仍存在，但并非当前可直接交付的 Debian Web 版本
+C# 线保留了较多历史功能与 Debian 友好的配置思路，但从当前文件状态看，它仍然是 Worker 应用，不是完整 Web 项目，且存在引用类与当前可见文件状态不完全一致的问题，因此不适合作为“已完成的 Debian Web 版”来对外描述。
+
+---
+
+## 二、实际检查到的仓库状态
+
+仓库路径：`/Users/chick/.Hermes/workspace/DbusSmsForward`
+
+### 目录结构观察
+- C# 主线目录：`DbusTest/`
+- Python 重构目录：`src/dbussmsforward/`
+- Python 测试目录：`tests/`
+- README：`README.md`
+
+### 粗略文件数量
+- `DbusTest/` 文件数：35
+- `src/dbussmsforward/` 文件数：14
+- `tests/` 文件数：9
+
+这说明仓库现在不是“只剩一个新实现”，而是明确的双轨并存状态。
+
+---
+
+## 三、Python 重构线：已完成内容
+
+### 1. 配置模型已成型
+已检查文件：
+- `src/dbussmsforward/config.py`
+
+已具备：
+- `DaemonConfig`
+- `ForwardingConfig`
+- `AutmanPushConfig`
+- `SmsSourceConfig`
+- `NotificationChannels`
+- `AppConfig`
+- legacy `appSettings/appsettings` 到新模型的兼容映射
+
+说明：Python 线已经不是零散脚本，而是具备明确配置边界的可持续实现。
+
+### 2. 短信源抽象已成型
+已检查文件：
+- `src/dbussmsforward/source.py`
+
+已具备：
+- `FileSmsSource`
+- `ModemManagerSmsSource`
+- `PythonDbusModemManagerProxy`
+- `FetchIssue`
+
+说明：
+- `modemmanager` source 是 Debian-first 能力，不是 OpenWRT 专属。
+- 当前 Python 线已经具备在 Debian + ModemManager 环境继续推进的正确技术基础。
+
+### 3. 通知分发核心已成型
+已检查文件：
+- `src/dbussmsforward/notifications.py`
+- `src/dbussmsforward/app.py`
+
+已具备：
+- console sender
+- AutmanPush sender
+- `DispatchOutcome`
+- `SenderDispatchResult`
+- sender 级别失败记录
+- HTTP/timeout/network/unknown 分类
+- HTTP 响应片段摘录
+- partial success 保留
+- dedupe
+- 轮询统计
+- fetch issue 聚合
+
+### 4. CLI 基本闭环已经存在
+已检查文件：
+- `src/dbussmsforward/cli.py`
+
+当前命令：
+- `run`
+- `send`
+- `validate-config`
+- `print-sample-config`
+
+说明：
+- 这已经满足“核心运行原型”的最低闭环。
+- 但还不是 Web 管理闭环。
+
+---
+
+## 四、Python 重构线：验证状态
+
+### 1. CLI 测试
+命令：
+```bash
+PYTHONPATH=src python3 -m unittest tests.test_cli -v
+```
+结果：10/10 通过
+
+### 2. 运行时流程测试
+命令：
+```bash
+PYTHONPATH=src python3 -m unittest tests.test_runtime_flow -v
+```
+结果：16/16 通过
+
+### 3. 配置模型测试
+命令：
+```bash
+PYTHONPATH=src python3 -m unittest tests.test_config_model -v
+```
+结果：4/4 通过
+
+### 4. 关于“全量测试”口径的注意事项
+如果直接运行：
+```bash
+python3 -m unittest discover -s tests -v
+```
+会失败，原因不是测试逻辑本身坏了，而是当前仓库还没有把 `PYTHONPATH=src` 或等价安装流程固化到默认测试入口里，导致：
+- `test_config_model`
+- `test_runtime_flow`
+在 discover 模式下导入 `dbussmsforward` 失败
+
+这说明：
+- **测试内容本身大体可用**
+- **但仓库级测试入口还没标准化**
+
+这属于 Debian 交付前必须补齐的一环。
+
+---
+
+## 五、C# 主线：当前真实状态
+
+### 1. 仍是 Worker，不是 Web 项目
+已检查文件：
+- `DbusTest/DbusSmsForward.csproj`
+
+当前项目 SDK：
+```xml
+<Project Sdk="Microsoft.NET.Sdk.Worker">
+```
+
+说明：
+- 这不是 `Microsoft.NET.Sdk.Web`
+- 当前 C# 主线不能被称为“已完成 Web 化”
+
+### 2. 有 Debian 友好的配置痕迹
+已检查文件：
+- `DbusTest/Helper/ConfigHelper.cs`
+
+确认存在：
+- `/etc/dbussmsforward/appsettings.json` 的优先加载路径
+- `DBUSSMSFORWARD_CONFIG_PATH` 环境变量支持
+- `SaveOptions` / `LoadOptions`
+- 旧配置与新配置转换
+
+说明：
+- C# 线并非完全无效，已经有面向 Debian 服务运行的配置设计。
+- 但这只是“服务化/配置化能力”，不是完整 Web 管理版。
+
+### 3. Program.cs 依赖的若干类当前未直接看到实现文件
+在 `DbusTest/Program.cs` 中可见引用：
+- `SampleConfigFactory`
+- `LegacyConfigurationBridge`
+- `CommandLineConfigurationApplier`
+- `ConfigurationValidator`
+
+但本轮目录巡检中未直接发现对应文件，说明至少有以下一种情况：
+- 文件缺失
+- 尚未提交完整
+- 放在当前未显式识别的位置
+- 或重构过程中断过
+
+因此，**当前不应把 C# 主线描述为“已稳定可构建的 Debian Web 版”。**
+
+### 4. README 仍是旧交付叙事
+已检查文件：
+- `README.md`
+
+当前 README 仍主要描述：
+- 直接运行旧二进制
+- `-fE/-fP/-fW/...` 旧参数模式
+- Native AOT 交叉编译
+
+没有覆盖：
+- Python 重构线的运行方式
+- Debian-first Web 管理目标
+- 统一部署方式
+- systemd 落地方式
+
+这意味着：
+- 仓库文档叙事仍停留在旧时代
+- 这会持续误导后续判断与交付方向
+
+---
+
+## 六、当前最准确的项目分层判断
+
+### 已完成层
+1. Python 核心配置模型
+2. Python 短信源抽象（含 ModemManager）
+3. Python 通知分发运行时
+4. Python CLI 基本闭环
+5. 单元/流程级测试覆盖的大部分核心行为
+
+### 半完成层
+1. C# Debian 服务化配置思路
+2. legacy -> 新配置兼容桥接思路
+3. 多通知渠道的旧实现保留
+
+### 明显未完成层
+1. Debian Web API
+2. Debian Web 前端
+3. Web 管理配置读写
+4. 服务状态查看接口
+5. 消息查看/发送 API
+6. systemd/service 交付物
+7. Debian 安装/升级/目录规范
+8. 统一测试入口
+9. README/部署文档重写
+
+---
+
+## 七、建议的方向收敛
+
+### 建议主路线
+**以 Python 线作为 Debian-first 主实现继续推进。**
+
+原因：
+1. Python 线目前已经具备可测试、可迭代的核心运行时
+2. 已有 ModemManager 抽象，技术方向与 Debian 目标一致
+3. 当前 Web 化缺口更适合作为 Python 层增量补齐
+4. C# 线当前更适合做“参考/兼容来源”，不适合作为当前主交付叙事
+
+### C# 线建议定位
+短期内将 C# 线定义为：
+- 历史主线
+- 兼容配置与行为参考来源
+- 功能映射对照对象
+
+而不是当前 Debian Web 交付主线。
+
+---
+
+## 八、下一步落地清单（按优先级排序）
+
+下面这份清单按“最小可落地 Debian Web 版”来排，不再发散。
+
+### 阶段 0：先把工程入口和叙事统一（高优先级，半天内可做）
+
+#### Task 0.1：补统一测试入口
+**Objective:** 让仓库级测试命令不依赖手工写 `PYTHONPATH=src`
+
+**Files:**
+- Create: `pyproject.toml` 或 `pytest.ini` / `tox.ini`（择一）
+- Optionally modify: `README.md`
+
+**Expected outcome:**
+以下命令之一可直接工作：
+```bash
+python3 -m unittest discover -s tests -v
+```
+或
+```bash
+python3 -m pytest -q
+```
+
+#### Task 0.2：补 Python 运行入口说明
+**Objective:** 把当前 Python 线的实际运行方式写清楚
+
+**Files:**
+- Modify: `README.md`
+
+**Must include:**
+- Python CLI 启动方式
+- `PYTHONPATH`/安装方式
+- `validate-config` / `run` / `send`
+- file source 与 modemmanager source 的示例配置
+
+#### Task 0.3：明确仓库主线状态说明
+**Objective:** 在 README 顶部写明当前仓库是 C# 历史主线 + Python Debian 重构线并存
+
+**Files:**
+- Modify: `README.md`
+
+**Must include:**
+- 当前推荐继续投入的是 Python Debian-first 线
+- C# 线主要用于兼容参考，不宣称已完成 Web 化
+
+---
+
+### 阶段 1：补最小 Debian Web API（最高业务优先级）
+
+#### Task 1.1：新增 Web 服务入口模块
+**Objective:** 在 Python 线增加最小 HTTP 服务，而不破坏 CLI
+
+**Files:**
+- Create: `src/dbussmsforward/web.py`
+- Modify: `src/dbussmsforward/cli.py`
+- Modify: `src/dbussmsforward/config.py`
+
+**API baseline:**
+- `GET /api/health`
+- `GET /api/system/status`
+- `GET /api/settings`
+- `POST /api/settings`
+- `POST /api/sms/send`
+
+#### Task 1.2：补 Web 层测试
+**Files:**
+- Create: `tests/test_web.py`
+
+**Validation:**
+- 健康检查返回 200
+- 设置读取/写入生效
+- send API 能触发 dispatcher
+- 错误配置返回结构化 4xx
+
+#### Task 1.3：定义配置文件持久化位置
+**Objective:** 对齐 Debian 运行约定
+
+**Files:**
+- Modify: `src/dbussmsforward/cli.py`
+- Modify: `src/dbussmsforward/web.py`
+- Create: `appsettings.example.json`
+
+**Recommended path order:**
+1. `--config`
+2. `DBUSSMSFORWARD_CONFIG_PATH`
+3. `/etc/dbussmsforward/appsettings.json`
+4. 项目内默认示例路径
+
+---
+
+### 阶段 2：补最小前端管理页（次高优先级）
+
+#### Task 2.1：加纯静态前端
+**Files:**
+- Create: `wwwroot/index.html`
+- Create: `wwwroot/app.js`
+- Create: `wwwroot/app.css`
+
+**UI minimum scope:**
+- 当前运行状态
+- 当前配置查看
+- 基础配置编辑保存
+- 手工发送短信/测试通知
+
+#### Task 2.2：把前端挂到 Web 服务
+**Files:**
+- Modify: `src/dbussmsforward/web.py`
+
+**Validation:**
+- 浏览器可直接打开管理页
+- 前端能调用 `settings` / `status` / `send`
+
+---
+
+### 阶段 3：补 Debian 部署闭环
+
+#### Task 3.1：新增 systemd service 文件
+**Files:**
+- Create: `deploy/dbussmsforward.service`
+
+**Must include:**
+- `Environment=DBUSSMSFORWARD_CONFIG_PATH=/etc/dbussmsforward/appsettings.json`
+- `WorkingDirectory=/opt/dbussmsforward`
+- `ExecStart=` 指向 Python 启动方式或打包后的启动方式
+- `Restart=always`
+
+#### Task 3.2：新增 Debian 部署说明
+**Files:**
+- Modify: `README.md`
+- Optionally create: `docs/debian-deploy.md`
+
+**Must include:**
+- 依赖安装
+- 目录布局
+- 配置文件位置
+- systemd 安装与启动
+- 日志查看方式
+- 升级步骤
+
+#### Task 3.3：明确“不在 Debian 目标机编译”的交付方式
+**推荐选项二选一：**
+1. Python wheel / source bundle + venv 安装
+2. 打包好的独立运行目录（含依赖）
+
+**建议优先：** Python venv + requirements/pip install 方案，先求稳。
+
+---
+
+### 阶段 4：补运维与可观察性
+
+#### Task 4.1：统一日志输出格式
+**Files:**
+- Modify: `src/dbussmsforward/cli.py`
+- Modify: `src/dbussmsforward/app.py`
+- Modify: `src/dbussmsforward/web.py`
+
+**Need:**
+- 标准 INFO/WARN/ERROR
+- sender failure / fetch issue 结构化输出
+- Web API 错误统一 JSON
+
+#### Task 4.2：补状态页指标
+**API suggested:**
+- 最近一次 poll 时间
+- 最近 dispatch failures 数量
+- 最近 fetch issues
+- 启用的通知渠道
+- 当前 source kind
+
+#### Task 4.3：补消息历史持久化（可选）
+这项不是第一阶段必须，但如果要做 Web 查看“最近短信”，就需要：
+- SQLite 或轻量 JSONL 存储
+- 最近 N 条消息与失败记录查询
+
+建议放到 Web API 稳定之后再做。
+
+---
+
+## 九、推荐执行顺序（最务实版本）
+
+### 最小 4 步路线
+1. **统一测试入口 + README 重写**
+2. **补 Python Web API 最小闭环**
+3. **补静态前端最小页面**
+4. **补 systemd + Debian 部署说明**
+
+这样完成后，项目才能第一次比较诚实地对外说：
+
+> 已具备 Debian-first 的可运行 Web 管理版本雏形。
+
+---
+
+## 十、风险与注意事项
+
+### 风险 1：双轨并存会继续制造误判
+如果不尽快在 README 和目录说明里明确：
+- 哪条线是当前主线
+- 哪条线只是历史参考
+
+后续任何人都可能再次把方向带偏。
+
+### 风险 2：测试入口不统一会导致“看起来坏了”
+目前 `unittest discover` 直接跑会误报导入失败，这会让人误以为 Python 重构质量不稳定。
+
+### 风险 3：如果先补太多高级功能，会拖慢最小交付
+比如：
+- 历史消息数据库
+- 权限系统
+- 多用户管理
+- 完整前端框架重构
+
+这些都不该排在 Debian 最小可交付之前。
+
+---
+
+## 十一、最终建议
+
+### 推荐的下一动作
+直接进入：
+
+**Phase 0 + Phase 1**
+- 统一测试入口
+- 重写 README 的 Debian-first 叙事
+- 增加最小 Web API
+
+这是最短路径，也最能避免继续空转。
+
+### 不建议的动作
+- 继续把目标描述为 OpenWRT 部署
+- 先做复杂前端重构
+- 先追求完整数据库历史功能
+- 继续把 C# Worker 当成当前 Web 主交付线
+
+---
+
+## 十二、执行准备说明
+
+如果下一步进入实现，建议采用以下节奏：
+
+1. 先修测试入口与 README
+2. 再加 `web.py` 和 `tests/test_web.py`
+3. API 稳定后再加 `wwwroot/`
+4. 最后补 `deploy/dbussmsforward.service`
+
+这样每一步都可验证，也不会再跑偏。