# 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`

这样每一步都可验证，也不会再跑偏。