7b1c087c00
架构与目录： - 引入分层 API：transport/interceptors 收敛到 src/api/client.ts， 域名端点拆到 src/api/modules，页面不再直接依赖 Axios - 服务层（src/services）承载 AI 流式解析与框架无关的 provider - TanStack Query 接管服务端状态，Pinia 仅保留会话/主题等客户端状态 - 路由表显式懒加载，组件/组合式函数按职责拆分 功能： - AI 流式对话：fetchStreamProvider + useStreamingChat + 安全 Markdown 渲染 - 商店模块：商品列表/详情/购物车/后台管理，多语言（中/英/日） - 示例页：请求错误矩阵、query 缓存、移动端适配、图标演示 - 离线页、PWA、图片优化、eruda 调试等能力 工程化： - ESLint/Prettier 迁移到 oxlint/oxfmt，stylelint 保留 - 新增 oxlint.config.ts（移植自 monorepo 的 @vh5/oxlint-config 全套规则） - 新增 oxfmt.config.ts（移植自 @vh5/oxfmt-config，printWidth 80） - lint-staged、format、lint 脚本同步切换 - pnpm 作为唯一包管理器，删除 package-lock.json 与 yarn.lock - 引入 Vitest/Playwright/release-please，补充单元与组件测试 - OpenAPI schema 与生成类型入库 - 环境变量按 mode 拆分，重构 wrapperEnv 解析 清理： - 删除 .commitlintrc.js（CJS 配置在 type:module 下会崩溃），改用 commitlint.config.mjs - 删除 eslint.config.mjs、prettier.config.js、.prettierignore - 停止跟踪 .eslintrc-auto-import.json（已切 oxlint，无人引用） - 移除 iconfont、旧 demo/list 页与 useAxiosApi/useFetchApi 等遗留实现 - husky 钩子移除 DEPRECATED 的 shebang 写法 - .workbuddy/ 加入 .gitignore
Vue H5 Template v2
面向真实移动 H5 业务的 Vue 3 工程模板。v2 不是组件库 Playground：它提供类型安全请求、OpenAPI 类型生成、TanStack Query、可中止的 Streaming AI Chat、PWA、SVG Sprite、production 图片优化、单选 UI 框架以及有意义的测试基线。
在线文档（简体中文） · English docs · 日本語ドキュメント · 迁移到 v2
核心能力
- Vue 3.5、Vite 8 / Rolldown、TypeScript 5.9、Vue Router 4、Pinia 3
@tanstack/vue-query管理 Server State，Pinia 只管理 Client State- Axios Type-safe Client：
ApiResponse<T>、ApiError、Request ID、Token、401、Timeout 与 Network Error pnpm api:generate从本地 OpenAPI Schema 生成后端契约类型- AI Chat：POST SSE、
ReadableStream、AbortController、Regenerate、Retry、Markdown、代码块与 DOMPurify - 真实商城：12+ 三语商品、搜索分类、下拉刷新、分页加载、详情、购物车与商品管理
- 交付项目管理：查看、新建、编辑、删除和状态筛选，Vite Mock / Gin + PostgreSQL 共用契约
- SVG Sprite：
src/assets/icons自动加载及类型化<SvgIcon /> - Vant / NutUI / Varlet 构建期单选，不把三套 UI 同时放入 production graph
- 可选 PWA；Service Worker 只缓存 App Shell 和静态图片，不默认缓存 API
- Sharp + SVGO 仅在 production build 按开关优化 png/jpeg/webp/svg
- Vitest + Vue Test Utils + Playwright；当前核心逻辑 line coverage 81.31%
- 克制的响应式 Design System：统一 typography、spacing、radius、color、control 和 motion tokens，移动端底栏在桌面自动切换为紧凑顶栏
- 中文、English、日本語三语懒加载，正文、导航和页面标题响应式同步
- ESLint、Prettier、Stylelint、Husky、lint-staged、Commitlint、GitHub Actions 与 Release Please
快速开始
要求 Node.js >=22.12.0、pnpm >=9.12.0。
pnpm install
cp .env.example .env.local
pnpm dev
开发环境默认启用 Mock，登录可以输入任意非空用户名和密码。底部第三个标签是工程示例；右下角 AI 悬浮入口打开 /ai/chat，Mock Server 会从 POST /api/ai/chat 逐 chunk 返回 SSE。
可直接访问 /shop、/shop/cart、/examples/request 和 /examples/workspace。请求示例包含 400/401/403/404/409、业务 422、500 和 timeout；交付项目页在 Mock 与真实后端两种模式下都支持完整增删改查。
常用命令
pnpm lint # ESLint + Stylelint
pnpm typecheck # vue-tsc project references
pnpm test # Vitest unit/component tests
pnpm test:coverage # 60%+ core coverage gate
pnpm test:e2e # Playwright 核心流程、响应式和 dark mode
pnpm build # production build
pnpm check # lint + typecheck + test + build
pnpm api:generate # OpenAPI -> TypeScript
pnpm check 默认不含 E2E，避免每次本地提交都启动浏览器；CI 在 check 之后单独运行 Playwright。
目录边界
src/
├── api/ # Axios client 与按业务域拆分的 API modules
├── components/ # 可复用、无页面路由职责的 UI
├── composables/ # Vue 生命周期/响应式编排
├── layout/ # App Shell、导航、safe-area
├── plugins/ # Vue Query 等 App 插件
├── router/ # 显式路由表、meta 类型与守卫
├── services/ # Provider/transport 等框架无关业务服务
├── store/ # Pinia client state
├── types/ # API、AI、Icon 领域类型
├── utils/ # 无 Vue 生命周期的纯函数
└── views/ # 懒加载页面
完整规则见 AGENTS.md。该文件也是 Codex、Claude Code、Cursor 和 Copilot 的首要工程上下文。
状态管理
- Pinia：登录会话、购物车、主题、Feature Flags 等客户端状态。
- TanStack Query：远程数据、缓存、重试、取消、Mutation、Pagination 与 Infinite Query。
- AI 对话：由
useStreamingChat编排会话生命周期；Provider 传输协议位于services/ai，不放进 Pinia 或 Query Cache。
API 与 OpenAPI
页面不直接调用 Axios，也不写 catch (error: any)。在 src/api/modules 增加函数，在页面/Query composable 中消费，并用 isApiError 收窄错误。
替换后端 Schema：
- 用真实
openapi.yaml替换openapi/schema.yaml，或修改api:generate的输入 URL； - 运行
pnpm api:generate； - API module 从
src/types/api/generated.d.ts引用 schema； - 提交 Schema 与生成文件，让 CI 的 typecheck 检查契约漂移。
AI Provider
模板采用轻量、供应商无关的接口：
interface ChatProvider {
chat(
messages: readonly ChatMessage[],
options?: ChatOptions,
): AsyncIterable<ChatChunk>;
}
默认 FetchStreamChatProvider 解析标准 SSE。真实项目应让服务端代理 OpenAI、Claude、Gemini 或 DeepSeek，不要把供应商密钥放在 VITE_* 环境变量或浏览器请求中。若后端使用 Vercel AI SDK data stream protocol，可新增 Provider adapter，无需重写页面状态机。
UI 框架单选
VITE_UI_FRAMEWORK=vant # vant | nutui | varlet
Vite 会同时选择对应 resolver 和 #ui-demo 别名。三套依赖留在模板中供创建项目时选择，但 production bundle 只包含当前值对应的框架。未来 create-vue-h5-template CLI 可以在生成阶段删除另外两套依赖。
每套框架示例都包含 Button、Cell/List、Switch、Tag/Chip 与 Progress，不再只是单按钮占位。
国际化
src/locales/langs 内置 zh-CN、en-US、ja-JP。首页语言选择器会懒加载语言包，并同步更新页面正文、底部导航、Router title、document.title 和 <html lang>。新增语言时还需要加入 SUPPORTED_LOCALES，并保持 common.json 键结构一致。
配套后端
后端已从前端仓库拆分，并整理为两个独立 Git 仓库：gin-service-template（建议 GitHub 仓库名 vue-h5-template-business-service）负责认证、用户、交付项目、商品业务和 PostgreSQL；fastapi-service-template（建议仓库名 vue-h5-template-ai-service）负责 AI Provider、POST SSE 和 Redis 限流。上层目录只负责本地 Compose 联调。
# 终端 1：启动 PostgreSQL + Gin + FastAPI + Redis
cd <workspace>/backend/vue-h5-template
docker compose up --build
# 终端 2：使用已提交的 .env.integration 启动真实联调模式
cd <workspace>/frontend/vue-h5-template
pnpm dev:integration
访问 Vite 输出的地址，使用 demo / demo1234 登录。/shop 读取公开商品，/shop/admin/products 提供三语商品管理，/examples/workspace 提供交付项目的完整增删改查，/ai/chat 把同一个 JWT 随 SSE 请求发送给 FastAPI。也可在后端目录运行 python3 scripts/smoke.py 自动验证 Vue 代理 → Gin 业务接口 → PostgreSQL → FastAPI SSE。
默认 pnpm dev 仍使用前端 Mock，不要求安装后端。Compose 默认数据库连接是 localhost:5432 / vue_h5_business / vue_h5 / vue_h5_local，可直接加入 DataGrip；这些凭证仅供本地使用。两个后端仓库的 docs 分支和前端 docs 分支都提供中、英、日开发文档。AI 密钥只放 FastAPI 服务，不进入任何 VITE_* 变量。
PWA 与图片优化
VITE_PWA_ENABLED=false
VITE_IMAGE_OPTIMIZE=true
PWA 默认关闭。开启后会缓存构建 App Shell 与静态图片，/api 被明确排除。图片优化仅在 production build 运行；若图片已经由 CDN image pipeline 处理，可关闭以缩短 CI。
浏览器与安全基线
目标为 iOS Safari 15+、Android Chrome 80+、微信与企业微信的现代 WebView，不为 IE 或极老 Android 注入整包 polyfill。Markdown 禁止原始 HTML并经过 DOMPurify；Redirect 仅接受站内绝对路径；Mock 生产默认关闭；鉴权 Token 示例使用 sessionStorage。生产项目优先采用 SameSite + Secure + HttpOnly Cookie/BFF，并在网关配置 CSP、CSRF 和速率限制。
文档与发布
架构、后端联调、商城、请求、状态、AI Chat、UI、测试、部署和 v2 迁移文档维护在仓库 docs 分支，并提供中文、英文和日文同步内容。合并 Conventional Commits 后，Release Please 自动维护版本、CHANGELOG 与 GitHub Release。
本轮完整决策、性能数据、Breaking Changes 和后续路线见 V2_UPGRADE_REPORT.md。
Roadmap
- P0 已实现：Auth 基线、路由权限、错误边界、网络状态、深色系统主题、懒路由、安全 Markdown、PWA/API 缓存隔离、依赖/提交/测试基线。
- P1 推荐按业务引入：Gateway/JWKS 身份、自动导出 Gin OpenAPI、数据库备份/回滚、Feature Flags、Analytics/Error Reporting adapter、Upload、Virtual List、WebView Bridge、Performance Monitoring、显式主题切换。
- P2 可选：QR/Camera/Web Share、Deep Link、SSR/SSG、CDN external、原生 App Bridge。它们依赖产品与部署环境，不应成为模板默认负担。