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

🚀 Coi Admin

基于 Vue3 + Vite + TypeScript + Naive UI 的现代化后台管理系统

English | 简体中文

---

✨ 项目介绍

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)

📥 安装依赖

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

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

# 安装依赖
pnpm install

🛠️ 开发环境

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

# 启动测试环境
pnpm dev:test

# 启动生产环境
pnpm dev:prod

🏗️ 构建部署

# 构建生产版本
pnpm build

# 构建开发版本
pnpm build:dev

# 构建测试版本
pnpm build:test

# 预览构建结果
pnpm preview

🔍 代码检查

# 运行 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 图标库

📝 使用示例

<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
• 接口分类: 认证、用户管理、角色管理、系统管理等
• Mock数据: 完整的接口 Mock 数据支持

📡 HTTP 客户端

基于 Alova 封装的 HTTP 客户端：

// 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 图标库
• 语义化图标 - 图标含义与功能匹配
• 按钮必备 - 所有按钮必须配备图标

---

🌍 国际化支持

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

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

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

支持语言：

• 🇨🇳 简体中文
• 🇺🇸 English

---

🎨 主题定制

🌙 主题切换

支持明暗主题无缝切换：

// 主题切换
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 组件命名规范

---

🚀 部署指南

📦 构建优化

# 生产构建
pnpm build

# 分析打包体积
pnpm sizecheck

🐳 Docker 部署

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

🌐 Nginx 配置

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

---

🤝 贡献指南

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

🐛 问题反馈

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

1. 查看 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 规范：

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

---

📄 许可证

本项目基于 MIT 许可证开源。

---

🙏 致谢

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

• Vue.js - 渐进式 JavaScript 框架
• Vite - 下一代前端构建工具
• Naive UI - Vue 3 组件库
• UnoCSS - 原子化 CSS 引擎
• Alova - 轻量级请求策略库

---

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

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