# AdminFramework 快速开始

## 🚀 3 分钟上手

### 第一步：引入框架

```javascript
import AdminFramework from './admin-framework.js'
```

### 第二步：创建应用

```javascript
const app = AdminFramework.createApp({
  title: '我的管理系统',
  apiUrl: 'http://localhost:9098/admin_api/',
  componentMap: {
    'business/product': ProductComponent,
    'business/order': OrderComponent
  }
})
```

### 第三步：挂载应用1

```javascript
app.$mount('#app')
```

## ✨ 就这么简单！

**完整代码只需 12 行：**

## 📁 文件下载功能

框架内置了便捷的文件下载功能：

```javascript
// 在组件中使用
export default {
  methods: {
    exportData() {
      // 调用 API 获取数据
      this.$http.fileExport('/api/export', params).then(res => {
        // 下载文件（自动处理换行符）
        this.$uiTool.downloadFile(res, '数据导出.csv')
      })
    }
  }
}
```

**特性：**
- ✅ 自动处理 CSV 换行符
- ✅ 支持多种文件格式
- ✅ 浏览器兼容性好

```javascript
// main.js
import AdminFramework from './admin-framework.js'
import ProductComponent from './views/business/product.vue'
import OrderComponent from './views/business/order.vue'

const app = AdminFramework.createApp({
  title: '我的管理系统',
  apiUrl: 'http://localhost:9098/admin_api/',
  componentMap: {
    'business/product': ProductComponent,
    'business/order': OrderComponent
  }
})

app.$mount('#app')
```

## 📋 组件映射表配置

`componentMap` 用于定义业务页面的动态路由。

**重要提示：** 只需传递不带 `.vue` 后缀的路径，框架会自动处理带后缀和不带后缀的两种情况！

```javascript
// 直接在 createApp 中配置
const app = AdminFramework.createApp({
  title: '我的管理系统',
  apiUrl: 'http://localhost:9098/admin_api/',
  componentMap: {
    // ✅ 正确：只传递不带 .vue 的路径
    'business/product': ProductComponent,
    'business/order': OrderComponent,
    'system/user': UserComponent,

    // ❌ 错误：不要同时传递带和不带 .vue 的路径（多余）
    // 'business/product.vue': ProductComponent,  // 框架会自动添加
  }
})
```

**说明：** 框架内部会自动为每个组件创建两个映射：
- `'business/product'` → ProductComponent
- `'business/product.vue'` → ProductComponent（自动添加）

所以后台菜单配置 `business/product` 或 `business/product.vue` 都可以正常工作！

## ⚙️ 配置说明

### 必填参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `title` | 应用标题 | `'我的管理系统'` |
| `apiUrl` | API 基础地址 | `'http://localhost:9098/admin_api/'` |
| `componentMap` | 组件映射表 | 见上方示例 |

### 可选参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `uploadUrl` | 上传文件地址 | `apiUrl + 'upload'` |
| `onReady` | 应用启动回调 | - |

## 🎯 完整示例

```javascript
import AdminFramework from './admin-framework.js'
import componentMap from './router/component-map.js'

const app = AdminFramework.createApp({
  // 必填配置
  title: '我的管理系统',
  apiUrl: 'http://localhost:9098/admin_api/',
  componentMap: componentMap,

  // 可选配置
  uploadUrl: 'http://cdn.example.com/upload', // 可选，默认为 apiUrl + 'upload'

  // 应用启动完成回调
  onReady() {
    console.log('应用已启动!')
    console.log('当前登录用户:', this.$store.state.user)
  }
})

app.$mount('#app')
```

## 📦 框架内置功能

使用 `createApp()` 后，框架会自动提供：

### 1. 内置页面
- ✅ 登录页面 (`/login`)
- ✅ 主页 (`/home`)
- ✅ 404 页面 (`/404`)
- ✅ 401 页面 (`/401`)
- ✅ 500 页面 (`/500`)

### 2. 系统管理页面
- ✅ 用户管理 (`/system/user`)
- ✅ 角色管理 (`/system/role`)
- ✅ 日志管理 (`/system/log`)
- ✅ 参数设置 (`/system/param`)
- ✅ 菜单管理 (`/system/menu`)
- ✅ 权限控制 (`/system/control`)
- ✅ 标题设置 (`/system/title`)

### 3. 全局组件
- ✅ `<Tables>` - 增强型表格
- ✅ `<UploadSingle>` - 单图上传
- ✅ `<UploadMultiple>` - 多图上传
- ✅ `<TreeGrid>` - 树形表格
- ✅ `<AsyncModal>` - 异步弹窗
- ✅ `<Editor>` - 富文本编辑器
- ✅ `<CommonIcon>` - 图标选择器
- ✅ `<FloatPanel>` - 浮动面板

### 4. 工具方法

在任何组件中可以使用：

```javascript
// HTTP 请求
this.$http.get('/api/users')
this.$http.post('/api/users', data)

// UI 工具
this.$uiTool.showLoading()
this.$uiTool.hideLoading()
this.$uiTool.showSuccess('操作成功')

// 通用工具
this.$tools.formatDate(new Date())
this.$tools.deepClone(obj)

// 文件下载
this.$uiTool.downloadFile(response, 'filename.xlsx')

// 配置信息
this.$config.title
this.$config.apiUrl
this.$config.uploadUrl

// 状态管理
this.$store.state.user.token
this.$store.state.app.sysTitle
```

## 🎨 自定义页面

### 1. 创建页面组件

```vue
<!-- views/business/product-list.vue -->
<template>
  <div>
    <Tables :columns="columns" :data="list" />
  </div>
</template>

<script>
export default {
  data() {
    return {
      list: [],
      columns: [
        { title: '产品名称', key: 'name' },
        { title: '价格', key: 'price' }
      ]
    }
  },
  created() {
    this.loadData()
  },
  methods: {
    async loadData() {
      const res = await this.$http.get('/products')
      this.list = res.data
    }
  }
}
</script>
```

### 2. 添加到组件映射表

```javascript
// router/component-map.js
import ProductList from '../views/business/product-list.vue'

export default {
  'business/product': ProductList  // 路径对应后台菜单的 component 字段
}
```

### 3. 在后台配置菜单

在"菜单管理"中添加菜单项：
- 菜单名称: `产品列表`
- 路由路径: `/business/product`
- 组件路径: `business/product`（对应 componentMap 的 key）

## 📝 常见问题

### Q1: uploadUrl 如何配置？

**A:** 默认情况下无需配置，框架会自动设置为 `apiUrl + 'upload'`。

如果需要自定义（如使用 CDN），可以手动传入：

```javascript
AdminFramework.createApp({
  apiUrl: 'http://localhost:9098/admin_api/',
  uploadUrl: 'http://cdn.example.com/upload' // 自定义上传地址
})
```

### Q2: 如何访问框架实例？

**A:** 框架实例会自动暴露到全局：

```javascript
// 浏览器控制台
window.framework // 框架实例
window.app       // Vue 实例
window.rootVue   // Vue 实例（别名）
```

### Q3: 如何添加自定义 Vuex 模块？

**A:** 使用旧的 `install()` 方式：

```javascript
import AdminFramework from './admin-framework.js'

AdminFramework.install(Vue, {
  config: { ... },
  ViewUI,
  VueRouter,
  Vuex,
  customModules: {
    myModule: myModuleConfig
  }
})
```

### Q4: 框架文件太大怎么办？

**A:** 新版框架（3.6 MB）内置了所有依赖，使用更方便。如果需要减小文件大小，可以使用旧的 `install()` 方式，手动引入依赖。

## 🔗 相关文档

- [简化使用说明.md](./简化使用说明.md) - 详细的使用说明和对比
- [README.md](./README.md) - 项目介绍和特性
- [demo/src/main.js](./demo/src/main.js) - 完整示例代码

## 💡 最佳实践

1. **推荐使用 `createApp()`** - 代码更简洁，减少 77% 的代码量
2. **组件映射表单独管理** - 方便维护和扩展
3. **利用内置组件** - 如 `<Tables>`、`<UploadSingle>` 等，提高开发效率
4. **使用 `onReady` 回调** - 在应用启动后执行初始化逻辑

## 🎉 开始开发吧！

现在你已经了解了 AdminFramework 的快速使用方法，开始构建你的管理系统吧！