docs: add static page migration design
This commit is contained in:
@@ -0,0 +1,255 @@
|
||||
# `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` 文档登记与本设计保持同步
|
||||
|
||||
Reference in New Issue
Block a user