wordpress-theme-aksrt/.specs/plans/frontend-modal-loading-upgrade.md

Plan: Frontend Modal Loading Upgrade

This is the coordination plan for the three executable plans below. Implementation work should run in dependency order; the detailed phase checklists live in the linked plan files.

Architectural Decisions

• Execution split: The shared modal runtime is a prerequisite. Identity/badges and orders/VIP can then proceed in parallel, each with its own domain API, UI, query optimization, and gray-release evidence.
• One canonical runtime: AksrtModalRuntime owns shell, skeleton, lifecycle, cancellation, cache, state, focus, and telemetry. Domain scripts only provide loaders and view models.
• Canonical data boundaries: Keep aksrt/v1, existing domain services, native operational admin, and AKSRT_Settings as the boundaries. No duplicate facts, compatibility reads, or long-lived old/new modal implementations.
• No core table replacement: Use existing order, identity, user-meta, payment, and badge data. The orders plan may add the required composite index through the existing DB migrator and schema-version process.
• Staged release: Roll out identity/badges first, then orders, then VIP payment. Each domain has an independent temporary switch and must meet the performance/error budget before the next switch is enabled.

---

Phase 1 — Shared modal runtime is ready for domain work

Detailed plan: .specs/plans/frontend-modal-runtime.md

User stories: US1–3, US12–14.

What to build

Complete both runtime phases: baseline/rollout observability and the cancellable shell/loader/cache/state contract. This phase is a foundation exception because all four existing flows currently own incompatible modal shells and request lifecycles; the runtime is demoable through the existing remote-modal entry path before domain JSON migrations begin.

Done when

• .specs/plans/frontend-modal-runtime.md Phase 1 and Phase 2 checklists are checked, php tools/audit-admin-contracts.php exits 0, and node --check passes for all runtime JS.
• Browser scenarios modal-baseline, modal-shell-lifecycle, and modal-cache-dedupe show shell-first behavior, cancellation, deduplication, invalidation, focus restoration, and cold/warm metrics.
• git grep inventory identifies every old remote-modal caller and labels the remaining domain migration owner before either business plan starts.

---

Phase 2 — Identity/badges and orders/VIP have vertical slices

Detailed plans: .specs/plans/frontend-modal-identity-badges.md and .specs/plans/frontend-modal-orders-vip.md

User stories: US4–11, US13.

What to build

Run the identity/badge plan and orders/VIP plan in parallel after Phase 1. Each plan must finish its read path, write path, query/API/UI integration, permission handling, and browser regression scenarios before its gray-release phase.

Done when

• .specs/plans/frontend-modal-identity-badges.md Phases 1–2 and .specs/plans/frontend-modal-orders-vip.md Phases 1–2 are checked with their named SAVEQUERIES, PHP, JS, API, and browser scenarios passing.
• Identity/badge and order/VIP loaders use independent cache/invalidation tags and cannot reuse another user or domain's payload.
• The native order/after-sale and identity/badge operational surfaces remain usable; no operational workbench is added to the Admin SPA.

---

Phase 3 — All domains are gray-released and old paths are removed

Detailed plans: the Phase 3 sections of all three detailed plans.

User stories: US1–14.

What to build

Release identity/badges, then orders, then VIP payment using independent switches. Compare shell/ready/error/status-mismatch metrics against the PRD budgets, pause the next domain on regression, update user-center summaries after successful writes, and remove old HTML/AJAX/domain-specific modal calls after each domain is permanently enabled.

Done when

• The Phase 3 checklist in each detailed plan is checked, with php tools/audit-admin-contracts.php, changed-file php -l, and changed-file node --check all passing.
• Desktop and mobile evidence shows approximately 100ms shell visibility, 200ms cache-hit content, p75 ≤800ms cold content, and p95 ≤1.5s initial budget, with errors/status mismatches recorded per domain.
• git grep confirms no active target old HTML badge modal, duplicate VIP purchase/poll coordinator, hard-coded order REST root, or bypassing domain loader remains after cutover.
• The final release record identifies the removal version for temporary rollout settings and confirms no compatibility alias, old option double-read, second fact store, or long-lived dual implementation remains.

---

Out of Scope

• 修改会员价格、会员权益、支付网关规则、订单账务、退款核算、认证资格/审核政策或徽章授予条件；这些规则只允许被新的流程正确调用和展示。
• 新增支付渠道、替换支付供应商、在浏览器保存支付凭证，或改变支付回调/异步结算机制。
• 新增公开认证资料库、向其他用户暴露认证文档、跨用户查看订单或徽章数据。
• 把订单、售后、认证审核或徽章运营工作台迁移进配置型 SPA；日常运营仍属于原生 WordPress 后台。
• 全站页面导航、用户中心信息架构、品牌设计系统或所有非弹窗页面的全面重做；本期只统一弹窗运行时和四类流程所需的轻量体验。
• 强制页面加载时预取所有弹窗数据、长期持久化敏感弹窗数据、建立订单/认证/徽章的第二套事实存储或长期保留旧新双路实现。
• 以新增兼容别名、旧 option 双读、静默降级或数据迁移层解决旧实现问题；流程切换后以新的规范化链路为唯一实现。
• 建立独立的数据仓库、复杂转化漏斗或第三方用户行为追踪系统；本期观测只服务于弹窗性能、错误和业务状态闭环。

Open Questions

• 部署是否已有统一的浏览器 RUM/Server-Timing 收集端；默认先提供 marks、响应头和现有部署观测，不新增主题指标表。
• 复合订单索引与临时 rollout 设置的删除版本需要在最终发布记录中确认。