# xi-admin

**Repository Path**: Peter_Mond/xi-admin

## Basic Information

- **Project Name**: xi-admin
- **Description**: 一个基于 .NET 10 + Vue 3 的现代化前后端分离权限管理系统
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
<h1>
Xi.Admin
</h1>

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![.NET](https://img.shields.io/badge/.NET-10.0-purple.svg)](https://dotnet.microsoft.com/)
[![Vue](https://img.shields.io/badge/Vue-3.5.34-4FC08D.svg)](https://vuejs.org/)
[![Element Plus](https://img.shields.io/badge/Element%20Plus-2.11.3-409EFF.svg)](https://element-plus.org/)
[![MySQL](https://img.shields.io/badge/MySQL-8.0-4479A1.svg)](https://www.mysql.com/)

一个基于 .NET 10 + Vue 3 的现代化前后端分离权限管理系统

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

</div>

## 目录

- [项目简介](#项目简介)
- [特性](#特性)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [核心功能](#核心功能)
- [API 接口说明](#api-接口说明)
- [配置说明](#配置说明)
- [开发指南](#开发指南)
- [数据库设计](#数据库设计)
- [构建部署](#构建部署)
- [常见问题](#常见问题)
- [贡献指南](#贡献指南)
- [特别鸣谢](#特别鸣谢)
- [许可证](#许可证)

## 项目简介

**Xi.Admin** 是一个轻量级、开箱即用的企业级权限管理及快速开发框架。系统采用 DDD（领域驱动设计）分层架构和 RBAC（基于角色的访问控制）权限模型，提供完整的身份认证、权限控制、用户管理等核心功能，并扩展了设备管理、文档查看等业务模块。

### 特性

- 🚀 **现代技术栈**：.NET 10 + Vue 3 + Vite，采用最新技术体系
- 🔐 **安全认证**：JWT Token 认证 + GIF 图形验证码 + 密码加密传输（前端 RSA + 后端 MD5）
- 🛡️ **权限验证**：基于 ASP.NET Core Authorization 策略的自定义 `[Permission]` 特性，支持权限缓存与自动失效
- 🎨 **精美界面**：Element Plus 组件库，提供一致的用户体验
- 👥 **权限控制**：基于 RBAC 的角色权限管理，支持菜单权限、操作权限、数据权限（5 种数据范围）
- 🔄 **动态路由**：前端路由根据用户权限动态生成，安全可靠
- 📁 **文件管理**：支持 MinIO 对象存储和本地文件系统，通过配置切换存储方案
- 📝 **操作审计**：`[Log]` 特性标记 + `GlobalActionFilter` 自动记录操作日志，可追溯用户行为
- 🛡️ **速率限制**：内置 ASP.NET Core Rate Limiting，按接口分级限流（strict/standard/relaxed），防刷防攻击
- 🏗️ **分层架构**：清晰的 DDD 分层代码结构，各层职责明确，易于维护和扩展
- 🧪 **单元测试**：xUnit 测试框架，覆盖授权、用户、角色等核心业务逻辑
- 📚 **API 文档**：Swagger 自动生成在线接口文档，方便前后端协作
- 🎯 **ID 生成**：实体主键使用 GUID，验证码等场景使用 Yitter 雪花算法生成分布式唯一 ID
- 🔄 **对象映射**：Mapster 高性能对象映射
- 🗄️ **审计追踪**：EF Core `SaveChangesAsync` 自动拦截，记录数据变更（新增/修改/删除）
- 🗑️ **软删除**：全局软删除过滤器，删除数据自动标记而非物理删除
- 📊 **Excel 导出**：BaseApiController 内置 Excel 导出和导入模板功能

## 技术栈

### 前端技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.34 | 渐进式 JavaScript 框架 |
| Vite | 8.0.5 | 新一代前端构建工具 |
| Element Plus | 2.11.3 | Vue 3 组件库 |
| Pinia | 3.0.4 | 新一代状态管理库 |
| Vue Router | 5.0.6 | 官方路由管理器 |
| Axios | 1.13.6 | HTTP 客户端 |
| ECharts | 5.6.0 | 数据可视化图表库 |
| @vueuse/core | 14.3.0 | Vue 组合式 API 工具集 |
| jsencrypt | 3.3.2 | RSA 加密库 |
| sass-embedded | 1.89.1 | CSS 预处理器 |

### 后端技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| .NET | 10.0 | 跨平台应用框架 |
| ASP.NET Core | 10.0 | Web API 框架 |
| Entity Framework Core | 10.0.8 | ORM 数据访问框架 |
| Microting.EntityFrameworkCore.MySql | 10.0.8 | MySQL 数据库驱动 |
| Microsoft.AspNetCore.Authentication.JwtBearer | 10.0.8 | JWT 认证中间件 |
| System.IdentityModel.Tokens.Jwt | 8.18.0 | JWT Token 生成和验证 |
| Microsoft.IdentityModel.Tokens | 8.19.1 | 令牌验证库 |
| Swashbuckle.AspNetCore | 10.2.1 | Swagger API 文档生成 |
| Serilog | 4.3.1 | 结构化日志记录（控制台+文件） |
| Mapster | 10.0.7 | 高性能对象映射 |
| MediatR | 14.1.0 | 领域事件接口基础（`IDomainEvent`） |
| Minio | 7.0.0 | MinIO 对象存储客户端 |
| MiniExcel | 1.44.1 | 轻量级 Excel 导入导出 |
| ToolGood.Words | 3.1.0.3 | 拼音转换（角色名归一化） |
| Yitter.IdGenerator | 1.0.14 | 雪花 ID 生成器 |
| Lazy.Captcha.Core | 2.2.4 | 图形验证码生成 |
| MD5 | 2.2.5 | MD5 加密 |

## 项目结构

```text
xi-admin
├── src
│   ├── xi-admin-vue3                  # 前端工程
│   │   ├── src
│   │   │   ├── api                    # API 接口封装（system/feature）
│   │   │   ├── assets                 # 静态资源（图标、样式、图片）
│   │   │   ├── components             # 公共组件（上传、分页、字典标签等）
│   │   │   ├── directive              # 自定义指令（v-hasPermi/v-hasRole）
│   │   │   ├── layout                 # 布局组件（侧边栏、导航栏、标签页）
│   │   │   ├── plugins                # 插件（auth、cache、download、modal）
│   │   │   ├── router                 # 路由配置（动态路由 + 静态路由）
│   │   │   ├── store                  # Pinia 状态管理模块
│   │   │   ├── utils                  # 工具函数（request、加密、验证等）
│   │   │   └── views                  # 页面视图（system/equipment/document 等）
│   │   ├── .env.development           # 开发环境配置
│   │   ├── .env.staging               # 测试环境配置
│   │   ├── .env.production            # 生产环境配置
│   │   ├── vite.config.js             # Vite 构建配置
│   │   └── package.json               # 项目依赖配置
│   │
│   └── xi-admin-server                # 后端解决方案
│       ├── Xi.Server                  # 入口层（Controller、Middleware、Filter、Authorization）
│       ├── Xi.Application             # 应用服务层（业务编排、DTO 转换）
│       ├── Xi.SystemManagement        # 领域服务层（核心业务逻辑、身份认证）
│       ├── Xi.Core                    # 核心层（接口定义、DTO/VM、配置、缓存）
│       ├── Xi.Infrastructure          # 基础设施层（EF Core、仓储、审计、文件存储）
│       ├── Xi.Domain                  # 领域层（实体、领域事件、核心基类）
│       ├── Xi.Common                  # 通用工具层（枚举、工具类、转换器）
│       ├── Xi.Tests                   # xUnit 单元测试
│       └── Xi.sln                     # 解决方案文件
│
├── docs/                              # 文档目录
└── README.md
```

### 分层架构说明

```
 Xi.Common (0)                Xi.Domain (0)
 枚举·工具·转换                实体·领域事件
      │                           │
      └───────────┬───────────────┘
                  │
           Xi.Core (1)
      接口·DTO·配置·缓存
                  │
      ┌───────────┼───────────────────┐
      │           │                   │
      ▼           ▼                   ▼
 Xi.Application  Xi.SystemManagement  Xi.Infrastructure
  应用层 (2)       领域服务层 (2)        基础设施层 (2)
 业务编排·DTO转换  核心业务·身份认证     EF Core·仓储·审计
      │           │                   │
      └───────────┼───────────────────┘
                  │
           Xi.Server (3)
      Controller·Middleware·Filter
```

> 括号内数字表示依赖层级，数字越小越底层。`Xi.Common` 和 `Xi.Domain` 不依赖任何项目，是最底层。

### 层间依赖关系

```
Xi.Server → Xi.Application, Xi.SystemManagement, Xi.Infrastructure, Xi.Core, Xi.Common
Xi.Application → Xi.Core, Xi.Domain
Xi.SystemManagement → Xi.Core, Xi.Domain, Xi.Common
Xi.Infrastructure → Xi.Core, Xi.Domain
Xi.Core → Xi.Domain, Xi.Common
Xi.Domain → (无依赖)
Xi.Common → (无依赖)
```

## 快速开始

### 环境要求

- **Node.js** >= 18.0.0
- **.NET SDK** >= 10.0
- **MySQL** >= 8.0
- **Yarn** 或 npm（推荐使用 Yarn）
- **MinIO**（可选，文件存储默认支持本地文件系统，也可配置为 MinIO 对象存储）

### 1. 克隆项目

```bash
git clone https://gitee.com/Peter_Mond/xi-admin.git
cd xi-admin
```

### 2. 数据库配置

#### 2.1 创建数据库

在 MySQL 中创建数据库：

```sql
CREATE DATABASE `xi-admin-platform` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

#### 2.2 修改配置文件

编辑 `src/xi-admin-server/Xi.Server/appsettings.json`，修改数据库连接字符串：

```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=127.0.0.1; Port=3306;Database=xi-admin-platform; User=root; Password=your_password; CharSet=utf8; Allow User Variables=true;sslMode=none;AllowPublicKeyRetrieval=true;"
  }
}
```

> **注意**：启动后端服务后，系统会自动执行 EF Core 数据库迁移（`InitializeAsync`）并初始化种子数据（`DatabaseSeeder`）。

### 3. 启动后端服务

```bash
cd src/xi-admin-server/Xi.Server
dotnet restore
dotnet run
```

后端服务默认运行地址：

| 模式 | 地址 |
|------|------|
| HTTP | `http://localhost:5075` |
| HTTPS | `https://localhost:7103` |
| Swagger 文档 | `http://localhost:5075/swagger` |

### 4. 启动前端服务

```bash
cd src/xi-admin-vue3
yarn install
yarn dev
```

前端服务默认运行在 `http://localhost:8089`，通过 Vite 代理（`/dev-api`）转发请求到后端 `http://localhost:5075`。

### 5. 登录系统

系统初始化后会创建默认用户：

| 用户名 | 密码 | 角色 | 说明 |
|--------|------|------|------|
| admin | admin | admin（超级管理员） | 拥有所有权限 |
| basic | basic | common（普通角色） | 基础权限 |

## 核心功能

### 身份认证

- ✅ 用户登录/登出
- ✅ JWT Token 签发与刷新
- ✅ 用户注册
- ✅ GIF 图形验证码（支持动画、干扰线、气泡）
- ✅ 密码加密传输（前端 RSA + 后端 MD5 + 盐值）
- ✅ 当前用户信息与权限查询
- ✅ 个人中心（信息修改、头像裁剪、密码修改）

### 权限控制

- ✅ 基于 `[Permission]` 特性的接口级权限验证
- ✅ `PermissionHandler` 自动校验用户权限集合与接口所需权限的交集
- ✅ 权限缓存机制（`CommonCacheService`），避免每次请求查库
- ✅ 前端 `v-hasPermi` / `v-hasRole` 指令控制按钮/元素显示
- ✅ 角色数据权限范围（5 种：全部/自定义/本部门/本部门及以下/仅本人）

### 系统管理

| 模块 | 功能描述 |
|------|----------|
| 用户管理 | 用户增删改查、状态管理、密码重置、角色分配、头像管理、用户授权角色 |
| 角色管理 | 角色增删改查、菜单权限分配、数据权限范围设置、用户分配、批量删除 |
| 菜单管理 | 目录(M)/菜单(C)/按钮(F)/链接(L) 四级管理、路由配置、操作权限标识 |
| 部门管理 | 组织架构树管理、部门增删改查、树形选择 |
| 组织管理 | 多组织架构管理，部门归属组织 |
| 字典管理 | 字典类型 + 字典数据两级管理，系统枚举数据维护 |
| 参数配置 | 系统参数键值对动态配置 |
| 通知公告 | 系统通知公告的发布、编辑与管理 |
| 操作日志 | `[Log]` 特性标记自动记录、多条件查询与导出 |

### 业务功能

| 模块 | 功能描述 |
|------|----------|
| 设备管理 | 设备列表、新增、编辑、删除、详情查看、文件附件管理 |
| 文档查看 | 文档信息查看、文件上传预览 |
| 系统日志 | 系统操作日志查询与管理 |
| 工作台 | 个人工作台、快捷入口 |

### 技术特性

- ✅ 完整的单元测试覆盖（授权、用户服务、角色服务等）
- ✅ 数据库自动迁移与种子数据初始化
- ✅ 基于 EF Core 的泛型仓储模式（`IRepositoryAsync` / `IReadOnlyRepositoryAsync`）
- ✅ 工作单元（`IUnitOfWork`）模式
- ✅ Mapster 对象高性能映射
- ✅ 雪花算法分布式 ID 生成（Yitter，用于验证码等场景；实体主键使用 GUID）
- ✅ Serilog 结构化日志记录（控制台 + 文件，按日滚动，保留 30 天）
- ✅ 全局异常处理中间件（`ErrorHandlerMiddleware`）
- ✅ 全局操作日志过滤器（`GlobalActionFilter` + `[Log]` 特性）
- ✅ 内存缓存服务
- ✅ EF Core 审计日志自动记录（数据变更追踪）
- ✅ 全局软删除过滤器（自动过滤 `IsDeleted=true` 的数据）
- ✅ 自动填充审计字段（`CreatedBy`/`CreatedAt`/`LastModifiedBy`/`LastModifiedAt`）
- ✅ Excel 导出与导入模板功能（`BaseApiController` 内置）
- ✅ 自定义 JSON 序列化（DateTime 格式化、CamelCase 命名策略）
- ✅ 多存储后端支持（MinIO 对象存储 / 本地文件系统），通过配置切换
- ✅ API 速率限制（strict/standard/relaxed 三级策略，按用户或 IP 限流）

## API 接口说明

### 接口规范

- **基础路径**：`/api`
- **数据格式**：JSON
- **字符编码**：UTF-8
- **认证方式**：JWT Bearer Token
- **命名策略**：CamelCase

### 统一响应格式

**成功响应**：

```json
{
  "success": true,
  "code": 200,
  "message": null,
  "data": {}
}
```

**失败响应**：

```json
{
  "success": false,
  "code": 500,
  "message": "错误信息",
  "data": null
}
```

**分页响应**：

```json
{
  "success": true,
  "code": 200,
  "message": null,
  "data": [...],
  "currentPage": 1,
  "totalPages": 5,
  "total": 50,
  "pageSize": 10,
  "hasPreviousPage": false,
  "hasNextPage": true
}
```

### 主要接口模块

#### 1. 身份认证 (`/api/identity`)

| 接口 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/identity/login` | POST | 用户登录 | 否 |
| `/api/identity/logout` | POST | 退出登录 | 是 |
| `/api/identity/user-info` | GET | 获取用户信息 | 是 |
| `/api/identity/refresh-token` | POST | 刷新 Token | 否 |
| `/api/identity/register-user` | POST | 用户注册 | 否 |

#### 2. 系统管理 (`/api/system`)

| 模块 | 基础路径 | 说明 |
|------|----------|------|
| 用户 | `/api/system/user` | 用户增删改查、状态管理、密码重置、角色分配 |
| 角色 | `/api/system/role` | 角色增删改查、菜单权限分配、数据权限设置 |
| 菜单 | `/api/system/menu` | 菜单增删改查、树形结构、路由配置 |
| 部门 | `/api/system/dept` | 部门增删改查、树形结构 |
| 组织 | `/api/system/org` | 组织增删改查、树形结构 |
| 字典类型 | `/api/system/dict/type` | 字典类型增删改查 |
| 字典数据 | `/api/system/dict/data` | 字典数据增删改查 |
| 参数配置 | `/api/system/config` | 系统参数配置增删改查 |
| 通知公告 | `/api/system/notice` | 通知公告增删改查 |
| 操作日志 | `/api/system/operation-log` | 操作日志查询、导出 |
| 个人中心 | `/api/system/user/profile` | 个人信息、头像、密码修改 |

#### 3. 业务功能 (`/api/equipment`)

| 模块 | 基础路径 | 说明 |
|------|----------|------|
| 设备 | `/api/equipment` | 设备增删改查、文件附件管理、Excel 导出 |

#### 4. 文件管理 (`/api/file`)

| 模块 | 基础路径 | 说明 |
|------|----------|------|
| 文档 | `/api/file/document` | 文档管理、文件夹/文件上传、下载、删除 |

#### 5. 公共接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/captcha/captcha-image` | GET | 获取 GIF 验证码 |

### 权限验证

系统使用 `[Permission]` 特性进行接口级权限验证：

```csharp
// 单个权限
[Permission("system:user:list")]
public async Task<IActionResult> List([FromQuery] SysUserQueryDto query) { }

// 多个权限（满足任一即可）
[Permission("system:user:add", "system:user:edit")]
public async Task<IActionResult> Save(SysUserDto dto) { }
```

权限验证流程：
1. `PermissionHandler` 从 `[Permission]` 特性获取接口所需权限
2. 从缓存（`CommonCacheService`）获取当前用户权限集合
3. 判断用户权限与所需权限是否有交集，有则授权成功

### Swagger 文档

启动后端服务后，访问 `http://localhost:5075/swagger` 可查看完整的 API 文档并进行接口测试。

## 配置说明

### 后端配置

主要配置文件位于 `src/xi-admin-server/Xi.Server/appsettings.json`

#### 核心配置项

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `ConnectionStrings:DefaultConnection` | MySQL 数据库连接字符串 | - |
| `AppConfiguration:MaxRequestBodySize` | 请求体最大大小 | 100000000 (100MB) |
| `AppConfiguration:Secret` | 应用密钥 | - |
| `AppConfiguration:JwtSetting:IssuerSigningKey` | JWT 签名密钥 | - |
| `AppConfiguration:JwtSetting:ValidIssuer` | 签发者 | Xi |
| `AppConfiguration:JwtSetting:ValidAudience` | 签收者 | Xi |
| `AppConfiguration:JwtSetting:ExpiredTime` | Token 过期时间（分钟） | 20 |
| `AppConfiguration:JwtSetting:ClockSkew` | 时间容错（秒） | 5 |
| `AppConfiguration:JwtSetting:Algorithm` | 加密算法 | HS256 |
| `AppConfiguration:CaptchaSettings:CaptchaType` | 验证码类型 | 10 |
| `AppConfiguration:CaptchaSettings:CodeLength` | 验证码长度 | 1 |
| `AppConfiguration:CaptchaSettings:ExpirySeconds` | 验证码过期时间（秒） | 60 |
| `AppConfiguration:MinioOptions:Endpoint` | MinIO 服务地址 | - |
| `AppConfiguration:MinioOptions:AccessKey` | MinIO 访问密钥 | - |
| `AppConfiguration:MinioOptions:SecretKey` | MinIO 密钥 | - |
| `AppConfiguration:MinioOptions:DefaultBucketName` | 默认 Bucket | xi |
| `AppConfiguration:StorageOptions:Provider` | 存储提供者（Minio/Local） | Local |
| `AppConfiguration:LocalStorageOptions:RootPath` | 本地存储根目录 | ./uploads |
| `AppConfiguration:IdGeneratorOptions:WorkerId` | 机器码 | 1 |
| `AppConfiguration:IdGeneratorOptions:WorkerIdBitLength` | 机器码位长 | 6 |
| `AppConfiguration:IdGeneratorOptions:SeqBitLength` | 序列数位长 | 6 |

#### 速率限制配置

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `RateLimiting:Strict:WindowSeconds` | 严格策略时间窗口（秒） | 60 |
| `RateLimiting:Strict:PermitLimit` | 严格策略窗口内最大请求数 | 10 |
| `RateLimiting:Standard:WindowSeconds` | 标准策略时间窗口（秒） | 60 |
| `RateLimiting:Standard:PermitLimit` | 标准策略窗口内最大请求数 | 60 |
| `RateLimiting:Relaxed:WindowSeconds` | 宽松策略时间窗口（秒） | 60 |
| `RateLimiting:Relaxed:PermitLimit` | 宽松策略窗口内最大请求数 | 200 |

> 策略分配：`strict` 用于登录/验证码接口，`standard` 用于文件上传/数据修改，`relaxed` 用于查询接口。

#### Serilog 日志配置

| 配置项 | 说明 |
|--------|------|
| `Serilog:MinimumLevel:Default` | 默认日志级别（Information） |
| `Serilog:WriteTo:Console` | 控制台输出 |
| `Serilog:WriteTo:File (debug)` | Debug 级别日志文件，按日滚动，保留 30 天 |
| `Serilog:WriteTo:File (info)` | Info 级别日志文件，按日滚动，保留 30 天 |
| `Serilog:WriteTo:File (error)` | Error 级别日志文件，按日滚动，保留 30 天 |

### 前端配置

| 文件 | 环境 | API 代理路径 |
|------|------|-------------|
| `.env.development` | 开发 | `/dev-api` → `http://localhost:5075` |
| `.env.staging` | 测试 | `/stage-api` |
| `.env.production` | 生产 | `/prod-api` |

## 开发指南

### 后端开发

#### 1. 项目结构规范

- **Xi.Domain**：领域层，仅包含实体、值对象、领域事件和核心基类
- **Xi.Core**：核心层，包含接口定义、DTO/VM、配置、缓存、结果模型
- **Xi.Common**：通用层，包含枚举、工具类、转换器、特性
- **Xi.Infrastructure**：基础设施层，包含 EF Core、仓储、审计、文件存储
- **Xi.SystemManagement**：领域服务层，包含系统管理核心业务逻辑
- **Xi.Application**：应用服务层，包含业务编排、业务功能服务
- **Xi.Server**：入口层，包含 Controller、Middleware、Filter、Authorization

#### 2. 添加新的业务模块

1. 在 `Xi.Domain/Entities/` 下创建实体（继承 `AuditableSoftDeleteEntity` 或 `AuditableEntity`）
2. 在 `Xi.Core/Models/Dto/` 和 `Xi.Core/Models/Vm/` 下创建 DTO 和 VM
3. 在 `Xi.Core/System/` 下定义服务接口
4. 在 `Xi.SystemManagement/System/` 下实现服务
5. 在 `Xi.Application/` 下添加应用服务（如需）
6. 在 `Xi.Server/Controllers/` 下创建 Controller（继承 `BaseApiController<T>`）
7. 在 `ApplicationDbContext` 中添加 `DbSet`
8. 添加数据库迁移

#### 3. 实体基类选择

| 基类 | 适用场景 | 特性 |
|------|----------|------|
| `AuditableEntity` | 需要审计字段的实体 | 自动填充创建/修改人和时间 |
| `AuditableSoftDeleteEntity` | 需要软删除的实体 | 审计 + 逻辑删除（IsDeleted） |
| `AuditableSoftDeleteSyncEntity` | 需要同步标记的实体 | 审计 + 软删除 + 同步字段 |
| `AuditableTreeEntity` | 树形结构实体 | 审计 + 父子节点（CascadeId/ParentId） |

#### 4. 权限标记

在 Controller 方法上添加 `[Permission]` 特性：

```csharp
[Permission("module:entity:action")]
```

在需要记录操作日志的方法上添加 `[Log]` 特性：

```csharp
[Log("分类", "操作类型", "业务类型")]
```

#### 5. 数据库迁移

```bash
cd src/xi-admin-server

# 添加迁移
dotnet ef migrations add MigrationName --project Xi.Infrastructure --startup-project Xi.Server

# 应用迁移
dotnet ef database update --project Xi.Infrastructure --startup-project Xi.Server

# 移除迁移
dotnet ef migrations remove --project Xi.Infrastructure --startup-project Xi.Server
```

#### 6. 运行测试

```bash
cd src/xi-admin-server
dotnet test
```

### 前端开发

#### 1. 项目结构规范

- `src/api/`：API 接口封装，按模块分类
- `src/assets/`：静态资源
- `src/components/`：公共组件
- `src/directive/`：自定义指令（`v-hasPermi`、`v-hasRole`、`v-copyText`）
- `src/layout/`：布局组件
- `src/plugins/`：插件（auth、cache、download、modal、tab）
- `src/router/`：路由配置
- `src/store/`：Pinia 状态管理
- `src/utils/`：工具函数
- `src/views/`：页面视图，按功能模块划分

#### 2. 添加新的业务页面

1. 在 `src/api/` 下创建 API 接口
2. 在 `src/views/` 下创建页面组件
3. 在系统菜单管理中添加菜单配置（系统自动生成路由）

#### 3. 权限指令

```html
<!-- 操作权限 -->
<el-button v-hasPermi="['system:user:add']">新增</el-button>

<!-- 角色权限 -->
<el-button v-hasRole="['admin']">管理员操作</el-button>
```

#### 4. 开发命令

```bash
cd src/xi-admin-vue3

# 安装依赖
yarn install

# 启动开发服务器
yarn dev

# 构建生产版本
yarn build:prod

# 构建测试版本
yarn build:stage
```

## 数据库设计

### 核心数据表

| 表名 | 说明 | 对应实体 |
|------|------|----------|
| SysUser | 用户表 | `SysUser` |
| SysRole | 角色表 | `SysRole` |
| SysUserRole | 用户角色关联表 | `SysUserRole` |
| SysMenu | 功能模块表 | `SysMenu` |
| SysRoleMenu | 角色菜单关联表 | `SysRoleMenu` |
| SysDept | 部门表 | `SysDept` |
| SysUserDept | 用户部门关联表 | `SysUserDept` |
| SysOrg | 组织表 | `SysOrg` |
| SysDictType | 字典类型表 | `SysDictType` |
| SysDictData | 字典数据表 | `SysDictData` |
| SysConfig | 参数配置表 | `SysConfig` |
| SysNotice | 通知公告表 | `SysNotice` |
| SysOperationLog | 操作日志表 | `SysOperationLog` |
| SysFile | 文件表 | `SysFile` |
| Equipment | 设备表 | `Equipment` |
| EquipmentFile | 设备文件关联表 | `EquipmentFile` |
| Audit | 审计日志表 | `Audit` |

### 实体关系

```
SysUser ──M:N── SysRole ──M:N── SysMenu
   │               │
   ├── SysUserRole ├── SysRoleMenu
   │
   ├── SysOrg (1:N)
   ├── SysDept (M:N via SysUserDept)
   │
   └── SysFile (头像等)
```

### 种子数据

系统启动时自动初始化以下数据：

- **角色**：admin（超级管理员）、common（普通角色）、editor（编辑角色）
- **用户**：admin（超级管理员）、basic（普通用户）
- **组织**：杭州测试公司
- **部门**：测试部
- **字典**：系统开关（sys_normal_disable）、用户性别（sys_user_sex）、菜单状态（sys_show_hide）

## 构建部署

### 后端部署

```bash
cd src/xi-admin-server/Xi.Server

# 发布
dotnet publish -c Release -o ./publish

# 运行
cd publish
dotnet Xi.Server.dll
```

### 前端部署

```bash
cd src/xi-admin-vue3

# 构建生产版本
yarn build:prod

# 构建产物在 dist/ 目录
# 部署到 Nginx 或其他 Web 服务器
```

### Nginx 配置示例

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /prod-api/ {
        proxy_pass http://localhost:5075/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 常见问题

### 1. 数据库连接失败

检查 `appsettings.json` 中的连接字符串是否正确，确保 MySQL 服务已启动，数据库 `xi-admin-platform` 已创建。

### 2. 前端无法访问后端接口

检查后端服务是否启动，确认 `vite.config.js` 中的代理配置正确（开发环境 `/dev-api` → `http://localhost:5075`）。

### 3. 数据库迁移失败

确保 `dotnet ef` 工具已安装：
```bash
dotnet tool install --global dotnet-ef
```

### 4. 权限验证不生效

- 确保用户已分配正确的角色
- 确保角色已分配正确的菜单权限（含权限标识）
- 检查 `[Permission]` 特性的权限标识是否与菜单配置一致

### 5. 日志文件位置

日志文件默认位于 `Xi.Server/logs/` 目录下，按级别分类：
- `debug-YYYYMMDD.log`：Debug 级别
- `info-YYYYMMDD.log`：Information 级别
- `error-YYYYMMDD.log`：Error 级别

### 6. 验证码不显示

检查 `appsettings.json` 中 `CaptchaSettings` 配置，确保 `CaptchaType` 值有效（0-11）。

## 贡献指南

欢迎提交 Issue 和 Pull Request！

## 特别鸣谢

- [RuoYi-Vue3](https://gitcode.com/yangzongzhuan/RuoYi-Vue3) - 若依管理系统前端框架

## 许可证

MIT License