前端移动脚手架 ​

一、项目概述 ​

基于 Vue 3 的移动端 H5 应用脚手架模板，面向海政通 / 海易办等移动端场景，提供开箱即用的开发体验。

二、运行环境要求 ​

​

三、技术栈 ​

3.1 文件路由（unplugin-vue-router） ​

• 自动生成路由：src/views/ 目录结构自动映射为路由，无需手动维护路由表
• 类型安全：自动生成 typed-router.d.ts，路由跳转有 TypeScript 提示
• 动态路由：通过 [param] 命名约定支持动态参数

src/views/
├── (home)/
│   ├── index.vue         → /
│   ├── query/
│   │   ├── index.vue     → /query
│   │   └── [id].vue      → /query/:id
│   └── routes/
│       ├── index.vue     → /routes
│       └── [slug].vue    → /routes/:slug
├── tools/
│   └── index.vue         → /tools
└── [...all].vue          → /:all(.*)  // 404

类型安全路由 ​

<script setup lang="ts">
const router = useRouter();
router.push('/query');

const route = useRoute('/query/[id]');
console.log(route.params.id); // 类型安全
</script>

3.2 API 自动导入 (unplugin-auto-import) ​

无需手动 import，直接使用 Composition API：

// without
import { computed, ref } from 'vue'

const count = ref(0)
const doubled = computed(() => count.value * 2)

// 直接使用，无需 import
const count = ref(0)
const doubled = computed(() => count.value * 2)
const router = useRouter()

自动导入范围：

3.3 组件自动加载 (unplugin-vue-components) ​

• Vant 组件按需导入：模板中直接使用 <van-button>，无需手动 import
• src/components/ 下的组件自动全局注册
• 仅打包实际使用的组件，减小产物体积

<!-- 直接使用，无需 import -->
<template>
  <van-button type="primary">按钮</van-button>
  <van-cell-group>
    <van-cell title="单元格" value="内容" />
  </van-cell-group>
</template>

3.4 请求与数据管理（TanStack Query） ​

解决的痛点：

• 每个组件随手 onMounted + axios，缺乏统一管理
• loading / error 各写一遍，风格不统一
• 相同数据被多处重复请求，浪费带宽
• 滚动加载、预加载、轮询，每一个都是专项工程

核心能力：

• 自动缓存：相同请求在 staleTime 内直接返回缓存
• 请求去重：多个组件使用同一 queryKey，只发一次请求
• 状态统一：loading、error、data 开箱即用
• 后台刷新：数据过期后自动在后台刷新，用户无感知
• DevTools：开发环境可视化查看缓存状态

调用关系链：

组件 → useQuery → queryFn → axios（http.request） → 后端 API
                ↕
          缓存 / 状态管理

src/utils/http/ 中的 Axios 封装继续负责请求拦截、Token 注入、错误码处理；TanStack Query 在其之上负责缓存和状态管理。

详细使用指南： docs/tanstack-query.md

示例页面：/query

TanStack Query DevTools ​

开发环境下显示 Query DevTools 面板，可视化查看所有查询的缓存状态、数据内容、时间线。

状态说明

3.5 UI和工具库 ​

Vant 4 组件库 ​

移动端 Vue 组件库，轻量可靠。通过 unplugin-vue-components 实现按需自动导入。

数海组件库建设中

Tailwind CSS v3 ​

当前项目说明：

• v4依赖的现代 CSS 特性，比如 @property 和 color-mix()，低版本移动端有兼容性问题

VueUse ​

100+ 实用 Composition API 工具集，通过 unplugin-auto-import 自动导入，直接使用即可。

项目已在 vite.config.ts 中通过 unplugin-auto-import 自动导入 @vueuse/core，因此在 script setup 中可以直接使用 VueUse API，无需手动 import。

例如下面这段代码可以直接使用：

<script setup lang="ts">
const { width, height } = useWindowSize()
const { copy, copied } = useClipboard()

async function handleCopy() {
    await copy(`当前窗口尺寸：${width.value} x ${height.value}`)
    showToast(copied.value ? '复制成功' : '复制失败')
}
</script>
<template>
    <div class="space-y-3 rounded-xl bg-white p-4">
        <div>宽度：{{ width }}</div>
        <div>高度：{{ height }}</div>
        <van-button type="primary" block @click="handleCopy">
            复制窗口信息
        </van-button>
    </div>
</template>

如果想做输入防抖，也可以直接这样写：

<script setup lang="ts">
const keyword = ref('')

const runSearch = useDebounceFn((value: string) => {
    console.log('搜索关键词:', value)
}, 300)

watch(keyword, (value) => {
    runSearch(value)
})
</script>
<template>
    <van-field v-model="keyword" placeholder="请输入关键词" />
</template>

说明：

• VueUse 已作为项目基础能力安装，版本见 package.json
• 自动导入类型声明文件为 src/typings/auto-imports.d.ts
• 适合优先用于窗口尺寸、剪贴板、元素监听、滚动状态、媒体查询、防抖节流等常见场景

3.6 代码规范 ​

ESLint (@antfu/eslint-config) ​

• 一个配置搞定所有：ESLint Flat Config，内置 Stylistic 格式化规则
• 不再依赖 Prettier：通过 @stylistic/eslint-plugin 接管代码风格（缩进、引号、分号等）
• pnpm lint** 一条命令**：同时完成 lint 检查和代码格式化
• eslint-plugin-format：用于格式化 CSS / HTML / Markdown 等非 JS/TS 文件

// eslint.config.ts
import antfu from '@antfu/eslint-config';

export default antfu({
  vue: true,
  typescript: true,
  formatters: true,
  stylistic: { quotes: 'single', semi: true },
}, {
  rules: {
    'no-console': 'off',
    'vue/block-order': ['error', { order: ['script', 'template', 'style'] }],
  },
});

3.7 开发调试（Code Inspector） ​

快速定位代码位置

代码中展示代码对应的文件路径

在浏览器中点击页面元素，自动在 IDE 中打开对应源码文件并定位到行号。

3.7.1 Vue DevTools ​

Vite 插件形式集成，支持组件树查看、Pinia 状态、路由信息、性能分析。

3.7.2 VConsole 移动端调试 ​

• 开发环境自动注入，页面右下角显示绿色按钮
• 支持 Console 日志、网络请求、DOM 元素、存储信息查看

3.7.3 Git 提交规范 (CommitLint + czg) ​

完整的 Git 提交规范链路：

git add .
↓
pnpm commit              ← czg 交互式选择 commit type
↓
pre-commit hook           ← lint-staged 自动 eslint --fix
↓
commit-msg hook           ← commitlint 校验 message 格式
↓
提交成功 ✓

3.7.4 Mock 开发服务 ​

在项目根目录创建 mock/ 目录：

// mock/user.mock.ts
import { defineMock } from 'vite-plugin-mock-dev-server';

export default defineMock([
  {
    url: '/dev-api/users',
    method: 'GET',
    body: {
      code: 200,
      data: [
        { id: 1, name: '张三', department: '研发部' },
        { id: 2, name: '李四', department: '产品部' },
      ],
    },
  },
]);

配置代理

仅 proxy 中配置的路径会被 mock 拦截：

// vite.config.ts
server: {
  proxy: {
    '^/dev-api': { target: '' },
  },
}

3.8. 图标方案 ​

项目内置两种图标方案：i-icon 和 svg-icon。

选择建议：

• 大多数页面优先使用 i-icon
• 只有图标需要放在仓库里自己维护时，再使用 svg-icon

3.8.1. i-icon ​

组件位置：src/components/i-icon/index.vue

支持两种写法：

• 在线图标：直接传 Iconify 图标名
• 离线图标：从 @iconify-icons/* 按需导入图标对象

<script setup lang="ts">
import LucideHome from '@iconify-icons/lucide/home'

const onlineIcon = 'lucide:route'
const offlineIcon = LucideHome
</script>
<template>
    <div class="flex items-center gap-3 text-xl text-blue-500">
        <i-icon :icon="onlineIcon" />
        <i-icon :icon="offlineIcon" class="text-orange-500" />
    </div>
</template>

说明：

• 在线图标适合快速开发，图标名可在 Iconify 官网 查找
• 离线图标适合固定图标、减少运行时请求，例如官网里的 lucide:home 可对应导入 @iconify-icons/lucide/home

3.8.2. svg-icon ​

组件位置：src/components/svg-icon/index.vue

使用方式：

• 把本地 SVG 文件放到 src/assets/icons/
• 文件名就是图标名
• 在模板中使用 <svg-icon name="文件名" />

<template>
    <div class="flex items-center gap-3 text-[18px]">
        <svg-icon name="light" class="text-yellow-500" />
        <svg-icon name="dark" class="text-slate-700" />
    </div>
</template>

说明：

• 适合项目私有图标和设计稿导出的 SVG
• 项目中的真实示例可参考 src/views/tools/index.vue

3.9 页面缓存与滚动缓存 ​

3.9.1. 开启页面缓存 ​

需要缓存的页面，在页面文件里这样写：

<route lang="json5">
{
    meta: {
        title: '列表页',
        keepAlive: true,
    },
}
</route>

不需要缓存的页面，不写 keepAlive 就行。

3.9.2. 开启滚动恢复 ​

如果你希望从详情页返回后回到离开前的滚动位置，再加上这个 Hook：

<script setup lang="ts">
import { usePageScrollCache } from '@/hooks/usePageScrollCache'

usePageScrollCache({ key: 'order-list' })
</script>

使用建议 ​

• 列表页一般写 keepAlive: true
• 详情页一般不用缓存
• usePageScrollCache 的 key 要保证每个页面都不一样，避免互相覆盖滚动位置

示例 ​

• 列表页示例：src/views/(home)/scroll-cache/index.vue
• 详情页示例：src/views/(home)/scroll-cache/[id].vue
• Hook：src/hooks/usePageScrollCache.ts

一句话：

• 想保留页面状态，就写 keepAlive: true
• 想返回后回到原来的位置，就再接 usePageScrollCache
• 分页数量也要一起保留，否则滚动恢复会失真

3.10 图片压缩 (szhn-cli) ​

双引擎智能压缩：

默认使用智能模式：优先 TinyPNG，超出 API 限额自动切换 Sharp。也可在 .szhnrc.cjs 中指定 engine: 'sharp' 强制使用本地引擎。

配置示例（.szhnrc.cjs）：

module.exports = {
  compress: {
    // 不指定 engine: 智能模式（优先 TinyPNG，超限自动切换 Sharp）
    // engine: 'sharp': 仅使用 Sharp 引擎（无需 API Key）
    apiKey: 'your-tinypng-api-key',
    targetDirs: ['./src/assets'],
    sharp: {
      jpegQuality: 80,
      pngQuality: 80,
      pngCompression: 9,
      webpQuality: 80,
      generateWebp: false,
    },
    watch: false,
  },
};

使用命令：

# 初始化配置文件（生成 .szhnrc.cjs）
pnpm compress:init

# 执行图片压缩（压缩 targetDirs 中的图片）
pnpm compress

四、AI 辅助开发 ​

项目内已经集成 AI 辅助开发能力，通过多层 Markdown 配置文件约束和引导 AI 行为，尽量保证生成的代码符合当前仓库规范。

4.1 AI 架构图 ​

4.2 配置链路 ​

当前仓库的 AI 配置入口主要有 6 个：

推荐理解方式：

• AGENTS.md 管项目规范
• CONSTITUTION.md 管行为边界
• CLAUDE.md、Cursor、Copilot 入口文件负责把这两份规范接进各自工具

4.3 重要文件说明 ​

4.3.1 AGENTS.md — 项目规范总入口 ​

文件位置：项目根目录 AGENTS.md

这是整套 AI 配置的核心文件，也是项目规范的统一入口。AI 工具真正需要遵循的技术栈、目录结构、编码规范、开发约定，统一以这里为准。

可以把它理解成：项目规范的 Single Source of Truth。其他入口文件本质上都是先把 AI 引导到这里，再继续执行任务。

4.3.2 CONSTITUTION.md — 行为边界与安全规则 ​

文件位置：项目根目录 CONSTITUTION.md

如果说 AGENTS.md 管“应该怎么做”，那 CONSTITUTION.md 管的是“哪些事不能做、哪些事要先确认”。

执行优先级：安全规则 > 核心原则 > 交互规范 > 边界约束。

4.3.3 CLAUDE.md — Claude Code 入口说明 ​

文件位置：项目根目录 CLAUDE.md

这是 Claude Code 的入口文件，本身不重复维护整套项目规范，而是负责把 Claude 引导到正确的规范来源。

也就是说，CLAUDE.md 更像“入口说明书”，而不是项目规范本体。

4.3.4 其他工具入口文件 ​

这些文件和 CLAUDE.md 的定位类似，都是不同 AI 工具的入口层，负责把工具接入到统一规范链路中。

整体关系可以概括为：

• AGENTS.md 负责项目规范
• CONSTITUTION.md 负责行为边界
• CLAUDE.md、.github/copilot-instructions.md、.cursor/rules/project.mdc 负责不同工具的入口接入
• .agents/skills/ 负责按任务补充专项能力

4.4 项目使用的 Skills ​

项目内当前已安装的 Skills 位于 .agents/skills/：

这些 Skills 的来源记录在 skills-lock.json 中，当前主要来自 vuejs-ai/skills，后续抽离统一管理维护

五、统一认证 ​

本脚手架为海政通 / 海易办政务移动端场景预置了完整的集成方案，通过 src/settings.ts 中的开关统一控制。

// src/settings.ts

/**
 * 登录方式枚举
 * - UAA: 统一登录（UAA SDK），适用于海政通、钉钉等环境
 * - TICKET_SNO: 传统登录（ticketSNO/OnecodeJSBridge），适用于旧版海政通等环境
 * - AUTH_CODE: 使用AUTH_CODE方式登录
 */
export type LoginType = 'UAA' | 'TICKET_SNO' | 'AUTH_CODE' | '';

/**
 * 当前使用的登录方式
 */
export const LOGIN_TYPE: LoginType = '';

5.1 UAA登录 ​

// src/settings.ts
/**
 * 当前使用的登录方式
 */
export const LOGIN_TYPE: LoginType = 'UAA';

// config/uaa.ts
/**
* 配置apiKey
**/
export const UAA_APP_KEY = {
  development: '',
  test: '',
  preview: '',
  staging: '',
  production: ''
};

5.2 TICKET_SNO 登录 ​

LOGIN_TYPE = 'TICKET_SNO' 时，路由守卫会走传统登录流程：

1. 进入 authCodeHandle
2. 从路由参数读取 ticketSNO
3. 调用 getTokenByTicketSNO({ ticketSNO })
4. 成功后将 token 写入 Store 和本地存储

5.3 AUTH_CODE 登录 ​

LOGIN_TYPE = 'AUTH_CODE' 时，同样会先进入 authCodeHandle：

1. 从路由参数读取 accountType 和 authCode
2. 调用 getTokenByAuthCode({ accountType, authCode })
3. 成功后将返回的 accessToken / token / access_token 写入 Store 和本地存储

六、监控 SDK ​

6.1 功能开关 ​

// src/settings.ts

// 是否启用火熊监控
export const hasFireBearBrowser = false;

// 是否启用土熊监控
export const hasNativeBearMonitor = false;

6.2 火熊监控 (FireBear) ​

文件位置： src/utils/fire-bear-browser.ts

6.3 土熊监控 (Native Bear) ​

文件位置： src/utils/native-bear-monitor.ts

说明： 两个监控 SDK 均按 development / test / production 环境区分配置（appKey、DSN 等），CDN 地址通过环境变量注入。settings.ts 中设为 true 后，main.ts 会在应用启动时自动初始化。

七、目录结构 ​

├── .cursor/                 # Cursor IDE 配置（rules / skills / commands）
├── .husky/                  # Git Hooks（pre-commit / commit-msg）
├── .vscode/                 # VS Code 配置（settings / extensions / snippets）
├── docs/                    # 项目文档
├── mock/                    # Mock 数据文件（按需创建）
├── openspec/                # OpenSpec 变更管理
├── scripts/                 # 构建脚本
├── src/
│   ├── api/                 # API 接口定义
│   ├── assets/              # 静态资源（图片、字体等）
│   ├── components/          # 公共组件（自动注册）
│   ├── composables/         # Composable hooks（含 TanStack Query hooks）
│   ├── config/              # 业务配置（UAA 等）
│   ├── enums/               # 枚举类型定义
│   ├── hooks/               # 自定义 Composition API hooks
│   ├── layout/              # 布局组件
│   ├── plugins/             # 插件配置（TanStack Query 等）
│   ├── router/              # 路由配置 + 守卫
│   ├── store/               # Pinia 状态管理
│   │   └── modules/
│   │       ├── auth.ts      # 认证：Token、用户信息、登录/登出
│   │       ├── dark-mode.ts # 深色模式状态
│   │       └── cached-view.ts # Keep-alive 缓存列表
│   ├── styles/              # 全局样式
│   ├── typings/             # TypeScript 类型定义
│   ├── utils/               # 工具函数
│   │   ├── http/            # Axios 封装（拦截器、错误处理）
│   │   ├── uaa-sdk.ts       # 海政通 UAA SDK
│   │   ├── firebear-manager.ts # 火熊监控
│   │   ├── native-bear-monitor.ts # 土熊监控
│   │   ├── dd-tools.ts      # 环境检测（钉钉/微信/移动端）
│   │   ├── storage.ts       # Token / 用户数据本地存储
│   │   ├── dark-mode.ts     # 深色模式工具
│   │   ├── class-names.ts   # clsx + tailwind-merge
│   │   ├── progress.ts      # NProgress 进度条
│   │   ├── set-page-title.ts # 页面标题设置
│   │   └── validate.ts      # 校验工具
│   ├── views/               # 页面组件（文件路由）
│   ├── App.vue              # 根组件
│   ├── main.ts              # 应用入口
│   └── settings.ts          # 功能开关配置
├── CLAUDE.md                # AI 开发指南
├── CONSTITUTION.md          # AI 行为准则
├── AGENTS.md                # AI 智能体配置
├── commitlint.config.js     # CommitLint + czg 配置
├── eslint.config.ts         # ESLint 配置
├── postcss.config.js        # PostCSS 配置
├── vite.config.ts           # Vite 配置（含 Tailwind CSS v4 插件）
└── tsconfig.json            # TypeScript 配置

八、常用命令 ​

常用命令 ​

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 构建测试环境
pnpm build:test

# 预览生产构建
pnpm preview

# 类型检查
pnpm type-check

# ESLint 检查 + 格式化
pnpm lint

# 初始化压缩资源配置
pnpm compress:init

# 执行压缩脚本
pnpm compress

# Git 交互式提交
pnpm commit

# 版本发布
pnpm release

后续规划 ​

1. 根据UI稿搭建数海UI组件库
2. 等UI规范确定后加入Design.md，规范AI生成UI
3. 创建数海Skills Hub，统一维护前后端Skills