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`