# XinAdmin 文档

> XinAdmin 企业级 PHP 全栈开发框架的中英文项目文档。

## 指南

- [指南概览](/guide/index.md): XinAdmin 文档导航，汇集项目介绍、环境准备、安装启动、源码目录以及前后端开发入口。及相关开发实践与注意事项。
- [项目介绍](/guide/introduction.md): 了解 XinAdmin 的 Laravel 与 React 技术栈、角色权限、动态菜单、系统模块、AI 助手和适用场景。
- [安装与启动](/guide/getting-started.md): 使用 Composer 和 pnpm 安装 XinAdmin，初始化 SQLite 或 MySQL 数据库，并启动 Laravel 与 React 开发环境。
- [目录结构](/guide/directory-structure.md): 梳理 XinAdmin 单仓库中的 Laravel 应用、React 前端、数据库迁移、系统模型和静态资源目录。
- [项目配置](/guide/configuration.md): 配置 XinAdmin 的应用地址、数据库、缓存、队列、邮件、存储、Redis 和前后端环境变量。及相关开发实践与注意事项。
- [核心概念](/guide/core-concepts.md): 理解 XinAdmin 中用户、部门、角色、权限规则、动态菜单、Token 和字典数据的核心关系。及相关开发实践与注意事项。
- [业务开发流程](/guide/development-workflow.md): 按数据库、模型、验证、注解接口、React 页面和权限菜单的顺序开发完整的 XinAdmin 业务功能。
- [测试与代码检查](/guide/testing.md): 使用 PHPUnit、内存 SQLite、TypeScript 和 Oxlint 检查 XinAdmin 后端业务与前端代码质量。
- [常见问题](/guide/faq.md): 排查 XinAdmin 安装、数据库迁移、前端接口、登录认证、动态菜单、权限和文件上传的常见问题。及相关开发实践与注意事项。

## 前端开发

- [前端概览](/frontend/index.md): 了解 XinAdmin 前端的 React、TypeScript、Zustand 与 Ant Design 结构，以及环境变量和 Axios 请求封装。
- [文件系统路由](/frontend/routing.md): 使用 XinAdmin 的 pages 目录生成 React Router 路由，理解懒加载、登录页、404 和动态菜单之间的关系。
- [新增业务页面](/frontend/new-page.md): 从页面组件、领域类型、API 函数、动态菜单和角色权限完整新增一个 XinAdmin 前端业务页面。
- [请求封装](/frontend/request.md): 深入使用 XinAdmin 的 Axios 请求去重、Bearer 认证、多语言请求头、业务错误和 401 处理机制。
- [状态管理](/frontend/state-management.md): 使用 XinAdmin 的 Zustand 用户、全局配置和字典 Store，理解持久化、初始化及认证状态同步。
- [XinTable 表格](/frontend/xin-table.md): 使用 XinTable 配置 CRUD 列表、搜索、分页、排序、表单、工具栏、操作权限和自定义请求。
- [XinForm 表单](/frontend/xin-form.md): 使用 XinForm 创建普通、弹窗和抽屉表单，配置字段、Grid、提交器、触发器及表单实例方法。及相关开发实践与注意事项。
- [字段与上传](/frontend/form-fields.md): 配置 XinAdmin 表单字段类型、依赖显隐、动态禁用、图片上传、图标选择和用户选择能力。及相关开发实践与注意事项。
- [权限组件](/frontend/auth-button.md): 使用 AuthButton 按用户权限标识控制 XinAdmin 操作入口，并与后端接口授权保持一致。
- [字典组件](/frontend/dict-tag.md): 使用 DictTag 按字典编码和值渲染文本、标签或徽标，并生成统一字典选项。及相关开发实践与注意事项。
- [布局与主题](/frontend/layout-theme.md): 配置 XinAdmin 的 side、top、mix、columns 布局及明暗主题、品牌色、尺寸和区域颜色。
- [国际化](/frontend/i18n.md): 维护 XinAdmin 前端中英文语言包、i18next 当前语言和后端 User-Language 请求头。
- [环境变量与构建](/frontend/environment.md): 管理 XinAdmin 前端 VITE_BASE_URL、开发环境、生产环境、TypeScript 检查和 Vite 构建预览命令。

## 后端开发

- [后端概览](/backend/index.md): 了解 XinAdmin 后端的 Laravel 分层、系统控制器、Eloquent 模型、Sanctum 认证、验证和数据库初始化方式。
- [注解路由与权限](/backend/routing.md): 使用 XinAdmin 的 PHP 属性声明 Laravel 接口路径、HTTP 方法、路由参数与权限标识，并配置控制器自动扫描。
- [接口响应约定](/backend/api-conventions.md): 遵循 XinAdmin 的统一 JSON 响应结构，理解 success、data、msg、showType、认证请求头和前端错误处理。
- [控制器与 CRUD](/backend/controllers.md): 使用 BaseController、Eloquent 和 Form Request 构建 XinAdmin 管理接口及标准增删改查流程。
- [列表查询](/backend/list-queries.md): 使用 BaseController 的筛选、快速搜索、日期范围、排序和分页参数构建 XinAdmin 列表接口。
- [模型与关联](/backend/models.md): 在 XinAdmin 中定义 Eloquent 模型、批量赋值、类型转换、关联关系和业务查询边界。及相关开发实践与注意事项。
- [表单验证](/backend/validation.md): 使用 Laravel Form Request 和 validate 验证 XinAdmin 接口参数、数组、路由 ID 与业务规则。
- [认证机制](/backend/authentication.md): 理解 XinAdmin 使用 Laravel Sanctum、SysAccessToken、SysUserModel 和 Bearer Token 的登录认证流程。
- [权限验证](/backend/authorization.md): 配置 XinAdmin 权限前缀、方法 authorize、角色规则和前端权限按钮，形成完整服务端授权链路。
- [中间件](/backend/middleware.md): 使用 XinAdmin 的跨域、语言和登录日志中间件，并理解 Laravel 全局注册与接口执行顺序。
- [服务与复用逻辑](/backend/services.md): 划分 XinAdmin 控制器、Services、Traits、Helpers 和模型职责，复用上传、响应与通用业务逻辑。
- [迁移与数据填充](/backend/database.md): 管理 XinAdmin 数据表迁移、系统初始数据、管理员、权限菜单、站点配置和 AI 助手 Seeder。
- [缓存、队列与 Redis](/backend/cache-queue.md): 配置 XinAdmin 的数据库缓存、同步或数据库队列、Redis 扩展及本地生产环境运行注意事项。
- [后端测试](/backend/testing.md): 为 XinAdmin 控制器、模型和权限接口编写 PHPUnit 单元与功能测试，并使用隔离的内存数据库。

## 系统功能

- [系统功能概览](/modules/index.md): 浏览 XinAdmin 仪表盘、管理员、组织权限、字典、文件、站点配置和个人中心等系统功能文档。及相关开发实践与注意事项。
- [仪表盘](/modules/dashboard.md): 了解 XinAdmin 分析、监控和工作台仪表盘页面，以及 ECharts 图表和静态监控资源的扩展方式。
- [管理员管理](/modules/users.md): 使用 XinAdmin 管理员列表、创建编辑、角色分配、状态、密码重置及关联用户权限能力。及相关开发实践与注意事项。
- [部门管理](/modules/departments.md): 使用 XinAdmin 部门树、部门创建编辑删除和部门成员查询，维护后台管理员组织结构。及相关开发实践与注意事项。
- [角色管理](/modules/roles.md): 使用 XinAdmin 角色列表、角色成员、状态、权限树查询和角色规则分配实现 RBAC 管理。及相关开发实践与注意事项。
- [权限与动态菜单](/modules/rules.md): 维护 XinAdmin 权限规则、动态菜单、页面路径、按钮权限、图标、排序、隐藏状态和外链。及相关开发实践与注意事项。
- [数据字典](/modules/dictionaries.md): 使用 XinAdmin 字典与字典项维护状态选项、标签、值、颜色，并在前端表格和表单中复用。及相关开发实践与注意事项。
- [文件管理](/modules/files.md): 使用 XinAdmin 文件上传、下载、分组、编辑和删除能力，并理解存储服务、公开资源与安全限制。及相关开发实践与注意事项。
- [站点配置](/modules/settings.md): 使用 XinAdmin 配置组和配置项维护站点标题、Logo、运行参数，并保存或刷新配置缓存。及相关开发实践与注意事项。
- [登录日志](/modules/login-records.md): 查看 XinAdmin 管理员登录日志和个人最近登录记录，理解中间件采集和审计扩展方式。及相关开发实践与注意事项。
- [个人中心](/modules/profile.md): 使用 XinAdmin 个人资料、头像、密码修改和登录记录接口维护当前管理员账号。及相关开发实践与注意事项。
- [AI 助手](/modules/ai-agents.md): 管理 XinAdmin AI 助手配置、默认助手数据和 Agent 接口，并理解助手与会话聊天的关系。
- [AI 会话与聊天](/modules/ai-chat.md): 使用 XinAdmin AI 会话、聊天和上下文管理页面，理解 Ant Design X、流式请求和异常处理。

## API 参考

- [API 使用说明](/api/index.md): 使用 XinAdmin API 的基础地址、Bearer 认证、多语言请求头、权限标识和统一 JSON 响应。
- [登录与当前用户](/api/auth.md): 调用 XinAdmin 登录、退出、用户信息、动态菜单、资料、密码、头像和最近登录记录接口。及相关开发实践与注意事项。
- [管理员接口](/api/users.md): 查询和维护 XinAdmin 管理员，调用创建、编辑、删除、密码重置以及角色部门选项接口。及相关开发实践与注意事项。
- [部门接口](/api/departments.md): 调用 XinAdmin 部门树、创建、编辑、批量删除和部门成员分页查询接口。及相关开发实践与注意事项。
- [角色接口](/api/roles.md): 调用 XinAdmin 角色增删改、成员、状态、权限树和角色规则分配接口。及相关开发实践与注意事项。
- [权限规则接口](/api/rules.md): 调用 XinAdmin 权限菜单树、规则创建编辑删除、父级选项、显示状态和启用状态接口。及相关开发实践与注意事项。
- [字典接口](/api/dictionaries.md): 调用 XinAdmin 字典和字典项的列表、创建、更新、删除及全部字典公开查询接口。及相关开发实践与注意事项。
- [文件接口](/api/files.md): 调用 XinAdmin 文件上传、下载、复制移动、重命名、回收站、恢复和强制删除及文件分组接口。及相关开发实践与注意事项。
- [系统配置接口](/api/settings.md): 调用 XinAdmin 配置组和配置项增删改查、批量保存站点设置及刷新配置缓存接口。及相关开发实践与注意事项。
- [AI 接口](/api/ai.md): 调用 XinAdmin AI 助手查询更新、聊天发送、会话列表、消息读取和会话删除接口。及相关开发实践与注意事项。
- [响应与错误](/api/responses.md): 处理 XinAdmin API 的 HTTP 状态、业务 success、data、msg、showType、验证错误和流式响应差异。

## 部署运维

- [部署概览](/deployment/index.md): 规划 XinAdmin 的 Laravel 与 React 生产部署、数据库、Web 服务器、队列、存储、安全和维护流程。
- [生产部署](/deployment/production.md): 按依赖、环境、数据库、Laravel 优化、React 产物和进程检查流程部署 XinAdmin 生产环境。
- [Nginx 与代理](/deployment/nginx.md): 配置 XinAdmin Laravel public 根目录、PHP-FPM、前端静态产物、浏览器路由回退和 API 反向代理。
- [数据库部署](/deployment/database.md): 为 XinAdmin 生产环境配置 MySQL 或 SQLite、迁移备份、最小权限账号和数据恢复验证。
- [队列与 Redis](/deployment/queue-redis.md): 在 XinAdmin 生产环境运行数据库或 Redis 队列、Worker、缓存和调度任务，并配置监控重启。
- [邮件与存储](/deployment/mail-storage.md): 配置 XinAdmin 生产邮件发件、队列投递、文件系统磁盘、上传限制、私有下载和存储备份。及相关开发实践与注意事项。
- [安全清单](/deployment/security.md): 检查 XinAdmin 上线前的默认密码、HTTPS、调试模式、密钥、权限、公开接口、上传和敏感日志风险。
- [更新与维护](/deployment/maintenance.md): 制定 XinAdmin 代码更新、数据库兼容、缓存刷新、Worker 重启、备份恢复和日志监控维护流程。

## 速查资料

- [参考资料概览](/reference/index.md): 快速查阅 XinAdmin 环境变量、开发命令、权限命名、响应类型、默认数据、技术版本和中英文术语。
- [环境变量速查](/reference/environment-variables.md): 速查 XinAdmin 后端 APP、DB、CACHE、QUEUE、REDIS、MAIL、FILESYSTEM 和前端 VITE 环境变量。
- [常用命令](/reference/commands.md): 速查 XinAdmin Composer 初始化、Laravel 服务、迁移测试以及 pnpm 前端开发检查和预览命令。
- [权限命名规范](/reference/permission-naming.md): 按资源与动作命名 XinAdmin 权限键，保持控制器、数据库规则、角色和前端按钮一致。及相关开发实践与注意事项。
- [响应类型速查](/reference/response-types.md): 速查 XinAdmin ShowType 的成功、警告、错误、通知和静默数值，以及统一响应字段。及相关开发实践与注意事项。
- [默认数据](/reference/default-data.md): 查阅 XinAdmin Seeder 默认管理员、示例用户、角色部门、权限菜单、站点配置和 AI 助手数据。
- [技术版本](/reference/versions.md): 查阅 XinAdmin 当前 PHP、Laravel、React、Ant Design、Vite、TypeScript、Zustand 和测试依赖版本。
- [术语表](/reference/glossary.md): 统一 XinAdmin 文档中的用户、角色、规则、菜单、权限、字典、配置、Token 和会话术语。及相关开发实践与注意事项。