Initial commit

reference/report/README.md

@@ -0,0 +1,18 @@
+# 开发进度报告目录
+
+本目录用于记录 PyGoEdge 面板的阶段性开发进度与问题汇总，便于团队同步与复盘。
+
+命名规范：
+- `progress_YYYY-MM-DD.md`：按日期生成的进度报告。
+
+报告建议结构：
+- 概览 / 本次迭代完成项
+- 关键修复与改动
+- 新增页面/接口
+- 环境与配置变化
+- 运行与预览地址
+- 待办与下一步
+- 风险与注意事项
+
+生成方式：
+- 由开发者在迭代结束或阶段性目标达成后新增一份报告文件，并在 README 中保持上述结构，以保证内容一致性与可读性。

reference/report/progress_2025-11-07.md

@@ -0,0 +1,76 @@
+# 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 状态与细粒度任务拆分。