coder-common-thin-backend/api/README.md

# Coder Common Thin Backend API 文档

## 项目概述

Coder Common Thin Backend 是一个基于Spring Boot 3.5.0的企业级开发框架，采用插件化架构设计，提供了完整的后台管理系统功能。

## 技术栈

- **后端框架**: Spring Boot 3.5.0 + Java 17
- **数据库**: MySQL 8 + MyBatis Plus 3.5.12
- **缓存**: Redis (Spring Data Redis)
- **安全认证**: Sa-Token 1.43.0
- **权限控制**: RBAC (Role-Based Access Control)
- **API文档**: OpenAPI 3.0 (Swagger)
- **工具库**: Hutool 5.8.38, Fastjson2 2.0.57, Guava 33.4.8

## 服务器信息

- **默认端口**: 18099
- **基础URL**: http://localhost:18099
- **API前缀**: /coder (除登录认证接口外)

## 认证方式

系统使用Sa-Token进行身份认证和权限管理：
- **Token类型**: Bearer Token
- **Token位置**: 请求头 `Authorization` 字段
- **Token过期**: 支持自定义过期时间
- **权限验证**: 基于注解的权限验证

## 统一响应格式

所有接口均采用统一的JSON响应格式：

```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    // 具体数据
  },
  "traceId": "trace-id-value"
}
```

### 状态码说明

- **200**: 成功
- **400**: 请求参数错误
- **401**: 认证失败/未登录
- **403**: 权限不足
- **500**: 服务器内部错误

## 分页查询格式

分页查询请求参数：
```json
{
  "pageNo": 1,
  "pageSize": 10,
  "params": {
    // 查询参数
  }
}
```

分页查询响应格式：
```json
{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "records": [
      // 数据记录
    ],
    "total": 100,
    "size": 10,
    "current": 1,
    "pages": 10,
    "searchCount": true
  },
  "traceId": "trace-id-value"
}
```

## 权限系统

系统采用RBAC权限模型：
- **用户 (User)**: 系统使用者
- **角色 (Role)**: 权限的集合
- **权限 (Permission)**: 具体的操作权限
- **菜单 (Menu)**: 系统菜单和按钮权限

### 权限验证流程

1. 用户登录获取Token
2. 请求接口时携带Token
3. 系统验证Token有效性
4. 根据用户角色验证权限
5. 允许或拒绝访问

## API模块分类

### 1. 认证模块 (Authentication)
- [登录认证API](./authentication/登录认证API)
- [验证码API](./authentication/验证码API)

### 2. 用户管理模块 (User Management)
- [用户管理API](./user/用户管理API)

### 3. 权限管理模块 (Permission Management)
- [菜单管理API](./permission/菜单管理API)
- [角色管理API](./permission/角色管理API)

### 4. 系统管理模块 (System Management)
- [文件管理API](./system/文件管理API)
- [图片管理API](./system/图片管理API)
- [登录日志API](./system/登录日志API)

## 错误处理

系统提供了完善的错误处理机制：

### 常见错误类型

1. **业务异常**: 自定义业务逻辑错误
2. **认证异常**: 登录认证相关错误
3. **权限异常**: 权限验证失败
4. **参数异常**: 请求参数验证失败
5. **系统异常**: 服务器内部错误

### 错误响应格式

```json
{
  "status": 400,
  "msg": "具体错误信息",
  "data": null,
  "traceId": "trace-id-value"
}
```

## 开发环境配置

### 数据库配置
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/coder_common_thin
    username: root
    password: your_password
```

### Redis配置
```yaml
spring:
  redis:
    host: localhost
    port: 6379
    password: your_password
```

### Sa-Token配置
```yaml
sa-token:
  token-name: Authorization
  timeout: 2592000
  activity-timeout: -1
  is-concurrent: true
  is-share: false
  is-read-head: true
  is-read-cookie: false
```

## 接口调用示例

### 登录接口调用
```bash
curl -X POST \
  http://localhost:18099/auth/login \
  -H 'Content-Type: application/json' \
  -d '{
    "loginName": "admin",
    "password": "123456",
    "codeKey": "uuid-key",
    "securityCode": "1234"
  }'
```

### 携带Token调用接口
```bash
curl -X GET \
  http://localhost:18099/coder/sysLoginUser/getLoginUserInformation \
  -H 'Authorization: Bearer your-token-value'
```

## 注意事项

1. 所有接口都需要进行认证，除了登录接口和验证码接口
2. 权限验证基于角色和权限码进行
3. 系统支持多设备登录
4. 敏感操作会记录操作日志
5. 建议在生产环境中启用HTTPS

## 更新日志

- **v1.0.0** (2025-07-05): 初始版本发布

## 联系方式

如有问题，请联系开发团队。