# 游戏部署指南 - 龙虾专用

> 本文档面向自动化程序（龙虾），用于实现游戏的自动新增与更新。

---

## 使用前提

> ⚠️ **Token 不支持自动获取**，请联系管理员获取有效 token。Token 一次有效，使用后需重新获取。

---

## 部署游戏

```
POST https://ifenshen.art/api/deploy
Content-Type: multipart/form-data
```

**表单字段**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `token` | string | ✅ | 管理员提供的 token |
| `mode` | string | ✅ | `new`=新增 或 `update`=更新 |
| `file` | file | ✅ | HTML 文件（multipart） |
| `filename` | string | 条件 | 新增时自定义文件名（可选） |
| `targetGame` | string | 条件 | 更新时必填，指定要更新的游戏名 |

---

## 场景一：新增游戏

**适用情况**：上传全新的游戏文件，系统自动分配文件名。

```bash
curl -X POST https://ifenshen.art/api/deploy \
  -F "token=管理员提供的token" \
  -F "mode=new" \
  -F "file=@/path/to/game.html"
```

**响应示例**：
```json
{
  "success": true,
  "filename": "mygame.html",
  "url": "/game/games/mygame.html",
  "isUpdate": false
}
```

**自定义文件名**（推荐）：
```bash
curl -X POST https://ifenshen.art/api/deploy \
  -F "token=管理员提供的token" \
  -F "mode=new" \
  -F "filename=awesome-game.html" \
  -F "file=@/path/to/game.html"
```

> 文件名冲突时，系统会自动在后面加数字后缀，如 `awesome-game_1.html`

---

## 场景二：更新游戏

**适用情况**：替换已有游戏的文件，老版本自动备份。

```bash
curl -X POST https://ifenshen.art/api/deploy \
  -F "token=管理员提供的token" \
  -F "mode=update" \
  -F "targetGame=mygame.html" \
  -F "file=@/path/to/new-game.html"
```

**响应示例**：
```json
{
  "success": true,
  "filename": "mygame.html",
  "url": "/game/games/mygame.html",
  "isUpdate": true
}
```

> 老版本会备份到 `.backups/` 目录，文件名格式：`原名_备份时间.html`

---

## 错误码

| HTTP 状态 | error 信息 | 说明 |
|-----------|------------|------|
| 400 | 没有上传文件 | file 字段缺失 |
| 400 | 只允许上传 HTML 文件 | 文件类型不符 |
| 400 | 要更新的游戏不存在 | targetGame 指定有误 |
| 401 | 无效的部署 token | token 错误或已过期 |
| 500 | 保存文件失败 | 磁盘写入错误 |

---

## 完整流程示例

```bash
#!/bin/bash

# 请先联系管理员获取有效 token
TOKEN="管理员提供的token"

# 部署文件（新增模式）
curl -X POST https://ifenshen.art/api/deploy \
  -F "token=$TOKEN" \
  -F "mode=new" \
  -F "filename=my-awesome-game.html" \
  -F "file=@./dist/game.html"

# 部署成功后，如需继续部署请重新获取 token
```

---

## 查询已部署的游戏

```bash
GET https://ifenshen.art/api/games
```

响应：
```json
[
  {"name": "game1.html", "url": "/game/games/game1.html", "size": 68835},
  {"name": "game2.html", "url": "/game/games/game2.html", "size": 53321}
]
```

---

## 访问地址

- 部署页面：https://ifenshen.art/game/deploy.html
- 游戏列表：https://ifenshen.art/game/
- 龙虾文档：https://ifenshen.art/game/deploy-guide.md