# 常见坑与注意事项

> 本文是 [`README.md`](https://git.fragrance.moe/Txiaochen/wahappy) 里被精简掉的
> 「常见坑与注意事项」章节的**详细版**。

---

## 一、二维码

| 项 | 说明 |
|---|---|
| 有效期 | **10 分钟**，过期后 aimedb 返回 `errorID=2` |
| 计量方式 | ★ **不是按次数计量的**，只是有时效；重新生成即可 |
| 来源 | 机台的「扫码登录」界面 |
| 每个脚本各要一次 | `reincarnate.py` 需要目标号的二维码；源号可以用 `--src-json` 免掉 |

---

## 二、账号状态

- **一定要登出。** 账号卡在 `isLogin=True` 时，下次登录会 `returnCode=100`。
  本工程所有主脚本都在 `finally` 里兜底登出，异常也不会漏。
- 想确认状态可以看 `GetUserPreviewApi` 的 `isLogin` 字段。
- 登出类型：真机用 **type=1（Logout）**，见 [账号转生说明.md](账号转生说明.md) 第五节。

---

## 三、功能票

- 账号**已经持有**功能票时，`buy_ticket.py` **会拒绝购买**（重复购买有封号风险）。
- 想再买一张，先用 `use_ticket.py` 把手里那张用掉，或直接在机台上打一局选用它。
- 不同店铺上架的票不一样，买之前先 `--list`。
- 详见 [功能票使用说明.md](功能票使用说明.md)。

---

## 四、副作用

| 命令 | 后果 |
|---|---|
| 不带 `--send` | 只构造报文，**不发包**（安全，随便跑） |
| 带 `--send` | **真实写入服务器，不可撤销** |

涉及真实写入的脚本：`upsert.py` / `buy_ticket.py` / `use_ticket.py` / `reincarnate.py`。

---

## 五、日志

```
logs/latest.log        只含**当次**运行（下次覆盖）
logs/YYYY-MM-DD.log    当日全部日志（追加）
```

改 `config.py` 的 `LOG_LEVEL`：

| 值 | 效果 |
|---|---|
| `"info"` | 只展示 api 脚本的运行情况和结果 |
| `"debug"` | 额外展示向 api 发送的数据与 api 返回的数据 |

> 主脚本也可以加 `--debug` 临时开启，不用改 `config.py`。
> DEBUG 日志很大（一局能到十几 MB），`config.LOG_VALUE_MAX` 可以限制单值长度。

---

## 六、网络

- 服务器偶发超时 / 连接重置，**重试即可**（买票那次就是这么过的）。
- 所有请求默认 `timeout` 10 秒，登录与结算用 60 秒。
- `GetGameChargeApi` 偶尔会读超时，重跑一次通常就好。

---

## 七、不要提交的东西

```
config.py      你的机台身份，.gitignore 已忽略
data/          用户数据快照
download/      .app / .opt 更新包
source/        反编译源码（版权）
logs/          运行日志
```

### ⚠️ `.gitignore` 的行尾注释不是注释

写：

```gitignore
data/            # 每账号一份用户数据快照
```

**是错的** —— `#` 只在**行首**才是注释，整行会被当成一个含空格和 `#` 的 pattern，
**匹配不到任何东西**。结果就是规则失效。

正确写法：

```gitignore
# 每账号一份用户数据快照
data/
```

> 这条坑踩过一次：`data/12570152.json`（604 KB 用户数据）被误提交进 git。
> 修复方式是 `git rm --cached` + `commit --amend` + `reflog expire` + `gc --prune=now`。

---

## 八、其它

- **换歌 / 换成绩只改 `config.py` 的 `PLAY_*`**，不用动任何代码。
- `config.py` 不入库，仓库里只有 `config.py.example` 模板；
  第一次用要先 `copy config.py.example config.py` 并填好「机台与店铺标识」。
- `api/` 里每个脚本 = 一个接口，函数名与文件名都带 `Get`（如果 API 名里有 Get）。
- 想离线复现某次请求，用 `--debug` 抓报文 + `selftest.py` 里的对拍用例。