# Team Card Web 功能文档

本文档面向部署者、运营人员和客服人员，说明系统能做什么、怎么使用、关键配置在哪里。

## 1. 系统定位

Team Card Web 是一个 Go + MySQL 的账号卡密兑换系统。后台导入账号库存后，运营人员按“每张卡密绑定几个账号”生成卡密；用户拿到卡密后，可以在前台兑换并下载所需格式的 ZIP，也可以用同一张卡密查询绑定邮箱里的验证码。

核心目标：

- 用户端尽量简单：输入卡密即可下载和接码。
- 运营端集中管理：导入账号、发卡、看库存、查下载日志、查 IP。
- 接码无需用户注册第三方邮箱站：服务端用内置邮箱站账号代理查询。
- 支持大客户：批量卡密下载、批量接码 API、重复下载记录。

## 2. 角色与入口

| 角色 | 入口 | 说明 |
| --- | --- | --- |
| 买家/用户 | `/` | 输入卡密，确认账号数量，选择格式下载 ZIP |
| 买家/用户 | `/mail?code=卡密&email=邮箱` | 使用卡密查询绑定邮箱验证码 |
| 买家/用户 | `/mail/batch` | 批量输入卡密查询验证码 |
| 对接方 | `/api/mail`、`/api/mail/batch` | JSON 接码接口 |
| 管理员 | `/admin/login` | 登录后台 |
| 管理员 | `/admin` | 上传账号、生成卡密、查看库存和下载日志 |
| 首次部署者 | `/install` | 首次安装，写入数据库和后台配置 |

## 3. 账号导入

后台支持上传单个 JSON 文件，也支持多文件批量上传。系统会自动识别以下结构：

- 单个账号对象
- 账号对象数组
- 包含 `accounts` 字段的对象
- 多层嵌套结构中的账号对象

推荐导入格式：

```json
{
  "phone": "PHONE",
  "email": "user@example.com",
  "password": "GPT_PASSWORD",
  "chatgpt_account_id": "ACCOUNT_ID",
  "plan_type": "free",
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "id_token": "ID_TOKEN",
  "expires_in": 864000,
  "auth_code": "AUTH_CODE",
  "state": "STATE"
}
```

字段说明：

| 字段 | 用途 |
| --- | --- |
| `email` | 默认作为账号邮箱和接码绑定邮箱 |
| `password` | GPT 账号密码，部分导出格式会使用 |
| `chatgpt_account_id` | ChatGPT 账号 ID |
| `plan_type` | 套餐类型，例如 `free` |
| `access_token` | OpenAI/ChatGPT 访问令牌 |
| `refresh_token` | 刷新令牌 |
| `id_token` | 身份令牌 |
| `phone`、`auth_code`、`state` | 保留原始信息，按格式需要导出 |

如果账号数据里有 `mailbox.email`、`email_account.email` 或 `extra.email_account.email`，系统会优先用这些字段作为接码邮箱；否则使用顶层 `email`。

## 4. 库存和卡密

账号导入后默认状态为 `available`。生成卡密时，系统会在数据库事务中锁定库存，把对应账号改为 `reserved` 并绑定到卡密。

卡密状态：

| 状态 | 含义 |
| --- | --- |
| `unused` | 已生成，尚未下载 |
| `redeemed` | 已至少下载一次 |

账号状态：

| 状态 | 含义 |
| --- | --- |
| `available` | 可售库存 |
| `reserved` | 已绑定卡密，等待用户下载 |
| `redeemed` | 已随卡密下载 |

生成卡密限制：

- 单张卡密至少绑定 1 个账号。
- 单张卡密最多绑定 10000 个账号。
- 单次最多生成 1000 张卡密。
- 如果可用库存不足，生成会失败并提示当前库存。

## 5. 用户兑换和下载

用户打开 `/` 后输入卡密：

1. 系统校验卡密是否存在。
2. 展示该卡密绑定的账号数量。
3. 展示可用导出格式。
4. 用户选择格式并下载 ZIP。

下载规则：

- 卡密可以重复下载。
- 首次下载会把卡密和账号状态改为 `redeemed`。
- 每次下载都会新增一条下载记录。
- 每次下载都会累加 `download_count`。
- 首次兑换时间不会被重复下载覆盖。
- 后台可以按卡密、IP、格式、备注查询下载记录。

## 6. 支持的导出格式

| 前台显示值 | 内部格式 | 输出说明 |
| --- | --- | --- |
| `sub2_json` | `sub2api` | Sub2API JSON，包含 `accounts` 和 `proxies` |
| `cpa_json` | `cpa` | CPA JSON；多账号时每个账号拆成独立 JSON |
| `codexManager_json` | `codexmanager` | Codex Manager JSON；多账号时每个账号拆成独立 JSON |
| `Cockpit Tools JSON` | `cockpit` | Cockpit Tools JSON |
| `batch_oauth_json` | `batchoauth` | 批量 OAuth 导入 JSON |
| `9router` | `9router` | 9router auth 数据 |
| `Codex auth.json` | `codex` | Codex `auth.json` |
| `AxonHub auth.json` | `axonhub` | AxonHub `auth.json` |

ZIP 内额外文件：

- 如果账号有邮箱字段，ZIP 会包含 `_mail-receive.txt`。
- 该文件会列出卡密、绑定邮箱和站内接码链接。

## 7. 接码功能

接码功能的授权方式是卡密本身。用户不需要第三方邮箱站账号。

单个接码：

- 页面：`/mail?code=卡密&email=可选邮箱`
- API：`/api/mail`

批量接码：

- 页面：`/mail/batch`
- API：`/api/mail/batch`
- 批量接口最多处理 2000 张卡密。
- 批量查询会复用一次邮箱列表，并按邮箱缓存查信结果，适合大客户批量查询。

接码查询逻辑：

1. 校验卡密是否存在。
2. 获取卡密绑定账号里的邮箱。
3. 如果请求指定 `email`，校验该邮箱是否属于此卡密。
4. 服务端登录配置好的邮箱站账号。
5. 拉取邮箱列表并找到对应邮箱 ID。
6. 触发邮箱站查信。
7. 拉取邮件记录。
8. 优先提取“验证码 / 登录代码 / verification code / login code”类邮件中的验证码。
9. 过滤 `000000` 这类占位数字，避免误取登录提醒邮件里的无效数字。

## 8. 后台功能

后台 `/admin` 包含以下区域：

- 库存统计：可售账号、已绑定账号、已下载账号、未下载卡密、已下载卡密。
- 上传账号：上传单个 JSON 文件。
- 批量上传：一次上传多个 JSON 文件。
- 生成卡密：设置每张卡密绑定账号数、生成张数、备注。
- 最近生成卡密：生成后展示本批次卡密，便于复制。
- 卡密列表：查看卡密、绑定数量、状态、下载次数、下载 IP、创建时间、下载时间、备注。
- 账号库存：查看账号名、状态、绑定卡密 ID、上传批次、创建时间、下载时间。
- 下载记录：查看卡密、格式、账号数量、下载时间、下载 IP。

后台查询：

- 卡密列表支持按卡密、下载 IP、备注、格式搜索。
- 下载记录支持按卡密、下载 IP、格式搜索。

## 9. 主要配置

部署配置来自环境变量或 `.env` 文件。

| 配置 | 说明 |
| --- | --- |
| `ADDR` | HTTP 监听地址，默认 `:8001` |
| `DB_HOST` | MySQL 主机 |
| `DB_PORT` | MySQL 端口 |
| `DB_NAME` | MySQL 数据库名 |
| `DB_USER` | MySQL 用户名 |
| `DB_PASS` | MySQL 密码 |
| `ADMIN_USERNAME` | 后台管理员用户名 |
| `ADMIN_PASSWORD_HASH` | 后台密码 bcrypt 哈希 |
| `ADMIN_PASSWORD` | 后台明文初始密码；启动时生成哈希使用 |
| `SESSION_SECRET` | Session 加密密钥 |
| `TZ` | 时区，默认 `Asia/Shanghai` |
| `UPLOAD_MAX_BYTES` | 单个上传文件大小限制，默认 10MB |
| `PAGE_SIZE` | 后台分页大小，默认 20 |
| `MAIL_SITE_BASE_URL` | 邮箱站地址，默认 `https://mail.kyon888.top` |
| `MAIL_SITE_TOKEN` | 邮箱站 Bearer Token，优先级最高 |
| `MAIL_SITE_USERNAME` | 邮箱站登录用户名 |
| `MAIL_SITE_PASSWORD` | 邮箱站登录密码 |

邮箱站配置优先级：

1. 如果设置 `MAIL_SITE_TOKEN`，直接使用该 token。
2. 否则使用 `MAIL_SITE_USERNAME` / `MAIL_SITE_PASSWORD` 登录。
3. 登录 token 在服务端缓存 50 分钟。

## 10. 部署方式

Docker 部署：

```bash
docker compose up -d --build
```

查看日志：

```bash
docker compose logs -f app
```

重启服务：

```bash
docker compose restart app
```

停止服务：

```bash
docker compose down
```

数据保存在 Docker volume `db_data` 中。迁移或重装时不要删除该 volume，除非确认不再需要旧数据。

## 11. 常见问题

### 卡密能否重复下载？

可以。重复下载会生成新的下载记录，并累加下载次数。

### 接码为什么查不到邮箱？

常见原因：

- 该卡密没有绑定包含邮箱字段的账号。
- 请求里指定的 `email` 不属于该卡密。
- 邮箱站账号下没有该邮箱。
- 邮箱站暂时没有拉到新邮件。

### 接码 API 是否需要后台登录？

不需要。接码 API 使用卡密授权。

### 后台上传文件大小限制是多少？

默认单文件 10MB，可通过 `UPLOAD_MAX_BYTES` 调整。

### 旧 PHP 文件还需要部署吗？

不需要。Go 版部署只需要 Go 源码、模板、静态文件、Dockerfile、docker-compose.yml 和 `.env`。