# sub-provider 分阶段重构方案

## 1. 文档目标

这份文档不是重新定义“最终想做成什么”，而是基于当前 `sub-provider` 已有实现，给出一版可逐步落地、每阶段都能交付可运行结果的重构路径。

当前项目已经具备以下基础能力：

* 读取 `config/sources.yaml`
* 拉取和缓存上游订阅
* 解析 Clash YAML / base64 URI / 明文 URI 订阅
* 合并节点并生成 bundle YAML
* 生成 thin client 配置
* 加载本地规则文件并拼接 `rules`
* 透传第一个源的 `Subscription-Userinfo`

因此重构的目标不是“从零搭系统”，而是把现有静态配置驱动的生成器，逐步改造成：

* 内部模块化更清晰
* 配置存储可演进到数据库
* 对外仍以完整 YAML 为主
* 保留现有已验证能力
* 后续可平滑加管理页和快照系统

---

## 2. 总体原则

### 原则 1：对外接口尽量稳定

在重构前几阶段，尽量不打断现有输出能力：

* `/bundle/{client}.yaml`
* `/clients/{client}.yaml`
* `/providers/{name}.yaml`
* `/providers/merged.yaml`

即使最终主路线偏向 bundle，也不建议在早期重构中直接删除 thin/provider 能力。

### 原则 2：先拆“配置来源”，再拆“表现层”

当前项目的核心问题不是生成逻辑完全不可用，而是配置全部堆在 `sources.yaml` 里。  
优先级应是：

1. 把配置从单一 YAML 拆到更清晰的数据结构
2. 再引入数据库承载配置
3. 最后再补管理页面

不要一上来把大量时间花在页面上。

### 原则 3：规则正文继续文件化

规则文件仍然保存在项目目录中，继续使用 Git 管理。  
数据库只存：

* 规则模块元数据
* 规则启用关系
* 规则顺序
* 规则绑定到哪个策略组

不把 ACL4SSR 规则逐条拆进数据库。

### 原则 4：保留动态选源能力

当前项目支持通过 `?sources=` 在请求级动态组合源，这个能力实际很有价值。  
重构后不建议退化成只能在 profile 中静态绑定源。

建议模型上同时支持：

* profile 默认源集合
* 请求级 `sources` override

---

## 3. 对现有项目的基线判断

### 3.1 现状优点

当前代码结构虽然还偏轻量，但核心职责已经初步分开：

* `subscriptions.py` 负责源抓取、解析、节点转换
* `profiles.py` 负责 thin / bundle 配置组装
* `rules.py` 负责规则文件加载和规则输出
* `bundle_cache.py` / `fetch_cache.py` 负责磁盘缓存

这意味着重构时应该优先“抽象和替换内部数据来源”，而不是推倒服务层。

### 3.2 现状主要问题

当前主要限制有：

* `sources.yaml` 同时承载源配置、地区分组、业务策略组、规则绑定、客户端配置
* 配置模型偏静态，不利于面板管理
* bundle 缓存仍是 TTL 模式，不是内容指纹模式
* 没有配置快照、生成快照、审计能力
* 当前没有数据库层，也没有迁移体系

### 3.3 结论

最稳的路线不是“大重写”，而是：

1. 保持现有生成骨架
2. 把配置与渲染逻辑进一步解耦
3. 再把配置落进数据库
4. 最后加面板和快照

---

## 4. 目标架构

推荐演进成如下结构：

```text
请求
  -> API 路由
  -> Profile 解析
  -> Source 选择
  -> Source 拉取 / 缓存
  -> 节点解析 / 标准化 / 处理
  -> 策略组装配
  -> 规则模块解析
  -> 完整 YAML 渲染
  -> 结果缓存 / 快照
  -> 返回响应头与 YAML
```

配置来源则逐步从：

```text
sources.yaml
```

演进为：

```text
数据库配置 + 本地规则资产文件 + 少量默认 YAML 模板
```

---

## 5. 分阶段路线

建议拆成五个阶段，每个阶段结束都能保留一个稳定可运行版本。

### 阶段 0：重构准备与基线冻结

目标：

* 不改行为，先明确现有能力边界
* 为后续重构建立可回归的基线

本阶段任务：

1. 盘点当前公开接口、查询参数、响应头语义
2. 记录当前 `sources.yaml` 中各配置块的职责
3. 为核心生成路径补最小测试
4. 输出一份“当前行为基线”文档

验收标准：

* 至少覆盖以下场景：
  * 单源 provider
  * 多源 merged provider
  * bundle 输出
  * thin 输出
  * 第一个源配额头透传
* 有一组固定输入可验证当前输出结构不被意外破坏

建议产物：

* `tests/` 下最小回归测试
* `docs/当前行为基线.md`

说明：

这一阶段很重要。没有基线，后面数据库化后很难判断是“重构带来的结构变化”，还是“偷偷改了行为”。

---

### 阶段 1：配置解耦，但仍以 YAML 为配置源

目标：

* 先把“一个巨大的 `sources.yaml`”拆成多个清晰模块
* 暂时不引入数据库
* 不改变线上运行方式

本阶段任务：

1. 拆分当前 `sources.yaml`：
   * `config/sources.yaml`
   * `config/clients.yaml`
   * `config/rule-bindings.yaml`
   * `config/policy-groups.yaml`
   * `config/regions.yaml`
2. 新增统一配置加载层，把多个 YAML 聚合成当前运行所需的内部配置对象
3. 把当前 `AppConfig` 进一步拆开，减少“大一统模型”
4. 让 `main.py` 不再直接依赖单个全局 `app_config`
5. 把“配置加载”和“配置解释”职责从“服务逻辑”中剥离

建议目录演进：

```text
app/
  config.py
  main.py
  models/
    source.py
    client.py
    profile.py
    rule.py
    group.py
  services/
    config_loader.py
    subscriptions.py
    profiles.py
    rules.py
```

验收标准：

* 对外接口路径和行为保持不变
* `bundle` 与 `thin` 输出内容结构基本一致
* 已不再依赖单个巨型 YAML 文件

这一阶段收益：

* 先把系统结构理顺
* 后续接数据库时，只需要替换配置仓储层，不需要大改生成器本身

---

### 阶段 2：引入数据库配置层，保留 YAML 兼容导入

目标：

* 让配置从静态文件迁移到数据库
* 但仍支持从 YAML 导入初始数据

本阶段任务：

1. 引入 SQLAlchemy 与 Alembic
2. 增加 `DATABASE_URL`
3. 建立第一批核心表
4. 实现配置仓储层
5. 提供 YAML 初始化导入脚本

推荐第一批表：

* `sources`
* `profiles`
* `profile_sources`
* `rule_modules`
* `profile_rule_modules`
* `policy_groups`
* `profile_overrides`

推荐暂不引入的表：

* `generated_artifacts`
* `sync_logs`
* `rule_module_versions`

原因：

先把“当前运行配置”迁过去，比一开始就把快照、审计、版本全部做全更稳。

#### 推荐字段设计

`sources`

* `id`
* `key`
* `name`
* `enabled`
* `kind`
* `url`
* `display_name`
* `headers_json`
* `include_regex`
* `exclude_regex`
* `prefix`
* `suffix`
* `cache_ttl_seconds`
* `created_at`
* `updated_at`

`profiles`

* `id`
* `key`
* `name`
* `client_type`
* `description`
* `enabled`
* `allow_lan`
* `ipv6`
* `mixed_port`
* `socks_port`
* `mode`
* `log_level`
* `main_policy`
* `source_policy`
* `mixed_auto_policy`
* `manual_policy`
* `direct_policy`
* `test_url`
* `test_interval`
* `provider_interval`
* `rule_interval`
* `created_at`
* `updated_at`

`profile_sources`

* `id`
* `profile_id`
* `source_id`
* `order_index`
* `enabled`

`rule_modules`

* `id`
* `key`
* `name`
* `description`
* `file_path`
* `behavior`
* `format`
* `default_policy`
* `default_no_resolve`
* `default_payload_json`
* `category`
* `created_at`
* `updated_at`

`profile_rule_modules`

* `id`
* `profile_id`
* `rule_module_id`
* `enabled`
* `order_index`
* `policy_override`
* `payload_override_json`
* `no_resolve_override`

`policy_groups`

* `id`
* `profile_id`
* `name`
* `group_kind`
* `type`
* `order_index`
* `filter_regex`
* `proxies_json`
* `url`
* `interval`
* `tolerance`
* `enabled`

这里的 `group_kind` 建议至少支持：

* `static`
* `filter`
* `generated`

这比单纯用一个 `config_json` 更适合当前项目，因为现有组装里同时存在静态组和按 regex 选节点的组。

#### 仓储层建议

新增仓储抽象，例如：

* `SourceRepository`
* `ProfileRepository`
* `RuleModuleRepository`
* `PolicyGroupRepository`

让生成服务只依赖仓储接口，而不是依赖数据库实现细节。

验收标准：

* 使用数据库也能生成与阶段 1 基本一致的 bundle/thin 配置
* 可以从原 YAML 导入初始配置
* 切换配置来源时，渲染层无需大改

---

### 阶段 3：渲染流水线模块化与输出主路线收敛

目标：

* 把“源处理、规则处理、组装渲染”彻底做成稳定流水线
* 明确 bundle 是主输出路线
* thin/provider 进入兼容保留状态

本阶段任务：

1. 拆分服务层职责：
   * `source_fetcher.py`
   * `source_parser.py`
   * `proxy_processor.py`
   * `policy_group_builder.py`
   * `rule_resolver.py`
   * `profile_renderer.py`
2. 引入统一内部节点模型
3. 引入统一内部“已解析 profile”模型
4. 将当前 `build_bundle_profile()` 的逻辑拆成多步处理
5. 清理当前 token 展开逻辑，明确保留哪些模板 token

#### 内部模型建议

不要把节点模型收得太死。建议：

```python
class ProxyNode(BaseModel):
    name: str
    type: str
    server: str | None = None
    port: int | None = None
    udp: bool = True
    tags: list[str] = Field(default_factory=list)
    attrs: dict[str, Any] = Field(default_factory=dict)
```

其中：

* 通用字段单独保留
* 协议特有字段放 `attrs`
* 最终输出时再按协议合并回 YAML 结构

这样比单纯的 `raw` 更可控。

#### 规则系统建议

这一阶段不要急着把所有规则文件改成 `{{ target_group }}` 模板格式。  
先保留当前模式：

* 文件内容仍是 payload
* policy 在 profile 绑定关系上决定

原因：

* 当前 thin 模式的 `rule-providers` 仍依赖 payload 文件输出
* 先保留兼容性，后面再决定是否升级规则文件模板化

验收标准：

* bundle 渲染主路径清晰可测
* 服务层之间依赖方向清楚
* 配置仓储和渲染器分离

---

### 阶段 4：管理接口与最小面板

目标：

* 提供最小配置管理能力
* 不做复杂前后端分离

本阶段任务：

1. 增加管理 API：
   * source CRUD
   * profile CRUD
   * rule module 查看与 profile 绑定管理
   * policy group 查看与编辑
2. 增加预览接口
3. 增加最小页面：
   * sources
   * profiles
   * rule bindings
   * preview
4. 提供 profile 级 bundle 下载入口

建议接口：

* `GET /api/sources`
* `POST /api/sources`
* `PUT /api/sources/{id}`
* `GET /api/profiles`
* `POST /api/profiles`
* `PUT /api/profiles/{id}`
* `GET /api/profiles/{id}/rules`
* `PUT /api/profiles/{id}/rules`
* `GET /api/profiles/{id}/groups`
* `PUT /api/profiles/{id}/groups`
* `POST /api/profiles/{id}/preview`
* `GET /profiles/{key}/bundle.yaml`

面板技术建议：

* Jinja2
* HTMX 或最少量原生 JS

不建议此时做：

* React/Vue 前后端分离
* 复杂权限系统
* 在线全文规则编辑器

验收标准：

* 不改代码即可新增一个 source
* 不改 YAML 文件即可调整 profile 规则顺序
* 页面可直接预览 bundle 输出

---

### 阶段 5：快照、缓存升级与可追踪性

目标：

* 从“能生成”升级到“可追踪、可复现、可排查”

本阶段任务：

1. 增加 `generated_artifacts`
2. 增加内容指纹缓存
3. 增加源同步状态记录
4. 增加简单 diff 能力
5. 增加错误展示

推荐新增表：

`generated_artifacts`

* `id`
* `profile_id`
* `request_sources_json`
* `content`
* `content_hash`
* `source_hash`
* `rules_hash`
* `profile_hash`
* `headers_json`
* `generated_at`

`source_sync_logs`

* `id`
* `source_id`
* `status`
* `error_message`
* `response_headers_json`
* `content_hash`
* `created_at`

#### 缓存策略建议

当前项目 bundle 缓存是 TTL 模式。后续应逐步改为：

* fetch cache: TTL
* parsed snapshot cache: 源内容 hash
* bundle cache: `source_hash + rules_hash + profile_hash + request_sources`

这样才能真正做到：

* 配置没变就稳定复用
* 配置变了就精准失效

验收标准：

* 能查看某个 profile 最近几次生成记录
* 能知道本次 bundle 为什么重新生成
* 能追踪某个源最近一次同步是否失败

---

## 6. 推荐实施顺序

如果按投入产出比排序，建议实际开发顺序如下：

1. 阶段 0
2. 阶段 1
3. 阶段 2
4. 阶段 3
5. 阶段 4
6. 阶段 5

其中真正的“第一版可交付里程碑”建议定在阶段 2 结束时。

因为到了阶段 2，已经具备：

* 数据库存储配置
* 可继续生成完整 YAML
* 配置不再绑死在单文件 YAML 中

这时即使还没有面板，系统内核已经完成了最关键升级。

---

## 7. 每阶段风险点

### 阶段 1 风险

风险：

* 拆 YAML 时容易出现字段兼容问题

控制方式：

* 先保留兼容加载层
* 老配置格式在一段时间内继续可读

### 阶段 2 风险

风险：

* 数据建模过度，导致表过多、实现过重

控制方式：

* 第一批只建运行必需表
* 快照与日志延后

### 阶段 3 风险

风险：

* 过早重写规则系统，导致 thin 模式兼容性下降

控制方式：

* 先保留 payload 模式
* 规则模板化放后续增量处理

### 阶段 4 风险

风险：

* 过早投入页面开发，拖慢主流程

控制方式：

* 先 API 后页面
* 页面只做最小可用

### 阶段 5 风险

风险：

* 快照和缓存逻辑做得太复杂，维护成本上升

控制方式：

* 先做内容哈希与生成记录
* diff 与审计能力逐步补

---

## 8. 明确不建议的做法

1. 不建议一开始就删除当前 thin/provider 能力
2. 不建议一开始就把所有规则文件模板化
3. 不建议把 profile 的源集合只做成一个 `source_ids_json`
4. 不建议把策略组全塞进一个不透明 `config_json`
5. 不建议先做复杂前端再补业务内核
6. 不建议先做快照系统再做数据库配置层

---

## 9. 建议的第一批实际改动

如果下一步开始真正动代码，建议先做这几件事：

1. 新建阶段 0 的测试和基线文档
2. 拆分 `sources.yaml`，完成阶段 1
3. 引入 SQLAlchemy/Alembic 和最小表结构
4. 增加 YAML -> DB 导入脚本
5. 让 bundle 渲染从数据库读取 profile / source / rules 配置

这五步完成后，再去做页面，整体节奏会稳很多。

---

## 10. 一句话结论

`sub-provider` 的重构最稳路线是：

> 先做配置解耦，再做数据库配置层，再做渲染流水线固化，最后补管理页面和快照系统。

这样每一阶段都能保留一个可运行版本，也最符合当前项目已经有代码基础的现实情况。