# UpsertUserAll 落库排查报告

> **背景**：`python upsert.py "<二维码>" --send` 修复闸门后能真实发包，
> 服务端返回 `returnCode=1`，但**数据未写入服务器**。
> 本文档记录已完成的全部排查与结论。

---

## 一、结论速览

| 项 | 状态 |
|---|---|
| 闸门放行 | 已修复，`returnCode=1` |
| 报文与真机对齐 | **非预期差异归零** |
| 数据落库 | **未落库**（`point`/`playCount` 回查不变） |
| 根因 | **未确定**，已排除 6 类可能 |

---

## 二、已修复的 5 个 Bug

### Bug 1：`upsert.py` 漏传 `confirm`（你遇到的直接原因）

`upsert.py` 原来只传 `dry_run=not opts["send"]`，但 `UpsertUserAll` 的规则是
`confirm=None` 时取 `config.UPSERT_CONFIRM`（默认 `False`），所以照样被拦。

```python
# 修复前
dry_run=not opts["send"],
# 修复后
dry_run=not opts["send"],
confirm=bool(opts["send"]),      # 关键
```

### Bug 2：`userExtend` 缺 2 个字段

| | Get 侧 | Upsert 侧 |
|---|---|---|
| 键数 | 14 | **16** |
| 差 | — | `isPhotoAgree`、`isGotoCodeRead` |

这两个字段**只在 Upsert 侧出现**，必须补上。

### Bug 3：`userRating.udemae` 有 7 个冗余大写字段

服务器 Get 响应里 `npcWinNum` 与 `NpcWinNum` **并存**（23 键）：

```json
// Get 侧（source/2026-10-05.log:87）
{ "npcWinNum": 0, ..., "NpcWinNum": 0, "NpcLoseNum": 0, ... }   // 23 键
// Upsert 侧（source/2026-10-05.log:123）
{ "npcWinNum": 0, ... }                                          // 16 键
```

源码 `Net.VO.Mai2/UserUdemae.cs` 只声明了**小写的 16 个**，所以大写那批是
服务端冗余输出，回传时必须裁掉。修复前请求体比真机大 119 字节。

### Bug 4：`userCharacterList` 排序错

| | 顺序 |
|---|---|
| `charaSlot` | [395, 101, 400402, 400401, 200401] |
| 真机 `userCharacterList` | **[101, 395, 200401, 400401, 400402]**（按 characterId 升序） |

回传时按 `characterId` 升序，不是按 `charaSlot` 顺序。

### Bug 5：扫码用的 chipID 形式错

| 用途 | 正确值 | 源码依据 |
|---|---|---|
| aimedb 扫码 | `XXXX-XXXXXXXXXXX`（**完整**） | `ChimeReaderManager.cs:250` `KeychipId.Value` |
| 游戏服务器 | `TESTCLIENT1`（短值） | `PacketGetGameSetting.cs:23` `KeychipId.ShortValue` |

我原来扫码也用了短值。已按源码修正为完整形式。

---

## 三、报文对齐最终状态

```
顶层键        : 7/7
36 节点形态   : 36/36
userData      : 82/82 键
userPlaylog   : 110/110 键
userExtend    : 16/16 键
udemae        : 16/16 键
非预期差异    : 0
请求体大小    : 17158 vs 17161 字节（差 3 字节，来自数值位数）
```

**深度递归对比（逐字段、逐元素）后，除「不同次登录必然不同」的值外，零差异。**

---

## 四、已排除的可能（6 类）

| # | 假设 | 验证方式 | 结果 |
|---|---|---|---|
| 1 | 时序问题（写入有延迟） | 发送后 T+0 / T+20s / T+45s 三次回查 | 都不变 |
| 2 | 差分节点为空导致「看不出变化」 | 直接改绝对值（`point` 4110→4111） | 仍不写 |
| 3 | 字段缺失/多余 | 深度递归键集合 + 值对比 | 已归零 |
| 4 | `number` 请求头缺失 | 补上 `Packet.cs:170` 要求的头 | 仍不写 |
| 5 | `playSpecial` 值不对 | 查源码 `CalcSpecialNum` = 硬件标志位 | 非根因 |
| 6 | 缺少 `GetUserNewItemList` 前置 | 完整复刻真机 121→123 流程 | 仍不写 |

### 关于第 2 项的探测细节

这是最关键的一次探测 —— 直接 `patch` 把 `userData.point` 从 4110 改成 4111 发上去：

```
baseline point = 4110
上传成绩成功：returnCode=1
T+ 0s  point = 4110
T+20s  point = 4110
T+45s  point = 4110
```

**连最简单的整数字段都不写**，说明不是「数据不对」而是「整包没被接受」。

---

## 五、当前判断

服务端**收下了**请求（返回正确的 `apiName`），但**没有应用**。

可能的方向（未验证）：

1. **账号/机台绑定校验** —— token 可能绑定了特定 keychip，而 `XXXX-XXXXXXXXXXX`
   只是文档里的示例值，不是**你实际机台**的 keychip。
   若服务端校验「token 对应的机台 ≠ 请求里的 chipID」，就会静默拒收。

2. **需要真实游玩产生的会话状态** —— 真机的 Upsert 发生在**真实游玩之后**，
   服务端可能记录了「本次 loginId 下有一局真实游玩」才允许结算。
   纯网络脚本没有这个前置状态。

3. **服务端侧的风控/审计** —— 真机与脚本的 TLS 指纹、请求节奏等特征不同。

---

## 六、需要你提供的信息

要继续定位，最有价值的是：

| # | 信息 | 为什么关键 |
|---|---|---|
| 1 | **你机台的真实 Keychip ID** | 若 `XXXX-XXXXXXXXXXX` 不是你的机台，方向 1 就成立 |
| 2 | 该机台在 `keychip.csv` 里的对应行 | 可确认 keychip 与店铺/区域的绑定关系 |
| 3 | 真机跑一局后立刻导出 Upsert 报文 | 可拿同账号同机台的最新报文做 1:1 对比 |

> `source/keychip.csv` 有 229KB 全量机台对照表，如果你能告诉我机台所在的
> 店铺 ID，我可以从中查出正确的 keychip。

---

## 七、本次排查的正面成果

即使尚未落库，这次排查也修掉了 **5 个真实 Bug**，其中 3 个（`userExtend` 缺字段、
`udemae` 冗余字段、`userCharacterList` 排序）是**只有做深度值对比才能发现**的：

- 修复前：报文与真机有 11 处非预期差异
- 修复后：**0 处**

自检 129/129 仍全绿。

---

## 八、复现方式

```powershell
# 1) 真实发送 + 落库验证（会写服务器，不可撤销）
python upsert.py "<二维码>" --send

# 2) 零网络自检
python selftest.py
```