# 码枪堂 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
```