# `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` 文档登记与本设计保持同步