feat: WaHappy v0 —— 舞萌DX 纯网络游戏助手（占位版）

当前仅 upsert.py 可用：扫码登录 -> 上传一局成绩 -> 落库回查 -> 登出。 - api/ 下 40+ 个接口模块已实现，236 项零网络自检全绿 - 上传成绩链路已真机跑通，报文与真机抓包逐字节一致 - 开发文档见 docs 分支；source/ 与 logs/ 不入库
2026-10-06 14:42:06 +08:00
commit 1636a79141
51 changed files with 10965 additions and 0 deletions
@@ -0,0 +1,124 @@
+# -*- coding: utf-8 -*-
+"""
+user_item.py —— 取用户道具（GetUserItemApi）
+================================================================================
+
+取玩家各类道具的库存（真机按 kind 分 12 次请求）。
+
+对应接口：GetUserItemApi
+请求体  ：UserItemRequestVO（userId + nextIndex + maxCount=100）
+响应    ：{userId, length, nextIndex, itemKind, userItemList:[{itemKind,itemId,stock,isValid}]}
+依据    ：source/Assembly-CSharp/Net.VO.Mai2/UserItemRequestVO.cs
+
+--------------------------------------------------------------------------------
+★★ 首发 nextIndex 必须带哨兵值（最容易踩的坑）
+--------------------------------------------------------------------------------
+source/Assembly-CSharp/Net.Packet.Mai2/PacketGetUserItem.cs:17-24
+
+    public PacketGetUserItem(ulong userId, long itemId, ...)
+    {
+        Create(GetNetQuery(userId, itemId * 10000000000L));   // <- 首包哨兵
+    }
+    // Proc(): nextIndex != 0 时继续翻页
+
+真机日志 source/2026-10-05.log:32 也是 nextIndex=10000000000。
+传 0 会被服务端拒绝（HTTP 500）。
+
+★ 请求体里**没有 itemKind 字段** —— 类别是靠 nextIndex 的哨兵值表达的：
+    第 1 页 nextIndex = kind * 1e10
+    后续翻页沿用响应回的 nextIndex
+
+调用示例：
+    from api import UserItem, UserItemAll
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from config import CLIENT_ID, TIMEOUT_MS
+
+from .log_setup import log_debug, log_info, log_warning
+from .maimai_net import MaimaiNetClient
+from .user_getter_common import _get, UserItemRequestVO, ITEM_KINDS, ITEM_NEXT_INDEX_FACTOR
+
+
+def UserItem(
+    user_id: int,
+    item_kind: int,
+    *,
+    next_index: Optional[int] = None,
+    client_id: str = CLIENT_ID,
+    timeout_ms: Optional[int] = None,
+    client: Optional[MaimaiNetClient] = None,
+) -> Dict[str, Any]:
+    """
+    取用户某一类道具（对应 GetUserItemApi）。
+
+    参数：
+        user_id:   用户 ID（必填）
+        item_kind: 道具类别（必填）：1=名牌 2=称号 3=头像 4=礼物 5=乐曲 …
+        next_index: 分页索引；**None（默认）表示首页**，会自动换算成
+                    item_kind * 10000000000 的哨兵值。
+
+    返回：
+        原始响应 dict，含 userItemList
+    """
+    if next_index is None:
+        next_index = item_kind * ITEM_NEXT_INDEX_FACTOR
+
+    log_info("取用户道具：user_id=" + str(user_id) + " item_kind=" + str(item_kind)
+             + " nextIndex=" + str(next_index))
+
+    return _get(
+        "GetUserItemApi",
+        UserItemRequestVO(userId=user_id, nextIndex=next_index, maxCount=100),
+        user_id, client_id=client_id, timeout_ms=timeout_ms, client=client,
+    )
+
+
+def UserItemAll(
+    user_id: int,
+    *,
+    item_kinds: Optional[List[int]] = None,
+    client_id: str = CLIENT_ID,
+    timeout_ms: Optional[int] = None,
+    client: Optional[MaimaiNetClient] = None,
+) -> Dict[str, Any]:
+    """
+    取用户全部道具（按 ITEM_KINDS 逐个类别抓取，并自动翻页）。
+
+    参数：
+        item_kinds: 类别列表（可选，默认 ITEM_KINDS）
+
+    返回：
+        {"userItemList": [...]}，已合并所有类别与分页
+    """
+    kinds = list(item_kinds) if item_kinds else list(ITEM_KINDS)
+    log_info("取用户全部道具：user_id=" + str(user_id) + " kinds=" + str(kinds))
+
+    merged: List[Dict[str, Any]] = []
+    for kind in kinds:
+        next_index: Optional[int] = kind * ITEM_NEXT_INDEX_FACTOR
+        page = 0
+        while next_index:
+            page += 1
+            resp = _get(
+                "GetUserItemApi",
+                UserItemRequestVO(userId=user_id, nextIndex=next_index, maxCount=100),
+                user_id, client_id=client_id, timeout_ms=timeout_ms, client=client,
+            )
+            items = resp.get("userItemList") or []
+            if isinstance(items, dict):
+                items = [items]
+            merged.extend(items)
+
+            next_index = int(resp.get("nextIndex") or 0)
+            log_debug("item_kind=" + str(kind) + " 第 " + str(page) + " 页："
+                      + str(len(items)) + " 条，nextIndex=" + str(next_index))
+            if page >= 200:
+                log_warning("item_kind=" + str(kind) + " 翻页超过 200 页，已中止")
+                break
+
+    log_info("道具获取完成：" + str(len(merged)) + " 条")
+    return {"userItemList": merged}