npm package: @mico_fe/mobile-templates
Description: H5 页面模板集合 - 支持 soulstar、hiyoo、yoho、dramabite 等业务
Author: zackshi@micous.com
Latest version: 1.0.4

# @mico_fe/mobile-templates

H5 页面模板集合，为多业务项目提供标准化的页面脚手架和完整项目脚手架。

## 📦 模板分类

### 🎯 Project 级别模板（完整项目脚手架）

| 项目类型      | 框架                 | 状态      | 说明                                   |
| ------------- | -------------------- | --------- | -------------------------------------- |
| **dashboard** | Vue 3 + Element Plus | ✅ 已发布 | PC 管理后台完整项目模板                |
| **mobile**    | Vue 3 + Vant         | ✅ 已发布 | H5 移动端多页面应用完整项目模板（MPA） |

### 📄 Page 级别模板（单页面脚手架）

| 业务          | 模板数量 | 状态      | 说明                |
| ------------- | -------- | --------- | ------------------- |
| **soulstar**  | 1        | ✅ 已发布 | 基础页面模板 (base) |
| **dramabite** | 1        | ✅ 已发布 | 基础页面模板 (base) |
| **hiyoo**     | 1        | ✅ 已发布 | 基础页面模板 (base) |
| **yoho**      | 1        | ✅ 已发布 | 基础页面模板 (base) |

## 🚀 安装

```bash
npm install @mico_fe/mobile-templates
# 或
pnpm add @mico_fe/mobile-templates
```

## 📖 使用方式

### 配合 @mico_fe/mcp 使用（推荐）

本模板包主要配合 `@mico_fe/mcp` MCP 服务使用：

1. 在 Cursor 中配置 MCP：

```json
{
  "mcpServers": {
    "h5-page": {
      "command": "npx",
      "args": ["@mico_fe/mcp", "h5-page"]
    }
  }
}
```

2. 在对话中使用：

**创建 Page（单页面）**：

```
创建一个新页面，使用 soulstar 的 base 模板，路径为 2025/activity
```

**创建 Project（完整项目）**：

```
创建一个新项目，使用 dashboard 模板，项目名为 my-admin
```

### 直接使用模板文件

如果需要直接访问模板文件：

```javascript
import { fileURLToPath } from "url";
import path from "path";

// 获取模板目录路径
const templatesDir = path.join(
  path.dirname(fileURLToPath(import.meta.url)),
  "node_modules/@mico_fe/mobile-templates/templates"
);

// 读取 soulstar/base 模板
const baseTemplatePath = path.join(templatesDir, "soulstar/base");
```

## 📁 目录结构

```
@mico_fe/mobile-templates/
├── templates/
│   ├── dashboard/              # Project: PC 管理后台
│   │   ├── project.json        # 项目配置
│   │   ├── package.json        # 依赖配置
│   │   ├── vite.config.ts      # Vite 配置
│   │   └── src/                # 源码目录
│   │       ├── views/          # 页面视图
│   │       ├── components/     # 公共组件
│   │       ├── router/         # 路由配置
│   │       └── stores/         # 状态管理
│   ├── mobile/                 # Project: H5 多页面应用
│   │   ├── project.json        # 项目配置
│   │   ├── package.json        # 依赖配置
│   │   ├── config/             # 配置文件
│   │   └── src/                # 源码目录
│   │       ├── page/           # 多页面目录
│   │       ├── components/     # 公共组件
│   │       └── utils/          # 工具函数
│   ├── soulstar/               # Page: SoulStar 业务
│   │   ├── business.json       # 业务配置
│   │   └── base/
│   │       ├── template.json   # 模板配置
│   │       ├── index.html      # 页面入口
│   │       ├── main.ts         # 应用初始化
│   │       ├── lang.ts         # 多语言配置
│   │       ├── router/         # 路由配置
│   │       ├── pages/          # 页面组件
│   │       ├── api/            # API 接口
│   │       └── assets/         # 静态资源
│   ├── dramabite/              # Page: Dramabite 业务
│   │   └── base/
│   ├── hiyoo/                  # Page: Hiyoo 业务
│   │   └── base/
│   └── yoho/                   # Page: Yoho 业务
│       └── base/
├── README.md
├── MIGRATION_GUIDE.md          # 迁移指南
└── TEMPLATE_SPEC.md            # 模板规范
```

## 🎨 模板特性

### Project 模板特性

#### dashboard（PC 管理后台）

- ✅ **Vue 3 Composition API** - 现代化的组件开发
- ✅ **Element Plus** - 企业级 UI 组件库
- ✅ **TypeScript** - 完整的类型支持
- ✅ **Pinia 状态管理** - 轻量级状态管理方案
- ✅ **Vue Router** - 完整的路由配置
- ✅ **国际化支持** - 多语言切换
- ✅ **权限系统** - 基于角色的权限控制
- ✅ **自动导入** - 组件和 API 自动导入

#### mobile（H5 多页面应用）

- ✅ **MPA 架构** - 多页面应用架构
- ✅ **Vant UI** - 移动端组件库
- ✅ **共享依赖优化** - 减少重复打包
- ✅ **REM 适配** - 移动端响应式方案
- ✅ **Sentry 监控** - 错误监控集成
- ✅ **TypeScript** - 完整的类型支持
- ✅ **PostCSS Mobile Forever** - 移动端适配插件

### Page 模板特性

#### soulstar/base

- ✅ **HeaderV2 组件集成** - 统一的页面标题组件
- ✅ **多语言支持** - 支持 en、ar、tr 三种语言
- ✅ **嵌套路由** - Vue Router 嵌套路由配置
- ✅ **API 占位符** - 预设的 API 请求结构
- ✅ **完整样式系统** - CSS 变量 + 全局样式
- ✅ **移动端适配** - 基于 750px 设计稿的响应式布局

#### dramabite/base

- ✅ **CustomHeader 组件** - 自定义标题栏
- ✅ **多语言支持** - 支持 en、ar、tr 三种语言
- ✅ **嵌套路由** - Vue Router 嵌套路由配置
- ✅ **移动端适配** - 基于 750px 设计稿
- ✅ **WebView 全屏支持** - H5 全屏自定义标题栏

#### hiyoo/base

- ✅ **useLangChill hook** - 基于 chatchill-mobile-vite 架构
- ✅ **h5Tracker 埋点** - 数据埋点支持
- ✅ **嵌套路由** - Vue Router 嵌套路由配置
- ✅ **API 封装** - 基于项目的请求封装
- ✅ **移动端适配** - 基于 750px 设计稿

#### yoho/base

- ✅ **useLang hook** - 多语言管理 (V4.34_guardianship)
- ✅ **嵌套子路由** - Home 父路由 + User/Rule 子路由示例
- ✅ **yoho-header 请求封装** - Yoho 项目专用请求封装
- ✅ **Flex 布局工具类** - common.scss 提供常用布局样式
- ✅ **移动端适配** - 基于 750px 设计稿
- ✅ **依赖项目基础设施** - 使用项目提供的工具函数和 hooks

## 🤝 贡献模板

如果您需要为自己的业务添加模板，请参考：

- [**MIGRATION_GUIDE.md**](./MIGRATION_GUIDE.md) - 详细的迁移步骤
- [**TEMPLATE_SPEC.md**](./TEMPLATE_SPEC.md) - 模板规范和要求

## 📝 版本历史

查看 [CHANGELOG.md](./CHANGELOG.md) 了解详细的版本变更记录。

## 🔗 相关项目

- [@mico_fe/mcp](https://www.npmjs.com/package/@mico_fe/mcp) - MCP 服务器集合