feat():learning后台管理项目初始化

internal/api/README.md

@@ -0,0 +1,179 @@
+# API 层
+
+本模块负责HTTP API的实现，提供RESTful接口。
+
+## 功能特性
+
+- RESTful API设计
+- JWT认证中间件
+- 跨域支持
+- 请求日志记录
+- 统一错误处理
+- 参数验证
+
+## 模块结构
+
+```
+api/
+├── middlewares/     # 中间件
+│   ├── auth.go      # 认证中间件
+│   ├── cors.go      # 跨域中间件
+│   └── logging.go   # 日志中间件
+├── handlers/        # 请求处理器
+│   ├── auth_handler.go    # 认证处理器
+│   ├── user_handler.go    # 用户处理器
+│   ├── role_handler.go    # 角色处理器
+│   └── menu_handler.go    # 菜单处理器
+├── routes/          # 路由配置
+│   └── routes.go    # 路由设置
+└── README.md        # 说明文档
+```
+
+## API 接口
+
+### 认证接口
+
+```
+POST /api/auth/login          # 用户登录
+POST /api/auth/logout         # 用户登出
+GET  /api/profile            # 获取用户信息
+PUT  /api/profile            # 更新用户信息
+PUT  /api/change-password    # 修改密码
+```
+
+### 用户管理接口（管理员）
+
+```
+POST   /api/admin/users           # 创建用户
+GET    /api/admin/users           # 获取用户列表
+GET    /api/admin/users/:id       # 获取用户详情
+PUT    /api/admin/users/:id       # 更新用户
+DELETE /api/admin/users/:id       # 删除用户
+PUT    /api/admin/users/:id/status # 更新用户状态
+```
+
+### 角色管理接口（管理员）
+
+```
+POST   /api/admin/roles           # 创建角色
+GET    /api/admin/roles           # 获取角色列表
+GET    /api/admin/roles/:id       # 获取角色详情
+PUT    /api/admin/roles/:id       # 更新角色
+DELETE /api/admin/roles/:id       # 删除角色
+PUT    /api/admin/roles/:id/status # 更新角色状态
+```
+
+### 菜单管理接口（管理员）
+
+```
+POST   /api/admin/menus           # 创建菜单
+GET    /api/admin/menus           # 获取菜单列表
+GET    /api/admin/menus/tree      # 获取菜单树
+GET    /api/admin/menus/:id       # 获取菜单详情
+PUT    /api/admin/menus/:id       # 更新菜单
+DELETE /api/admin/menus/:id       # 删除菜单
+PUT    /api/admin/menus/:id/status # 更新菜单状态
+PUT    /api/admin/menus/:id/sort  # 更新菜单排序
+```
+
+## 请求示例
+
+### 用户登录
+
+```bash
+curl -X POST http://localhost:8080/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "admin",
+    "password": "password"
+  }'
+```
+
+### 获取用户列表
+
+```bash
+curl -X GET "http://localhost:8080/api/admin/users?page=1&size=10&username=admin" \
+  -H "Authorization: Bearer your-jwt-token"
+```
+
+### 创建用户
+
+```bash
+curl -X POST http://localhost:8080/api/admin/users \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-jwt-token" \
+  -d '{
+    "username": "newuser",
+    "email": "newuser@example.com",
+    "password": "password",
+    "nickname": "新用户",
+    "role": "user"
+  }'
+```
+
+## 响应格式
+
+### 成功响应
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "id": 1,
+    "username": "admin",
+    "email": "admin@example.com"
+  }
+}
+```
+
+### 分页响应
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": [...],
+  "total": 100,
+  "page": 1,
+  "size": 10
+}
+```
+
+### 错误响应
+
+```json
+{
+  "code": 400,
+  "message": "参数错误"
+}
+```
+
+## 中间件
+
+### 认证中间件
+
+验证JWT token，将用户信息存储到上下文中。
+
+### 管理员中间件
+
+验证用户是否具有管理员权限。
+
+### 跨域中间件
+
+处理跨域请求，支持预检请求。
+
+### 日志中间件
+
+记录HTTP请求日志，包括请求方法、路径、状态码、响应时间等。
+
+## 错误处理
+
+所有API都遵循统一的错误处理模式：
+
+- 参数验证错误：400 Bad Request
+- 认证失败：401 Unauthorized
+- 权限不足：403 Forbidden
+- 资源不存在：404 Not Found
+- 服务器错误：500 Internal Server Error
+