fix(tracker): 修复嚣翻牌底被误放到牌顶

[llsccm]

变更内容

• 修复 normalizeProtocolZoneTarget 对协议 pos 的错误顶底互换
• 嚣翻 SpellID=3336 的牌底观看结果会正确定位到牌堆底
• 补充牌底明牌同步与幂等回归测试
• 补充嚣翻协议文档与索引说明

原因

CGsRoleSpellOptRep 嚣翻分支本身已经按 POSITION_BOTTOM 同步，但控制器在规范化协议 zone 时把 POSITION_BOTTOM 又翻成了 POSITION_TOP，导致协议第一项（牌底）被当成牌顶展示。

协议 pos 与 Zone.add/remove 共用同一套端点约定，显式端点应直接透传。

影响

• 嚣翻看牌时，Datas 第一项会正确落在牌堆底
• 未携带 pos 的牌堆观看消息仍默认按牌顶处理
• 其它已显式传 pos 的公共区明牌同步不再被错误翻转

验证

• pnpm exec vitest run tests/tracker/trackerController.test.ts tests/tracker/roleSpellOptRep.test.ts
• pnpm typecheck:tracker
• pnpm lint

Summary by CodeRabbit

• 功能改进

  • 优化牌堆底明牌同步，确保卡牌按协议指定位置正确落位。
  • 重复接收相同消息时保持状态稳定，避免重复调整牌堆顺序。

• 文档

  • 补充“嚣翻：观看牌堆底”消息格式、字段含义及处理规则。
  • 更新协议索引，明确相关牌堆底查看语义。

[coderabbitai]

Warning

Review limit reached

@llsccm, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 45 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a0e986d7-690e-46e7-a762-6839dac4de37

📥 Commits

Reviewing files that changed from the base of the PR and between abcd471 and 329e481.

📒 Files selected for processing (1)

• src/tracker/runtime/trackerController.ts

📝 Walkthrough

Walkthrough

更新 CGsRoleSpellOptRep 对嚣翻观看牌堆底的协议说明，统一显式牌堆端点定位规则，并新增牌堆底同步及重复消息幂等测试。

Changes

牌堆端点语义

Layer / File(s)	Summary
观看牌堆底协议说明 docs/protocols/CGsRoleSpellOptRep.md, docs/protocols/README.md	补充 SpellID=3336、Type=50 的消息字段、Datas 逆序处理规则及牌堆底同步约束。
牌堆端点归一化与幂等验证 src/tracker/runtime/trackerController.ts, tests/tracker/trackerController.test.ts	显式 POSITION_BOTTOM 直接透传至牌堆底端点，并验证已有卡牌定位、实体标记和重复消息幂等性。

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• llsccm/tracker#37：同样调整 normalizeProtocolZoneTarget 的牌堆端点顶底归一化逻辑。
• llsccm/tracker#38：调整牌堆端点顺序规范及揭示逻辑。

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	标题准确概括了本次修复：嚣翻牌底被错误放到牌顶的问题。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/xiaofan

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

src/tracker/runtime/trackerController.ts (1)

853-855: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

使用空值合并运算符（??）简化代码。

你可以使用 ?? 运算符来替代显式的 undefined 和 null 检查，这在 TypeScript 中更加简洁且符合惯用语。

♻️ 建议的重构

-    const hasExplicitPosition = protocolZone.pos !== undefined && protocolZone.pos !== null
-    // 未携带 pos 的看牌消息默认表示牌顶。
-    const position = hasExplicitPosition ? protocolZone.pos : POSITION_TOP
+    // 未携带 pos 的看牌消息默认表示牌顶。
+    const position = protocolZone.pos ?? POSITION_TOP

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/tracker/runtime/trackerController.ts` around lines 853 - 855, 简化
protocolZone 位置解析逻辑：移除 hasExplicitPosition 及其显式的 undefined/null 检查，在 position
赋值中使用空值合并运算符，使缺少 pos 时仍默认使用 POSITION_TOP，存在有效 pos 时保持原值。

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/tracker/runtime/trackerController.ts`:
- Around line 853-855: 简化 protocolZone 位置解析逻辑：移除 hasExplicitPosition 及其显式的
undefined/null 检查，在 position 赋值中使用空值合并运算符，使缺少 pos 时仍默认使用 POSITION_TOP，存在有效 pos
时保持原值。

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0ad0956c-f0c8-45c5-844e-6548c67c7d0f

📥 Commits

Reviewing files that changed from the base of the PR and between 047ec4c and abcd471.

📒 Files selected for processing (4)

• docs/protocols/CGsRoleSpellOptRep.md
• docs/protocols/README.md
• src/tracker/runtime/trackerController.ts
• tests/tracker/trackerController.test.ts