# API接口速查表

**版本**: v1.0
**日期**: 2025-11-17
**后端地址**: `http://172.16.0.55:8073`

---

## 📌 认证接口

### 1. 统一登录接口

**端点**: `POST /auth/login`

**支持两种方式**:

#### OAuth登录

```typescript
POST /auth/login
Content-Type: application/json

{
  "userInfo": {
    "sub": "user123",          // 必填
    "username": "zhangsan",    // 可选
    "nickname": "张三",        // 可选
    "email": "...",            // 可选
    "phone_number": "...",     // 可选
    "ou_id": "dept001",        // 可选
    "ou_name": "技术部",       // 可选
    "is_leader": false         // 可选
  },
  "expiresIn": 3600,           // 必填
  "area": "梅州"               // 可选，仅首次创建时保存
}
```

#### 密码登录

```typescript
POST /auth/login
Content-Type: application/json

{
  "username": "000",    // 实际是sub字段
  "password": "admin06111"
}
```

**成功响应**:

```json
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user_info": {
      "user_id": "5",
      "username": "admin",
      "nick_name": "管理员",
      "email": null,
      "phone_number": null,
      "ou_id": "default",
      "ou_name": "未分配部门",
      "is_leader": true,
      "user_role": "admin",
      "sub": "000"
    }
  }
}
```

**失败响应**:

```json
{
  "success": false,
  "error": "用户名或密码错误"
}
```

---

## 📌 RBAC路由接口

### 2. 获取用户路由

**端点**: `GET /user/routes` 或 `GET /rbac/user/routes`

**请求头**:

```
Authorization: Bearer {JWT_TOKEN}
```

**响应**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "user_id": 6,
    "username": "001",
    "routes": [
      {
        "id": 1,
        "route_path": "/",
        "route_name": "Layout",
        "component": "layout/index",
        "route_title": "入口页",
        "icon": "el-icon-s-home",
        "sort_order": 1,
        "is_hidden": false,
        "is_cache": true,
        "children": [...]
      }
    ]
  }
}
```

### 3. 检查路由权限

**端点**: `GET /rbac/check-route`

**请求参数**:

```
route_path: /system/users
```

**请求头**:

```
Authorization: Bearer {JWT_TOKEN}
```

**响应**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "route_path": "/system/users",
    "has_access": true
  }
}
```

### 4. 清除路由缓存

**端点**: `POST /rbac/clear-routes-cache`

**请求头**:

```
Authorization: Bearer {JWT_TOKEN}
```

**响应**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "message": "路由缓存已清除"
  }
}
```

---

## 📌 PostgREST数据接口

### 通用规则

**所有数据表访问格式**:

```
GET    /{table_name}              # 查询
POST   /{table_name}              # 创建
PATCH  /{table_name}?{filter}     # 更新
DELETE /{table_name}?{filter}     # 删除
```

**请求头**:

```
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
```

### PostgREST过滤操作符

| 操作符 | 说明 | 示例 |
|-------|------|------|
| `eq` | 等于 | `id=eq.5` |
| `neq` | 不等于 | `status=neq.1` |
| `gt` | 大于 | `id=gt.10` |
| `gte` | 大于等于 | `id=gte.10` |
| `lt` | 小于 | `id=lt.100` |
| `lte` | 小于等于 | `id=lte.100` |
| `like` | 模糊匹配 | `title=like.*合同*` |
| `ilike` | 不区分大小写模糊匹配 | `title=ilike.*word*` |
| `in` | 在列表中 | `id=in.(1,2,3)` |
| `is` | 是NULL | `deleted_at=is.null` |
| `not.is` | 不是NULL | `deleted_at=not.is.null` |

### 查询参数

| 参数 | 说明 | 示例 |
|-----|------|------|
| `select` | 选择字段 | `select=id,title,created_at` |
| `order` | 排序 | `order=created_at.desc` |
| `limit` | 限制数量 | `limit=20` |
| `offset` | 偏移量 | `offset=40` |

---

## 📌 常用数据表

### documents（文档表）

**查询文档列表**:

```typescript
GET /documents?user_id=eq.5&status=eq.0&select=id,title,created_at&order=created_at.desc&limit=20&offset=0
```

**创建文档**:

```typescript
POST /documents
Content-Type: application/json

{
  "title": "测试文档",
  "user_id": 5,
  "status": 0
}
```

**更新文档**:

```typescript
PATCH /documents?id=eq.123
Content-Type: application/json

{
  "title": "新标题",
  "status": 1
}
```

**删除文档**:

```typescript
DELETE /documents?id=eq.123
```

### sso_users（用户表）

**查询用户**:

```typescript
GET /sso_users?sub=eq.000&select=id,username,nick_name,email
```

**注意**: 普通用户无法直接访问 `sso_users` 表，需要通过特殊接口。

### roles（角色表）

**查询所有角色**:

```typescript
GET /roles?is_system_role=eq.true&select=id,role_key,role_name,priority&order=priority.desc
```

### user_role（用户-角色关联表）

**查询用户角色**:

```typescript
GET /user_role?user_id=eq.5&select=role_id
```

### sys_routes（路由表）

**查询所有路由**:

```typescript
GET /sys_routes?status=eq.0&deleted_at=is.null&select=id,route_path,route_title&order=sort_order
```

### role_route（角色-路由关联表）

**查询角色路由**:

```typescript
GET /role_route?role_id=eq.1&select=route_id
```

---

## 📌 完整示例

### 登录 + 获取路由 + 查询数据

```typescript
import axios from 'axios';

const API_BASE = 'http://172.16.0.55:8073';

// 1. 登录
const login = async () => {
  const response = await axios.post(`${API_BASE}/auth/login`, {
    username: '001',
    password: 'gdyc06111'
  });

  const { access_token, user_info } = response.data.data;
  localStorage.setItem('token', access_token);

  return { token: access_token, userInfo: user_info };
};

// 2. 获取路由
const fetchRoutes = async (token: string) => {
  const response = await axios.get(`${API_BASE}/user/routes`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  return response.data.data.routes;
};

// 3. 查询文档（普通用户）
const fetchDocuments = async (token: string, userId: string) => {
  const response = await axios.get(`${API_BASE}/documents`, {
    params: {
      user_id: `eq.${userId}`,  // 只查自己的数据
      status: `eq.0`,
      select: 'id,title,created_at',
      order: 'created_at.desc',
      limit: 20,
      offset: 0
    },
    headers: { 'Authorization': `Bearer ${token}` }
  });

  return response.data;
};

// 4. 创建文档
const createDocument = async (token: string, userId: string) => {
  const response = await axios.post(`${API_BASE}/documents`, {
    title: '测试文档',
    user_id: parseInt(userId),
    status: 0
  }, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });

  return response.data;
};

// 使用示例
const main = async () => {
  // 登录
  const { token, userInfo } = await login();
  console.log('登录成功:', userInfo);

  // 获取路由
  const routes = await fetchRoutes(token);
  console.log('用户路由:', routes);

  // 查询文档
  const docs = await fetchDocuments(token, userInfo.user_id);
  console.log('文档列表:', docs);

  // 创建文档
  const newDoc = await createDocument(token, userInfo.user_id);
  console.log('新建文档:', newDoc);
};

main();
```

---

## 📌 错误码对照表

| HTTP状态码 | 说明 | 处理方式 |
|-----------|------|---------|
| 200 | 成功 | 正常处理 |
| 400 | 请求参数错误 | 检查请求参数 |
| 401 | 未授权/Token过期 | 重新登录 |
| 403 | 无权限访问 | 提示用户无权限 |
| 404 | 资源不存在 | 检查路径是否正确 |
| 500 | 服务器错误 | 联系后端开发人员 |

---

## 📌 测试账号

| 用户名 | 密码 | 角色 | 路由数 | 说明 |
|--------|------|------|-------|------|
| 000 | admin06111 | 超级管理员 | 29 | 所有权限 |
| 001 | gdyc06111 | 普通用户 | 19 | 有限权限 |
| jy001 | jyyc0814 | 系统管理员 | 29 | 管理员权限 |
| mz001 | mzyc06111 | 系统管理员 | 29 | 管理员权限 |
| yf001 | yfyc06111 | 系统管理员 | 29 | 管理员权限 |
| cz001 | czyc06111 | 系统管理员 | 29 | 管理员权限 |

---

## 📌 快速链接

- **完整对接文档**: `docs/RBAC/前端完整对接文档_RBAC与PostgREST.md`
- **快速开始**: `docs/RBAC/前端快速开始_5分钟集成.md`
- **用户管理**: `docs/RBAC/用户管理完整指南.md`
- **RBAC总结**: `docs/RBAC/RBAC系统使用总结.md`

---

**创建时间**: 2025-11-17
**维护者**: Claude Code