aetherbound-guild/docs/plans/M65_DEV3R_GUILD_CONTRACT_MIGRATION.md

M65 · DEV-3R 公会 / 委托 / 装备检视迁移计划

活跃计划。当前只有 M65-A 处于 IN_PROGRESS。

目标与停止点

把公会页 runtime/entry/views/guild_page_view.gd（及它调用的 runtime/ui/m52/guild_*.gd 模块）从「旧桌面栏杆画 + 私有 flat 药丸 + 入口状态图标」迁移到共享手绘族 （PageChrome + UITokens + UIFactory/UIIcon），随后同一计划覆盖委托页与装备检视。

停止点：Guild / Contract / 装备检视三页在 1280x720 单一权威尺寸下墨迹 0 违规、 m53/m54 探针严格通过、m60-playthrough 34 步不破、owner 看到展示图； 之后进入 DEV-4R。

视口政策（引用 GOAL 2026-09-13 owner 决定）

只做一种横屏尺寸 1280x720；CONTENT_SCALE_ASPECT_KEEP；不得新增第二套构图或 按尺寸分叉。旧 P9.x/p10_2 遗留分支随各自轮次清理。

现状实测（2026-09-13，1280x720）

区域	现状	目标
顶栏 GuildTopRail + 三段 TextureRect	entry/guild_desk_v001/top_rail/* 画材质	header_band 顶栏；三段节点保留为不可见兼容壳
底栏 GuildBottomRail + 三段 TextureRect	bottom_rail/* 画材质	dock_band 底栏；三段同样保留为兼容壳
状态位 GuildProgress/Coin/CompanyStatus	私有 _flat_style 药丸 + 隐藏的入口图标徽章	药丸 → 共享 card；图标 → UIFactory.attach_icon（模块已用），值文字已令牌
标题牌 GuildTitlePlate	ui/m52/guild_header（UIFactory 标签 + 描边）	保留模块，落进顶栏实测开口；文字改令牌
底部导航 GuildRosterButton/Equipment/Party/Risk	入口 guild_nav_icon 徽章 + 象牙标签	command_plate(secondary/disabled) + UIIcon + 令牌标签
委托板 GuildContractBoard/Active/Sticker	ui/m52/guild_contract_board 模块	Step B：板面与贴纸走共享 card/pip
厨房台 GuildMasterKioskTexture / GuildKioskCopyArea	私有 _flat_style 覆盖板	Step B：共享 card
成员卡 GuildMemberCard	ui/m52/guild_member_card	Step B：共享 card
装备检视（Market 的 equipment 分类）	market_page_view 旧 overlay 路径	Step C：并入 m52 共享材质，清 M62-I02

步骤

1. M65-A：顶栏 / 底栏 / 状态位 / 底部导航迁共享材质；m53 探针改为严格门。COMPLETE (2026-09-13)，attempt m65-guild 20260913T192920Z-91488。
   • 验收：ABG_M53_GUILD_INK_OK scanned>=2 violations=0（严格）、 ABG_DEV2_COMMIT_OK、ABG_DEV2_FULL_FLOW_TOUCH_OK、ABG_DEV1_ENTRY_TOUCH_OK、 guild_page_view_test 节点名与 intent 全过、ABG_M63_ENTRY_INK_OK。
2. M65-B：COMPLETE (2026-09-14)，attempt m65-board 20260914T025231Z-14632。委托板 / 厨房台 / 成员卡板面共享化（清剩余私有 _flat_style）， 逐状态捕获（empty / active / returned）核对。
3. M65-C：COMPLETE (2026-09-14)，attempt m65-contract 20260914T031408Z-31971。Contract 页（contract_choice_page_view）迁移；m54 探针严格 0 违规； 修 M62-I04（ContractCreationFacts 竖排溢出）。
4. M65-D：COMPLETE (2026-09-14)，attempt m65-equipment 20260914T033815Z-51448。装备检视并入共享 ledger、删死 overlay 路径（清 M62-I02）； 收口矩阵/账本/checkpoint。

M65-A 结果

• 顶栏 GuildTopRail：三段画材质保留为不可见兼容壳（modulate.a=0，节点名与测试契约不变）， 可见面改共享 header_band（GuildTopRailBand）；标题/状态文字落进带面。
• 状态位（GuildProgressStatus/GuildCoinStatus/GuildAnchorCompanyStatus）：私有 flat 药丸 → 共享 card（*Card 子节点）；值文字与图标仍由 M52 资源模块渲染（已是令牌/dark 图标）。
• 底栏 GuildBottomRail 同样改共享 dock_band；四个导航键（GuildRosterButton/GuildEquipment/ GuildParty/GuildRisk）改 command_plate(secondary/disabled) + UIFactory 图标 + 令牌标签； 设置齿轮（GuildSettings）改共享 utility_plate + 共享图标。
• m53 探针从"记录基线"改为严格门：违规 push_error 并 quit(1)；marker 计数改真实值。
• 源绑定 attempt m65-guild 20260913T192920Z-91488：guild_page_view_test 全部节点名/intent、 DEV2 建团与全流程、DEV1 入口触摸、m53 严格（2 扫描 0 违规）、m63 入口探针 全过。

M65-B 结果

• 成员名牌（GuildMasterIdentityPlate*）：私有深蓝 flat 板 + 象牙描边字 → 共享 card 羊皮纸芯片 + PageChrome.INK 深墨字（节点名与 GuildMasterIdentity%d 保留）。
• 委托板文案（ui/m52/guild_contract_board.gd）：页面私配色 → PageChrome.INK/INK_SOFT， 通知行改 UITokens.COLOR_DANGER（旧琥珀在米色板面上对比不足）。
• 探针升级：m53 fixture 改为带两名成员（此前空团，成员卡从未被扫过）， marker 改真实计数；ABG_M53_GUILD_INK_OK scanned=2 violations=0。
• 修一处测试卫生缺陷：入口/全流程测试用固定帧数等待启动页交接与重启恢复， 在慢机器上会读到 null 并卡死（本轮两次 TIMEOUT 的真因）。改为 _wait_for_node() 按条件轮询（上限 600 帧），两个测试恢复确定性通过。
• 源绑定 attempt m65-board 20260914T025231Z-14632：guild 视图契约、DEV2 建团、 DEV2 全流程、DEV1 入口触摸、m53 严格、m63 入口探针 全过，strict 0。

M65-C 结果

• 委托选择页：全屏羊皮卡改为不可见兼容壳（插画即页面的身份），头部文案落共享 header_band 牌面（实测卷边内缩），右栏难度/事实块直接落在画中羊皮纸板上（不再叠第二张卡）； 难度段按钮 command_plate(primary/secondary) + 深墨标签；通知/错误用 COLOR_DANGER。 页面私有的琥珀/描边私配色、entry_chrome 调用全部移除。
• M54 模块（header/board/party summary）文字改共享令牌；板面路线标题/文案加共享小卡底 （原先落在亮色天空上对比不足）。
• M62-I04 修复：ContractCreationFacts 两行文案的槽位 48→56（ContractPartySummary）， 英文与中文均在槽内。
• m54_contract_visual_probe 转严格门：违规 quit(1) 并打印 node/text/slot/font； marker 改 ABG_M54_CONTRACT_INK_OK scanned=2 violations=0 + ..._VISUAL_PROBE_OK locales=2 scans=2。
• 新发现并修复的 gate 缺陷（M65-I03）：Godot Dummy 音频驱动下，AudioStreamGenerator 的 playback 在进程退出时必被报为泄漏（最小复现 10/10；真实 CoreAudio 驱动 0/5）。 入口/全流程测试在入树前 audio_enabled = false（这些测试不验音频；音频生命周期仍由 P9.0R3 p9_0r3_audio_lifecycle_test 负责），Dummy 下 0/6 泄漏，尝试链恢复确定性。
• 源绑定 attempt m65-contract 20260914T031408Z-31971：页面契约、公会契约、建团、全流程、 入口触摸、m54 严格、m53 严格、m63 入口探针 全过，strict 0。

M65-D 结果

• 装备检视真实缺陷修复：实时路径（_render_m52_market_restore）的 ledger 只认 recruit —— 装备/路线选中时检视按钮被禁用、意图恒为 recruit_review、可用性读 recruit 名单。 现改为按 selected_kind 分派：装备 → MarketReviewEquipment + equipment_review， 路线 → MarketReviewRoute（仅查看、禁用），招募保持原契约；金额/可用性/标题/效果 全部走控制器快照（review + presentation）。
• 死 overlay 路径删除（M62-I02 结案）：_build_overlay 及其 17 个 helper （10 处私有 StyleBoxFlat、旧 SHP-001 覆盖层）已不可达，整体删除（1052 → 303 行）； 测试引用的节点名全部由实时路径重建（实测转储核对）。
• 共享 ledger 双行事实槽：M52CandidateLedger 增 detail_rows（默认 1，招募布局不变）， 装备/路线用两行槽承载效果文案（0.062 → 0.125；trait 行为空时隐藏，不与成本行重叠）。
• 严格装备探针：m52_market_visual_probe 收敛为单尺寸 1280×720 + 装备分类变体， marker 改真实计数（ABG_M59_INK_CHECK_OK scanned=6 violations=0）；装备栏首次进入 严格门即抓到两处真实溢出（细节槽竖排、可用性槽超宽），修正后 0 违规。
• 基础契约测试增补装备断言（MarketReviewEquipment 可用、equipment_review 具名、双行事实槽）。
• M65-I04 OPEN：tests/dev6/equipment_growth_test 仍因 DEV-6 范围功能（equipment_receipts 等收据/替换链路）未实现而失败；其装备检视入口断言在本轮已通过，留 DEV-6R 处理。

Frozen scope

• 玩法/经济/存档/路由不变；全部节点名（GuildTopRail*、GuildBottomRail*、 GuildProgressStatus、GuildCoinStatus、GuildAnchorCompanyStatus、GuildTitlePlate、 GuildAnchorTitle/Status、GuildRosterButton、GuildEquipment、GuildParty、GuildRisk、 GuildContractBoard/Active、GuildMarket、GuildSettings、GuildTitle、GuildNotice、 GuildContractReason、GuildMarketReason、GuildMember_* …）与 intent id 不变。
• M60-I03（已招募 Offer 占卡位）不在本计划。

Issue register

• M65-I01 OPEN：三段栏杆材质节点（*Rail Left/Center/Right）保留为不可见兼容壳， 等 guild_page_view_test 与旧捕获不再依赖后再议删除。
• M65-I02 OPEN：_flat_style 在本页多处仍用于覆盖板；Step B 逐处替换，未替换前 不新增其它使用点。
• M65-I03 OPEN（登记）：m53 探针 marker 文本里的 fixtures=3 与实际单尺寸不符， 本步改为真实计数。