xuanzhi/xuanzhi-wx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3153494e7cecdb1d6f43d26f770ce6308c158152
xuanzhi-wx/.ai-specs/coding-specs/2026-04-23-frontend-static-page-migration-design.md

9.2 KiB
Raw Blame History

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 不变
  • 所有新增页面必须能从现有可见入口进入
  • 页面间只保留静态跳转链路，不建立真实业务流
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

静态数据模型约束

  • 页面只消费最小展示字段
  • 字段名按当前项目需要重新定义
  • 同一视觉卡片可以和旧项目使用不同字段名
  • 所有展示数据都由当前仓库内静态工厂返回

推荐数据形态：

{
  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 View Git Blame Copy Permalink