RaidTierTracker · 团本套装收集助手

适配本机正式服 12.1.5.70575，Interface 120105，简体中文。当前版本 1.0.2，使用暴雪原生窗口、下拉菜单与展开按钮。独立插件，无游戏内第三方依赖。账号 API 尚未进行逐部位实机核对，新版排版需在游戏内 /reload 后确认。

已安装旧版的用户直接 /reload 即可加载本次 UI 更新；收藏缓存会继续使用。改动见 CHANGELOG_zhCN.md。

安装与第一次使用

插件已放在本机：

J:\World of Warcraft\_retail_\Interface\AddOns\RaidTierTracker\

其他电脑解压安装包，把 RaidTierTracker 整个目录放入正式服的 _retail_\Interface\AddOns。目录内应直接看到 RaidTierTracker.toc，避免嵌套两层同名目录。新装插件后重新启动游戏，在角色选择页确认已启用。

1. 登录任意职业，输入 /rtt。首次扫描分帧进行，窗口底部显示进度；战斗中暂停。
2. 职业选“法师”，资料片选“巨龙时代”，表格显示 T29、T30、T31。
3. 主表直接显示 缺：肩 腿 腕 等实际缺失部位；点击英雄等难度单元格，右侧查看固定顺序的九部位。
4. 悬停部位可看物品、已知获取来源与状态。点击打开物品提示，试穿和聊天链接使用游戏的修饰键设置。
5. 点击“全部职业”切换 13 职业对比，点职业列标题切回单职业。职业表头固定在顶部，纵向滚动时保持可见；底部横向滑条或 Shift+滚轮会同步移动表头与内容，普通滚轮只滚动内容。单职业的难度表头同样固定。
6. “仅未完成”包含未知数据，避免把尚未验证的收藏隐藏。收集率排序把未知放在前面；缺失数排序只计算已确认缺失。
7. 资料片标题可折叠。窗口可拖动，右下角可缩放，ESC 关闭；位置和大小保存在账号设置中。

默认矩阵为随机团队、普通、英雄、史诗四列。在难度筛选中选“特殊/复刻”可查看独立的复刻 SetID。设置可开关“隐藏不适用职业/套装”和调试 ID。

职业从左到右按以下顺序展示：唤魔师、牧师、德鲁伊、圣骑士、术士、猎人、法师、恶魔猎手、武僧、战士、萨满祭司、死亡骑士、盗贼。下拉菜单沿用此顺序；隐藏不适用职业时其余职业仍保持相对顺序。

状态含义与跨职业限制

账号级收藏不代表每个 API 都能对其他职业可靠返回 false。 本插件按如下次序查询：

1. 以静态数字 ID 遍历全部职业的官方 SetID，不依赖当前职业的套装列表、中文名称或收藏筛选器。
2. GetSetPrimaryAppearances 确认主外观定义。这里的 appearanceID 实际是 SourceID，暴雪 UI 也将其传入 GetSourceInfo；不会把它与视觉 AppearanceID 混用。
3. 通过永久账号来源、同视觉 ID 的其他永久来源，或有效角色上下文的外观收藏状态确认已收集。套装完成布尔值不用于推测部位。
4. 对未收集，只接受当前职业且适用的主外观结果，或 GetAppearanceInfoBySource 明确给出 isAnySourceValidForPlayer=true 的外观结果。其他职业的受限 false 不作为缺失证据。
5. 第二条定义路径 C_Transmog.GetAllSetAppearancesByID 只有在同一套装组至少两个不同 SetID 与主外观 ID 完全一致、且没有反例时，才可作为定义回退；不会无条件把所有来源当成主外观。
6. API 无法返回定义时，可使用相同客户端版本中以前验证过的主外观定义，重新查询账号永久来源；仍不能确认的部位保留历史快照或未知。

因此，不能保证在未实测的客户端上仅登录一个角色就能确认其他 12 个职业的所有“未收集”部位。如果客户端限制跨职业查询，请分别登录相关职业一次建立真实账号快照；之后任意角色都能查看这些快照，且会明确显示历史状态。可靠的实时账号结果会逐部位替换快照。不会用猜测的 0/9 补齐表格。

API 没有提供可靠永久状态、精确颜色或有效来源时，插件宁可显示未知。物品名称缓存失败不会改变收藏判断。阵营变体保留独立 SetID；另一阵营无法确认的部位也不会自动记为未收集。

数据库范围与历史规则

数据库来自 12.1.5.70575 的客户端 DB2：TransmogSet、TransmogSetGroup、TransmogSetItem、ItemModifiedAppearance、Item、ItemNameDescription、Map、JournalInstance。原始 CSV、SHA-256、版本及关联缺口位于 Research，静态主表在 Data/Generated.lua，维护入口为 Data/catalog.json。

已覆盖要求中的 31 个 T 等级、1022 个官方 SetID、21530 条可关联的来源成员，包括 T1、T2、T2.5、T3、T4–T21、T28–T36。其中 13 个为独立特殊/复刻变体。以上是数据库记录数，不是账号收藏进度。

• T2/T4 等多个团本使用统一 T 等级目标，保留所有关联 MapID，账号总计按 SetID 去重。
• T3 使用套装组 42，T7 使用组 38。MapID 533 被旧版/新版共用，不能单独据此区分；插件不把已移除的旧版纳克萨玛斯当成当前掉落地点。T3 的重新获取情况由真实收藏 API 判定。
• T2.5 独立使用套装组 51；实际五件、六件、八件或九部位以游戏主外观定义为准。
• T6 的黑暗神殿与太阳之井外观保留独立 SetID，在“普通”单元格中显示多变体，可在详情内切换。
• T7/T8 保留 10/25 人普通子模式；T10 保留 10 人普通、25 人普通、25 人英雄的实际收藏变体。
• T9 保留联盟/部落 SetID；普通/英雄关联同一收藏外观。T16 当前普通/英雄共用外观，旧英雄外观在当前收藏系统中标为史诗。共用关系在 Data/Overrides.lua，不生成新颜色，账号与职业总计去重。
• T17 客户端没有传统职业随机团队套装 ID，显示不适用；T18 的随机团队为四种护甲共享外观，按实际 classMask 展示。
• 武僧、恶魔猎手、唤魔师推出前的职业套装显示不适用；不会从相似散件生成职业套装。
• 争霸艾泽拉斯、暗影国度 9.0–9.1 没有本任务所列传统职业 T 套，因此不生成虚构记录。
• 原始表有 105 条来源引用无法完成 DB2 关联，详见 Research/database_validation.json。运行时会尝试正式 API 补齐，失败则显示未知；这些缺口不代表 105 个未收集部位。
• 数据库未随客户端升级时，未映射的组合显示待验证；已映射条目继续核对运行时元数据与视觉 ID，发生冲突时停止推断。

MapID 是地图 ID，JournalInstanceID 是地下城手册 ID，TransmogSetGroupID 是套装组 ID，三者不混用。静态数据库保存所有成员来源及原始 Flags；不根据未经验证的 Flags 位猜主外观。

导出到 Excel

1. 等扫描结束，输入 /rtt export，或点击“导出”。导出包含所有职业、T 等级、标准难度和特殊变体，不受当前筛选限制。
2. 执行 /reload 或正常退出游戏，等待账号 SavedVariables 落盘。游戏内 Lua 不能任意创建本地 CSV。
3. 双击 Tools\导出CSV.cmd。默认读取本安装目录，输出到用户“文档”中的 RaidTierTracker导出 目录。Windows 如重定向了“文档”，此默认路径为 %USERPROFILE%\Documents\RaidTierTracker导出，也可自行指定。
4. 使用 Excel 打开 RaidTierTracker_套装总览.csv 和 RaidTierTracker_缺失部位.csv。两份均为 UTF-8 BOM，支持中文、引号、逗号和换行。

工具只需 Python 3.10+ 标准库。启动器先尝试 py -3、再尝试 python，本机已有 uv 时也能使用已有 Python 运行。

手动指定游戏和输出目录：

py -3 "J:\World of Warcraft\_retail_\Interface\AddOns\RaidTierTracker\Tools\export_savedvariables.py" --wow-root "J:\World of Warcraft" --output "D:\套装收藏"

直接读取文件：

py -3 export_savedvariables.py --input "J:\World of Warcraft\_retail_\WTF\Account\你的账号目录\SavedVariables\RaidTierTracker.lua" --output "D:\套装收藏"

多个账号时，添加 --account "账号目录名" 选择，或 --all-accounts 分目录导出，工具不会混合多个账号的收藏。

总览有要求的 22 列，缺失明细有 13 列。历史部位在九部位列中导出为“未知”，数据状态列明确注明“历史快照”；有未知/历史部位时留空无法确认的已收集数量，定义不完整时留空总数。缺失明细仅包含本次有证据的 MISSING，历史缺失不会冒充当前待刷清单。

总览的一个单元格可能有多个真实 SetID（如 T6 子模式、T9 阵营），CSV 为各 SetID 分行。共用普通/英雄外观会分别展示模式行，计算独立外观总数时可按 SetID 去重。

工具使用有限的 Lua 字面量解析器，不执行 Lua、不调用 eval。物品名称未加载时输出“名称未缓存”；来源无法确认时输出“未查询（关联团本：…）”，不会捏造 Boss。CSV 中有公式前缀的外部文本会加前置单引号。

命令与故障诊断

出现大量“未知”时：先等扫描结束，非战斗状态执行 /rtt refresh；再执行 /rtt diagnose。诊断与错误保存在账号 SavedVariables 的 diagnostics 中，/reload 后可读取。若只限于其他职业，登录该职业刷新一次建立历史回退。若所有职业均未知，检查客户端版本、API 缺失或加载问题，不能将未知手动当作未收集。

安装了插件却没有命令时，检查目录结构、插件启用状态和版本；可开启游戏 Lua 错误查看第一条报错。插件不修改收藏窗口筛选器，不自动换装、不操作受保护按钮。

测试与实机验收

开发环境使用真实 Lua 5.1 虚拟机运行 Lua 模块及模拟 WoW API，Python 工具使用标准库测试。当前自动化结果见 Tests/RESULTS_zhCN.md 和 Tests/test-results.txt。

自动覆盖：13 职业 ID、31 个 T 等级、难度/职业不适用、五部位统计、精确缺失、替代来源去重、多团本去重、跨职业受限 false、nil/缺失 API/异常、阵营限制、精确颜色 ID、历史回退/时间、筛选、UI 构建、完整分帧扫描、命令注册、CSV BOM/22 列/13 列/转义、安全解析及 SavedVariables→CSV 往返。

复现测试（仅测试需要 lupa；游戏内插件和 CSV 工具不需要它）：

py -3 -m pip install lupa
py -3 Tests\run_tests.py
# 本机已有 uv 时也可：
uv run --no-project --python 3.12 --with lupa Tests\run_tests.py

数据库重建：

py -3 Tools\build_database.py

原始 CSV 已随工程保留。更新版本时先检查该版本 DB2 和 API，再更新 Data/catalog.json、下载原始表并重建；不能只修改 TOC 宣称兼容。数据来源与 API 审查详见 Research/API_AUDIT_zhCN.md。