pyGoEdge-UserPanel/.trae/rules/project_rules.md

项目开发需求说明文档（Django + Bootstrap + MySQL）

本文档用于告诉 AI Agent：需要开发一个 类似 Cloudflare / 百度云加速的域名加速面板，
使用 Python + Django（非前后端分离）+ Bootstrap + MySQL，并集成 GoEdge 管理员 API 作为底层 CDN 引擎。

---

1. 项目目标

• 搭建一个 按域名计费的 CDN 加速控制面板，用户以 CNAME 方式接入域名。
• 每个域名默认有 每月 15GB 免费流量（该值应可在管理后台配置，并可对用户/域名单独调整）。
• 支持多种 套餐（Plan），不同套餐控制：
  • 每个域名的免费/包含流量额度
  • 每 GB 超量单价
  • 可用功能（WAF、日志、HTTP/3、访问控制、缓存高级规则等）
• 系统提供：
  • 用户注册登录、域名接入管理、流量统计展示
  • 套餐订购与变更、账单与支付（先定义结构，支付接入可预留）
  • 强大的管理后台（基于 Django Admin + 自定义页面），可灵活配置套餐、免费额度、功能开关、超量策略等。
• 后端使用 Django 模板 + Bootstrap 完成 UI，不做前后端分离。

---

2. 技术栈与基础要求

• 后端框架：Python 3.x + Django 4.x（或当前 LTS）
• 前端框架：Django Template + Bootstrap 5（或当前版本）
• 数据库：MySQL 8.x
• CDN 引擎集成：通过 HTTP 调用 GoEdge 管理员 API（使用 X-Edge-Access-Token）
• 用户认证：
  • 使用 Django 内置认证体系扩展（或自定义 User 模型）
  • 支持邮箱 / 用户名登录
• 语言：
  • 首版可仅中文界面，保留 i18n 结构，便于未来多语言。

---

3. 核心业务概念与模型

3.1 用户（User）

• 平台登录账号（客户）。
• 一个用户可以拥有多个域名。

3.2 域名（Domain / Site / Zone）

• 用户添加的待加速域名，如 example.com。
• 用户通过将其子域名（如 www.example.com）CNAME 到平台提供的加速域名接入。
• 每个域名：
  • 绑定一个当前套餐（Plan）
  • 拥有每月免费/包含流量额度
  • 有一套独立的功能配置（WAF 开关、缓存规则等）

3.3 套餐（Plan）

• 按域名计费的套餐模版。
• 定义：
  • 基础月费：每个域名每月多少钱
  • 包含流量：每个域名每月包含多少 GB
  • 超量单价：每 GB 超出后的费用
  • 功能开关：是否支持 WAF、日志下载、HTTP/3、WebSocket、自定义规则等
  • 可见/可购状态：是否显示给普通用户新购/升级、是否仅管理员可用

3.4 域名套餐实例（DomainPlan / Subscription）

• 某个域名当前使用的套餐实例。
• 记录：
  • domain + plan
  • 当前计费周期（开始时间/结束时间）
  • 实际生效的配额（可在 Plan 基础上对该域名单独 override）
  • 自定义价格/流量/功能

3.5 流量使用记录（Traffic Usage）

• 以 域名 + 日期 为粒度记录流量数据。
• 用于：
  • 展示流量图表
  • 计算是否超过“免费额度”和“套餐包含流量”
  • 计算超量费用

3.6 账单 / 订单（Invoice / Order）

• 对应一个计费周期或某一段用量的费用结果。
• 包含：
  • 基础套餐费用
  • 超量流量费用
  • 优惠/调整
  • 是否已支付

---

4. 功能模块（用户侧）

4.1 用户注册 / 登录 / 账号管理

需求：

• 用户可以通过邮箱注册账号。
• 登录支持：
  • 用户名 + 密码 或 邮箱 + 密码
• 验证码系统（预留，可以用简单图形验证码）。
• 用户中心页面：
  • 修改密码
  • 查看登录历史（最近若干登录 IP、时间）
  • 管理个人信息（名称、联系方式）

4.2 域名列表 & 概览

• 页面：/domains/
• 展示内容：
  • 域名名称
  • 当前套餐名称
  • 本月已用流量 / 当前月度可用流量
  • 状态（未接入 / DNS 未生效 / 正常 / 超额 / 暂停）
• 支持操作：
  • 添加新域名
  • 进入域名详情
  • 删除/停用域名（逻辑删除或状态标记）

4.3 添加域名流程（CNAME 接入向导）

页面流程（可以拆成一个页面多步骤）：

1. 用户输入域名（example.com）
2. 选择接入子域名（可填多个，如 www.example.com、static.example.com）
3. 填写源站信息：
   • 源站地址（IP 或 源站域名）
   • 回源协议（HTTP/HTTPS）
   • 回源端口
4. 选择套餐（默认 Free 套餐，支持可选升级）
5. 创建后：
   • 后端调用 GoEdge Admin API 创建对应的 Server 与配置；
   • 生成 CNAME 目标，例如：www.example.com.cdn.platform.com
6. 页面展示：
   • 需要添加的 DNS 记录列表
   • 状态为“等待 DNS 配置”
   • 提供“立即检测 DNS 生效情况”的按钮（后台通过 DNS 查询判断）

4.4 域名详情页

• 路径示例：/domains/<domain_id>/
• 展示模块：

1. 概览

   • 当前套餐信息
   • 本月流量进度条（已用 vs 总额度）
   • 超量状态提示（如已超过套餐流量 X GB）

2. 统计（流量 / 请求）

   • 近 24 小时 / 7 天 / 30 天：
     • 流量图（MB/GB）
     • 请求数
     • HTTP 状态码分布（200/404/5xx）
     • 按地区/运营商分布（若 GoEdge 支持）

3. 接入信息

   • 当前接入的子域名和对应的 CNAME 记录
   • DNS 状态

4. 功能设置（视套餐决定是否可见/可编辑）

   • SSL/TLS 设置
   • 缓存规则
   • WAF 总开关
   • IP 黑白名单
   • 路径规则（简单页面规则）

所有修改类操作都通过 Django 视图调用 GoEdge Admin API 更新配置。

4.5 套餐列表 & 升级

• 页面：/plans/
• 展示所有 对用户公开的套餐，包括：
  • 套餐名称、月费
  • 每域名包含流量
  • 超量单价
  • 功能对比（表格形式）
• 在域名详情页可以：
  • 点击「升级套餐」
  • 跳转到套餐列表，选中一个 Plan → 后端进行升级逻辑（仅变更套餐记录，计费逻辑后续执行）

支付可先不做实际第三方接口，预留订单记录和“标记为已支付”的操作。

4.6 账单 / 费用

• 页面：/billing/
• 用户可查看：
  • 历史账单列表：时间区间、金额、状态
  • 每个账单详情：
    • 流量用量明细（按域名）
    • 超量部分计算方式

样式可以简单先实现，支付流程在后端逻辑中预留钩子。

---

5. 功能模块（管理员后台）

5.1 使用 Django Admin 的基础管理

• 启用 Django Admin，并注册模型：
  • 用户管理
  • 域名管理
  • 套餐管理
  • 域名套餐实例（DomainPlan/Subscription）
  • 流量记录
  • 账单/订单

5.2 自定义管理面板（独立于 admin site 的运营后台）

目的：提供一个比 Django Admin 更贴合业务的运营控制台。

可能路径：/admin-panel/（与 Django admin 区分）

功能：

5.2.1 全局系统设置

• 例如 SystemSettings 表，对应的配置项：
  • default_free_traffic_gb_per_domain（默认每域名每月免费流量，默认 15）
  • 默认超量策略（超量是否允许访问、是否限速、是否自动停服）
  • GoEdge API 地址 + 管理员 X-Edge-Access-Token
  • 默认 CNAME 目标域名模板（如 <subdomain>.cdn.xxx.com）

5.2.2 套餐管理（Plans）

• 新增/编辑/删除套餐：
  • 套餐名称、描述
  • 月费（每域名月费）
  • 每域名包含流量（GB）
  • 超量单价（元/GB）
  • 功能开关（布尔或 JSON 配置）：
    • 启用 WAF（是/否）
    • 是否支持自定义 SSL 证书
    • 是否支持实时日志
    • 是否支持 HTTP/3
    • 是否支持 WebSocket
    • 是否支持自定义规则（页面规则数量上限）
  • 可见性：
    • 是否对普通用户展示
    • 是否允许新购
    • 是否允许续费
    • 是否只允许管理员手动分配

5.2.3 用户与域名管理

• 用户列表：
  • 查看用户基本信息、注册时间、状态
  • 查看该用户下所有域名
• 域名列表：
  • 按域名搜索、按用户过滤
  • 查看当前使用的套餐、用量、状态
  • 操作：
    • 手动切换套餐
    • 为该域名增加 额外的免费流量额度（本周期）
    • 为该域名设置 自定义超量单价
    • 暂停/恢复域名
    • 查看与 GoEdge 的映射关系（serverId / clusterId 等）

5.2.4 免费流量与配额调整

• 支持对以下层级做手动调整：

  1. 全局默认（所有新域名默认免费 15GB）
  2. 某个套餐的包含流量
  3. 某个用户的默认免费额度（该用户新添加的域名都使用这个值）
  4. 某个具体域名在当前周期的 个人额外赠送流量

• 在管理面板中应有页面：

  • 显示每个域名：
    • 基础套餐流量
    • 全局默认调整
    • 用户层级额外
    • 域名本身额外
  • 以及最终计算出的“本周期可用总免费流量”。

5.2.5 计费与账单管理

• 账单列表：
  • 账单编号、用户、计费周期、总金额、是否已支付
• 支持：
  • 手动标记账单为已支付
  • 重新生成某个周期的账单（用于调试或运营）
  • 对超量部分进行 人工减免或加价（在账单上增加调账项目）

5.2.6 运维监控 & 风控（可分阶段实现）

• 简单版本：
  • 全平台每日总流量曲线
  • 域名按流量排序的 Top N 列表
• 进一步：
  • 配置“异常流量检测阈值”（例如当日流量超过过去 7 日平均的 3 倍）→ 标记异常域名

---

6. 数据库设计（概要说明）

这里仅做表与字段的概念说明，具体字段类型和索引由 AI Agent 在实现时按 MySQL 习惯设计。

6.1 用户相关

• users（可扩展 Django User 或自定义）

  • id
  • username
  • email
  • password_hash
  • is_active
  • is_staff / is_superuser
  • created_at, updated_at

• user_profile（可选扩展）

  • user_id (FK)
  • display_name
  • contact_phone
  • default_free_traffic_gb_per_domain_override（用户级默认免费流量覆盖值）

6.2 域名与接入

• domains

  • id
  • user_id (FK)
  • name（example.com）
  • status（pending_dns / active / suspended / deleted）
  • current_plan_id (FK → plans)
  • current_cycle_start
  • current_cycle_end
  • cname_targets（JSON，子域名与 CNAME 目标映射）
  • origin_config（JSON：源站地址/端口/协议等）
  • edge_server_id（在 GoEdge 中的 serverId）
  • created_at, updated_at

• domain_overrides（域名级别的配额/价格/功能覆盖，可合并到 domains 里）

  • domain_id (FK)
  • extra_free_traffic_gb_current_cycle（本周期额外赠送的免费流量）
  • custom_overage_price_per_gb
  • custom_features (JSON)
  • note

6.3 套餐 & 功能

• plans

  • id
  • name
  • description
  • billing_mode（per_domain_monthly）
  • base_price_per_domain
  • included_traffic_gb_per_domain
  • overage_price_per_gb
  • allow_overage（是否允许超量计费）
  • is_active
  • is_public
  • allow_new_purchase
  • allow_renew
  • created_at, updated_at

• plan_features（或直接用 JSON 存在 plans 中）

  • plan_id
  • key（如 waf_enabled、http3_enabled 等）
  • value（bool/int/string）

6.4 流量统计与计费

• domain_traffic_daily

  • id
  • domain_id (FK)
  • day（日期）
  • bytes
  • peak_bandwidth_mbps
  • created_at

• invoices

  • id
  • user_id
  • period_start
  • period_end
  • amount_plan_total（该周期所有域名套餐费用之和）
  • amount_overage_total
  • amount_adjustment（手工调整）
  • amount_total
  • status（unpaid / paid / cancelled）
  • created_at, paid_at

• invoice_items

  • id
  • invoice_id (FK)
  • domain_id (FK)
  • description（如“基础套餐费用”、“超量流量费用”等）
  • quantity（如 GB 数）
  • unit_price
  • amount

---

7. 业务流程说明（供实现时参考）

7.1 域名接入流程

1. 用户登录 → 添加域名 → 填写源站 → 选择套餐 → 创建域名记录 + 调 GoEdge 创建 Server
2. 系统生成 CNAME 目标 → 显示给用户
3. 用户配置 DNS → 前端提供“检测”按钮 → 后端通过 DNS 查询判断已生效
4. DNS 生效后，域名状态从 pending_dns → active，开始正式计流量。

7.2 计费周期与流量统计（按月）

1. 每天定时任务，从 GoEdge 统计 API 拉各域名的流量/请求数据，写入 domain_traffic_daily。

2. 每个域名有自己的计费周期（默认按自然月，也可按首次接入日算周期）。

3. 周期结束时，后台任务：

   • 计算该周期每个域名总流量
   • 对比“免费/套餐包含流量”：
     • 未超出 → 只收套餐费
     • 超出 → 套餐费 + 超量*单价
   • 生成 invoice 和 invoice_items 记录。

4. 对于未支付账单，可根据策略：

   • 在下一周期开始前停止所有域名（状态为 suspended）
   • 或只允许免费额度，超出部分阻断。

---

8. 界面与前端要求（Django + Bootstrap）

• 全站使用 Django 模板 + Bootstrap 布局：
  • 顶部导航：登录用户信息、域名列表入口、套餐、账单入口
  • 左侧在“域名详情页”使用类似 Cloudflare 的菜单列表（概览 / 分析 / SSL / 缓存 / 防火墙 / 设置）
• 表格和列表使用 Bootstrap Table 风格。
• 表单使用 CSRF 保护。
• 操作类按钮（如“升级套餐”、“暂停域名”）需二次确认弹窗。

---

9. 安全与权限

• 使用 Django Auth + login_required 装饰器保护用户页面。
• 管理后台分两套：
  • Django Admin（仅超级用户访问）
  • 自定义运营面板 /admin-panel/（限 staff 与具有相应权限的用户）
• 所有与 GoEdge API 交互的操作仅在后端进行，前端不暴露任何 GoEdge Access Token。
• 重要操作（删除域名、切换套餐、调账等）写「操作日志表」，记录操作人、时间、变更内容。

---

10. 可扩展点（后续版本预留）

• 支付功能集成（支付宝 / 微信 / Stripe 等）基于易支付：
  • 暂时只定义订单、账单结构，后续接入支付网关。
• 工单系统（Ticket）

---

AI Agent 实施重点：

• 先完成基础模型（用户 / 域名 / 套餐 / 流量 / 账单）和管理后台结构。
• 实现「添加域名 → 生成 CNAME → 拉取流量 → 生成账单」完整闭环。
• 前端使用 Django 模板 + Bootstrap 提供一个简单但清晰的 Cloudflare 风格面板。