# 路由与页面结构

> 本项目含三类界面：**用户端页面**（Django 模板 SSR，终端用户自助）、**对外 HTTP API**（DRF，程序调用）、**运营后台**（django-admin）。本文约定各自路由与页面职责。
> 接口请求/响应合约以 [`api.md`](api.md) 为准。

## 用户端页面（Django 模板 SSR，session 登录）

| 路由 | 方法 | 职责 | 鉴权 |
| --- | --- | --- | --- |
| `/signup` `/login` `/logout` | GET/POST | 自助注册（邮箱验证）/登录/登出（Django auth/allauth） | 公开 |
| `/dashboard` | GET | 个人中心：剩余点数、充值总额、快捷入口 | session |
| `/recharge` | GET/POST | 发起充值：选金额→展示支付二维码→轮询到账 | session |
| `/records/recharge` | GET | 充值记录 | session |
| `/records/usage` | GET | 点数使用（消费/调用）记录 | session |
| `/apikeys` | GET/POST | API Key 管理：列表 / 生成 / 删除（明文只显示一次） | session |

## API 路由（对外，DRF）

| 路由 | 方法 | 职责 | 鉴权 |
| --- | --- | --- | --- |
| `/api/v1/generate/title` | POST | 生成标题 | API Key |
| `/api/v1/generate/image` | POST | 生成图片（同步） | API Key |
| `/api/v1/balance` | GET | 查询点数余额 | API Key |
| `/api/v1/recharge/create` | POST | 用户端发起充值（weixin/alipay），下单取二维码 | Session（用户端） |
| `/api/v1/recharge/status` | GET | 轮询订单状态（前端每秒） | Session（用户端） |
| `/api/v1/recharge/callback/wechat` | POST | 微信 V3 异步回调 | 验签（`@csrf_exempt`） |
| `/api/v1/recharge/callback/alipay` | POST | 支付宝异步回调 | 验签（`@csrf_exempt`） |

## 运营后台（django-admin，`/admin/`）

后台用 Django Session 登录，按模型注册 Admin：

| 管理项 | 对应模型 | 运营能做什么 |
| --- | --- | --- |
| 注册用户 | User | 查看/禁用注册用户；查看其钱包点数余额 |
| 点数钱包 | UserWallet | 查看余额；手工调整点数（必填原因，经计费层写流水，不直接改字段） |
| API Key | ApiKey | 查看 / 吊销用户的 Key（脱敏显示 prefix，不回显明文） |
| 计费规则 | PricingRule | 配置「操作类型 × 能力别名（+ 可选分辨率）→ 点数单价」 |
| 汇率 | ExchangeRate | 配置金额→点数汇率 |
| 充值订单 | RechargeOrder | 检索订单、查看状态/金额/入账点数/支付流水号 |
| 点数流水 | PointsLedger | 检索充值/消费/调整/冲正流水（只读，对账用） |
| 调用记录 | CallRecord | 按账号/时间/状态检索调用、查看别名/实际模型/消耗/错误（只读） |
| 模型配置 | AiModel | 维护上游模型（url/model/api_key[加密脱敏]/api_type/capabilities/timeout） |
| 能力别名 | ModelAlias | 维护对外别名 → 具体模型的映射；换供应商在此改指向 |

## 后台职责约定

### 用户与账号管理

- 用户自助注册；API Key 由用户在用户端自助生成（服务端生成、哈希存储、明文只显示一次），运营侧只能查看 prefix / 吊销，不回显明文。
- 禁用用户或吊销 Key 后，相关调用一律 403 / 401。
- 手工调整点数必须经计费层方法（写 `PointsLedger`、锁 `UserWallet`），不允许直接编辑 `points_balance` 字段。

### 模型与别名管理

- AiModel 的 `api_key` 加密存储，列表/详情脱敏显示，不回显明文。
- 换供应商：改 `ModelAlias` 的指向即可，对外别名与计费规则不变。
- AiModel / ModelAlias / 密钥的变更需留痕（谁、何时、改了什么）。

### 流水 / 调用记录

- 只读列表，支持按账号、时间范围、类型/状态筛选与搜索。
- 不允许在后台修改或删除流水与调用记录（账目不可篡改）。

### 列表与检索

- 充值订单、流水、调用记录默认按时间倒序，提供账号与状态筛选。

## 导航规则

- 对外只暴露 `/api/v1/*`；`/admin/` 仅限运营，生产环境建议限制来源或加额外保护。
- 未授权访问 admin 跳转登录；API 未授权返回 401，不静默失败。