aiot-uniapp/CLAUDE.md

# aiot-uniapp - AIoT 移动端管理系统

## 项目愿景

基于 UniApp + Vue 3 + TypeScript 的 AIoT（人工智能物联网）移动端管理应用。项目源自 [unibest](https://unibest.tech) 模板（v4.1.0），二次开发适配 [芋道管理系统](https://www.iocoder.cn/)（yudao-version: 2026.01.0-snapshot）后端。支持 H5、微信/支付宝小程序、Android/iOS APP 多端运行。

## 架构总览

- **前端框架**: Vue 3.4 + TypeScript 5.8
- **跨端框架**: UniApp (DCloudio 3.0)
- **构建工具**: Vite 5.2
- **状态管理**: Pinia 2.0 + pinia-plugin-persistedstate（uni.storage 持久化）
- **UI 组件库**: wot-design-uni（Wot Design）
- **CSS 方案**: UnoCSS（@uni-helper/unocss-preset-uni）+ SCSS
- **路由**: @uni-helper/vite-plugin-uni-pages（约定式路由，基于文件系统）
- **HTTP**: 自封装 uni.request，支持双 Token 无感刷新、API 加解密（AES/RSA）
- **国际化**: vue-i18n 9
- **分包**: @uni-ku/bundle-optimizer（分包优化 + 异步跨包调用）
- **代码规范**: ESLint（@uni-helper/eslint-config）+ Husky + lint-staged + commitlint
- **包管理器**: pnpm 10+

## 模块结构图

```mermaid
graph TD
    A["aiot-uniapp (Root)"] --> B["src/pages - 主包页面"]
    A --> C["src/pages-core - 核心分包"]
    A --> D["src/pages-system - 系统管理分包"]
    A --> E["src/pages-infra - 基础设施分包"]
    A --> F["src/pages-bpm - 工作流程分包"]
    A --> G["src/api - API 接口层"]
    A --> H["src/store - 状态管理"]
    A --> I["src/http - HTTP 请求封装"]
    A --> J["src/hooks - 组合式函数"]
    A --> K["src/utils - 工具函数"]
    A --> L["src/tabbar - 底部导航配置"]
    A --> M["docs - VitePress 文档站"]

    click C "./src/pages-core/CLAUDE.md" "查看 pages-core 模块文档"
    click D "./src/pages-system/CLAUDE.md" "查看 pages-system 模块文档"
    click E "./src/pages-infra/CLAUDE.md" "查看 pages-infra 模块文档"
    click F "./src/pages-bpm/CLAUDE.md" "查看 pages-bpm 模块文档"
```

## 模块索引

| 模块路径 | 职责 | 语言 | 页面/文件数 |
|---------|------|------|-----------|
| `src/pages/` | 主包：工作台、审批、通讯录、消息、个人中心（5 个 Tab 页） | Vue/TS | ~21 vue |
| `src/pages-core/` | 核心分包：登录/注册/忘记密码、用户资料/安全/设置、404 | Vue/TS | ~17 vue |
| `src/pages-system/` | 系统管理分包：用户、角色、菜单、部门、岗位、字典、租户、通知、日志、邮件、短信、OAuth2、社交 | Vue/TS | ~90+ vue |
| `src/pages-infra/` | 基础设施分包：API 日志、配置管理、数据源、文件管理、定时任务、WebSocket | Vue/TS | ~20 vue |
| `src/pages-bpm/` | 工作流程分包：流程分类、流程实例、任务审批、用户组、OA 请假、流程表达式/监听器 | Vue/TS | ~40 vue |
| `src/api/` | API 接口层：按后端模块组织，封装所有 HTTP 请求 | TS | ~45 ts |
| `src/store/` | Pinia 状态管理：token、user、dict、theme | TS | 5 ts |
| `src/http/` | HTTP 封装：请求/响应拦截、双 Token 刷新、类型定义 | TS | 5 ts |
| `src/hooks/` | 组合式函数：useAccess、useDict、useRequest、useScroll、useUpload | TS | 5 ts |
| `src/utils/` | 工具函数：加解密、日期、防抖、下载、校验、树操作、常量/枚举 | TS | ~15 ts |
| `src/components/` | 全局业务组件：DictTag（字典标签）、UserPicker（用户选择器） | Vue/TS | 4 files |
| `src/tabbar/` | 底部导航栏配置与状态管理 | TS | 3 ts |
| `docs/` | VitePress 文档站 | MD/Vue/TS | ~20 files |

## 运行与开发

### 环境要求

- Node.js >= 20
- pnpm >= 9（项目强制使用 pnpm，`preinstall` 脚本会检查）

### 安装依赖

```bash
pnpm install
```

### 开发命令

| 命令 | 说明 |
|------|------|
| `pnpm dev` / `pnpm dev:h5` | 开发 H5 版本（默认端口 9000） |
| `pnpm dev:mp` / `pnpm dev:mp-weixin` | 开发微信小程序 |
| `pnpm dev:mp-alipay` | 开发支付宝小程序 |
| `pnpm dev:app` | 开发 APP 版本 |
| `pnpm dev:h5:test` | 开发 H5（test 环境） |
| `pnpm dev:h5:prod` | 开发 H5（production 环境） |
| `pnpm build` / `pnpm build:h5` | 构建 H5 生产版本 |
| `pnpm build:mp` | 构建微信小程序 |
| `pnpm build:app` | 构建 APP |
| `pnpm lint` | ESLint 检查 |
| `pnpm lint:fix` | ESLint 自动修复 |
| `pnpm type-check` | TypeScript 类型检查 |

### 环境变量

环境变量文件位于 `env/` 目录：

| 文件 | 用途 |
|------|------|
| `env/.env` | 通用配置（后端地址、AppID、认证模式等） |
| `env/.env.development` | 开发环境覆盖 |
| `env/.env.test` | 测试环境覆盖 |
| `env/.env.production` | 生产环境覆盖 |

关键变量：
- `VITE_SERVER_BASEURL` - 后端 API 基地址（默认 `http://localhost:48080/admin-api`）
- `VITE_AUTH_MODE` - 认证模式：`single`（单 Token）/ `double`（双 Token，默认）
- `VITE_APP_TENANT_ENABLE` - 多租户开关（默认 `true`）
- `VITE_APP_CAPTCHA_ENABLE` - 验证码开关（默认 `false`）
- `VITE_APP_API_ENCRYPT_ENABLE` - API 加解密开关
- `VITE_WX_APPID` - 微信小程序 AppID

### 后端对接

后端为芋道（yudao）管理系统，API 前缀为 `/admin-api`。登录接口 `/system/auth/login`，支持账号密码、短信验证码、微信三方登录。

## 测试策略

- 当前项目**未配置单元测试**和端到端测试框架。
- 依赖 `@dcloudio/uni-automator` 已安装（devDependencies），但未发现测试用例文件。
- 代码质量依赖 ESLint + TypeScript 类型检查 + lint-staged。

## 编码规范

### 文件组织

- 页面文件使用约定式路由，`src/pages/` 为主包，`src/pages-*` 为分包
- 每个页面通过 `definePage({...})` 宏声明路由元信息（标题、样式等）
- 分包页面必须放在 `src/pages-*` 目录（不能放在 `src/pages` 下）
- API 按后端模块分目录组织（如 `src/api/system/user/index.ts`）

### 代码风格

- Vue SFC 使用 `<script lang="ts" setup>` + Composition API
- 样式使用 UnoCSS 原子类为主，SCSS 为辅（scoped）
- UI 组件使用 wot-design-uni（`wd-*` 前缀），自动导入无需手动引入
- 列表滚动使用 z-paging 组件
- 图标系统：UnoCSS Icons（`i-carbon-*`）+ 本地 SVG（`i-my-icons-*`）

### HTTP 请求约定

- 使用 `src/http/http.ts` 提供的 `http.get/post/put/delete` 方法
- API 函数返回 `Promise<T>`（已拆包，直接返回 `data` 字段）
- 分页请求使用 `PageParam` / `PageResult<T>` 类型
- 401 响应自动触发 Token 刷新或跳转登录
- 可通过 `isEncrypt: true` 选项启用 API 加密

### 权限控制

- 路由级别：`src/router/interceptor.ts` 实现白名单登录拦截
- 操作级别：`useAccess()` Hook 提供 `hasAccessByRoles` / `hasAccessByCodes`
- 字典数据：登录后自动缓存，通过 `useDict` / `getDictLabel` 使用

## AI 使用指引

### 添加新页面

1. 在对应分包目录创建 `.vue` 文件（如 `src/pages-system/xxx/index.vue`）
2. 使用 `definePage({...})` 声明路由元信息
3. 重启开发服务器使路由生效

### 添加新 API

1. 在 `src/api/` 下对应模块目录创建 `index.ts`
2. 定义 TypeScript 接口（Request/Response VO）
3. 使用 `http.get/post/put/delete` 封装请求函数

### 全局业务组件

项目提供 2 个按需导入的全局组件：

| 组件 | 路径 | 用途 | 使用频率 |
|------|------|------|---------|
| `DictTag` | `@/components/dict-tag` | 字典值渲染为彩色标签（依赖 `getDictObj`） | BPM 模块 |
| `UserPicker` | `@/components/system-select` | 用户选择器（单选/多选，支持 v-model） | 9 处（部门负责人、审批人等） |

使用示例：
```vue
<DictTag :type="DICT_TYPE.COMMON_STATUS" :value="item.status" />
<UserPicker v-model="formData.userId" type="radio" label="负责人" />
```

### 添加新分包

1. 在项目根创建 `src/pages-xxx/` 目录
2. 在 `vite.config.ts` 的 `UniPages.subPackages` 数组中注册
3. 重启开发服务器

### 注意事项

- 修改 `vite.config.ts`、`pages.config.ts`、`tabbar/config.ts` 后需重启
- 微信小程序有 2MB 主包限制，利用分包优化
- `src/manifest.json` 和 `src/pages.json` 是自动生成的（已 gitignore），不要手动编辑
- 条件编译使用 `// #ifdef PLATFORM` / `// #ifndef PLATFORM` 语法

## 变更记录 (Changelog)

| 时间 | 操作 | 说明 |
|------|------|------|
| 2026-02-06 22:35:10 | 初始创建 | 首次扫描生成，覆盖率约 85% |
| 2026-02-06 22:40:00 | 补充扫描 | 补扫 user/、tenant/、components/，覆盖率提升至约 92% |
| 2026-02-06 22:50:00 | 全量补扫 | pages-system 全部 16 个子模块完成深度分析，覆盖率约 97% |