v0版本完成：新增 4 篇详细文档（README 精简内容的落点）

README 为了防冗余做了精简，被移出的详细内容写成文档放这里：

- 功能票使用说明.md      买票/用票的完整原理、报文依据、playCredit 公式、实测记录
- 账号转生说明.md        reincarnate 完整流程、分批规则（避开 2 首）、
                          续关登录依据、登出 type=1 依据、playlog 合成、迁移范围
- 常见坑与注意事项.md    二维码 / 账号状态 / 功能票 / 副作用 / 日志 / 网络 /
                          不入库清单 + .gitignore 行尾注释的坑
- netdelivery说明.md     DLI 协议、amdaemon.exe 字符串出处、用法与实测结论

docs/常见坑与注意事项.md

@@ -0,0 +1,114 @@
+# 常见坑与注意事项
+
+> 本文是 [`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` 里的对拍用例。