docs: add profile page design spec

2026-04-22 22:28:59 +08:00
parent 1949cb9c1e
commit c77883fcbf
3 changed files with 231 additions and 2 deletions
--- a/.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md
+++ b/.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md
@@ -0,0 +1,213 @@
+# `pages/profile/index` 未登录态静态页面设计
+
+## 文档元信息
+
+- 日期：`2026-04-22`
+- 目标页面：`pages/profile/index`
+- 设计范围：`结构复刻 + 纯静态展示 + 未登录态`
+- 关联文档：`AGENTS.md`、`README.md`
+
+## 目标
+
+在不引入接口、store、页面跳转和新增组件的前提下，将 `pages/profile/index` 从占位页升级为一个可直接展示的个人中心静态页面。页面目标是复刻参考图的区块结构和信息层级，同时沿用仓库现有暖色、卡片化视觉语言，避免做截图级像素还原。
+
+## 范围与非目标
+
+### 本次范围
+
+- 仅修改 `pages/profile/index.js`、`pages/profile/index.wxml`、`pages/profile/index.wxss`
+- 页面首屏固定为未登录态
+- 页面包含 5 个区块：用户卡片、会员引导卡片、学习资产四宫格、最近记录空状态、其它功能列表
+- 页面内容使用静态 `data` 驱动
+- 按微信原生小程序常规写法实现，不新增通用组件
+
+### 非目标
+
+- 不接入 `stores/modules/session.js`
+- 不调用 `services/api/*` 或 `services/request/index.js`
+- 不新增图标图片资源、不新增字体资源
+- 不接按钮点击、页面跳转、分享能力、登录能力
+- 不处理已登录态、真实记录列表、真实资产计数
+
+## 方案选择
+
+### 备选方案
+
+1. 页面内一次性落地
+2. 先抽资产区和列表行为局部组件
+3. 强行复用现有 `components/base/app-button` 与 `components/biz/entry-card`
+
+### 最终选择
+
+采用“页面内一次性落地”方案。
+
+选择原因：
+
+- 当前目标是静态结构复刻，范围小，直接写在页面内更短更稳
+- 现有组件与目标结构不贴合，强复用会增加样式扭曲和模板复杂度
+- 通过结构化 `data` 和分区 class 命名，后续仍可平滑抽组件，不会锁死实现
+
+## 页面结构
+
+页面按纵向信息流组织，顺序固定如下：
+
+1. 用户卡片
+2. 会员引导卡片
+3. 学习资产四宫格
+4. 最近记录
+5. 其它功能
+
+各区块关系如下：
+
+```mermaid
+flowchart TD
+    PAGE["profile-page 页面根容器"] --> USER["用户卡片<br/>头像占位 / 登录文案 / 设置入口占位"]
+    PAGE --> VIP["会员引导卡片<br/>图标占位 / 说明文案 / CTA 按钮占位"]
+    PAGE --> ASSET["学习资产四宫格<br/>我的笔记 / 我的书架 / 我的收藏 / 浏览历史"]
+    PAGE --> RECENT["最近记录卡片<br/>标题 + 空状态文案"]
+    PAGE --> MORE["其它功能列表<br/>意见反馈 / 分享 APP / 关于我们 / 设置"]
+```
+
+## 数据模型
+
+页面 `data` 只承载静态展示信息，建议按 5 组对象/数组组织：
+
+```js
+{
+  userCard: {
+    avatarText: '?',
+    title: '点击登录',
+    subtitle: '登录后查看你的学习资产',
+    settingsText: '设'
+  },
+  vipCard: {
+    icon: '会员',
+    title: '开通会员',
+    subtitle: '解锁更多学习资料、AI 仪表与阅读辅助能力',
+    actionText: '成为会员'
+  },
+  assetItems: [
+    { key: 'notes', icon: '记', title: '我的笔记', count: 0 },
+    { key: 'bookshelf', icon: '架', title: '我的书架', count: 0 },
+    { key: 'favorites', icon: '藏', title: '我的收藏', count: 0 },
+    { key: 'history', icon: '史', title: '浏览历史', count: 0 }
+  ],
+  recentRecord: {
+    title: '最近记录',
+    emptyTitle: '还没有回访记录',
+    emptyDescription: '去典籍阅读或 AI 页完成一次学习，记录会出现在这里。'
+  },
+  moreItems: [
+    { key: 'feedback', title: '意见反馈' },
+    { key: 'share', title: '分享 APP' },
+    { key: 'about', title: '关于我们' },
+    { key: 'settings', title: '设置' }
+  ]
+}
+```
+
+约束：
+
+- `assetItems` 和 `moreItems` 必须使用 `wx:for`
+- `key` 只用于渲染稳定性和后续扩展，不在本次承担业务逻辑
+- 所有文本先静态写入 `data`，避免模板中散落魔法字符串
+
+## WXML 结构边界
+
+WXML 只保留三级边界：
+
+- 页面根：`profile-page`
+- 区块卡片：`section-card`
+- 区块内部局部结构：`profile-header`、`vip-banner`、`asset-grid`、`recent-panel`、`menu-list`
+
+结构要求：
+
+- 顶部用户卡片和会员卡片为独立卡片，不合并
+- 资产区一行固定 4 列，每项包含图标容器、标题、数字
+- 最近记录固定为空状态，不渲染列表分支
+- 其它功能为纵向列表，每一行使用“左文案 + 右箭头占位”的标准结构
+
+## 样式策略
+
+页面视觉遵循“结构复刻，风格贴合仓库”的原则。
+
+### 页面级
+
+- 延续当前项目已有的米白到浅金渐变背景
+- 保持主内容纵向滚动，顶部和底部有稳定安全边距
+
+### 卡片级
+
+- 统一使用浅底、圆角、大留白、轻阴影
+- 卡片间距与首页的 `section-card` 节奏接近
+- 避免复杂装饰、绝对定位角标和图片背景
+
+### 文本级
+
+- 区块标题延续首页的 `Songti` / serif 风格
+- 正文、副文案、数字采用更轻的系统字体层级
+- 用户卡片标题突出，辅助说明弱化
+
+### 图标级
+
+- 本次不新增图片资源
+- 头像、会员、四宫格图标、右箭头均用字符或简单容器占位
+- 图标容器风格统一，避免每块都出现不同视觉语言
+
+## 行为与数据流
+
+本页当前没有真实行为流，只保留静态展示结构。
+
+```mermaid
+flowchart LR
+    DATA["Page data 静态对象"] --> WXML["WXML 区块渲染"]
+    WXML --> WXSS["WXSS 卡片与布局样式"]
+    WXSS --> UI["未登录态个人中心静态页面"]
+```
+
+约束：
+
+- 不出现 `onLoad` 拉取数据逻辑
+- 不出现 `wx.navigateTo`、`wx.switchTab`、`wx.login`、`wx.getUserProfile`
+- 不出现依赖外部状态的分支渲染
+
+## 错误处理与边界
+
+由于本次没有网络请求和真实交互，错误处理重点放在布局稳定性：
+
+- `assetItems` 固定为 4 项；若后续数量变化，需要单独评估布局是否仍保持 4 列
+- 文案长度以当前中文文案为基准，样式需避免一行被异常挤压
+- 图标占位必须在没有外部资源时也能稳定渲染
+- 页面在微信常规设备宽度下不能出现卡片溢出、四宫格换行错位、列表箭头挤压
+
+## 测试与验收
+
+本次设计对应的最小验证范围：
+
+1. 页面整体包含 5 个区块，顺序与设计一致
+2. 学习资产区稳定为一行 4 列
+3. 最近记录展示为空状态，不出现列表分支
+4. 其它功能区展示 4 行静态入口
+5. 改动范围仅限 `pages/profile/index.*`，不新增业务组件、不接 API / store
+
+若补测试，优先补：
+
+- 页面 `data` 结构渲染测试
+- 四宫格与功能列表项数量断言
+- 关键标题文案存在性断言
+
+## 实施边界
+
+实施顺序固定为：
+
+1. 重写 `pages/profile/index.js` 中的静态数据
+2. 重写 `pages/profile/index.wxml` 的区块结构
+3. 重写 `pages/profile/index.wxss` 的整体布局与卡片样式
+4. 回查 `app.json` 中 `pages/profile/index` 路由已存在，无需新增注册
+
+禁止事项：
+
+- 不提前抽新组件
+- 不顺手接登录态
+- 不顺手接页面跳转
+- 不为“以后可能要用”增加额外抽象