cl-uniapp/.claude/CLAUDE.md

# CLAUDE.md

此文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

## 项目概述

**msmg-uni** 是一个基于 UniApp 框架构建的微信小程序移动应用，使用 Vue 3 + TypeScript + Vite + Unocss + uview-plus 技术栈。

## 编码风格

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

## 开发命令

### 开发环境
- `npm run dev:mp-weixin` - 微信小程序开发

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

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

## 架构设计

### 核心目录结构
```
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 组合式 API
- **语言**: TypeScript 4.9+
- **构建工具**: Vite 5.2.8
- **状态管理**: Pinia 2.0.36
- **UI 库**: uview-plus 3.6.17
- **样式**: UnoCSS + SCSS
- **HTTP**: 自定义工具 + 拦截器
- **国际化**: vue-i18n
- **图标**: unocss icons tabler图标，使用i-tabler-* 引入图标

### 核心模式

**状态管理**
- 使用 `/src/stores/` 中的 Pinia stores
- 主题 store 支持明暗模式切换
- 响应式状态的组合模式

**API 层**
- API 定义在 `/src/@api/` 中，使用 `.api.ts` 后缀
- `/src/utils/http.ts` 中的 HTTP 工具处理：
  - 请求/响应日志
- `/types/` 中的 TypeScript DTO/VO 模式

**组件开发**
- 使用 Vue 3 组合式 API 和 `<script setup>`
- `/src/@layout/` 中的可复用布局组件
- `/src/hooks/` 中的自定义组合函数
- uview-plus 组件保证 UI 一致性

**样式**
- UnoCSS 用于原子化样式
- 基于 CSS 变量的自定义主题系统
- `/src/static/styles/theme.css` 中的全局样式
- SCSS 支持，已屏蔽弃用警告

**类型安全**
- `/types/` 中的全面 TypeScript 定义
- 分离的 DTO (数据传输对象) 和 VO (值对象)
- API 集成的 HTTP 响应类型
- Vue 3 原生类型支持

## 跨平台开发

### 平台特定配置
- `manifest.json` 包含平台特定应用配置
- `pages.json` 定义页面路由和导航
- 使用 `#ifdef` 和 `#ifndef` 条件编译

### 支持平台
此应用支持部署到：
- 微信小程序

## 开发规范


### Git 提交规范
- 使用简洁明了的 commit 信息
- 不要包含额外的开发者信息标注（如：🤖 Generated with [Claude Code]、Co-Authored-By 等）
- 保持纯粹的提交信息

### 文件命名
- API 文件：`*.api.ts` 在 `/src/@api/`
- 组件：PascalCase (如 `PageBack.vue`)
- 组合函数：`*.use.ts` 在 `/src/hooks/`
- 状态管理：`*.store.ts` 在 `/src/stores/`
- 类型：按类别组织在 `/types/dto/` 和 `/types/vo/`
- 其他文件: 遵循`xxx-xxx.xxx`命名

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

### 组件结构
```vue
<template>
  <!-- 使用 uview-plus 组件的模板 -->
</template>

<script setup lang="ts">
// TypeScript 组合式 API
</script>

<style lang="scss" scoped>
// UnoCSS 工具类的作用域样式
</style>
```

### 页面结构

根组件为<RootView />

### HTTP 请求
使用配置的 HTTP 工具：
```typescript
import { http } from '@/utils/http'
```

### 状态管理
创建带 TypeScript 的 Pinia stores：
```typescript
import { defineStore } from 'pinia'

export const useExampleStore = defineStore('example', {
  state: () => ({
    // 响应式状态
  }),
  actions: {
    // 操作方法
  }
})
```

## 构建配置

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

### UnoCSS 配置
- 配置自定义主题颜色
- Tabler 图标集成
- 微信小程序兼容性
- 定义的实用快捷方式

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

## API 文档查询

### Context7 集成
可以使用 Context7 查询相关技术栈的最新 API 文档：


### 查询建议
- 在开发过程中遇到 API 使用问题时，优先使用 Context7 查询最新文档
- 可以指定 topic 参数来查询特定主题，例如：`topic="composition-api"`
- 对于具体的组件或功能，可以直接查询相关主题：`topic="u-button"`、`topic="router"`