From 644bafb35ce7d2bea7f79f0b3ef84ff6bedef845 Mon Sep 17 00:00:00 2001 From: unknown Date: Wed, 5 Aug 2026 16:11:50 +0800 Subject: [PATCH] docs(plan): promotion center standalone tab + UI/UX redesign --- .../user-promotion-center-inline-uiux.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 .specs/plans/user-promotion-center-inline-uiux.md diff --git a/.specs/plans/user-promotion-center-inline-uiux.md b/.specs/plans/user-promotion-center-inline-uiux.md new file mode 100644 index 00000000..e0fef24e --- /dev/null +++ b/.specs/plans/user-promotion-center-inline-uiux.md @@ -0,0 +1,68 @@ +# Plan: 用户中心内链推广中心与 UI/UX 重设计 + +> 现状校正：邀请卡片当前**已不在**“账号设置”中，而是作为一个区块内嵌在“收益中心 / revenue”标签内 +> （`inc/helpers/user-center-renderers/profile-revenue.php:63` 依据 `show_invite_section` `require profile-invite.php`）。 +> 本计划按用户决定，将推广能力抽出为**独立的 `promotion` 标签**，并对其完成 UI/UX 重设计。 + +## Architectural Decisions + +Durable decisions that apply across all phases: + +- **独立标签键 `promotion`**：在 `src/User/Center.php` 面板注册表新增 `promotion` 面板；标签键与 URL 参数统一为 `promotion`，复用现有 `?tab=` 机制，不新增前台路由或页面模板。 +- **复用现有用户中心壳与渲染管线**：沿用 `page-profile.php` 壳、`aksrt_get_user_center_render_context()` 上下文、`templates/parts/user-center/panel.php` 面板包裹、侧栏组合器、`mobile-tabs.php` 移动导航与 `aksrt_get_user_center_tab_url()` URL 生成；只新增/移动渲染片段，不复制渲染路径。 +- **可见性沿用现有开关**：推广标签的注册与渲染沿用现有 `$invite_on` 判定（`credits_enabled()` && `invite_enabled()` && `invite_registration_enabled()`，见 `Center.php:130-133` 与 `aksrt-user-center.php:497-500`）；任一关闭即不注册标签、不出现入口。 +- **深链归一到单一目标**：`invite` / `promotion` 深链统一解析到 `promotion` 标签（替换现有 `invite/promotion → revenue` 折叠）；保留 `invite → promotion` 归一以满足 PRD “旧邀请深链归一”，不保留 revenue 双渲染路径。 +- **单一邀请渲染位置**：邀请卡片只在推广标签渲染；`revenue` 标签恢复为纯“收益与提现”，不再 `require profile-invite.php`。 +- **复用既有业务通路**：继续使用现有 REST 端点 `aksrt/v1/invite/me`、`aksrt/v1/invite/list`（`src/Credits/Invite.php:49,56`，登录用户权限）与前端 `assets/js/credits.js` 的 `initInvite()`（`:193`，`[data-aksrt-invite]` 契约）；不新增邀请码生成、cookie、归因、注册绑定、奖励结算逻辑或第二套请求。 +- **样式模块化**：推广卡 `uc-promotion-*` 样式迁入独立 `assets/css/routes/user-center/promotion.css`，由 `assets/css/routes/user-center.css` 引入；从 `user-center/revenue.css` 移除，不引入独立 UI 框架。 + +--- + +## Phase 1 — 推广中心作为独立标签可端到端进入 + +**User stories**: US1、US4、US6、US7 + +### What to build + +将邀请能力从收益标签迁出为独立 `promotion` 标签的完整纵切：在面板注册表按现有邀请开关注册 `promotion` 面板；新增 `profile-promotion.php` 面板渲染器承接现有 `data-aksrt-invite` 卡片（本阶段保持行为一致，视觉重设计留待 Phase 2）；从 `revenue` 标签移除邀请区块使其恢复为纯收益/提现；将 `invite`/`promotion` 深链与运行时别名统一归一到 `promotion`；在桌面侧栏与移动导航暴露推广入口。REST 与 `credits.js` 邀请逻辑保持不变。 + +### Done when + +- [ ] `src/User/Center.php` 注册 `promotion` 面板（`type=panel`），其注册受 `credits_enabled() && invite_enabled() && invite_registration_enabled()` 门控；三者任一关闭时 `get_dashboard_tabs()` 不含 `promotion`；`revenue` 面板的注册不再依赖 `$invite_on`。 +- [ ] 新增 `inc/helpers/user-center-renderers/profile-promotion.php` 输出含 `data-aksrt-invite` 的卡片；`aksrt-user-center.php` 的 `$built_in_tabs`（`:182`）与视图映射（`:147-162`）能将 `promotion` 解析到该文件；`profile-revenue.php` 不再 `require profile-invite.php`（`grep -n "profile-invite" inc/helpers/user-center-renderers/profile-revenue.php` 无结果）。 +- [ ] 深链归一：`aksrt_get_user_center_tab_url()`（`aksrt-user-center.php:106`）、`aksrt_user_center_resolve_tabs()`（`:289`）、`aksrt_user_center_runtime_config()` 的 `tabAliases`（`:347-350`）与 `inc/modules/user-parts/urls.php` 别名表（`:31-37`）均将 `invite`/`promotion` 归一到 `promotion`；访问 `?tab=invite` 服务端激活 `promotion` 面板（`is-active` 落在 `#panel-promotion`）。 +- [ ] 桌面侧栏（`sidebar-nav.php` 或 `sidebar-creator.php`）与 `mobile-tabs.php`（经 `dashboard_tabs` 自动渲染）暴露“推广中心”入口，其 `href` 来自 `aksrt_get_user_center_tab_url('promotion')`；`assets/js/credits.js` `initInvite()` 仍通过 `[data-aksrt-invite]` 绑定（该契约选择器未改名）。 +- [ ] 运行 `php tools/audit-admin-contracts.php`，退出码为 0 且报告 `errors=0`。 + +--- + +## Phase 2 — 推广中心完成 UI/UX 重设计与移动适配 + +**User stories**: US2、US3、US5 + +### What to build + +在独立推广标签内按“成果概览 → 分享操作 → 奖励说明 → 邀请记录”优先级重组信息架构并完成视觉重设计；把 `uc-promotion-*` 样式迁入独立 `promotion.css` 模块；确保加载中/空数据/请求失败的非误导状态反馈、键盘可操作的复制交互与可见成功/失败反馈、语义化结构与不只依赖颜色的状态；移动端单列、无横向溢出、复制按钮易触达。数据仍来自现有 `/invite/me`、`/invite/list`。 + +### Done when + +- [ ] 新增 `assets/css/routes/user-center/promotion.css` 承载 `uc-promotion-*` 规则并在 `assets/css/routes/user-center.css` 中 `@import`；`assets/css/routes/user-center/revenue.css` 不再包含 `uc-promotion-*` 规则（`grep -n "uc-promotion" assets/css/routes/user-center/revenue.css` 无结果）。 +- [ ] `profile-promotion.php` 面板按“成果概览 → 分享操作 → 奖励说明 → 邀请记录”顺序输出；复制按钮为可聚焦的 `