# PyGoEdge 面板开发进度报告（2025-11-07）

## 概览
- 本次迭代聚焦：修复 GoEdge API 认证与集群配置问题，完善域名接入闭环的关键一环（创建服务），并补齐“套餐”展示与选择。
- 当前状态：开发服务器运行稳定；关键错误已可读性提示；新增页面可预览。

## 本次迭代完成项
- 核心配置与容错
  - 在 `SystemSettings` 新增 `default_node_cluster_id` 字段，并完成迁移，支持默认集群配置。
  - `GoEdgeClient` 增强：
    - `base_url` 解析与端口范围校验（1–65535），提前发现无效配置。
    - 所有 HTTP 请求统一添加超时（连接 5s / 读取 15s），避免长时间卡顿。
    - 令牌使用策略优化：优先使用已有 `edge_access_token`（在有效期内），否则用 `AccessKeyId/AccessKey` 获取；错误信息更清晰。
    - `nodeClusterId` 使用回退顺序：入参 → `SystemSettings.default_node_cluster_id` → 环境变量 `GOEDGE_DEFAULT_NODE_CLUSTER_ID`；未配置时立即抛出引导性错误。
- 业务流程：添加域名
  - `domains/add` 提交时调用 `createBasicHTTPServer` 创建网站，错误通过 Django messages 快速展示。
  - 自动生成 CNAME 映射并保存域名记录为 `pending_dns` 状态。
- 套餐管理与展示
  - 新增套餐列表页 `/plans/`，展示“公开（is_public）+ 激活（is_active）+ 允许新购（allow_new_purchase）”的套餐。
  - 添加域名表单的套餐下拉仅显示可购套餐，避免用户选择不可用套餐。
  - 导航在“域名列表 / 添加域名”中增加“套餐”入口便于跳转。
- 管理后台
  - `SystemSettings` 管理页列表中新增显示 `default_node_cluster_id`，便于运维核对与配置。

## 关键修复与改动详情
- 端口非法导致“Failed to parse”问题：通过 `base_url` 校验在初始化阶段就抛出可读性错误，避免到请求阶段才发现。
- POST 提交卡顿问题：统一请求超时，网络错误通过异常转为明确提示（如连接超时）。
- `invalid 'nodeClusterId'`：通过新增默认集群 ID 并在客户端加入回退逻辑解决。

## 新增页面/接口
- 页面：
  - `GET /plans/`：公开套餐列表（模板：`templates/plans/list.html`）。
  - 导航更新：`templates/domains/list.html`、`templates/domains/add.html` 增加“套餐”按钮。
- 客户端接口：
  - `GoEdgeClient.create_basic_http_server()` 与 `create_server_http_proxy()` 注入 `nodeClusterId` 回退逻辑与请求超时。

## 环境与配置变化
- `.env` 新增占位：
  - `GOEDGE_DEFAULT_NODE_CLUSTER_ID=`（需填写为 GoEdge 的有效集群 ID）。
- 可在 Django Admin → `SystemSettings` 中配置：
  - `goedge_base_url`、`admin_access_key_id`、`admin_access_key`、`default_node_cluster_id`。
- 获取 `nodeClusterId` 的方法（管理员 API）：
  - 使用 `APIAccessTokenService/getAPIAccessToken` 获取令牌后，调用 `NodeClusterService/findAllEnabledNodeClusters`。
  - PowerShell 示例：
    ```powershell
    $base = $env:GOEDGE_ADMIN_API_BASE_URL
    $id = $env:GOEDGE_ACCESS_KEY_ID
    $key = $env:GOEDGE_ACCESS_KEY
    $resp = Invoke-RestMethod -Method Post -Uri "$base/APIAccessTokenService/getAPIAccessToken" -ContentType 'application/json' -Body (@{type='admin';accessKeyId=$id;accessKey=$key}|ConvertTo-Json)
    $token = $resp.data.token
    $clusters = Invoke-RestMethod -Method Post -Uri "$base/NodeClusterService/findAllEnabledNodeClusters" -ContentType 'application/json' -Headers @{ 'X-Edge-Access-Token' = $token } -Body '{}'
    $clusters.nodeClusters | Select-Object id, name
    ```

## 运行与预览
- 开发服务器：`0.0.0.0:8001`（已运行）。
- 预览地址：
  - 套餐列表：`http://127.0.0.1:8001/plans/`
  - 域名列表：`http://127.0.0.1:8001/domains/`
  - 添加域名：`http://127.0.0.1:8001/domains/add/`
- 当前状态：系统检查无问题；错误通过页面消息提示。

## 待办与下一步
- DNS 生效检测：在域名详情页提供“立即检测”，后端调用 DNS 查询判断。
- 域名详情页：展示当前套餐、流量进度、接入信息、功能设置入口。
- 流量统计任务：基于 `domains.management.commands.pull_daily_stats` 增加调度与管理页入口。
- 账单生成与展示：实现周期账单与明细页（billing），支持人工调账与标记支付。
- 运营控制台 `/admin-panel/`：搭建基础框架与系统设置、套餐管理、配额调整。

## 风险与注意事项
- 生产配置：`goedge_base_url` 建议使用 HTTPS；不要在前端暴露 Access Token。
- 集群 ID：必须配置为有效的可用集群，否则创建网站会失败。
- 令牌与密钥安全：AccessKey 请使用受控凭据；令牌缓存过期需自动续期（已支持）。

---
> 备注：`reference/todolist.md` 中的初始化任务（T02）已实际完成（项目结构与核心 app 已就位），后续可统一在运营面板上线后更新 todolist 状态与细粒度任务拆分。