diff --git a/README.md b/README.md index 0165a773cef027e7dc2f314808d57e28b22e3813..f67bee5d624803dc114b0a30fea1a88d3faf8aa9 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,191 @@ -

Laravel Logo

-

-Build Status -Total Downloads -Latest Stable Version -License -

-## About Laravel +# Sanmo API + +三国联机游戏后端 API 服务 + +## 项目简介 + +Sanmo API 是一个基于 Laravel 框架构建的 RESTful API 后端服务，专为联机游戏提供数据接口支持。 + +## 技术栈 + +- **框架**: Laravel 12 +- **PHP**: 8.2+ +- **数据库**: MySQL +- **认证**: Laravel Sanctum (Token 认证) + +## 功能特性 + +### 认证系统 +- 管理员登录/登出/密码修改 +- 用户登录 +- Token 授权验证 + +### 内容管理 +- 文章 CRUD 操作 (后台管理) +- 文件上传支持 + +### API 设计 +- 统一的响应格式封装 +- 自定义异常处理 +- 规范化路径处理 + +## 项目结构 + +``` +app/ +├── Common/ # 公共函数库 +│ └── helpers.php # API 响应辅助函数 +├── Enums/ # 枚举定义 +│ └── ApiCode.php # API 错误码 +├── Exceptions/ # 异常处理 +│ └── ApiException.php # API 异常类 +├── Http/Controllers/ # 控制器 +│ ├── Admin/ # 后台管理控制器 +│ │ ├── ArticleController.php +│ │ └── AuthController.php +│ ├── Home/ # 前台用户控制器 +│ │ └── AuthController.php +│ └── UploadController.php +├── Models/ # 数据模型 +│ ├── Admin.php +│ ├── Article.php +│ └── User.php +└── Boost/Agents/ # AI Agent 配置 + └── Trae.php + +routes/ +├── admin.php # 后台路由 +├── api.php # API 路由 +└── web.php # Web 路由 +``` + +## 快速开始 + +### 环境要求 + +- PHP 8.2+ +- Composer +- MySQL 5.7+ +- Node.js (可选，用于前端资源) + +### 安装步骤 + +1. 克隆项目 +```bash +git clone https://gitee.com/sanmokeji/sanmo-api.git +cd sanmo-api +``` + +2. 安装依赖 +```bash +composer install +``` + +3. 配置环境 +```bash +cp .env.example .env +``` + +4. 生成应用密钥 +```bash +php artisan key:generate +``` + +5. 配置数据库连接 + +编辑 `.env` 文件中的数据库配置： +``` +DB_CONNECTION=mysql +DB_HOST=127.0.0.1 +DB_PORT=3306 +DB_DATABASE=sanmo_api +DB_USERNAME=your_username +DB_PASSWORD=your_password +``` + +6. 执行数据库迁移 +```bash +php artisan migrate +``` + +7. 启动服务 +```bash +php artisan serve +``` + +## API 使用指南 + +### 响应格式 + +成功响应： +```json +{ + "data": {}, + "message": "success", + "status": 200 +} +``` + +错误响应： +```json +{ + "message": "错误信息", + "status": 400 +} +``` + +### 主要接口 + +#### 认证接口 + +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | /api/admin/login | 管理员登录 | +| POST | /api/admin/logout | 管理员登出 | +| GET | /api/admin/me | 获取当前管理员信息 | +| POST | /api/admin/password | 修改密码 | +| POST | /api/home/login | 用户登录 | + +#### 内容管理 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | /api/admin/articles | 文章列表 | +| POST | /api/admin/articles | 创建文章 | +| GET | /api/admin/articles/{id} | 文章详情 | +| PUT | /api/admin/articles/{id} | 更新文章 | +| DELETE | /api/admin/articles/{id} | 删除文章 | + +#### 文件上传 -Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as: - -- [Simple, fast routing engine](https://laravel.com/docs/routing). -- [Powerful dependency injection container](https://laravel.com/docs/container). -- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage. -- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent). -- Database agnostic [schema migrations](https://laravel.com/docs/migrations). -- [Robust background job processing](https://laravel.com/docs/queues). -- [Real-time event broadcasting](https://laravel.com/docs/broadcasting). - -Laravel is accessible, powerful, and provides tools required for large, robust applications. - -## Learning Laravel - -Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out [Laravel Learn](https://laravel.com/learn), where you will be guided through building a modern Laravel application. - -If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library. - -## Laravel Sponsors - -We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com). - -### Premium Partners - -- **[Vehikl](https://vehikl.com)** -- **[Tighten Co.](https://tighten.co)** -- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)** -- **[64 Robots](https://64robots.com)** -- **[Curotec](https://www.curotec.com/services/technologies/laravel)** -- **[DevSquad](https://devsquad.com/hire-laravel-developers)** -- **[Redberry](https://redberry.international/laravel-development)** -- **[Active Logic](https://activelogic.com)** - -## Contributing - -Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions). - -## Code of Conduct - -In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct). - -## Security Vulnerabilities - -If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed. - -## License - -The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | /api/upload | 文件上传 | + +## 测试 + +```bash +# 运行测试 +php artisan test + +# 或使用 Pest +./vendor/bin/pest +``` + +## 开发规范 + +- 遵循 Laravel 框架约定 +- 使用 Pest 进行单元测试 +- 代码风格遵循 Laravel Pint 规范 + +## 许可证 + +MIT License + +## 相关链接 + +- [Laravel 文档](https://laravel.com/docs) +- [Laravel 中文文档](https://learnku.com/laravel) +- [Gitee 仓库](https://gitee.com/sanmokeji/sanmo-api) \ No newline at end of file