XW-AIOT/aiot-uniapp
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6be7d38e63f2ccf7817dbce9122bec330be80d4e
aiot-uniapp/CLAUDE.md
lzh 1fecece73f docs: 初始化项目 AI 上下文文档 (CLAUDE.md) 
生成根级 + 4 个模块级 CLAUDE.md，覆盖率约 97%。
包含架构总览、模块索引、Mermaid 结构图、编码规范、
pages-system 全部 16 个子模块深度分析及跨模块依赖关系。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 12:16:22 +08:00

8.6 KiB
Raw Blame History

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

项目愿景

基于 UniApp + Vue 3 + TypeScript 的 AIoT（人工智能物联网）移动端管理应用。项目源自 unibest 模板（v4.1.0），二次开发适配 芋道管理系统（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+

模块结构图

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 脚本会检查）

安装依赖

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 处（部门负责人、审批人等）

使用示例：

<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%