# 项目开发需求说明文档（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 风格面板。