mqsrv/API.md

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

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 字段，前端实际用索引区分）

{
  "success": true,
  "data": [
    { "category": "突击步枪", "scheme_count": 887 },
    { "scheme_count": 353 },
    { "category": "射手步枪", "scheme_count": 260 }
  ]
}

2. 获取武器列表

GET /api/weapons                    → 全部
GET /api/weapons?category=突击步枪   → 按分类（传中文名！）

Query:

参数	必填	说明
category	否	中文分类名如 突击步枪，空则返回全部

响应：

{
  "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。空则返回全部

响应：

{
  "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>

响应（解密后）：

{
  "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 字段。

响应（加密）：

{
  "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：

{
  "description": "方案描述（≤50字）",
  "category": "武器分类中文名，如 突击步枪",
  "weaponName": "武器中文名，如 M4A1",
  "scheme": "配置代码字符串",
  "tags": [],
  "price": 15
}

• price 仅烽火模式需要，范围 1-999
• tags 目前传空数组

响应（成功）：

{
  "success": true
}

响应（含敏感词）：

{
  "success": false,
  "message": "内容包含敏感词",
  "sensitiveWords": ["词1", "词2"]
}

---

5. 记录方案使用次数

POST /api/schemes/{schemeId}/use
POST /api/schemes_aob/{schemeId}/use

响应：

{
  "success": true,
  "message": "使用次数已记录"
}

---

6. 举报方案

POST /api/schemes/{schemeId}/report
POST /api/schemes_aob/{schemeId}/report

Headers:

键	值
Content-Type	application/json
Authorization	Bearer <token>

Body：

{
  "reason": "invalid",
  "description": "详细举报说明（≤200字）"
}

reason 枚举：

• invalid — 方案失效
• inappropriate — 内容不当

响应：

{
  "success": true
}

---

7. 收藏操作

7.1 添加收藏

POST /api/favorites

Headers:

键	值
Content-Type	application/json
Authorization	Bearer <token>

Body：

{
  "schemeId": "方案ID",
  "source": "烽火地带"
}

响应：

{
  "success": true,
  "alreadyFavorited": false
}

7.2 取消收藏

DELETE /api/favorites/{schemeId}?source={source}

source: 烽火地带 或 全面战场

Headers: Authorization: Bearer <token>

响应：

{
  "success": true
}

7.3 检查收藏状态

GET /api/favorites/check?schemeId={id}&source={source}

Headers: Authorization: Bearer <token>

响应：

{
  "isFavorited": true
}

---

8. 广告

8.1 获取广告列表

GET /api/adverts/list

响应：

{
  "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

响应：

{
  "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）：

[
  { "display_name": "M4A1" },
  { "display_name": "AK-47" }
]

---

分类代码映射

代码	中文名
AR	突击步枪
SMG	冲锋枪
SR	狙击步枪
LMG	轻机枪
SG	霰弹枪
Pistol	手枪
Launcher	发射器

---

前端状态变量

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