UI 功能实现与 Handoff 标准
本文用于 Project2 后续 UI 功能的可复用实现方案和 handoff 判断。它不替代具体功能策划案、repo-local policy、制作人审核或实现 repo 的 MR evidence。
适用范围
适用于需要 Unity UI、面板、弹窗、页签、按钮、红点、奖励展示、列表、视觉状态、PSD/参考图、导出资源或视觉 QA 的功能。
不适用于纯后端规则、纯配置表、纯数值、纯文本或没有 UI 表现面的任务。若功能只复用已审核现有 UI 和现有资源，可记录为无需新增 art handoff，但仍应在 execution brief 中说明复用依据。
Handoff 判断
| Handoff | 何时需要 | 何时可不需要 | 输出位置 |
|---|---|---|---|
art-ui-handoff | 有 PSD、参考图、切图、源美术、导出资源、资源重命名、九宫格、状态图、Spine 或视觉验收需求。 | 完全复用已入 Unity 且已有审核证据的现有资源，不新增源美术或导出。 | project2-art 中的 project2.art_ui_handoff.v1，Hub 只记录 review summary。 |
ui-handoff | 前端需要实现或改动 Unity UI、绑定数据、状态、交互、红点、奖励展示、适配、截图或视觉 QA。 | 仅做只读诊断，或功能没有 UI 触达。 | Hub specs/features/<feature>/ui/<screen-id>/ui-handoff.yaml。 |
PSD 图层名、截图文字、资源文件名和导出 PNG 只作为证据，不直接批准 Unity 节点名、配置字段、语言 key、协议名或奖励规则。
标准执行步骤
| Step | Owner | 输出 | Gate |
|---|---|---|---|
HUB-001 | Hub | 读取 issue、功能策划、参考图、附件 manifest、repo registry；判断单一 producer-verifiable result。 | 若是多个独立可验收结果，进入 Split Review。 |
PL-001 | Planning | 配置/奖励/语言/数值/字段/默认值/ID 的正式 contract 或 blocker。 | 不得从 PSD 或截图推断字段、奖励、语言 key、ID、默认值。 |
ART-001 | Art | project2.art_ui_handoff.v1、PSD metadata、导出清单、资源命名、尺寸、状态覆盖、contact sheet 或 blocker。 | 原始 PSD/JPG/PNG 不等于可实现 art handoff。 |
HUB-002 | Hub | project2.ui_handoff.v1，汇总 source spec、art handoff、目标 frontend、状态、交互、资源、布局、验证和 open questions。 | 未确认事实必须留在 open_questions。 |
BE-001 | Backend | 当状态权威、奖励发放、防重复领取、持久化或 API 行为需要可信端时，产出服务端实现和验证。 | 若只需要客户端本地表现，应明确 backend not required。 |
FRO-001 | Frontend | Unity UI 面板/弹窗/入口/红点/数据绑定/资源接入实现和截图证据。 | 必须消费已审核 Planning/Art/Handoff，不得自创 contract。 |
IT-001 | Integration | Planning、Art、Backend、Frontend contract 对齐和最小端到端验证。 | 任一 repo step 缺 evidence 时不能进入 Done。 |
QA-001 | QA | 功能、状态、适配、视觉、红点、奖励、防重复、失败态和回归验证。 | producer review 仍由制作人/审核人完成。 |
单个 UI issue 可以包含上述多 repo step，前提是所有 step 都服务于同一个 producer-verifiable result。若 Planning、Art、Frontend 或 Backend 本身已经是独立可验收结果、独立排期或独立审批门，Hub 必须输出 Split Review preview，不继续写 repo。
执行 issue 的默认粒度是一个 producer-facing feature acceptance result。Planning /
Art / Hub / Backend / Frontend / Integration / QA 可以是同一 issue 下的顺序
workflow_plan.steps[]，各自产出可审核 repo evidence；不要仅因为跨 repo、跨
discipline、需要多个 principal agent 或验证面不同而拆子 issue。只有当 handoff、
contract、实现切片、联调或 QA 本身需要单独 producer review、独立排期、独立审批、
独立发布或独立回滚时，才拆成独立 execution issue。
禁止推断
- 不从 PSD、截图、图层名或切图名推断配置表名、字段名、默认值、ID、语言 key、奖励内容、协议名、API、错误码、Unity 节点名、脚本类名或 Command 名。
- 不把 raw PSD/JPG/PNG 当作 art owner 审核通过。
- 不把 Hub
ui-handoff.yaml当作制作人批准或 implementation repo merge approval。 - 不把 UI 表现需求降级为单 repo 混写；repo 写入必须走对应 principal agent、branch、MR 和 evidence。
图鉴当前应用
怪物图鉴应按一个 producer-facing feature result 管理：图鉴可用，并完成实现、联调
和 QA 验收闭环。若 handoff 需要 producer 或 art owner 单独审核，它可以作为独立输入
先完成；后续 implementation + integration QA 默认应放在一个 execution issue 中，
通过 PL-001 -> ART-001 -> HUB-002 -> BE-001 -> FRO-001 -> IT-001 -> QA-001
等 workflow steps 串起来，而不是按 repo 或 discipline 自动拆成多个 child issues。
#30 / #31 / #32 的拆分暴露了 evidence-sync 风险：上游 backend/frontend 在
Plane 上看似完成，但若分支未集成或 ADP execution result 缺失，最终 integration-only
issue 会因为依赖证据不完整而 Blocked。后续类似 UI 功能应避免纯“最终闭环”子 issue，
除非上游 branches、MR、verification 和 ADP evidence 已经是 review-terminal，且该
closure issue 只负责审计和汇总。
当前已有资料：
- 功能策划：
docs-site/docs/planning/project2-game-feature-library-v1/features/monster-npc-manual.md。 - Hub UI handoff：
specs/features/monster-npc-manual/ui/monster_manual/ui-handoff.yaml。 - 美术证据评审：
specs/features/monster-npc-manual/ui/monster_manual/art-ui-handoff.review.md。 - 原始美术证据：
project2-art-svn:new-tower-defense-ui-official-ui/图鉴/下的 3 张 JPG、1 个 PSD 和 5 个卡牌 PNG。
当前缺失 contract：
- Planning：正式配置源、字段命名、奖励引用、阈值、语言 key、红点规则是否包含进度宝箱。
- Art：
project2.art_ui_handoff.v1、PSD metadata、完整导出清单、资源尺寸、状态图、设计分辨率和 art owner review。 - Frontend：Unity module、panel/prefab/view、资源导入路径、Command/事件命名、节点绑定、适配策略和截图验证入口。
- Backend：状态权威端、首次遇到触发点、奖励发放、防重复领取、持久化和 API/proto 是否需要后端 owner。
- QA：默认态、未解锁、可领奖、已领取、详情、tips、进度宝箱、红点、异常/后端不可用、适配截图和回归范围。
推荐后续执行 plan：
PL-001：确认图鉴配置 contract、奖励/阈值、语言 key 和红点完整规则。ART-001：在project2-art生成图鉴art-ui-handoff包，覆盖 PSD metadata、导出图、资源命名和状态图。HUB-002：用已审核的 Planning/Art 结果更新ui-handoff.yaml，清掉已解决 open questions。BE-001：仅当奖励、持久化或防重复领取需要可信端时实现 backend contract。FRO-001：前端消费ui-handoff实现入口、主界面、页签、卡片状态、详情、tips、红点和资源接入。IT-001：联调首次遇到、领取、进度宝箱、红点刷新和重登/异常状态。QA-001：产出截图、交互、适配、奖励防重和回归 evidence 后进入 producer review。