2026年山东大学软件学院创新项目实训博客（一）

一、工作进展

本阶段围绕 MetalCat 前端工程，把产品在 Web 侧的定位落实为可运行的信息架构与技术骨架，并完成与后续接口对接相匹配的占位逻辑。

主要产出：

1. 确定与产品文档一致的主交互结构：四模块（身体 / 训练 / 营养 / 发现）+ 首页总览 + 全局 AI 对话区 + 账户与登录路径。
2. 确定前端技术栈为 React 18 + TypeScript + Vite + React Router + Ant Design + Tailwind CSS + Zustand；一期不引入 TanStack Query。
3. 在仓库 app/ 工程中搭建可运行前端框架：源码根为 app/src/，其下以 app/src/app/ 承载应用入口、路由表、布局壳与全局 Provider；app/src/pages/ 为各路由页面入口；app/src/features/ 放跨页面业务（如全局对话）；另有 app/src/components/、app/src/services/（含 API 封装）、app/src/stores/ 等。本阶段已跑通路由、双端布局壳与全局对话壳，约定与 docs/prd/app/AECHITECTURE.md、app/AGENTS.md 对齐。
4. 完成登录态与 HTTP 请求层的占位（环境变量配置 API 根地址、本地认证状态、登录页表单壳），为后续真实鉴权与业务接口预留扩展点。

本地可启动开发服务器跑通主流程；宽窄屏共用同一套路由，以固定断点切换桌面布局与移动布局；登录入口独立于主布局之外，便于日后做登录态与重定向策略。

二、详细内容

1. 产品形态与信息架构在前端的体现

MetalCat 定位为面向健身新手的一站式 AI 健身助理，前端需要承载的是「展示区 + 对话区」并列的体验，而不是四个互不相干的静态页。若只做四个独立页面而不把 AI 嵌进布局，对话入口一旦过深，产品容易被理解成普通资讯类站点，AI 使用率会受影响。

当前做法是：用统一的一级导航保证用户在同一 SPA 内切换模块；把全局对话挂在布局层，桌面端侧栏与主内容、对话区同屏，对话区可折叠；移动端用底部导航配合抽屉式对话与悬浮入口，避免小屏上对话被边缘化。首页用四张卡片概括四个模块的入口与说明，对应一期「主界面四卡片总览」。Agent 之间的状态同步由 Agent 架构模块负责，本阶段前端只把壳、路由、页面与业务 feature 的分层定清楚，为后续用结构化数据驱动卡片与详情留出边界。

2. 技术选型

构建与语言：Vite 在冷启动与热更新上优于传统 CRA 类方案，适合实训阶段频繁改界面；TypeScript 便于在对接接口前固定组件与请求数据的形状，减少联调低级错误。

路由：React Router 与 React 生态一致；主布局嵌套子路由形成「壳 + 页面」；登录态单独挂在布局外，避免未登录仍套完整导航的不合理体验。

UI 与样式：Ant Design 覆盖表单、卡片、按钮等高频场景，缩短骨架周期；Tailwind 承担布局与视觉骨架，与「组件库 + 工具类样式」的分工约定一致，后续换主题或抽设计 token 时改动面可控。

状态：当前全局状态规模小，Zustand 足够轻量。一期暂缓 TanStack Query，理由是接口与缓存策略尚未稳定，过早引入会把加载态、重试与缓存键和后端强耦合；待契约稳定后再评估是否增加专门的数据获取层。

3. 前端工程初始化

前端工程以仓库下的 app/ 为 npm 工程根，页面与逻辑源码集中在 app/src/（注意与 app/src/app/ 这一层「应用壳」目录区分：后者专管入口、路由与布局）。当前目录框架如下（只列一级职责，不展开到具体文件）：

app/
└── src/
    ├── app/          # 入口、路由表、布局壳、Provider
    ├── pages/        # 各 URL 页面入口，以拼装为主
    ├── features/     # 跨页面业务（如全局对话）
    ├── components/   # 可复用展示组件
    ├── services/     # 请求与适配（含 API 客户端）
    ├── stores/       # 全局状态
    ├── hooks/、utils/、styles/ 等

（上表路径均相对于仓库中的 app/ 工程，即实际为 app/src/...。）

核心意图仍是分层、单向依赖：路由与壳在 app/src/app/ 侧统一注册；叶子路由落在 app/src/pages/，只负责组装 feature、组件与 store；HTTP 细节不进页面，集中在 app/src/services/；跨页状态进 app/src/stores/。认证当前用占位跑通导航，接口定稿后再在 services 与 stores 中接 token、请求头与 401。约束见 app/AGENTS.md，结构说明与 docs/prd/app/AECHITECTURE.md 同步，便于多人并行。

4. 登录与请求层占位

本阶段只固定三件事：用环境变量配置 API 根地址，使请求与部署环境解耦；全局 store 暴露是否已登录与展示名等最小字段，后续可扩展 token 与过期时间；登录页提供表单壳与登录成功后的回到首页流程。真实提交、鉴权失败与持久化等细节留待接口约定明确后再实现，避免在协议未定稿时写死逻辑。

5. 多端适配

多端采用同一构建产物，在约定断点处分叉为桌面布局与移动布局，并与聊天区域的断点保持一致，避免同一视口宽度下行为矛盾。纯 CSS 媒体查询也能做响应式，但移动端需要抽屉与悬浮对话入口，双布局组件比强行用单棵 DOM 树折来折去更易维护，因此采用脚本侧断点切换壳，而不是只靠样式缩放。

三、总结

本阶段完成了从产品设计到可运行前端骨架的落地，核心是在信息架构、技术栈与分层规范上做出一组与当前阶段匹配的选择。

1. 统一 SPA + 双布局壳：同一套路由下区分桌面与移动，全局 AI 挂在布局层，避免对话入口被弱化。
2. Vite + TS + AntD + Tailwind + Zustand：在开发效率与一期复杂度之间折中，并遵循一期暂缓重型数据获取库的约定。
3. 分层与协作约定：页面拼装、业务进 feature、请求进服务层，降低后续并行开发与联调冲突。
4. 认证与 HTTP 占位：先固定状态形状与环境配置，再接入真实鉴权，避免过早绑定接口细节。

共同原则是：不为尚未稳定的协议过度设计实现。下一阶段将侧重具体页面数据展示、接口联调或 mock，并开始把 Agent 结构化输出纳入 UI 映射。