xuanzhi/xuanzhi-wx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

文档

Browse Source
This commit is contained in:
wdh-home
2026-04-23 21:46:46 +08:00
parent 19035e8f93
commit baa355fa8b
4 changed files with 1 additions and 2215 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md
View File

@@ -1,213 +0,0 @@
# `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` 路由已存在，无需新增注册
禁止事项：
- 不提前抽新组件
- 不顺手接登录态
- 不顺手接页面跳转
- 不为“以后可能要用”增加额外抽象

255
.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md
View File

@@ -1,255 +0,0 @@
# `frontend` 老项目静态页面迁移设计
## 文档元信息
- 日期：`2026-04-23`
- 目标仓库：`xuanzhi-wx`
- 参考来源：`D:\Code3\wdp\xuanzhi\frontend`
- 设计范围：`静态页面复刻 + 可点击导航 + 基础前端交互`
- 关联文档：`AGENTS.md`、`README.md`、`.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md`
## 目标
在不复刻旧项目接口、数据结构、状态管理、工程组织和业务逻辑的前提下，将 `frontend` 项目中的主要页面形态迁移到当前微信原生小程序仓库，形成一套：
- 保持当前 `4 tab` 结构不变
- 页面都能看得到并点得到
- 只依赖静态 `data` 和页面内交互
- 与当前项目目录职责一致
的静态 UI/UX 壳层。
## 范围与非目标
### 本次范围
- 完善现有主包页面：`pages/home/index`、`pages/library/index`、`pages/ai/index`、`pages/profile/index`、`pages/login/index`
- 新增分包页面：
- `packages/tcm/pages/*`
- `packages/mingli/pages/*`
- `packages/learning/pages/*`
- 补齐从主包 `tab` 页进入新增分包页的静态导航入口
- 在页面内保留纯前端交互：
- 切换
- 输入
- 弹层
- 抽屉
- 静态结果展示
- 新增纯静态数据与路由映射工具，服务页面渲染
### 非目标
- 不接入 `services/api/*`
- 不复用旧项目的 `services/*`、`stores/*`、`composables/*`、`utils/*workflow*`
- 不保留旧项目的 `bookId / recordId / passageId` 真实业务语义
- 不实现真实登录、历史、搜索、收藏、书架、阅读进度、AI 回答、八字排盘
- 不复制旧项目的页面目录命名和信息架构问题
- 不新增底部 `tab`
## 页面归属与路由设计
### 总体原则
- 主包继续承担 `tab` 与公共入口职责
- 新增业务页优先进入分包
- 已经存在的主包页面只做增强，不重复新建第二套首页或第二套我的页
### 主包保留页面
| 路由 | 角色 | 本次定位 |
|:---|:---|:---|
| `pages/home/index` | 首页 tab | 总入口页，承接中医域、易学域、学习中心入口 |
| `pages/library/index` | 典籍 tab | 保留中医书城主体，补易学阁入口 |
| `pages/ai/index` | AI tab | 保留中医 AI 主体，补命理解读和相关深入口 |
| `pages/profile/index` | 我的 tab | 复刻静态个人页，并补学习中心、资产、历史等入口 |
| `pages/login/index` | 登录页 | 改成纯静态登录展示页，不保留 mock 会话逻辑 |
### 中医分包
| 路由 | 对应旧页 | 定位 |
|:---|:---|:---|
| `packages/tcm/pages/ai-history/index` | `src/pages/tcm/ai-history/index.vue` | AI 历史静态页 |
| `packages/tcm/pages/assets/index` | `src/pages/tcm/assets/index.vue` | 学习资产静态页 |
| `packages/tcm/pages/bianzheng/index` | `src/pages/tcm/bianzheng/index.vue` | 辨证分析静态页 |
| `packages/tcm/pages/book-detail/index` | `src/pages/tcm/book-detail/index.vue` | 典籍详情静态页 |
| `packages/tcm/pages/search-books/index` | `src/pages/tcm/search-books/index.vue` | 搜索静态页 |
| `packages/tcm/pages/section/index` | `src/pages/tcm/section/index.vue` | 阅读页静态壳 |
| `packages/tcm/pages/placeholder/index` | `src/pages/tcm/placeholder/index.vue` | 占位说明页 |
### 易学分包
| 路由 | 对应旧页 | 定位 |
|:---|:---|:---|
| `packages/mingli/pages/hall/index` | `src/pages/mingli/books/index.vue` | 易学阁首页，重新命名为 `hall` |
| `packages/mingli/pages/bazi/index` | `src/pages/bazi/index.vue` | 八字排盘静态页 |
| `packages/mingli/pages/book-detail/index` | `src/pages/mingli/book-detail/index.vue` | 易学典籍详情静态页 |
| `packages/mingli/pages/search-books/index` | `src/pages/mingli/search-books/index.vue` | 易学搜索静态页 |
| `packages/mingli/pages/section/index` | `src/pages/mingli/section/index.vue` | 易学阅读静态页 |
| `packages/mingli/pages/interpret/index` | `src/pages/mingli/interpret/index.vue` | 命理解读静态页 |
### 学习中心分包
| 路由 | 对应旧页 | 定位 |
|:---|:---|:---|
| `packages/learning/pages/center/index` | `src/pages/learning/index.vue` | 学习中心聚合页 |
### 导航要求
- 保持当前 `4 tab` 不变
- 所有新增页面必须能从现有可见入口进入
- 页面间只保留静态跳转链路，不建立真实业务流
```mermaid
flowchart TD
HOME["pages/home/index"] --> TCM_BOOK_DETAIL["packages/tcm/pages/book-detail/index"]
HOME --> TCM_SECTION["packages/tcm/pages/section/index"]
HOME --> MINGLI_HALL["packages/mingli/pages/hall/index"]
HOME --> BAZI["packages/mingli/pages/bazi/index"]
HOME --> LEARNING["packages/learning/pages/center/index"]
LIBRARY["pages/library/index"] --> TCM_SEARCH["packages/tcm/pages/search-books/index"]
LIBRARY --> MINGLI_HALL
AI["pages/ai/index"] --> TCM_AI_HISTORY["packages/tcm/pages/ai-history/index"]
AI --> TCM_BIANZHENG["packages/tcm/pages/bianzheng/index"]
AI --> MINGLI_INTERPRET["packages/mingli/pages/interpret/index"]
PROFILE["pages/profile/index"] --> TCM_ASSETS["packages/tcm/pages/assets/index"]
PROFILE --> TCM_AI_HISTORY
PROFILE --> LEARNING
PROFILE --> TCM_PLACEHOLDER["packages/tcm/pages/placeholder/index"]
```
## 静态数据与最小复用层
### 目标
定义当前项目自己的静态展示模型，只为支撑页面渲染，不兼容旧项目业务模型。
### 允许新增的静态工具
| 路径 | 职责 |
|:---|:---|
| `utils/static-ux/route-map.js` | 维护页面跳转路径常量 |
| `utils/static-ux/shared.js` | 维护纯静态数据克隆、场景选择等无状态工具 |
| `utils/static-ux/tcm.js` | 维护中医域静态页面数据工厂 |
| `utils/static-ux/mingli.js` | 维护易学域与八字域静态页面数据工厂 |
| `utils/static-ux/learning.js` | 维护学习中心聚合页静态数据工厂 |
### 允许抽取的公共层级
- 少量全局视觉 token 放入 `app.wxss`
- 只抽纯静态、无业务含义的复用
- 页面结构优先在页面内落地，避免过早抽组件
### 禁止抽取的层级
- `services/api/*`
- `services/request/*`
- `stores/*`
- 旧项目的 `domain-*`、`standalone-storage*`、`workflow*`、`composables/*`
- 与后端 response contract 强绑定的 model、mapper、adapter
### 静态数据模型约束
- 页面只消费最小展示字段
- 字段名按当前项目需要重新定义
- 同一视觉卡片可以和旧项目使用不同字段名
- 所有展示数据都由当前仓库内静态工厂返回
推荐数据形态：
```js
{
card: { key, title, subtitle, icon, actionText },
book: { key, title, subtitle, coverText, tags },
section: { key, title, children },
historyItem: { key, label, title, subtitle, meta },
formPreset: { title, fields, examples, buttonText },
resultPreset: { title, summary, highlights },
baziPreset: { profile, pillars, summary, highlights }
}
```
## 交互边界
### 允许保留的前端交互
- 页面跳转
- tab / segment / 分类切换
- 输入框、textarea、选项选中态
- 抽屉、弹层、目录展开
- 静态结果卡显示与隐藏
- `wx.showToast` 占位提示
### 明确禁止的交互
- 真实登录态判断
- mock session 写入
- 本地持久化历史、收藏、书架、笔记
- 按真实 ID 请求详情
- 真实搜索过滤
- 真实阅读器分页逻辑
- 真实 AI 输出和引用结构
- 真实八字计算或记录管理
### 参数策略
参数只允许承担静态场景切换，不承担业务身份标识。
允许的参数示例：
- `kind=notes|bookshelf|favorites|history`
- `mode=qa|analysis|constitution`
- `domain=tcm|mingli`
- `scene=default|empty|result`
禁止继续沿用的旧式业务参数语义：
- `bookId`
- `recordId`
- `passageId`
如果某个页面确实需要多个视觉场景，应使用当前项目自定义的轻量参数，例如：
- `scene=classic-a`
- `scene=record-preview`
## 视觉风格约束
- `tcm` 域沿用当前项目暖金、米白、浅棕的卡片化风格
- `mingli / bazi` 域保留偏红棕的区分，但统一到当前小程序样式体系
- 同域页面的标题、卡片、按钮、背景节奏必须一致
- 不做截图级像素还原，优先保证结构、层级、节奏、交互反馈一致
- 不擅自重做当前项目已经确定的 tab 结构和全局视觉方向
## 实施边界
### 实施顺序
1. 更新 `app.json` 注册分包与页面路由
2. 搭建 `utils/static-ux/*` 静态数据层
3. 完善主包 4 个 tab 页和登录页的入口与静态结构
4. 落地 `tcm` 分包静态页
5. 落地 `mingli` 分包静态页
6. 落地 `learning` 分包静态页
7. 回查路由、入口、样式一致性与文档登记
### 禁止事项
- 不把旧项目目录整体照搬到当前仓库
- 不为了复刻 UI 顺手补接口或 store
- 不为了“以后可能会接后端”先设计复杂状态层
- 不新建第二套首页、第二套我的页、第二套主导航
## 验收标准
1. 当前项目保留 `4 tab` 结构不变
2. `frontend` 目标页面在当前仓库都有静态对应页
3. 当前已经存在的主包页只做增强，不重复建页
4. 所有新增页面都能从可见入口点进去
5. 页面内主要操作都有静态反馈、切换或跳转结果
6. 实现过程中不新增 API、request、store 依赖
7. 实现过程中不复刻旧项目数据结构、工具链和目录组织
8. `AGENTS.md` 的 `.ai-specs` 文档登记与本设计保持同步

1744
.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-implementation-plan.md
View File

File diff suppressed because it is too large Load Diff

4
AGENTS.md
View File

@@ -107,9 +107,7 @@ flowchart LR
| 路径 | 用途 | 说明 | | 路径 | 用途 | 说明 |
|:---|:---|:---| |:---|:---|:---|
| `.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md` | `pages/profile/index` 未登录态静态页面设计 | 涉及本页结构复刻、静态数据组织、样式边界与验收范围时必读 |
| `.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md` | `frontend` 老项目静态页面迁移设计 | 涉及旧项目页面迁移、分包归属、静态数据边界、导航与交互约束时必读 |
| `.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-implementation-plan.md` | `frontend` 老项目静态页面迁移实施计划 | 涉及实现顺序、文件落点、测试策略和分任务执行时必读 |
### 后端接口文档 ### 后端接口文档
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-dict 字典参考