chore: mqsrv backend

2026-05-09 00:52:04 +08:00
commit b84f111e8f
21 changed files with 4593 additions and 0 deletions
--- a/API_FULL_ANALYSIS.md
+++ b/API_FULL_ANALYSIS.md
@@ -0,0 +1,192 @@
+# 码枪堂 API 全线分析报告
+
+> 基于 Fiddler 抓包 ss3.saz（原版 API）+ ss4.saz（自定义服务器）对比
+
+---
+
+## 一、API 域名概览
+
+| 域名 | 用途 |
+|------|------|
+| `https://maqt.top/api/*` | 主业务 API |
+| `https://pop.maqt.top/api/*` | 弹窗广告 API |
+| `https://update.maqt.top/*` | 更新服务 |
+| `https://tuku.maqt.top/*` | 图片托管 |
+| `http://100.105.17.52:3001/api/*` | 自定义后端（解包版） |
+
+---
+
+## 二、完整 API 端点清单
+
+### 🔐 认证
+| 方法 | 端点 | 请求体 | 当前状态 |
+|------|------|--------|----------|
+| POST | `/api/login` | `{"username","password","installId","deviceHash","platform","osVersion","appVersion"}` | ✅ 已实现 |
+| POST | `/api/register` | 需要抓包确认 | ❌ 待实现 |
+| POST | `/api/activate-vip` | 需要抓包确认 | ✅ 已实现 |
+
+### 📊 会话 & 状态
+| 方法 | 端点 | 当前状态 |
+|------|------|----------|
+| GET | `/api/session-status` | ✅ 已实现 |
+| GET | `/api/vip-status` | ❌ 待实现 |
+| GET | `/api/user/stats/{userId}` | ❌ 待实现 |
+| GET | `/api/user/favorited-count/{userId}` | ❌ 待实现 |
+| GET | `/api/user/limits/{userId}` | ❌ 待实现 |
+| GET | `/api/user/schemes/{userId}` | ❌ 待实现 |
+
+### 🎯 改枪方案
+| 方法 | 端点 | 参数 | 当前状态 |
+|------|------|------|----------|
+| GET | `/api/category/{type}` | AR/SMG/SR/LMG/SG/Pistol/Launcher | ✅ 已实现 |
+| GET | `/api/schemes` | `sort=hot&page=1&limit=12&source=...` | ✅ 已实现 |
+| GET | `/api/schemes` | `sort=hot&page=1&limit=12&weaponCategory&weaponName` | ✅ 已实现 |
+| POST | `/api/schemes/{id}/use` | 需要抓包确认 | ❌ 待实现 |
+
+### ❤️ 收藏
+| 方法 | 端点 | 当前状态 |
+|------|------|----------|
+| GET | `/api/favorites/count` | ✅ 已实现 |
+| GET | `/api/favorites/check?schemeId={id}&source=...` | ✅ 已实现 |
+
+### 🎯 弹出广告
+| 方法 | 端点 | 当前状态 |
+|------|------|----------|
+| GET | `/api/popups/test_beta_01` | ❌ 待实现 |
+| GET | `/api/aftersale-tutorial-popup` | ❌ 待实现 |
+| GET | `/api/software-version-ad` | ❌ 待实现 |
+
+### 🔄 更新服务
+| 方法 | 端点 | 备注 |
+|------|------|------|
+| GET | `/latest.yml` | Electron auto-updater 配置 |
+| GET | `/update-config.json` | 更新配置 |
+
+### 🖼️ 图片托管
+| 方法 | 端点 | 备注 |
+|------|------|------|
+| GET | `tuku.maqt.top/i/2026/03/22/*.png` | 静态图片资源 |
+
+---
+
+## 三、ss3 vs ss4 请求对比（关键差异）
+
+### 原版（ss3）完整流程：
+```
+1. 检查更新: GET update.maqt.top/{latest.yml,update-config.json}
+2. 弹窗广告: GET pop.maqt.top/api/software-version-ad
+3. 会话状态: GET maqt.top/api/session-status (高频轮询!)
+4. 注册/登录: POST maqt.top/api/register
+5. 获取分类: GET maqt.top/api/category/{type}
+6. 获取方案: GET maqt.top/api/schemes?...
+7. 收藏检查: GET maqt.top/api/favorites/check?schemeId=...
+8. 激活VIP: POST maqt.top/api/activate-vip
+9. VIP状态: GET maqt.top/api/vip-status
+10. 用户数据: GET maqt.top/api/user/{stats,favorited-count,limits,schemes}/{id}
+11. 方案使用: POST maqt.top/api/schemes/{id}/use
+12. 图片加载: GET tuku.maqt.top/... (持续轮询)
+```
+
+### 自定义服务器（ss4 后半段）请求序列：
+```
+162: GET  /api/popups/test_beta_01
+163: GET  /api/session-status
+164: GET  /api/software-version-ad
+165: GET  /api/aftersale-tutorial-popup
+166: GET  /update-config.json
+169: GET  /api/software-version-ad
+170: GET  /api/popups/test_beta_01
+171: GET  /api/aftersale-tutorial-popup
+172: GET  /update-config.json
+173: GET  /api/category/AR
+174: GET  /api/schemes?sort=hot&page=1&limit=12&source=...
+175: GET  /api/category/SMG
+176: GET  /api/category/SR
+177: GET  /api/category/LMG
+178: GET  /api/category/SG
+179: GET  /api/category/Pistol
+180: GET  /api/category/Launcher
+181: POST /api/login
+182: GET  /api/session-status
+183: GET  /api/favorites/count
+184: GET  /api/schemes?...
+185: GET  /api/schemes?...
+186: GET  /api/favorites/count
+187: GET  /api/session-status
+190: GET  /api/session-status
+194-199: GET /api/session-status (轮询...)
+```
+
+### ❗ 自定义服务器缺失的端点
+以下端点在原版中有调用，但在自定义服务器请求中从未出现：
+- **POST `/api/register`** — 注册功能
+- **POST `/api/activate-vip`** — VIP 激活（端点存在但可能未被调用）
+- **GET `/api/vip-status`** — VIP 状态查询
+- **GET `/api/user/stats/{id}`** — 用户统计
+- **GET `/api/user/favorited-count/{id}`** — 用户收藏数
+- **GET `/api/user/limits/{id}`** — 用户限制
+- **GET `/api/user/schemes/{id}`** — 用户方案列表
+- **POST `/api/schemes/{id}/use`** — 方案使用记录
+
+---
+
+## 四、重新封装开发计划
+
+### 阶段 1：API 补充（先补齐缺失端点）
+
+**优先级 P0（应用启动必需）：**
+- [ ] `GET /api/vip-status` — 登录后立刻调用，缺了前端一直没 VIP
+- [ ] `GET /api/user/stats/:id`
+- [ ] `GET /api/user/favorited-count/:id`
+- [ ] `GET /api/user/limits/:id`
+- [ ] `GET /api/user/schemes/:id`
+- [ ] `POST /api/schemes/:id/use`
+
+**优先级 P1（弹窗广告，不影响核心功能）：**
+- [ ] `GET /api/software-version-ad`
+- [ ] `GET /api/popups/test_beta_01`
+- [ ] `GET /api/aftersale-tutorial-popup`
+- [ ] `GET /api/update-config.json`
+
+**优先级 P2（注册，一次性的）：**
+- [ ] `POST /api/register`（含 installId, deviceHash）
+
+### 阶段 2：桌面端复刻（Electron + React）
+
+等 API 补全后，桌面端从头写：
+
+```
+maqt-desktop/
+├── electron/
+│   ├── main.ts      # 窗口管理
+│   └── preload.ts   # electronAPI
+├── src/
+│   ├── App.tsx
+│   ├── pages/
+│   │   ├── Home.tsx        # 桌面首页
+│   │   ├── Login.tsx
+│   │   ├── Schemes.tsx     # 改枪方案
+│   │   ├── Filters.tsx     # 画面滤镜
+│   │   ├── Optimization.tsx
+│   │   └── ...
+│   ├── components/
+│   │   ├── Dock.tsx        # 底部导航
+│   │   ├── DesktopIcons.tsx
+│   │   └── ...
+│   └── hooks/
+│       ├── useAuth.ts
+│       └── useApi.ts
+├── native/                  # 原生程序
+│   ├── MaqiangTangh1.exe
+│   ├── nvidiaProfileInspector.exe
+│   └── tools/
+└── package.json
+```
+
+### 阶段 3：原生功能对接
+
+- [ ] spawn `MaqiangTangh1.exe` 执行系统优化
+- [ ] spawn `MaqiangTangXiXiOverlay.exe` 游戏内 Overlay
+- [ ] 调用 PowerShell 脚本 Gamma 校准
+- [ ] NVIDIA Profile Inspector 配置
+- [ ] 硬件监控面板