# ATSFlare 开发计划

## 1. 目标

当前开发目标是完成 ATSFlare 的 MVP 闭环：

```text
后台改规则 -> 点击发布 -> Agent 拉到新版本 -> 写入 Nginx 路由配置 -> nginx 校验并 reload -> 节点状态可见
```

在这个闭环完成之前，不新增高级功能。

## 2. 里程碑

### Phase 1: Server 数据层与发布闭环

目标：

* 完成 `proxy_routes`
* 完成 `config_versions`
* 能从规则生成 Nginx 路由配置
* 能激活一个全局版本

交付：

* 新模型
* AutoMigrate
* 路由 CRUD API
* 发布 API
* 激活版本 API
* 渲染 service

完成标准：

* 后台能维护规则
* 可以生成并查看版本记录

### Phase 2: Agent API 与节点状态

目标：

* 建立节点注册、心跳、版本查询、应用结果上报链路

交付：

* `nodes`
* `apply_logs`
* Agent Token 鉴权
* 节点在线状态计算
* 节点与应用日志查询接口

完成标准：

* Server 能记录节点和最近状态

### Phase 3: Agent 本体

目标：

* 实现最小可运行 Agent

交付：

* 本地配置文件读取
* `node_id` 持久化
* 心跳循环
* 版本检查
* 下载配置
* 写入 Nginx 路由配置
* 配置校验、reload 与失败回滚
* 应用结果上报

完成标准：

* 单节点可跑通“发布到 Nginx 生效”的闭环

### Phase 4: 管理端页面

目标：

* 提供 MVP 所需最小可视化界面

交付：

* 反代规则页
* 版本页
* 节点页
* 应用记录页

完成标准：

* 不依赖直接查库即可完成日常操作和排障

### Phase 5: 联调与收尾

目标：

* 完成本地或测试环境联调
* 补齐运行说明

交付：

* 手工部署说明
* Agent 配置示例
* 最小联调脚本或命令说明
* 问题清单与后续迭代列表

完成标准：

* 新环境能按文档手工部署并跑通最小闭环

## 3. 当前建议执行顺序

建议严格按以下顺序开发：

1. Server 模型和 `AutoMigrate`
2. 路由 CRUD 与发布逻辑
3. Agent API 与节点状态表
4. Agent 同步、落盘、reload、回滚
5. 管理端页面
6. 联调和部署文档

不要先做以下内容：

* 权限扩展
* 缓存策略平台化
* 证书平台化
* 多节点分批发布
* 高级监控接入

## 4. 每阶段的验收检查

### Phase 1 检查项

* 可以创建、编辑、删除反代规则
* 可以基于当前规则生成版本
* 可以查看哪个版本处于激活状态
* 激活旧版本时不会修改历史快照

### Phase 2 检查项

* Agent 可以通过 Token 访问 Agent API
* 节点可以注册并重复心跳
* 节点超过超时时间会显示为离线
* 可以查询节点最近一次应用状态

### Phase 3 检查项

* Agent 检测到新版本后会下载配置
* 写入前会备份旧路由配置文件
* `nginx -t` 或 reload 失败后会回滚
* 回滚结果会回传给 Server
* Agent 可使用独立 Nginx 路径或 Docker Nginx 容器运行

### Phase 4 检查项

* 页面可直接完成规则维护和发布
* 页面可查看节点在线状态
* 页面可查看应用失败原因

### Phase 5 检查项

* 按文档可完成一次从零部署
* 至少完成一次真实联调记录
* 已记录当前遗留问题和下一阶段候选项

## 5. 变更控制

开发中如果出现以下情况，需要先调整计划再继续编码：

* MVP 目标发生变化
* 需要引入新的中间件
* 需要新增核心数据模型
* 需要把控制面扩展到独立生成的 Nginx 路由配置文件之外

计划更新时，应同步修改：

* `docs/design.md`
* `docs/development-guidelines.md`
* `docs/development-plan.md`