Files
CardAuth/README.md
T

600 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CardAuth - 卡密授权管理系统
一个轻量级的卡密(激活码)+ 机器授权管理系统,支持多项目管理、代理分销、在线支付购买,适用于软件授权、会员激活等场景。
## 技术栈
| 层 | 技术 |
|---|---|
| 后端 | PHP 7.4+ 自研框架(Router + Middleware + Controller) |
| 数据库 | MySQL 8.0+ |
| 前端 | Vue 3 + Element Plus + Pinia + ECharts |
| 构建 | Vite |
## 功能概览
### 角色体系
- **超级管理员**:全部权限,用户管理、项目管理、系统配置、操作日志
- **项目管理员**:仅管理指定项目(不会看到代理信息),可操作卡密、授权、订单
- **代理**:代理商城、卡密生成/导入(余额扣费)、授权管理,可发展下级代理
### 核心功能
- 项目与 API 密钥管理(每个项目独立密钥,API 鉴权)
- 商品/套餐管理(自定义时长、价格、代理价格)
- 卡密生成、批量导入、状态追踪
- 在线授权(直接创建授权,不依赖卡密;代理按代理价扣费)
- 代理余额体系(充值记录、扣费追溯、额度查询)
- 订单管理(代客手动完成 / 手动确认)
- 在线购买商城(公开页面,支持 epay/codepay 支付回调)
- 黑名单系统(机器码/IP 封禁,可配置封禁策略)
- SMTP 邮件通知(授权快到期自动发送提醒到联系人 QQ 邮箱)
- 仪表盘统计图表(收入趋势、授权趋势、套餐销售占比)
- 操作日志
### 内置页面
- `/` 仪表盘
- `/login` 管理员登录
- `/agent/login` 代理登录
- `/agent/register` 代理注册
- `/shop` 自助购买(公开页面)
## 快速开始
### 环境要求
- PHP 7.4+(需启用 PDO、PDO_MySQL)
- MySQL 8.0+
- Node.js 16+
### 1. 初始化数据库
```bash
mysql -u root -p < backend/database/schema.sql
```
### 2. 配置后端
```bash
cd backend
cp .env.example .env
# 编辑 .env 填入数据库信息
```
### 3. 启动
```bash
# 一键启动(前端 + 后端)
.\start.ps1
# 或分别启动
cd backend && php -S 0.0.0.0:8080 -t backend
cd frontend && npm install && npm run dev
```
### 4. 访问
- 管理后台:`http://localhost:3000`
- 代理登录:`http://localhost:3000/#/agent/login`
- 购买商城:`http://localhost:3000/#/shop`
### 5. 默认管理员
| 用户名 | 密码 |
|--------|------|
| admin | admin123456 |
## SMTP 邮件通知配置
在系统配置 -> SMTP邮件配置中填写 SMTP 信息,系统将自动在授权到期前 N 天发送提醒邮件到联系人的 QQ 邮箱(`contact_qq@qq.com`)。
### 定时任务 (Cron)
建议设置每 6 小时执行一次过期检查:
```bash
# Linux crontab
0 */6 * * * curl -s http://your-domain/api/cron/notify-expiring > /dev/null
# Windows 任务计划程序
curl -s http://your-domain/api/cron/notify-expiring
```
---
# API 文档
## 鉴权说明
| 类型 | 说明 |
|------|------|
| **JWT Token** | 登录后获取,请求头 `Authorization: Bearer <token>`,有效期 24 小时 |
| **API Key** | 项目密钥,仅用于授权验证接口,请求头 `X-Api-Key: <key>` |
| **公开接口** | 无需认证,有频率限制(60秒内 30 次) |
---
## 一、公开接口(无需认证)
### 1.1 查询授权状态(按机器人QQ)
```
GET /api/public/authorizations/query?bot_qq=123456789
```
**响应示例:**
```json
{
"code": 200,
"data": {
"bot_qq": "123456789",
"total": 2,
"active_count": 1,
"expired_count": 1,
"revoked_count": 0,
"has_valid_auth": true,
"list": [
{
"id": 1,
"card_key": "CA-XXXX-XXXX",
"project_name": "演示项目",
"bot_qq": "123456789",
"contact_qq": "987654321",
"contact_name": "张三",
"duration_days": 30,
"status": "active",
"authorized_at": "2026-01-01 12:00:00",
"expire_time": "2026-01-31 12:00:00",
"is_expired": false
}
]
}
}
```
### 1.2 验证授权有效性(客户端调用)
```
POST /api/public/authorizations/verify
Content-Type: application/json
{
"bot_qq": "123456789",
"card_key": "CA-XXXX-XXXX", // 可选
"contact_qq": "987654321" // 可选
}
```
**响应示例(有效):**
```json
{
"code": 200,
"data": {
"valid": true,
"bot_qq": "123456789",
"contact_qq": "987654321",
"card_key": "CA-XXXX-XXXX",
"project_name": "演示项目",
"expire_time": "2026-01-31 12:00:00",
"days_left": 20,
"has_valid_auth": true,
"message": "授权有效"
}
}
```
**响应示例(无效):**
```json
{
"code": 200,
"data": {
"valid": false,
"bot_qq": "123456789",
"has_valid_auth": false,
"message": "未找到有效授权"
}
}
```
### 1.3 API Key 授权验证
```
POST /api/public/verify
X-Api-Key: <项目的 API Key>
Content-Type: application/json
{
"bot_qq": "123456789",
"contact_qq": "987654321" // 可选
}
```
**响应格式同 1.2。**
### 1.4 获取项目列表(商城用)
```
GET /api/public/projects
```
### 1.5 获取项目套餐列表
```
GET /api/public/projects/{project_id}/card-types
```
### 1.6 创建订单
```
POST /api/public/orders
Content-Type: application/json
{
"project_id": 1,
"card_type_id": 1,
"amount": 29.90,
"pay_type": "wxpay",
"contact_qq": "987654321",
"bot_qq": "123456789",
"coupon_code": "" // 可选,优惠码
}
```
**响应示例:**
```json
{
"code": 200,
"data": {
"order_no": "2026062317530410859",
"pay_url": "https://pay.example.com/xxx",
"is_renew": false,
"contact_qq_warn": null,
"contact_qq": "987654321"
}
}
```
### 1.7 查询订单
```
GET /api/public/orders/query?order_no=2026062317530410859
```
---
## 二、认证接口
### 2.1 管理员登录
```
POST /api/auth/admin-login
Content-Type: application/json
{
"username": "admin",
"password": "admin123456"
}
```
**响应示例:**
```json
{
"code": 200,
"data": {
"token": "eyJ...",
"user": { "id": 1, "username": "admin", "role": "admin" }
}
}
```
### 2.2 代理登录
```
POST /api/auth/agent-login
Content-Type: application/json
{
"username": "agent001",
"password": "123456"
}
```
### 2.3 代理注册
```
POST /api/auth/agent-register
Content-Type: application/json
{
"username": "new_agent",
"password": "123456",
"nickname": "新代理"
}
```
### 2.4 刷新 Token
```
POST /api/auth/refresh
Authorization: Bearer <token>
```
### 2.5 获取当前用户信息
```
GET /api/auth/me
Authorization: Bearer <token>
```
---
## 三、仪表盘
### 3.1 仪表盘数据
```
GET /api/dashboard
Authorization: Bearer <token>
```
**响应包含:**
- 统计数字(项目数、卡密数、订单数、收入等)
- `order_trend`: 近 7 天订单趋势
- `revenue_trend_30`: 近 30 天收入趋势
- `auth_trend_30`: 近 30 天新增授权趋势
- `package_distribution`: 套餐销售占比
- `expiring_soon`: 即将过期授权数
---
## 四、项目与套餐管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/projects` | 项目列表 |
| GET | `/api/projects/all` | 全部项目(下拉用) |
| GET | `/api/projects/{id}` | 项目详情 |
| POST | `/api/projects` | 创建项目 |
| PUT | `/api/projects/{id}` | 更新项目 |
| DELETE | `/api/projects/{id}` | 删除项目 |
| POST | `/api/projects/{id}/regenerate-key` | 重新生成 API Key |
| GET | `/api/projects/{id}/card-types` | 某项目的套餐列表 |
| POST | `/api/projects/{id}/card-types` | 创建套餐 |
| PUT | `/api/projects/{id}/card-types/{typeId}` | 更新套餐 |
| DELETE | `/api/projects/{id}/card-types/{typeId}` | 删除套餐 |
| GET | `/api/products` | 全量商品列表 |
| GET | `/api/products/export` | 导出商品 |
### 创建项目
```
POST /api/projects
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "我的项目",
"description": "项目描述"
}
```
### 创建套餐
```
POST /api/projects/1/card-types
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "月卡",
"duration_days": 30,
"price": 29.90,
"agent_cost": 20.00,
"sort": 1,
"status": 1
}
```
---
## 五、卡密管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/cards` | 卡密列表(支持分页、筛选、排序) |
| GET | `/api/cards/stats` | 卡密统计 |
| GET | `/api/cards/{id}` | 卡密详情 |
| POST | `/api/cards/generate` | 批量生成卡密 |
| POST | `/api/cards/import` | 导入卡密 |
| POST | `/api/cards/batch-status` | 批量修改状态 |
| POST | `/api/cards/batch-delete` | 批量删除 |
| PATCH | `/api/cards/{id}/status` | 单个卡密启用/禁用 |
| GET | `/api/cards/export` | 导出卡密(CSV/Excel) |
### 生成卡密
```
POST /api/cards/generate
Authorization: Bearer <token>
Content-Type: application/json
{
"project_id": 1,
"card_type_id": 1,
"count": 100,
"prefix": "CA"
}
```
---
## 六、授权管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/authorizations` | 授权列表 |
| GET | `/api/authorizations/stats` | 授权统计 |
| GET | `/api/authorizations/{id}` | 授权详情 |
| POST | `/api/authorizations` | 新增授权 |
| PUT | `/api/authorizations/{id}/revoke` | 撤销授权 |
| DELETE | `/api/authorizations/{id}` | 删除授权 |
| POST | `/api/authorizations/batch-delete` | 批量删除 |
| GET | `/api/authorizations/export` | 导出授权 |
### 新增授权
```
POST /api/authorizations
Authorization: Bearer <token>
Content-Type: application/json
{
"project_id": 1,
"card_type_id": 1,
"bot_qq": "123456789",
"contact_qq": "987654321",
"contact_name": "张三"
}
```
**续费逻辑**:若 `bot_qq + contact_qq` 已存在活跃授权,自动续费延长过期时间。
### 撤销授权
```
PUT /api/authorizations/{id}/revoke
Authorization: Bearer <token>
Content-Type: application/json
{
"reason": "用户违规"
}
```
---
## 七、订单管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/orders` | 订单列表 |
| GET | `/api/orders/{id}` | 订单详情 |
| POST | `/api/orders/{id}/complete` | 手动完成订单 |
| GET | `/api/orders/export` | 导出订单 |
---
## 八、用户管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/users` | 用户列表 |
| GET | `/api/users/stats` | 用户统计 |
| POST | `/api/users` | 创建用户 |
| PUT | `/api/users/{id}` | 更新用户 |
| DELETE | `/api/users/{id}` | 删除用户 |
| POST | `/api/users/batch-delete` | 批量删除 |
| GET | `/api/users/export` | 导出用户 |
---
## 九、代理管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/agents` | 代理列表 |
| GET | `/api/agents/my-quota` | 当前代理额度 |
| POST | `/api/agents/recharge` | 充值额度 |
| POST | `/api/agents/adjust-quota` | 调整额度 |
| GET | `/api/agents/quota-logs` | 额度变动日志 |
| POST | `/api/agents/{id}/reset-password` | 重置代理密码 |
---
## 十、优惠券
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/coupons` | 优惠券列表 |
| POST | `/api/coupons` | 创建优惠券 |
| PUT | `/api/coupons/{id}` | 更新优惠券 |
| DELETE | `/api/coupons/{id}` | 删除优惠券 |
---
## 十一、黑名单
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/blacklists` | 黑名单列表 |
| POST | `/api/blacklists` | 添加黑名单 |
| POST | `/api/blacklists/batch` | 批量添加 |
| POST | `/api/blacklists/import` | 导入黑名单 |
| PUT | `/api/blacklists/{id}` | 更新黑名单 |
| DELETE | `/api/blacklists/{id}` | 删除黑名单 |
| POST | `/api/blacklists/batch-delete` | 批量删除 |
---
## 十二、系统配置
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/system/configs?keys=key1,key2` | 获取配置 |
| POST | `/api/system/configs` | 保存配置 |
| GET | `/api/system/smtp-config` | 获取 SMTP 配置 |
| POST | `/api/system/smtp-config` | 保存 SMTP 配置 |
| POST | `/api/system/test-smtp` | 发送测试邮件 |
| POST | `/api/system/notify-expiring` | 手动触发过期提醒 |
---
## 十三、定时任务
```
POST /api/cron/notify-expiring
GET /api/cron/notify-expiring
```
无需认证,检查即将过期的授权并向联系人 QQ 邮箱发送提醒。
---
## 错误码说明
| code | 说明 |
|------|------|
| 200 | 成功 |
| 400 | 参数错误 |
| 401 | 未登录 / Token 无效 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器错误 |
通用错误响应:
```json
{
"code": 400,
"message": "参数错误描述"
}
```
## 项目结构
```
card/
├── backend/ # PHP 后端
│ ├── app/
│ │ ├── Controllers/ # 控制器 (12 个模块)
│ │ ├── Core/ # 框架核心 (Router/Controller/Database/Middleware/Validator)
│ │ ├── Middleware/ # 中间件 (Auth/JWT/RateLimit/ApiKey/Blacklist/Role)
│ │ └── Services/ # 服务层 (Jwt/Blacklist/Permission/Snowflake)
│ ├── config/ # 配置文件
│ ├── database/ # SQL 与 Migration
│ └── routes/ # 路由定义
├── frontend/ # Vue 3 前端
│ └── src/
│ ├── api/ # 接口封装
│ ├── composables/ # 组合式函数
│ ├── router/ # 路由配置
│ ├── stores/ # Pinia 状态管理
│ └── views/ # 页面组件 (管理后台 + 代理 + 公开)
└── deploy/ # 部署配置 (Nginx + 宝塔)
```
## License
MIT