fix(tracker): 区分外部建牌与 known 兜底

[llsccm]

变更内容

• 新增 KnownCardCreationReason，显式区分 external-source 与 known-fallback。
• 保持 createExternalCards 为中性的实体/匿名占位创建入口，并在 known 解析层决定诊断语义。
• 为 outside/exile、既有正 ID 暗实体和普通路径实体缺口补充注释、日志字段与回归测试。

原因

额外区正常生成牌与 known 路径缺失实体都会调用 createExternalCards。此前仅根据新建实体的初始暗态补确认，导致 12 区正常建牌也被记录为兜底诊断，且无法从日志中明确辨别创建原因。

验证

• pnpm test:tracker（40 个测试文件，292 个测试通过）
• pnpm typecheck:tracker
• pnpm lint
• pnpm exec prettier --check src/tracker/roomMovement.ts src/tracker/roomMovement/types.ts src/tracker/Room.ts tests/tracker/knownDiscardConfirm.test.ts
• pnpm build
• pnpm build:prod

风险与备注

• 未改变 createExternalCards 的底层创建行为或匿名占位语义。
• 12 区新牌仍会正常确认明牌；普通 known 实体缺口仍保留兜底诊断。

Summary by CodeRabbit

• Bug 修复

  • 优化已知卡牌移动与补建流程，正确区分外部来源和兜底来源。
  • 改善卡牌从处理区进入弃牌堆后的确认状态，减少状态判断异常。
  • 完善正 ID 暗态卡牌的过渡处理与缺失诊断。

• 测试

  • 扩充相关场景覆盖，确保卡牌确认状态及追踪日志符合预期。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2e2823c9-f995-4f83-ae9b-500355a7ee5f

📥 Commits

Reviewing files that changed from the base of the PR and between 251bfb1 and ead5739.

📒 Files selected for processing (4)

• src/tracker/Room.ts
• src/tracker/roomMovement.ts
• src/tracker/roomMovement/types.ts
• tests/tracker/knownDiscardConfirm.test.ts

---

📝 Walkthrough

Walkthrough

本次变更为 resolveKnownMoveCards 增加补建原因区分，调整外部来源与 known-fallback 的确认处理，并扩展日志字段与测试断言；同时更新相关类型和文档注释。

Changes

已知牌解析与确认

Layer / File(s)	Summary
补建原因与确认分支 src/tracker/roomMovement/types.ts, src/tracker/roomMovement.ts, src/tracker/Room.ts	新增 KnownCardCreationReason，区分 external-source 与 known-fallback；解析流程据此处理补建实体、确认状态和日志字段。
确认路径测试验证 tests/tracker/knownDiscardConfirm.test.ts	新增确认日志 spy 与字段断言，并验证补建牌进入弃牌堆及处理区牌集合的结果。

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• llsccm/tracker#45：同样调整外部来源牌在 resolveKnownMoveCards 中的创建与确认处理。
• llsccm/tracker#54：同样涉及已知牌补建、confirmKnown() 路径及相关测试。
• llsccm/tracker#56：同样增强缺失正 ID 的补建与恢复流程中的确认和日志记录。

🚥 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	标题准确概括了本次变更的核心：区分外部建牌与 known 兜底语义。
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/tracker-known-card-creation-semantics

---

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.}