From c77883fcbfb41d43a0aef41adaa51dbebac268a3 Mon Sep 17 00:00:00 2001
From: wdh-home <243823965@qq.com>
Date: Wed, 22 Apr 2026 22:28:59 +0800
Subject: [PATCH] docs: add profile page design spec
---
.../2026-04-22-profile-page-static-design.md | 213 ++++++++++++++++++
AGENTS.md | 14 +-
README.md | 6 +
3 files changed, 231 insertions(+), 2 deletions(-)
create mode 100644 .ai-specs/coding-specs/2026-04-22-profile-page-static-design.md
diff --git 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
new file mode 100644
index 0000000..586e17a
--- /dev/null
+++ 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["用户卡片
头像占位 / 登录文案 / 设置入口占位"]
+ PAGE --> VIP["会员引导卡片
图标占位 / 说明文案 / CTA 按钮占位"]
+ PAGE --> ASSET["学习资产四宫格
我的笔记 / 我的书架 / 我的收藏 / 浏览历史"]
+ PAGE --> RECENT["最近记录卡片
标题 + 空状态文案"]
+ PAGE --> MORE["其它功能列表
意见反馈 / 分享 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` 路由已存在，无需新增注册
+
+禁止事项：
+
+- 不提前抽新组件
+- 不顺手接登录态
+- 不顺手接页面跳转
+- 不为“以后可能要用”增加额外抽象
diff --git a/AGENTS.md b/AGENTS.md
index aae7248..fad256f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -85,8 +85,8 @@ flowchart LR
## 项目文档
-- **当前已启用文档**：根目录 `README.md`
-- **预留扩展目录**：`.ai-specs`（当前未创建；一旦创建必须在本节登记）
+- **当前已启用文档**：根目录 `README.md`、`.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md`
+- **预留扩展目录**：`.ai-specs`（已创建；后续新增/删除文档必须在本节登记）
- **要求**：开始修改前，先按任务类型定位文档；有对应文档必须先读；未命中时按本文件通用规则和现有同层代码风格实现。
### root-docs
@@ -103,6 +103,16 @@ flowchart LR
| `logic-specs` | 存放业务流程、页面信息架构、角色权限等业务说明 | 涉及多页面串联和复杂交互时补齐 |
| `sys-specs` | 存放环境、发布、CI、版本管理等系统级规则 | 涉及发布流程和工程治理时补齐 |
+### .ai-specs 已启用文档
+
+| 路径 | 用途 | 说明 |
+|:---|:---|:---|
+| `.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md` | `pages/profile/index` 未登录态静态页面设计 | 涉及本页结构复刻、静态数据组织、样式边界与验收范围时必读 |
+
+### 后端接口文档
+D:\Code3\wdp\xuanzhi-service\.worktrees\feat-xuanzhi-service\server\.ai-specs\doc-dict 字典参考
+D:\Code3\wdp\xuanzhi-service\.worktrees\feat-xuanzhi-service\server\.ai-specs\doc-api\admin 后端 api文档
+
## 可复用代码/组件
| 中文 | 代码文件名 | 说明 |
diff --git a/README.md b/README.md
index d20c82a..2bab0ca 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,7 @@
- 主包页面：`首页`、`登录页`
- 示例分包：`packages/demo/pages/workbench`
- 公共层：`services`、`stores`、`config`、`components`
+- AI 文档：`.ai-specs`
- 工程化：`ESLint`、`Jest`、`Prettier`、`miniprogram-ci`
## 环境准备
@@ -92,6 +93,7 @@ npm run format
```text
.
+├─.ai-specs # AI 规范与设计文档
├─components
│ ├─base # 基础组件封装，当前包含 app-button
│ └─biz # 业务组件封装，当前包含 entry-card
@@ -105,6 +107,10 @@ npm run format
└─utils # 纯工具函数
```
+`.ai-specs` 当前已启用文档：
+
+- `coding-specs/2026-04-22-profile-page-static-design.md`
+
## 运行说明
- 页面里不要直接调用 `wx.request`，统一走 `services/request`