# API 接口设计

> DDS-Section: 7. 接口设计 (API)
> DDS-Lines: L781-L818

## 项目管理接口

| 方法 | 路径 | 描述 | 权限 |
|:---|:---|:---|:---|
| 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/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 |
| POST | `/api/project/draft/diff` | 获取草稿与主线的差异 | 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 |

## 请求/响应示例

### 创建项目

**请求**
```json
{
    "project_name": "测试项目",
    "namespace": "test-project-ns",
    "detail_filler_id": 123,
    "detail_filler_name": "张三"
}
```

**响应**
```json
{
    "code": 0,
    "message": "success",
    "data": {
        "project_id": "proj_20260120_001",
        "workflow_id": "wf_20260120_001"
    }
}
```

### 保存草稿

**请求**
```json
{
    "project_id": "proj_20260120_001",
    "form_data": {
        "deploy_business": {
            "deployer_name": "李四",
            "deployer_phone": "13800138000",
            "system_version": "v2.0.0"
        },
        "deploy_env": {
            "network_type": "internal",
            "host_count": 3
        }
    },
    "middlewares": [
        {
            "middleware_type": "mysql",
            "internal_ip": "10.0.0.1",
            "internal_port": 3306
        }
    ]
}
```

### 获取版本差异

**请求**
```json
{
    "project_id": "proj_20260120_001",
    "base_version": 1,
    "target_version": 2
}
```

**响应**
```json
{
    "code": 0,
    "data": {
        "diffs": [
            {
                "module": "部署业务",
                "field_diffs": [
                    {
                        "field_path": "deploy_business.system_version",
                        "field_name": "系统版本",
                        "old_value": "v1.0.0",
                        "new_value": "v2.0.0",
                        "change_type": "modify"
                    }
                ]
            }
        ]
    }
}
```

## 错误码定义

| 错误码 | 说明 |
|:---|:---|
| `PROJECT_NOT_FOUND` | 项目不存在 |
| `NAMESPACE_EXISTS` | 命名空间已存在 |
| `VERSION_CONFLICT` | 版本冲突（并发修改） |
| `PERMISSION_DENIED` | 权限不足 |
| `INVALID_LIFECYCLE_STATUS` | 无效的生命周期状态 |
| `DRAFT_NOT_FOUND` | 草稿不存在 |
| `WORKFLOW_ERROR` | 工单操作失败 |
