# API 接口设计

---
DDS-Section: 10. 接口设计 (API)
DDS-Lines: L781-L833
---

## 认证接口 (公共)

| 方法 | 路径 | 说明 | 鉴权 |
|:---|:---|:---|:---|
| GET | `/api/auth/rsa/public-key` | 获取 RSA 公钥 | 公共 |
| POST | `/api/auth/login` | RSA 加密密码登录 | 公共 |
| POST | `/api/auth/register` | 自助注册 | 公共 |

### POST /api/auth/login

**Request:**
```json
{
  "username": "string",
  "encrypted_password": "string"
}
```

**Response:**
```json
{
  "token": "string",
  "user": {
    "id": 0,
    "username": "string",
    "role": "string",
    "status": "string"
  },
  "must_change_password": false,
  "password_expire_days": 0,
  "account_expire_days": 0
}
```

---

## 用户管理接口

| 方法 | 路径 | 说明 | 鉴权 |
|:---|:---|:---|:---|
| GET | `/api/users` | 用户列表（分页/筛选） | JWT |
| GET | `/api/users/:id` | 用户详情 | JWT |
| POST | `/api/users` | 创建用户（自动创建注册工单） | JWT + Admin |
| PUT | `/api/users/:id` | 更新用户（草稿/需工单） | JWT + Admin |
| DELETE | `/api/users/:id` | 删除用户 | JWT + SuperAdmin |
| PUT | `/api/user/profile` | 更新本人资料 | JWT |
| PUT | `/api/user/password` | 本人改密 | JWT |
| PUT | `/api/user/password/force-change` | 首次登录强制改密 | JWT |

### GET /api/users 查询参数

| 参数 | 类型 | 说明 |
|:---|:---|:---|
| `page` | int | 页码 |
| `size` | int | 每页数量 |
| `role` | string | 角色筛选 |
| `status` | string | 状态筛选 |
| `group` | string | 小组筛选 |
| `search` | string | 关键词搜索 |
| `scope` | string | 范围：`all`/`created_by_me` |

---

## Jenkins 权限接口

| 方法 | 路径 | 说明 | 鉴权 |
|:---|:---|:---|:---|
| GET | `/api/permissions/jenkins/my-tree/organizations` | 我的组织列表 | JWT |
| POST | `/api/permissions/jenkins/my-tree/repositories` | 我的仓库 | JWT |
| POST | `/api/permissions/jenkins/my-tree/branches` | 我的分支 | JWT |
| GET | `/api/permissions/jenkins/my-tree/full` | 我的完整权限树 | JWT |
| GET | `/api/permissions/jenkins/check/:organization/:branch` | 检查分支权限 | JWT |
| GET | `/api/permissions/jenkins/tree` | 全量权限树 | JWT + Admin |
| GET | `/api/permissions/jenkins/users/role/:role` | 按角色查用户 | JWT + Admin |
| GET | `/api/permissions/jenkins/:userId` | 获取用户权限 | JWT + Admin |
| POST | `/api/permissions/jenkins/assign` | 分配权限 | JWT + Admin |
| POST | `/api/permissions/jenkins/copy` | 拷贝权限 | JWT + Admin |
| GET | `/api/permissions/jenkins/user-tree/:userId/organizations` | 懒加载组织 | JWT + Admin |
| GET | `/api/permissions/jenkins/user-tree/:userId/organizations/:org/repositories` | 懒加载仓库 | JWT + Admin |
| GET | `/api/permissions/jenkins/user-tree/:userId/organizations/:org/repositories/:repo/branches` | 懒加载分支 | JWT + Admin |

---

## 项目权限接口

| 方法 | 路径 | 说明 | 鉴权 |
|:---|:---|:---|:---|
| GET | `/api/permissions/projects/user/:userId/summary` | 用户项目权限摘要 | JWT + Admin |
| POST | `/api/permissions/projects/grant` | 授予项目模块权限 | JWT + Admin |
| POST | `/api/permissions/projects/revoke` | 撤销项目模块权限 | JWT + Admin |

---

## 系统配置接口

| 方法 | 路径 | 说明 | 鉴权 |
|:---|:---|:---|:---|
| GET | `/api/user/system-config` | 获取配置 | JWT |
| PUT | `/api/user/system-config` | 更新配置 | JWT |

---

## 重要约束

⚠️ **前端不允许直接调用创建工单接口**

用户注册/管理工单通过用户管理接口内部自动创建：
- `POST /api/users` → 自动创建 user_registration 工单
- `PUT /api/users/:id` → 自动创建 user_management 工单（正式修改时）
