coder-common-thin-frontend/README.zh-CN.md

<div align="center">
<img src="https://gaoziman.oss-cn-hangzhou.aliyuncs.com/uPic/2025-07-09-%E7%94%B0%E5%9B%AD%E7%8A%AC.svg" style="width:150px"/>
<h1>🚀 Coi Admin</h1>
<p>基于 Vue3 + Vite + TypeScript + Naive UI 的现代化后台管理系统</p>
</div>

<div align="center">

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Vue](https://img.shields.io/badge/Vue-3.5.16-4FC08D?logo=vue.js&logoColor=white)](https://vuejs.org/)
[![Vite](https://img.shields.io/badge/Vite-6.3.5-646CFF?logo=vite&logoColor=white)](https://vitejs.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8.3-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Naive UI](https://img.shields.io/badge/Naive%20UI-2.41.1-18A058?logo=vue.js&logoColor=white)](https://www.naiveui.com/)
[![UnoCSS](https://img.shields.io/badge/UnoCSS-66.2.0-333333?logo=unocss&logoColor=white)](https://unocss.dev/)

</div>

<div align="center">

**[English](./README.md) | 简体中文**

</div>

---

## ✨ 项目介绍

**Coi Admin** 是一个基于最新前端技术栈开发的现代化后台管理系统模板。项目采用简洁的设计理念，提供完整的权限管理、用户管理、系统管理等功能，旨在为开发者提供开箱即用的后台管理解决方案。

### 🎯 设计理念

- **🎨 简洁美观** - 采用 Naive UI 设计语言，界面简洁现代
- **⚡ 开发友好** - 完善的 TypeScript 支持，优秀的开发体验
- **📱 响应式设计** - 完美适配桌面端和移动端
- **🔧 易于定制** - 灵活的配置系统，轻松定制主题和布局
- **📚 规范完善** - 详细的开发规范和代码注释

---

## 🚀 核心特性

### 💎 技术架构
- **🔥 Vue 3.5.16** - 最新的 Vue3 Composition API
- **⚡ Vite 6.3.5** - 极速的前端构建工具
- **📘 TypeScript 5.8.3** - 完整的类型安全支持
- **🎨 Naive UI 2.41.1** - 企业级组件库
- **🎪 UnoCSS 66.2.0** - 高性能原子化 CSS 引擎
- **🌐 Vue Router 4** - 官方路由管理器
- **📦 Pinia** - 新一代状态管理
- **🔗 Alova** - 轻量级请求库

### 🛠️ 功能特性
- **🔐 完整权限系统** - 基于 RBAC 的权限管理，支持路由级、组件级、按钮级权限控制
- **👤 用户管理** - 完整的用户CRUD操作，支持角色分配和权限管理
- **🏷️ 角色管理** - 灵活的角色权限配置，支持动态权限分配
- **📋 菜单管理** - 动态菜单配置，支持图标、路由等多种属性设置
- **🔄 路由管理** - 支持静态路由和动态路由，自动生成面包屑导航
- **🌙 主题切换** - 支持明暗主题切换，保持视觉一致性
- **🌍 国际化** - 完整的多语言支持
- **📊 数据可视化** - 集成图表组件，支持各种数据展示需求

### 🎨 界面特色
- **📱 响应式布局** - 完美适配各种屏幕尺寸
- **🎯 现代化设计** - 采用最新的 UI 设计趋势
- **🎪 动画效果** - 丰富的过渡动画，提升用户体验
- **📐 灵活布局** - 支持左侧菜单、顶部菜单、混合菜单等多种布局
- **🔖 标签页管理** - 支持多标签页操作，提高工作效率

---

## 📦 技术栈

| 技术 | 版本 | 描述 |
|------|------|------|
| **Vue** | `3.5.16` | 渐进式 JavaScript 框架 |
| **Vite** | `6.3.5` | 下一代前端构建工具 |
| **TypeScript** | `5.8.3` | JavaScript 的超集，提供类型安全 |
| **Naive UI** | `2.41.1` | Vue 3 企业级组件库 |
| **UnoCSS** | `66.2.0` | 高性能原子化 CSS 引擎 |
| **Vue Router** | `4.5.1` | Vue.js 官方路由管理器 |
| **Pinia** | `3.0.3` | Vue 状态管理库 |
| **Alova** | `3.3.2` | 轻量级请求策略库 |
| **Vue I18n** | `11.1.5` | 国际化插件 |
| **VueUse** | `13.3.0` | Vue Composition 工具库 |

---

## 📂 项目结构

```
coder-common-thin-frontend/
├── 📁 src/
│   ├── 📁 components/          # 公共组件
│   │   ├── 📁 common/          # 通用组件 (Coi 系列)
│   │   └── 📁 custom/          # 自定义组件
│   ├── 📁 views/               # 页面组件
│   │   ├── 📁 dashboard/       # 仪表盘
│   │   ├── 📁 system/          # 系统管理
│   │   ├── 📁 personal-center/ # 个人中心
│   │   └── 📁 login/           # 登录页面
│   ├── 📁 store/               # 状态管理
│   │   ├── 📁 auth.ts          # 认证状态
│   │   ├── 📁 router/          # 路由状态
│   │   └── 📁 app/             # 应用状态
│   ├── 📁 router/              # 路由配置
│   ├── 📁 service/             # API 服务
│   │   ├── 📁 api/             # 接口定义
│   │   └── 📁 http/            # HTTP 配置
│   ├── 📁 utils/               # 工具函数
│   ├── 📁 hooks/               # 组合式函数
│   ├── 📁 constants/           # 常量定义
│   ├── 📁 typings/             # 类型定义
│   └── 📁 styles/              # 样式文件
├── 📁 doc/                     # 项目文档
├── 📁 locales/                 # 国际化语言包
└── 📄 CLAUDE.md                # 开发规范文档
```

---

## 🚀 快速开始

### 📋 环境要求

确保你的开发环境满足以下要求：

- **Node.js** `>= 21.x`
- **pnpm** `>= 10.x` (推荐使用 pnpm)

### 📥 安装依赖

```bash
# 克隆项目
git clone <your-project-url>

# 进入项目目录
cd coder-common-thin-frontend

# 安装依赖
pnpm install
```

### 🛠️ 开发环境

```bash
# 启动开发服务器 (默认端口: 9980)
pnpm dev

# 启动测试环境
pnpm dev:test

# 启动生产环境
pnpm dev:prod
```

### 🏗️ 构建部署

```bash
# 构建生产版本
pnpm build

# 构建开发版本
pnpm build:dev

# 构建测试版本
pnpm build:test

# 预览构建结果
pnpm preview
```

### 🔍 代码检查

```bash
# 运行 ESLint 检查和类型检查
pnpm lint

# 自动修复代码问题
pnpm lint:fix

# 检查 ESLint 配置
pnpm lint:check

# 查看打包体积分析
pnpm sizecheck
```

---

## 🎯 核心功能

### 🔐 权限管理系统

- **多层权限验证** - 路由级、组件级、API级权限控制
- **RBAC权限模型** - 基于角色的访问控制
- **权限指令** - `v-permission` 指令和 `usePermission` 组合函数
- **Super权限** - 支持超级管理员绕过权限检查

### 👥 用户管理

- **用户CRUD** - 完整的用户增删改查功能
- **角色分配** - 灵活的用户角色管理
- **状态管理** - 用户启用/禁用状态控制
- **密码管理** - 安全的密码重置功能

### 🏷️ 角色管理

- **角色配置** - 灵活的角色权限配置
- **权限分配** - 可视化的权限分配界面
- **角色继承** - 支持角色权限继承机制

### 🌐 路由系统

- **动态路由** - 支持后端返回的动态路由配置
- **静态路由** - 本地静态路由配置
- **路由守卫** - 完整的路由权限验证
- **面包屑** - 自动生成导航面包屑

---

## 🎨 组件系统

### 🧩 Coi 组件库

项目内置了一套 **Coi** 系列组件，提供统一的设计语言：

- **CoiDialog** - 统一的对话框组件，支持 ESC 关闭、遮罩关闭等功能
- **CoiEmpty** - 美观的空状态组件，支持多种类型和自定义操作
- **CoiIcon** - 图标组件，支持 Iconify 图标库

### 📝 使用示例

```vue
<template>
  <!-- 对话框使用 -->
  <CoiDialog
    ref="dialogRef"
    title="确认操作"
    @coi-confirm="handleConfirm"
    @coi-cancel="handleCancel"
  >
    <template #content>
      <p>确定要执行此操作吗？</p>
    </template>
  </CoiDialog>

  <!-- 空状态使用 -->
  <CoiEmpty
    type="search"
    :show-action="true"
    action-text="重新搜索"
    @action="handleRefresh"
  />
</template>
```

---

## 📊 接口管理

### 🔗 API 接口

项目使用 **ApiFox** 进行接口管理和 Mock：

- **在线文档**: [https://nova-admin.apifox.cn](https://nova-admin.apifox.cn)
- **接口分类**: 认证、用户管理、角色管理、系统管理等
- **Mock数据**: 完整的接口 Mock 数据支持

### 📡 HTTP 客户端

基于 **Alova** 封装的 HTTP 客户端：

```typescript
// API 调用示例
import { addUser, getUserList } from '@/service/api/system/user'

// 获取用户列表
const { data } = await getUserList({ pageNo: 1, pageSize: 10 })

// 添加用户
await addUser({ userName: 'test', loginName: 'test' })
```

---

## 📚 开发规范

项目包含完整的开发规范文档 `CLAUDE.md`，涵盖：

### 🎯 核心原则
- **可读性优先** - 代码是写给人看的
- **DRY原则** - 不重复造轮子
- **高内聚低耦合** - 模块化设计

### 📋 编码规范
- **命名规范** - 统一的命名约定
- **文件组织** - 清晰的目录结构
- **组件开发** - 组件开发最佳实践
- **API设计** - RESTful API 设计规范

### 🎨 图标使用规范
- **统一图标库** - 使用 `icon-park-outline` 图标库
- **语义化图标** - 图标含义与功能匹配
- **按钮必备** - 所有按钮必须配备图标

---

## 🌍 国际化支持

项目内置完整的国际化支持：

```typescript
// 语言配置
const { t } = useI18n()

// 使用翻译
const title = t('common.confirm')
```

支持语言：
- 🇨🇳 简体中文
- 🇺🇸 English

---

## 🎨 主题定制

### 🌙 主题切换

支持明暗主题无缝切换：

```typescript
// 主题切换
const { theme, toggleTheme } = useTheme()
```

### 🎨 样式定制

- **CSS变量** - 支持CSS变量定制
- **UnoCSS** - 原子化CSS，灵活定制
- **主题色** - 可配置的主题色彩方案

---

## 📖 开发指南

### 🔧 添加新页面

1. 在 `src/views/` 创建页面组件
2. 在 `src/router/routes.static.ts` 添加路由配置
3. 配置权限要求（roles字段）

### 🔌 添加新API

1. 在 `src/service/api/` 定义接口
2. 使用项目封装的 alova 实例
3. 遵循统一的响应处理格式

### 🧩 添加新组件

1. 在 `src/components/` 创建组件
2. 使用 TypeScript 定义 Props 和 Emits
3. 遵循 Coi 组件命名规范

---

## 🚀 部署指南

### 📦 构建优化

```bash
# 生产构建
pnpm build

# 分析打包体积
pnpm sizecheck
```

### 🐳 Docker 部署

```bash
# 使用 Docker Compose 部署
docker compose -f docker-compose.product.yml up --build -d
```

### 🌐 Nginx 配置

参考项目中的 `nginx.conf` 配置文件。

---

## 🤝 贡献指南

我们欢迎所有形式的贡献！

### 🐛 问题反馈

如果你发现了 bug 或有功能建议：

1. 查看 [Issues](../../issues) 是否已有相关问题
2. 创建新的 Issue，详细描述问题或建议
3. 如果可能，提供复现步骤或期望行为

### 💡 功能建议

我们欢迎新功能建议：

1. 确保建议符合项目目标
2. 详细描述功能需求和使用场景
3. 如果可能，提供设计方案或原型

### 🔧 代码贡献

1. Fork 本仓库
2. 创建新的功能分支: `git checkout -b feature/amazing-feature`
3. 提交你的更改: `git commit -m 'feat: add amazing feature'`
4. 推送到分支: `git push origin feature/amazing-feature`
5. 提交 Pull Request

### 📝 Commit 规范

请遵循 [Conventional Commits](https://conventionalcommits.org/) 规范：

```
feat: 新功能
fix: bug修复
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建过程或辅助工具的变动
```

---

## 📄 许可证

本项目基于 [MIT](LICENSE) 许可证开源。

---

## 🙏 致谢

感谢以下优秀的开源项目：

- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Vite](https://vitejs.dev/) - 下一代前端构建工具
- [Naive UI](https://www.naiveui.com/) - Vue 3 组件库
- [UnoCSS](https://unocss.dev/) - 原子化 CSS 引擎
- [Alova](https://alova.js.org/) - 轻量级请求策略库

---

<div align="center">

**如果这个项目对你有帮助，请给它一个 ⭐**

**让我们一起构建更好的后台管理系统！**

</div>