# API 端点清单

## 项目管理

| 方法 | 路径 | 描述 | 权限 |
|:---|:---|:---|:---|
| POST | `/api/project/list` | 获取项目列表 (自动过滤ACL) | Login |
| POST | `/api/project/detail` | 获取项目详情 (Master版本) | View ACL |
| POST | `/api/project/create` | 创建项目 | SuperAdmin |
| POST | `/api/project/update` | 直接更新项目 | SuperAdmin |
| POST | `/api/project/delete` | 删除项目 (软删除) | SuperAdmin |
| POST | `/api/project/export` | 导出项目信息 | Export ACL |

## 版本管理

| 方法 | 路径 | 描述 | 权限 |
|:---|:---|:---|:---|
| POST | `/api/project/version/list` | 获取版本历史列表 | View ACL |
| POST | `/api/project/version/detail` | 获取指定版本详情 | View ACL |
| POST | `/api/project/version/diff` | 获取版本差异 | View ACL |
| POST | `/api/project/version/diff-with-current` | 对比指定版本与当前版本差异 | View ACL |

## 草稿管理

| 方法 | 路径 | 描述 | 权限 |
|:---|:---|:---|:---|
| POST | `/api/project/draft/get` | 获取当前用户的草稿 | View ACL |
| POST | `/api/project/draft/save` | 保存草稿 | View ACL |
| POST | `/api/project/draft/submit` | 提交审核 | View ACL |
| POST | `/api/project/draft/discard` | 放弃草稿 | View ACL |

## 权限管理 (SuperAdmin)

| 方法 | 路径 | 描述 | 权限 |
|:---|:---|:---|:---|
| POST | `/api/project/permission/list` | 获取项目权限列表 | SuperAdmin |
| POST | `/api/project/permission/grant` | 授予权限 | SuperAdmin |
| POST | `/api/project/permission/revoke` | 撤销权限 | SuperAdmin |
| POST | `/api/project/permission/batch` | 批量设置权限 | SuperAdmin |

## 授权管理 (SuperAdmin)

| 方法 | 路径 | 描述 | 权限 |
|:---|:---|:---|:---|
| POST | `/api/project/auth/config` | 获取授权配置 | SuperAdmin |
| POST | `/api/project/auth/update` | 更新授权配置 | SuperAdmin |
| POST | `/api/project/auth/grant` | 下发授权 | SuperAdmin |
| POST | `/api/project/auth/revoke` | 撤销授权 | SuperAdmin |

## 请求/响应示例

### 项目列表

**Request:**
```json
{
  "page": 1,
  "page_size": 20,
  "keyword": "",
  "lifecycle_status": "",
  "province": ""
}
```

**Response:**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "list": [
      {
        "project_id": "proj_001",
        "name": "示例项目",
        "namespace": "example-ns",
        "lifecycle_status": "RELEASED",
        "certification_status": "official",
        "province": "北京市",
        "city": "北京市"
      }
    ]
  }
}
```

### 保存草稿

**Request:**
```json
{
  "project_id": "proj_001",
  "basic_info": {
    "province": "北京市",
    "city": "北京市",
    "industry_contact": "张三",
    "industry_phone": "13800138000"
  },
  "deploy_business": {
    "deployer_name": "李四",
    "system_version": "v2.0.0"
  }
}
```

**Response:**
```json
{
  "code": 0,
  "message": "草稿保存成功",
  "data": {
    "draft_id": 123,
    "updated_at": "2026-01-21T10:00:00Z"
  }
}
```

### 版本对比

**Request:**
```json
{
  "project_id": "proj_001",
  "base_version": 2,
  "target_version": 3
}
```

**Response:**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "diffs": [
      {
        "module": "部署环境",
        "field_diffs": [
          {
            "field_path": "deploy_env.host_count",
            "field_name": "主机台数",
            "old_value": 3,
            "new_value": 5,
            "change_type": "modify"
          }
        ]
      }
    ]
  }
}
```
