align API response format with maqt.top real specs: weapon-categories, weapons, schemes, schemes_aob, favorites check, encryption key derivation
This commit is contained in:
461
API.md
Normal file
461
API.md
Normal file
@@ -0,0 +1,461 @@
|
||||
# 码枪堂 weapon-tuner API 文档
|
||||
|
||||
> 来源：原版 `app.asar` 中 `dist/weapon-tuner.html` (v7.0.4)
|
||||
> BASE_URL: `https://maqt.top`
|
||||
> 复刻目标: `https://gch3n.online/delta`
|
||||
|
||||
---
|
||||
|
||||
## 全局约定
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| 基础路径 | `/api` |
|
||||
| 认证方式 | `Authorization: Bearer <JWT>` |
|
||||
| 加密算法 | AES-256-CBC |
|
||||
| 加密密钥 | `maqt-delta-force-2024-secret-key-32` |
|
||||
| 密钥派生 | SHA-256(KEY) → 32字节 AES key |
|
||||
| 密文格式 | `{ "encrypted": true, "iv": "hex", "data": "hex" }` |
|
||||
|
||||
### Unicode-safe Base64
|
||||
|
||||
```js
|
||||
function base64EncodeUnicode(str) {
|
||||
return btoa(encodeURIComponent(str).replace(/%([0-9A-F]{2})/g,
|
||||
function(match, p1) { return String.fromCharCode('0x' + p1); }));
|
||||
}
|
||||
```
|
||||
|
||||
### 响应加密（服务端可选）
|
||||
|
||||
当响应中 `encrypted` 为 `true` 时，客户端执行：
|
||||
```
|
||||
hex(iv) → ArrayBuffer
|
||||
hex(data) → ArrayBuffer
|
||||
SHA-256(KEY) → AES-CBC.decrypt(iv, data) → UTF-8 → JSON.parse
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 端点列表
|
||||
|
||||
### 1. 获取武器分类
|
||||
|
||||
```
|
||||
GET /api/weapon-categories
|
||||
```
|
||||
|
||||
**响应：** （注意：部分条目缺 `category` 字段，前端实际用索引区分）
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{ "category": "突击步枪", "scheme_count": 887 },
|
||||
{ "scheme_count": 353 },
|
||||
{ "category": "射手步枪", "scheme_count": 260 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取武器列表
|
||||
|
||||
```
|
||||
GET /api/weapons → 全部
|
||||
GET /api/weapons?category=突击步枪 → 按分类（传中文名！）
|
||||
```
|
||||
|
||||
**Query:**
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `category` | 否 | **中文分类名**如 `突击步枪`，空则返回全部 |
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"weapon_name": "M7",
|
||||
"display_name": "M7战斗步枪",
|
||||
"category": "突击步枪",
|
||||
"use_count": 143
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
GET /api/weapon-categories
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{ "category": "AR", "display_name": "突击步枪" },
|
||||
{ "category": "SMG", "display_name": "冲锋枪" },
|
||||
{ "category": "SR", "display_name": "狙击步枪" },
|
||||
{ "category": "LMG", "display_name": "轻机枪" },
|
||||
{ "category": "SG", "display_name": "霰弹枪" },
|
||||
{ "category": "Pistol", "display_name": "手枪" },
|
||||
{ "category": "Launcher", "display_name": "发射器" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 获取武器列表
|
||||
|
||||
```
|
||||
GET /api/weapons
|
||||
GET /api/weapons?category=AR
|
||||
```
|
||||
|
||||
**Query:**
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `category` | 否 | 分类代码，例如 `AR`、`SMG`。空则返回全部 |
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{ "display_name": "M4A1" },
|
||||
{ "display_name": "AK-47" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 获取方案列表
|
||||
|
||||
```
|
||||
GET /api/schemes → 烽火地带
|
||||
GET /api/schemes_aob → 全面战场（AOB）
|
||||
GET /api/favorites → 我的收藏（需登录）
|
||||
```
|
||||
|
||||
**Query:**
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `sort` | 是 | `hot` / `new` |
|
||||
| `page` | 是 | 页码，从 1 开始 |
|
||||
| `limit` | 是 | 固定 `12` |
|
||||
| `weaponCategory` | 否 | 武器分类中文名，如 `突击步枪` |
|
||||
| `weaponName` | 否 | 武器中文显示名，如 `M4A1` |
|
||||
| `minPrice` | 否 | 最低价格（万） |
|
||||
| `maxPrice` | 否 | 最高价格（万） |
|
||||
| `search` | 否 | 搜索关键词 |
|
||||
| `category` | 否 | `favorites` 模式用此字段传分类 |
|
||||
|
||||
**收藏模式额外 Headers：** `Authorization: Bearer <token>`
|
||||
|
||||
**响应（解密后）：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": 1237,
|
||||
"user_id": 1006,
|
||||
"username": "揽贝电竞-迟到了",
|
||||
"avatar": "https://...",
|
||||
"description": "M7满改方案",
|
||||
"scheme_content": "M7战斗步枪-烽火地带-6I17GK0059L1ICRB4NQP4",
|
||||
"category": "突击步枪",
|
||||
"weapon_name": "M7战斗步枪",
|
||||
"price": "97W",
|
||||
"tags": [],
|
||||
"uses": 10299,
|
||||
"total_historical_uses": 10298,
|
||||
"status": "normal",
|
||||
"source": 1,
|
||||
"created_at": "2025-11-20T16:00:00.000Z",
|
||||
"updated_at": "2026-05-23T17:09:11.000Z",
|
||||
"partner_type": "club",
|
||||
"partner_level": "bronze",
|
||||
"partner_badge": "揽贝电竞",
|
||||
"partner_logo": "https://...",
|
||||
"social_link": null
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 12,
|
||||
"hasMore": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **注意：** `price` 是字符串含 `"W"` 单位（如 `"97W"`），`pagination` 只有 `{page,limit,hasMore}` 不返回 total。schemes_aob 模式不含 price 字段。
|
||||
|
||||
**响应（加密）：**
|
||||
```json
|
||||
{
|
||||
"encrypted": true,
|
||||
"iv": "a1b2c3d4...",
|
||||
"data": "e5f6a7b8..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 发布方案
|
||||
|
||||
```
|
||||
POST /api/schemes → 烽火地带
|
||||
POST /api/schemes_aob → 全面战场
|
||||
```
|
||||
|
||||
**Headers:**
|
||||
| 键 | 值 |
|
||||
|----|-----|
|
||||
| `Content-Type` | `application/json` |
|
||||
| `x-user-info` | `Base64({ id: number, username: string })` |
|
||||
|
||||
**Body：**
|
||||
```json
|
||||
{
|
||||
"description": "方案描述（≤50字）",
|
||||
"category": "武器分类中文名，如 突击步枪",
|
||||
"weaponName": "武器中文名，如 M4A1",
|
||||
"scheme": "配置代码字符串",
|
||||
"tags": [],
|
||||
"price": 15
|
||||
}
|
||||
```
|
||||
- `price` 仅烽火模式需要，范围 1-999
|
||||
- `tags` 目前传空数组
|
||||
|
||||
**响应（成功）：**
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
**响应（含敏感词）：**
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "内容包含敏感词",
|
||||
"sensitiveWords": ["词1", "词2"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 记录方案使用次数
|
||||
|
||||
```
|
||||
POST /api/schemes/{schemeId}/use
|
||||
POST /api/schemes_aob/{schemeId}/use
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "使用次数已记录"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. 举报方案
|
||||
|
||||
```
|
||||
POST /api/schemes/{schemeId}/report
|
||||
POST /api/schemes_aob/{schemeId}/report
|
||||
```
|
||||
|
||||
**Headers:**
|
||||
| 键 | 值 |
|
||||
|----|-----|
|
||||
| `Content-Type` | `application/json` |
|
||||
| `Authorization` | `Bearer <token>` |
|
||||
|
||||
**Body：**
|
||||
```json
|
||||
{
|
||||
"reason": "invalid",
|
||||
"description": "详细举报说明（≤200字）"
|
||||
}
|
||||
```
|
||||
|
||||
`reason` 枚举：
|
||||
- `invalid` — 方案失效
|
||||
- `inappropriate` — 内容不当
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. 收藏操作
|
||||
|
||||
#### 7.1 添加收藏
|
||||
|
||||
```
|
||||
POST /api/favorites
|
||||
```
|
||||
|
||||
**Headers:**
|
||||
| 键 | 值 |
|
||||
|----|-----|
|
||||
| `Content-Type` | `application/json` |
|
||||
| `Authorization` | `Bearer <token>` |
|
||||
|
||||
**Body：**
|
||||
```json
|
||||
{
|
||||
"schemeId": "方案ID",
|
||||
"source": "烽火地带"
|
||||
}
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"alreadyFavorited": false
|
||||
}
|
||||
```
|
||||
|
||||
#### 7.2 取消收藏
|
||||
|
||||
```
|
||||
DELETE /api/favorites/{schemeId}?source={source}
|
||||
```
|
||||
|
||||
`source`: `烽火地带` 或 `全面战场`
|
||||
|
||||
**Headers:** `Authorization: Bearer <token>`
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
#### 7.3 检查收藏状态
|
||||
|
||||
```
|
||||
GET /api/favorites/check?schemeId={id}&source={source}
|
||||
```
|
||||
|
||||
**Headers:** `Authorization: Bearer <token>`
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"isFavorited": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. 广告
|
||||
|
||||
#### 8.1 获取广告列表
|
||||
|
||||
```
|
||||
GET /api/adverts/list
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": "string",
|
||||
"author": "广告主昵称",
|
||||
"avatar": "头像URL",
|
||||
"shareTime": "ISO 8601",
|
||||
"title": "广告标题",
|
||||
"description": "简短描述",
|
||||
"image_url": "图片URL（可选）",
|
||||
"link_url": "跳转链接",
|
||||
"isVip": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 8.2 记录广告点击
|
||||
|
||||
```
|
||||
POST /api/adverts/{advertId}/click
|
||||
```
|
||||
|
||||
**响应：**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "点击已记录"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. 旧版武器分类（逐个获取）
|
||||
|
||||
```
|
||||
GET /api/category/AR
|
||||
GET /api/category/SMG
|
||||
GET /api/category/SR
|
||||
GET /api/category/LMG
|
||||
GET /api/category/SG
|
||||
GET /api/category/Pistol
|
||||
GET /api/category/Launcher
|
||||
```
|
||||
|
||||
**响应：** 直接返回武器对象数组（不包裹 `success`）：
|
||||
```json
|
||||
[
|
||||
{ "display_name": "M4A1" },
|
||||
{ "display_name": "AK-47" }
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 分类代码映射
|
||||
|
||||
| 代码 | 中文名 |
|
||||
|------|--------|
|
||||
| `AR` | 突击步枪 |
|
||||
| `SMG` | 冲锋枪 |
|
||||
| `SR` | 狙击步枪 |
|
||||
| `LMG` | 轻机枪 |
|
||||
| `SG` | 霰弹枪 |
|
||||
| `Pistol` | 手枪 |
|
||||
| `Launcher` | 发射器 |
|
||||
|
||||
---
|
||||
|
||||
## 前端状态变量
|
||||
|
||||
```js
|
||||
let currentMode = 'schemes'; // 'schemes' | 'schemes_aob' | 'favorites'
|
||||
let currentSort = 'hot'; // 'hot' | 'new'
|
||||
let currentPage = 1;
|
||||
let currentFilters = {
|
||||
weaponCategory: '', // 分类代码如 'AR'
|
||||
weaponName: '', // 武器中文显示名
|
||||
minPrice: '', // 字符串
|
||||
maxPrice: '',
|
||||
search: ''
|
||||
};
|
||||
let hasMore = true;
|
||||
let userToken = ''; // JWT token
|
||||
```
|
||||
Reference in New Issue
Block a user