# API 文档基础规范

## 📋 文档说明

本文档记录项目 API 接口的通用规范和标准，包括请求方式、参数说明、响应格式等。所有 API 接口必须遵循此基础规范。

### 🔧 基础信息

-   **基础路径**: `/api`
-   **响应格式**: JSON
-   **字符编码**: UTF-8
-   **权限认证**: Sa-Token + JWT
-   **版本**: v1.0

---

## 🌐 API 文档访问方式

### 🌟 Swagger UI 在线文档（推荐）

**访问地址**: [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) ⭐

**功能特点**:

-   🎨 可视化界面，易于浏览和理解
-   🧪 支持在线测试，无需其他工具
-   📊 按业务模块自动分组展示
-   🔍 支持接口搜索和筛选
-   📋 自动生成请求示例和响应格式

**使用场景**:

-   ✅ 接口调试和测试
-   ✅ 快速查看接口列表
-   ✅ 了解请求参数和响应格式
-   ✅ 验证接口功能

### 📁 项目内置文档（详细参考）

**位置**: `docs/开发文档/API/`

**特点**:

-   📝 中文详细说明和业务逻辑解释
-   💡 完整的使用示例和最佳实践
-   🔗 模块间交叉引用和关联说明
-   📊 业务流程图和数据字典

**使用场景**:

-   ✅ 深入了解业务逻辑
-   ✅ 开发时参考规范
-   ✅ 新人学习和培训

---

## 🔐 请求头规范（强制性）

**所有需要认证的接口必须在请求头中包含 Token，格式如下：**

```json
{
    "Content-Type": "application/json;charset=utf-8",
    "Authorization": "Bearer {access_token}",
    "clientid": "e5cd7e4891bf95d1d19206ce24a7b32e",
    "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
    "referer": "http://localhost/login?redirect=%252Findex"
}
```

### 📋 请求头字段说明

| 字段名          | 必填 | 说明                             | 示例值                                           |
| --------------- | ---- | -------------------------------- | ------------------------------------------------ |
| Authorization   | 是   | Bearer + Token 值（⚠️ 注意空格） | "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." |
| clientid        | 是   | 客户端 ID，用于权限验证          | "e5cd7e4891bf95d1d19206ce24a7b32e"               |
| Content-Type    | 是   | 请求内容类型                     | "application/json;charset=utf-8"                 |
| Accept-Language | 是   | 语言设置，用于国际化             | "zh-CN,zh;q=0.9,en;q=0.8"                        |
| referer         | 是   | 来源页面，用于安全验证           | "http://localhost/login?redirect=%252Findex"     |

### ⚠️ Token 格式强制要求

-   ✅ **正确**: `"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."`
-   ❌ **错误**: `"Authorization": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."` （缺少 Bearer 前缀）
-   ❌ **错误**: `"Authorization": "Bearer eyJ0eXAi..."` （Bearer 后面没有空格）

---

## 🔴 统一响应格式（强制性）

**⚠️ 所有 API 接口必须严格遵循以下统一响应格式！**

### 📊 分页列表响应格式

```json
{
    "total": 100,
    "rows": [
        {
            "id": 1,
            "name": "示例数据1",
            "createTime": "2025-06-30 12:00:00"
        },
        {
            "id": 2,
            "name": "示例数据2",
            "createTime": "2025-06-30 12:01:00"
        }
    ],
    "code": 200,
    "msg": "查询成功"
}
```

### 🎯 非分页列表响应格式

```json
{
    "code": 200,
    "msg": "查询成功",
    "data": [
        {
            "id": 1,
            "name": "示例数据1"
        },
        {
            "id": 2,
            "name": "示例数据2"
        }
    ]
}
```

### 🎯 单条数据响应格式

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "name": "示例数据",
        "createTime": "2025-06-30 12:00:00"
    }
}
```

### 🎯 操作成功响应格式（无数据）

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": null
}
```

### ❌ 错误响应格式

```json
{
    "code": 400,
    "msg": "参数错误：用户名不能为空",
    "data": null
}
```

---

## 📋 状态码规范

### ✅ 成功状态码

-   `200` - 操作成功
-   `201` - 创建成功

### 🚫 客户端错误（4xx）

-   `400` - 请求参数错误
-   `401` - 未认证/认证失败
-   `403` - 无权限访问
-   `404` - 资源不存在
-   `409` - 数据冲突

### 💥 服务端错误（5xx）

-   `500` - 服务器内部错误
-   `502` - 网关错误
-   `503` - 服务不可用

---

## 🚨 开发强制要求

1. **请求头必须包含 Bearer Token 格式的 Authorization**
2. **分页接口必须直接返回 TableDataInfo 格式（total、rows、code、msg）**
3. **非分页接口必须使用 R 类型包装返回结果**
4. **单条数据接口必须使用 R 类型包装返回结果**
5. **操作类接口必须使用 R 类型包装返回结果**
6. **必须包含 clientid、Content-Type 等必要请求头**

---

## 📝 业务错误码

### 通用错误码

| 错误码 | 说明         | 解决方案                   |
| ------ | ------------ | -------------------------- |
| 40001  | 参数校验失败 | 检查请求参数格式和必填字段 |
| 40002  | 数据不存在   | 检查资源 ID 是否正确       |
| 40003  | 权限不足     | 联系管理员分配权限         |
| 40004  | 操作失败     | 重试或联系技术支持         |
| 40005  | 数据冲突     | 检查数据是否重复           |

### 认证相关错误码

| 错误码 | 说明           | 解决方案              |
| ------ | -------------- | --------------------- |
| 40101  | Token 无效     | 重新登录获取 Token    |
| 40102  | Token 已过期   | 刷新 Token 或重新登录 |
| 40103  | 用户未登录     | 请先登录              |
| 40104  | 客户端 ID 异常 | 检查 clientId 配置    |

### 业务模块错误码

| 错误码 | 说明               | 解决方案                |
| ------ | ------------------ | ----------------------- |
| 41001  | 物业报修相关错误   | 参考物业报修 API 文档   |
| 41002  | 满意度调查相关错误 | 参考满意度调查 API 文档 |

---

## 📚 数据字典

### 🎯 通用状态

| 值  | 说明 | 备注       |
| --- | ---- | ---------- |
| 0   | 停用 | 不可用状态 |
| 1   | 正常 | 可用状态   |

### 🎯 是否标识

| 值  | 说明 | 备注  |
| --- | ---- | ----- |
| 0   | 否   | false |
| 1   | 是   | true  |

### 🎯 删除标识

| 值  | 说明 | 备注   |
| --- | ---- | ------ |
| 0   | 正常 | 未删除 |
| 1   | 删除 | 已删除 |

### 🎯 用户类型

| 值  | 说明       | 角色映射                                                  |
| --- | ---------- | --------------------------------------------------------- |
| 1   | 学生       | student、学生、stu 等角色映射为此值                       |
| 2   | 教师       | teacher、老师、教师、教职工、tea 等角色映射为此值         |
| 3   | 超级管理员 | admin、管理员、超级管理员、administrator 等角色映射为此值 |

---

## ⚙️ 开发配置说明

### 🔧 接口测试工具

推荐使用以下工具进行接口测试：

-   **Postman**: 图形化接口测试工具
-   **Apifox**: 国产 API 管理工具
-   **curl**: 命令行工具

### 🔧 时间格式规范

所有时间字段统一使用以下格式：

-   **数据库存储**: `YYYY-MM-DD HH:mm:ss`
-   **API 传输**: `ISO 8601`格式 `YYYY-MM-DDTHH:mm:ss.sssZ`

### 🔧 分页参数规范

所有分页接口统一使用以下参数：

-   `pageNum`: 页码，从 1 开始
-   `pageSize`: 页大小，默认 10

### 🔧 安全传输规范

1. **密码安全**:

    - BCrypt 哈希加密存储
    - 登录失败次数限制
    - 账户自动锁定机制

2. **传输安全**:

    - AES+RSA 混合加密
    - 防重放攻击保护
    - HTTPS 协议传输

3. **会话安全**:

    - JWT Token 认证
    - Token 自动过期机制
    - 刷新 Token 机制

4. **多租户安全**:
    - 租户隔离验证
    - 客户端权限控制
    - 不同设备类型支持

---

## 📞 联系方式

如有 API 相关问题，请联系开发团队或查看项目仓库的 Issues。

---

**📝 维护**: API 基础规范文档  
**🔄 更新**: 2025-07-01  
**�� 文件**: API 文档基础规范.md

## UI 规范

### 主题色系统

-   Web 端主题色: rgb(50, 20, 255)
-   变量定义: --art-primary
-   更新时间: 2025-07-05

### Element Plus 主题定制

```css
// Element Plus 主题色变量
--el-color-primary: rgb(var(--art-primary));
```

### 按钮样式规范

-   主要按钮: 使用主题色
-   次要按钮: 使用轮廓式设计
-   危险按钮: 使用错误色
-   禁用状态: 降低透明度