lzh
1fecece73f
生成根级 + 4 个模块级 CLAUDE.md，覆盖率约 97%。 包含架构总览、模块索引、Mermaid 结构图、编码规范、 pages-system 全部 16 个子模块深度分析及跨模块依赖关系。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
202 lines
8.6 KiB
Markdown
202 lines
8.6 KiB
Markdown
# 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% |
|