# dev-aims

**Repository Path**: liangdandan/dev-aims

## Basic Information

- **Project Name**: dev-aims
- **Description**: aims
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-03
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AIMS 管理系统

> **基于 Vue2 + TypeScript + Pinia + UnoCSS + element-ui 的模块化管理系统框架**

## 🚀 快速开始

```bash
# 安装依赖
npm install

# 启动开发服务器（默认端口 8080，HTTPS）
npm run serve

# 构建生产版本
npm run build

# 分析打包体积
npm run analyze
```

## 🎯 技术栈

- **Vue 2.7.16** - 主框架，支持 Composition API
- **TypeScript 4.5.5** - 类型安全
- **Vue Router 3.5.1** - 路由管理
- **Pinia 2.2.6** - 状态管理（带持久化插件）
- **UnoCSS 0.58.0** - 原子化 CSS 框架
- **element-ui 2.15.14** - UI 组件库（组件以 `el-` 开头，项目中以 `kc-` 开头）
- **Axios 1.4.0** - HTTP 请求库
- **dayjs 1.11.9** - 日期处理
- **echarts** - 图表库（按需引用）

## 📁 项目结构

```
src/                              # 主应用（仅基础页面：登录/布局）
├── apiDefine/                    # API 类型定义
├── assets/images/                # 图片资源 + index.scss（ci-* 类定义）
├── components/                   # 全局组件（自动注册）
├── router/                       # 路由配置
├── store/                        # Pinia 状态管理
├── styles/dark|light/var.scss    # ⭐ 主题变量（7 个主题颜色 + 3 个背景边框变量）
└── views/                        # ❌ 登录页&导航栏(禁止新增页面)

submodule/模块名/                 # ✅ 所有新页面在此创建
├── apiDefine/                    # 模块API定义
├── assets/images/                # 图片资源 + index.scss（ci-* 类定义）
├── router/                       # 模块路由
├── store/                        # 模块状态
└── views/                        # 模块页面
uno.config.ts                     # UnoCSS 配置（颜色变量注册）
vue.config.js                     # Webpack 配置（px2rem 转换、代理等）
```

## 📖 核心规范

### 1️⃣ 页面生成位置

- ✅ **所有新页面必须在 `submodule/模块名/views/` 下创建**
- ❌ **禁止在 `src/views/` 中生成新页面**（仅保留登录、导航栏等基础页面）

### 2️⃣ 样式规范（UnoCSS）

**尺寸单位**：

- ❌ 禁用 `px` 单位
- ✅ 换算规则：`1rem = 4×值 = 16px`（如 `w-60 = 15rem = 240px`）
- ✅ 宽高相等时使用 `size-`（如 `size-full`、`size-16`）

**颜色使用**：

- ❌ 禁止直接使用颜色值（如 `bg-[#fff]`）
- ✅ 必须使用主题颜色变量
- ✅ 7 个主题颜色：`primary`、`white`、`black`、`green`、`orange`、`red`、`blue`
- ✅ 3 个背景边框变量：`bg`、`bc`、`bc-light`
- ⚠️ **重要**：深色主题下 `--white` 与 `--black` 值是反转的，文字颜色不能使用 `c-white`

**样式要求**：

- ✅ 仅用 UnoCSS 原子类，禁止自定义 CSS
- ✅ UI 组件宽度加 `!`：`<el-input class="w-60!" />`
- ✅ 列表子项要有 `hover:bg-primary` 和选中时 `b-primary` 样式

### 3️⃣ TypeScript 类型

- ✅ 必须用 `ResponseType` / `ResponseTypeFromArray` 从 `apiDefine` 推断类型
- ❌ 禁止用 `interface` 定义 API 响应类型

```typescript
import { ResponseType, ResponseTypeFromArray } from 'utils/ajax'
type Summary = ResponseType<'/api/home/device/summary'>
type TableList = ResponseType<'/api/demo/table/list', 'list'>
type TableItem = ResponseTypeFromArray<'/api/demo/table/list', 'list'>
```

### 4️⃣ 命名规范

| 类别      | 规则                   | 示例                                    |
| --------- | ---------------------- | --------------------------------------- |
| 组件 name | `PascalCase`           | `UserList`                              |
| 加载状态  | `loading` / `*Loading` | `loading` `tableLoading`                |
| 表单数据  | `form` / `*Form`       | `form` `searchForm`                     |
| 表格数据  | `tableData` / `*List`  | `tableData` `userList`                  |
| 分页参数  | `pagination`           | `{ pageNo: 1, pageSize: 10, total: 0 }` |
| 弹窗状态  | `*Visible`             | `dialogVisible`                         |
| 初始化    | `init*`                | `init()` `initChart()`                  |
| 数据获取  | `fetch*`               | `fetchList()` `fetchDetail()`           |
| 事件处理  | `handle*`              | `handleSubmit()` `handleDelete()`       |
| 弹窗控制  | `open*/close*Dialog`   | `openAddDialog()` `closeDialog()`       |

### 5️⃣ API 请求

**流程**：在 `apiDefine/index.ts` 定义接口 → 组件中 `this.$ajax(url, params, method)` 调用

```typescript
// 1. 定义接口
'/api/meeting/list': {
  method: 'POST' as 'POST',
  request: { pageNo: 0, pageSize: 10 },
  response: { list: [{ id: 0, name: '', status: 0, start_time: '' }], total: 0 }
}

// 2. 组件中调用
let res = await this.$ajax('/api/meeting/list', { pageNo: 1, pageSize: 10 }, 'POST')
```

### 6️⃣ 组件使用

- **element-ui**（`el-` 前缀，项目中以 `kc-` 开头）：`<kc-input>` `<kc-select>` `<kc-table>` 等
- **echarts**：`mounted()` 中 `this.$echarts.init()` + `setOption()`，`beforeDestroy()` 中 `dispose()`
- **全局组件**：放入 `src/components/` 或 `submodule/xxx/components/`

### 7️⃣ 图片资源

图片放入 `submodule/xx/assets/images/` → 在 `submodule/xx/assets/index.scss` 定义 `ci-*` 类（使用 mask data:image/svg+xml 占位） → 组件中 `<i class="size-* ci-xxx" />`

## ⚡ 快速参考

### UnoCSS 常用类

| 类别 | 常用类                                            | 说明                           |
| ---- | ------------------------------------------------- | ------------------------------ |
| 布局 | `flex` `flex-col` `flex-center` `flex-1`          | 弹性布局                       |
| 对齐 | `items-center` `justify-between` `justify-center` | 对齐方式                       |
| 尺寸 | `size-full` `size-16` `w-60` `h-full`             | `1rem = 4×值 = 16px`           |
| 间距 | `p-2` `m-2` `gap-2` `mb-2`                        | `p-2 = 0.5rem = 8px`           |
| 文本 | `text-ellipsis` `c-secondary` `text-4`            | `text-4 = 1rem = 16px`         |
| 组合 | `card` `shadow` `pointer` `disabled`              | `card` = b + rd + shadow + p-2 |

### 主题颜色变量

| 类别     | 示例                                                                  | 说明                                       |
| -------- | --------------------------------------------------------------------- | ------------------------------------------ |
| 主题     | `--primary` `--black` `--white` `--green` `--orange` `--red` `--blue` | 7 个核心颜色, 均支持透明度，如 bg-black/45 |
| 背景边框 | `--bg` `--bc`                                                         | 默认背景/默认边框                          |
| 文字     | `c-primary` `c-black` `c-text-secondary` `c-text-gray`                | 主要/默认/次要/置灰                        |

## 🔧 路径别名

- `@` → `src/`
- `submodule` → `submodule/`
- `utils` → `utils/`

## 🌍 环境配置

项目启动时会从 `public/static/config/global-${NODE_ENV}.json` 加载配置：

- `global-development.json` - 开发环境配置
- `global-production.json` - 生产环境配置

配置项：

- `BASE_URL` - API 基础地址
- `CLOUD_RBAC_URL` - 权限服务地址
- `CUSTOM_CONFIG` - 自定义配置

## ✨ 功能特性

- ✅ 模块化架构（子模块系统）
- ✅ JWT 认证（自动管理 Token）
- ✅ 路由守卫（自动检查认证）
- ✅ 状态持久化（Pinia + persist）
- ✅ 深色主题（科技蓝）
- ✅ 组件自动注册
- ✅ TypeScript 类型支持
- ✅ px2rem 自动转换

## 📚 相关文档

- **[CLAUDE.md](./CLAUDE.md)** - ⭐ 详细开发指南（专为 AI 代码生成工具设计，包含完整规范和工作流）
- [uno.config.ts](./uno.config.ts) - UnoCSS 配置文件

## 📝 注意事项

1. Vue2 的 computed 对 ts 支持不好，若要使用 this，先定义 `let _this: any = this`
2. 使用 `text-ellipsis` 样式时，请同步添加 `:title` 属性
3. 字体默认为 `text-3.5 c-black`，无需生成 `text-3.5` `c-black` 样式
4. 已有全局样式 `{ border: 0 solid var(--bc) }`，设置边框用 `b` 就可以了
5. uno.config.ts 中定义了两个 variants，其中`：`可针对子项进行样式设置，`dark-`可针对深色主题单独定制。如：`.el-input:c-primary`,`dark-c-black/70`, 使用 unoCss 插件后，如果样式没带下划虚线，请检查样式书写是否符合规范
6. Vue (Official) 3.0.8 为必装插件，兼容 vue2 下的 ts 语法(更高版本不支持 vue2 的 ts)，使用 Vue.extend({...})即可应用 ts 语法识别
7. 添加路由时要写中文 name

## 🌐 浏览器支持

- Chrome >= 88

## License

Private