Jyuhou Wong - 黃宇豪

MoonAI-Web v1.0.0 前端开发总结

Posted on

uml

1. 项目概况

  • 项目名称：MoonAI Web
  • 版本号：v1.0.0
  • 上线环境：测试环境 https://agent.moontestenv.com/
  • 目标平台：移动端为主，兼容桌面端
  • 项目角色：前端开发负责人

2. 技术栈

  • 框架：Vue 3 + <script setup> + TypeScript
  • 构建工具：Vite 6 + esbuild（启用原生 ESM）
  • 包管理工具：pnpm
  • 样式体系：UnoCSS（原子化）+ Less 自定义主题变量（light / dark）
  • 路由系统：unplugin-vue-router（基于文件自动生成）
  • 状态管理：Pinia + pinia-plugin-persistedstate（本地持久化）
  • 国际化支持：vue-i18n（支持英文 / 中文）
  • 网络层封装：Axios 封装统一请求
  • 组件库：Vant 4（移动优先设计）
  • 自动导入：unplugin-auto-import + unplugin-vue-components
  • 调试工具：vConsole（按需注入）
  • 单元测试：Vitest + @vitest/ui
  • Lint & 提交校验：ESLint + simple-git-hooks + commitlint + lint-staged

3. 关键实现

第三方登录整合

  • 支持 Google / Apple 登录，统一跳转逻辑封装
  • 动态生成 nonce 与 state，防止 CSRF / Replay 攻击
  • 使用 id_token + response_mode=fragment 直接获取身份令牌
  • 判断系统：基于 UA 使用不同跳转策略（iOS / Android）
  • iOS 使用 Universal Link 唤起 App，未安装 fallback 到中间页或商店链接
  • Android 使用 Scheme + App Store 双跳兼容
  • 提供手动点击、自动 fallback、多渠道 fallback 安全机制

SVG 图标类型自动生成

  • 自定义 Node 脚本扫描 assets/icons 目录生成 svg-icon.d.ts 类型文件
  • 实现图标组件的类型提示与 IDE 补全支持

横向滚动组件封装

  • 使用 Splide + AutoScroll 插件构建支持无限循环的横滑卡片
  • 支持 hover 暂停、离开自动恢复、支持手动滑动不影响自动动画

移动 + 桌面端双适配策略

  • 使用 vw/vh + 响应式容器适配不同尺寸设备
  • 桌面端限定内容宽度为 390px 并居中显示，保持移动体验一致性

暗黑模式与主题切换

  • 使用 html.dark 控制暗黑模式样式激活
  • 支持根据系统偏好自动切换
  • 设置 <meta name="theme-color"> 动态响应主题
  • 支持 favicon 图标深浅切换

4. 文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
src/
├── api/                    # API 接口封装
├── assets/                 # 静态资源（icons / images）
├── components/             # 通用组件库（Button / Popup 等）
├── composables/            # 组合式函数逻辑封装
├── constants/              # 常量定义（环境、枚举）
├── directives/             # 自定义指令（如 v-focus-border）
├── locales/                # 国际化语言包（en-US / zh-CN）
├── pages/                  # 页面模块（文件路由自动生成）
├── router/                 # 路由注册与类型定义
├── stores/                 # 状态管理模块（Pinia）
├── styles/                 # 全局样式、变量与主题
├── types/                  # 项目类型声明
├── utils/                  # 工具函数（Clipboard / OAuth / Request 等）
└── main.ts                 # 项目入口

5. 开发与构建脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
pnpm dev           # 启动本地开发环境
pnpm build:cf      # Cloudflare Pages 构建（支持环境判断）
pnpm build:dev     # 开发构建（含 debug 信息）
pnpm build:pro     # 正式环境构建
pnpm preview       # 本地预览 dist 内容
pnpm lint          # ESLint 检查代码风格
pnpm lint:fix      # 自动修复代码格式问题
pnpm typecheck     # TS 类型检查（vue-tsc）
pnpm test          # 单元测试（Vitest）
pnpm test:ui       # 单元测试 UI 面板模式
pnpm release       # 自动版本号变更 + Git Tag 发布
pnpm commitlint    # 检查 Git 提交信息格式
pnpm prepare       # 初始化 Git Hooks（pre-commit、commit-msg）

6. 问题记录与优化建议

问题 当前处理 后续建议
Universal Link 测试复杂 使用 schema 跳转 + fallback 到商店链接 引入 Universal Link 中转页，通过设置 href=universal link 跳转到独立页面，在该页面判断是否已安装 App，支持自动跳转 Scheme、手动触发 Scheme、或进入商店地址

7. 开发总结

  • 搭建完整 Vue 3 + Vite + UnoCSS 移动端前端架构，集成组件/路由/API 自动导入方案
  • 设计并实现第三方登录认证（Google / Apple）跳转与状态验证机制
  • 封装横向滚动组件，集成动画暂停/恢复与无缝轮播
  • 使用 Node 脚本自动生成 SVG 图标类型，保障开发时类型安全
  • 构建深色 / 浅色主题系统，支持 favicon 与系统颜色自动适配
  • 完善 CI 构建流程，支持测试 / 生产 / Cloudflare Pages 多环境构建与部署

8. 样式体系与 Vant 变量覆盖

  • 使用 Less 编写 light / dark 主题文件，分别通过 @import 引入

  • 使用 :root:root 提高变量优先级以覆盖 Vant 默认变量

  • 样式变量与设计系统映射，统一管理如文本、背景、边框、按钮等主题色

  • 定制组件样式：

    • 禁用默认滚动条（scrollbar-width / ::-webkit-scrollbar）
    • 自定义 .van-toast, .van-button, .van-tabs 等核心组件外观
    • 设置动画类 .fade-enter-* 控制页面切换动画
    • 通过 mask-image, transform, -webkit-mask-smoothing 优化 .van-image 展示质量

  • 支持 viewport 高度单位 100dvh，处理 iOS 地址栏收缩带来的布局问题