docs: plan V2 development - HTTPS, token mgmt, node groups, custom headers, config preview

Co-authored-by: Rain-kl <63696351+Rain-kl@users.noreply.github.com>

docs/development-guidelines.md

@@ -2,19 +2,27 @@
 
 ## 1. 适用范围
 
-本规范适用于 ATSFlare 当前 MVP 阶段。
+本规范适用于 ATSFlare 第一版与第二版阶段。
 
-项目当前只做以下能力：
+项目第一版已完成以下能力：
 
 * 配置发布与同步
 * 节点心跳检测
 * Nginx 反向代理配置下发
 
-当前明确不做：
+第二版在此基础上新增以下能力：
+
+* HTTPS/TLS 路由支持
+* Agent Token 管理
+* 节点分组与差异化下发
+* 路由自定义请求头
+* 配置预览与变更摘要
+
+当前明确仍不做：
 
 * 多租户
 * WAF、限流、Bot、防刷
-* 灰度发布、分组发布、百分比发布
+* 百分比灰度发布
 * Redis、MQ、对象存储、Prometheus
 * 复杂缓存策略、证书托管、Purge、审批流
 * mid-tier、分层缓存、复杂策略编排
@@ -107,32 +115,38 @@ Agent 放在 `atsf_agent`，使用 Go 单体程序开发。
 所有实现都必须遵守以下原则：
 
 * 先完成闭环，再做抽象。
-* 不为了“以后可能会支持”提前引入复杂模型。
+* 不为了"以后可能会支持"提前引入复杂模型。
 * Server 只管状态和配置，不直接 SSH 改节点。
 * Agent 是唯一落地入口。
-* 所有发布都是“新版本激活”，不是在线覆盖编辑。
-* 所有节点默认拉同一份全量配置，不做差异化编排。
+* 所有发布都是"新版本激活"，不是在线覆盖编辑。
+* 第一版：所有节点默认拉同一份全量配置；第二版：可按节点分组差异化下发。
 * 能用 SQLite 解决的问题，不引入额外中间件。
 * 新功能优先复用现有 gin-template 结构，不平行造第二套框架。
 
 ## 5. 数据模型规范
 
-第一版只允许引入以下核心实体：
+第一版核心实体（已实现）：
 
 * `proxy_routes`
 * `config_versions`
 * `nodes`
 * `apply_logs`
 
-约束：
+第二版新增实体：
+
+* `node_groups` — 节点分组
+* `agent_tokens` — Agent Token 管理
+
+约束（全版本）：
 
 * 不新增 `zone`、`origin_pool`、`policy`、`deployment` 这类平台化对象
 * `proxy_routes` 一条域名只对应一个 `origin_url`
 * `config_versions` 必须保存完整快照和渲染后的 Nginx 路由配置
-* 激活版本全局只能有一个
-* 回滚通过“激活旧版本”实现，不直接修改历史记录
+* 同一分组内激活版本只能有一个；全量版本（group_id = null）全局只能有一个
+* 回滚通过"激活旧版本"实现，不直接修改历史记录
+* `agent_tokens` 中的 Token 值不可更新，只能创建或撤销
 
-如需新增表，必须先证明它服务于 MVP 主链路。
+如需新增表，必须先证明它服务于当前迭代版本的主链路。
 
 ## 6. Server 开发规范
 
@@ -181,12 +195,19 @@ Server 代码按以下职责拆分：
 
 * 继续复用 gin-template 的登录、角色和 session 体系
 
-Agent：
+Agent（第一版）：
 
-* 第一版使用预共享 Token
+* 预共享单 Token，来自环境变量
 * 请求头统一使用 `X-Agent-Token`
 * Agent 与管理端认证逻辑必须分开
 
+Agent（第二版）：
+
+* Token 改为查 `agent_tokens` 表验证
+* 环境变量 Token 降级为 bootstrap 模式：数据库存在有效 Token 记录时，环境变量 Token 不再有效
+* Token 创建时生成随机值，不允许外部传入
+* Token 值不可更新，仅支持撤销（设 `is_active=false`）
+
 注意：
 
 * 不要让 Agent 接口走用户登录态
@@ -339,7 +360,7 @@ MVP 前端只做最小管理界面，不重做整套后台。
 
 ## 10. 测试与验收规范
 
-### 10.1 最低测试要求
+### 10.1 第一版最低测试要求（已完成）
 
 Server 至少覆盖：
 
@@ -356,9 +377,21 @@ Agent 至少覆盖：
 * `nginx -t` 或 `nginx -s reload` 失败分支
 * 本地状态文件读写
 
-### 10.2 联调验收标准
+### 10.2 第二版新增测试要求
 
-MVP 完成至少要通过以下手工验证：
+Server 新增覆盖：
+
+* HTTPS server 块渲染正确性（`enable_https=true` 时生成 443 块，`redirect_http=true` 时生成重定向块）
+* HTTP-only 路由渲染结果不受 HTTPS 字段影响
+* `custom_headers` 注入到渲染结果的正确性
+* `agent_tokens` 创建与查表验证逻辑
+* Token 撤销后验证失败
+* bootstrap Token 降级行为（数据库有 Token 时环境变量 Token 失效）
+* 分组发布逻辑（group_id 筛选激活版本）
+* 预览接口不写库
+* diff 接口变更摘要计算正确性
+
+### 10.3 联调验收标准（第一版，已完成）
 
 1. 管理端新增反代规则并成功发布版本
 2. Agent 能检测到新版本并拉取
@@ -367,15 +400,26 @@ MVP 完成至少要通过以下手工验证：
 5. 节点页能看到当前版本和最后心跳
 6. 当 reload 失败时，Agent 能回滚到旧配置并上报失败
 
+### 10.4 联调验收标准（第二版）
+
+1. 创建含 HTTPS 字段的路由并发布，Nginx 能以 HTTPS 正确转发
+2. 通过管理界面创建 Token，Agent 使用新 Token 成功访问
+3. 撤销 Token 后 Agent 请求返回 401
+4. 创建分组并按分组发布，不同分组节点拉到不同版本
+5. 路由配置自定义头后，渲染结果包含对应指令
+6. 发布页预览展示正确渲染结果
+7. 变更摘要正确列出域名变化
+
 ## 11. 文档维护规范
 
 出现以下情况时必须同步更新文档：
 
-* MVP 范围变化
+* 产品版本范围变化（V1 → V2 → V3）
 * API 发生破坏性变更
 * 数据模型新增或删除
 * Agent 本地文件路径变更
 * 部署方式变化
+* 新增或撤销对中间件/基础设施的依赖
 
 优先更新：