# 工作区（Workspace）管理 API

本项目的 API v1 支持**多工作区并行**：

- 一个 API 用户可以创建多个 `workspace_id`
- 每个 workspace 有独立的：
  - 容器（运行隔离）
  - `project/`（工具读写的根目录）
  - `data/`（对话等数据落盘）
  - `user_upload/`（上传目录）
- 并发限制以 workspace 为粒度：**同一 workspace 禁止并发任务**，不同 workspace 可同时运行。

鉴权：所有接口均需要 `Authorization: Bearer <TOKEN>`

`workspace_id` 规则：

- 仅允许字符：字母/数字/`.`/`_`/`-`
- 长度：1~40

---

## 1) 列出工作区

### GET `/api/v1/workspaces`

成功响应（200）：

```json
{
  "success": true,
  "items": [
    {
      "workspace_id": "ws1",
      "project_path": ".../api/users/api_demo/workspaces/ws1/project",
      "data_dir": ".../api/users/api_demo/workspaces/ws1/data",
      "has_conversations": true
    }
  ]
}
```

---

## 2) 创建/确保工作区存在

### POST `/api/v1/workspaces`

Body(JSON)：

```json
{ "workspace_id": "ws1" }
```

成功响应（200）：

```json
{
  "success": true,
  "workspace_id": "ws1",
  "project_path": ".../api/users/<user>/workspaces/ws1/project",
  "data_dir": ".../api/users/<user>/workspaces/ws1/data"
}
```

错误：

- `400`：workspace_id 不合法

---

## 3) 查询单个工作区

### GET `/api/v1/workspaces/{workspace_id}`

成功响应（200）：

```json
{
  "success": true,
  "workspace": {
    "workspace_id": "ws1",
    "project_path": "...",
    "data_dir": "...",
    "has_conversations": true
  }
}
```

错误：

- `404`：workspace 不存在

---

## 4) 删除工作区

### DELETE `/api/v1/workspaces/{workspace_id}`

说明：

- 会删除该 workspace 的 `project/`、`data/`、`logs/` 等目录；
- **不会删除用户级共享**的 `prompts/personalization`（它们不属于 workspace）；
- 如果该 workspace 有运行中的任务，会返回 `409`（禁止删除）。

成功响应（200）：

```json
{ "success": true, "workspace_id": "ws1" }
```

错误：

- `409`：该工作区有运行中的任务
- `404`：workspace 不存在