cl-uniapp/README.md

# msmg-uni

基于 UniApp 框架构建的微信小程序移动应用，采用 Vue 3 + TypeScript + Vite + UnoCSS + uview-plus 现代化技术栈。

## 🚀 快速开始

### 环境要求

- Node.js >= 16.0.0
- pnpm (推荐) 或 npm
- 微信开发者工具

### 安装依赖

```bash
# 使用 pnpm (推荐)
pnpm install

# 或使用 npm
npm install
```

### 开发环境

```bash
# 启动微信小程序开发
npm run dev:mp-weixin
```

### 生产构建

```bash
# 构建微信小程序
npm run build:mp-weixin
```

### 类型检查

```bash
# 运行 TypeScript 类型检查
npm run type-check
```

## 📁 项目结构

```
src/
├── @api/           # API 层和服务定义
├── @layout/        # 布局组件 (PageTitle, RootView)
├── components/     # 可复用的 Vue 组件
├── common/         # 全局工具函数和常量
├── hooks/          # Vue 3 组合式函数
├── pages/          # 应用页面
├── stores/         # Pinia 状态管理
├── static/         # 静态资源
├── utils/          # 工具函数
├── App.vue         # 根应用组件
├── main.ts         # 应用入口文件
├── pages.json      # UniApp 页面配置
└── manifest.json   # 平台特定应用配置
```

## 🛠️ 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| **UniApp** | 3.x | 跨平台开发框架 |
| **Vue 3** | ^3.4.21 | 渐进式 JavaScript 框架 |
| **TypeScript** | ^4.9.4 | JavaScript 超集，提供类型安全 |
| **Vite** | 5.2.8 | 现代化前端构建工具 |
| **Pinia** | 2.0.36 | Vue 3 状态管理库 |
| **uview-plus** | ^3.6.17 | UniApp 生态 UI 组件库 |
| **UnoCSS** | - | 原子化 CSS 引擎 |
| **vue-i18n** | ^9.1.9 | 国际化解决方案 |

## 📋 开发规范

### 编码风格

1. **条件语句** - 尽可能使用 `if return` 代替 `if else`
2. **注释** - 代码结构清晰，关键地方需要中文注释
3. **引号** - 使用单引号替代双引号
4. **参数传递** - 函数参数尽量使用解构赋值
5. **分号** - 行结尾禁止添加分号

### 文件命名规范

| 文件类型 | 命名规范 | 示例 |
|----------|----------|------|
| API 文件 | `*.api.ts` | `user.api.ts` |
| Vue 组件 | PascalCase | `PageBack.vue` |
| 组合函数 | `*.use.ts` | `useAuth.use.ts` |
| 状态管理 | `*.store.ts` | `user.store.ts` |
| 类型定义 | 按类别组织 | `/types/dto/`, `/types/vo/` |
| 其他文件 | `xxx-xxx.xxx` | `user-info.ts` |

### 导入规范

- 使用绝对导入：`import { http } from '@/utils/http'`
- `@/` 指向 `./src/` (在 vite.config.ts 中配置)

### Vue 组件结构

```vue
<template>
  <!-- 使用 uview-plus 组件的模板 -->
  <RootView>
    <PageTitle title="页面标题" />
    <view class="container">
      <!-- 页面内容 -->
    </view>
  </RootView>
</template>

<script setup lang="ts">
// TypeScript 组合式 API
import { ref, onMounted } from 'vue'
</script>

<style lang="scss" scoped>
// UnoCSS 工具类的作用域样式
.container {
  @apply flex flex-col p-4;
}
</style>
```

### 页面结构

- 根组件统一使用 `<RootView />` 包装
- 页面标题使用 `<PageTitle />` 组件
- 布局组件位于 `/src/@layout/` 目录

### HTTP 请求

使用统一的 HTTP 工具：

```typescript
import { http } from '@/utils/http'

// GET 请求示例
const getUserInfo = async (userId: string) => {
  return http.get(`/api/users/${userId}`)
}

// POST 请求示例
const createUser = async (userData: CreateUserDto) => {
  return http.post('/api/users', userData)
}
```

### 状态管理

使用 Pinia 进行状态管理：

```typescript
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => ({
    userInfo: null as UserInfo | null,
    token: ''
  }),
  actions: {
    async login(credentials: LoginDto) {
      // 登录逻辑
    },
    logout() {
      this.userInfo = null
      this.token = ''
    }
  }
})
```

## 🎨 样式规范

### UnoCSS 使用

- 使用原子化 CSS 类进行样式开发
- 集成 Tabler 图标：`i-tabler-*`
- 支持自定义主题色彩变量

### 主题色彩

```scss
// 使用 CSS 变量
color: var(--primary-color);
background: var(--bg-color);
```

## 🔧 构建配置

### Vite 配置特性

- UnoCSS 集成与微信小程序预设
- SCSS 预处理支持
- Vue JSX 支持
- 路径别名配置

### TypeScript 配置

- Vue 3 TypeScript 支持
- UniApp 类型定义
- 清理导入的路径映射
- 启用严格模式

### 查询建议

- 遇到 API 使用问题时，优先使用 Context7 查询最新文档
- 可以指定 `topic` 参数查询特定主题，如：`topic="composition-api"`
- 对于具体组件，可以直接查询相关主题：`topic="u-button"`

### Git 提交规范

- `feat:` 新功能
- `fix:` 修复 bug
- `docs:` 文档更新
- `style:` 代码格式调整
- `refactor:` 代码重构
- `test:` 测试相关
- `chore:` 构建过程或辅助工具的变动