From ee46a5b1f85d076fbd66ca86786fcc7e364d5507 Mon Sep 17 00:00:00 2001 From: wdh-home <243823965@qq.com> Date: Thu, 23 Apr 2026 11:06:01 +0800 Subject: [PATCH] docs: add static page migration design --- ...3-frontend-static-page-migration-design.md | 255 ++++++++++++++++++ AGENTS.md | 3 +- 2 files changed, 257 insertions(+), 1 deletion(-) create mode 100644 .ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md diff --git a/.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md b/.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md new file mode 100644 index 0000000..ade8e15 --- /dev/null +++ b/.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md @@ -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` 文档登记与本设计保持同步 + diff --git a/AGENTS.md b/AGENTS.md index fad256f..2b94793 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -85,7 +85,7 @@ flowchart LR ## 项目文档 -- **当前已启用文档**：根目录 `README.md`、`.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md` +- **当前已启用文档**：根目录 `README.md`、`.ai-specs/coding-specs/2026-04-22-profile-page-static-design.md`、`.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md` - **预留扩展目录**：`.ai-specs`（已创建；后续新增/删除文档必须在本节登记） - **要求**：开始修改前，先按任务类型定位文档；有对应文档必须先读；未命中时按本文件通用规则和现有同层代码风格实现。 @@ -108,6 +108,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` 老项目静态页面迁移设计 | 涉及旧项目页面迁移、分包归属、静态数据边界、导航与交互约束时必读 | ### 后端接口文档 D:\Code3\wdp\xuanzhi-service\.worktrees\feat-xuanzhi-service\server\.ai-specs\doc-dict 字典参考