# 鉴权与目录结构（API v1）

本项目的 API v1 使用 **Bearer Token** 鉴权，并且与网页端账号体系隔离。

---

## 1) 鉴权方式

所有需要鉴权的 API 请求都必须带 Header：

```
Authorization: Bearer <TOKEN>
```

- `<TOKEN>` 是你分配给 API 调用方的明文 token
- 服务端不会保存明文 token，只保存其 SHA256

---

## 2) API 用户与 token 的配置文件

文件：`data/api_users.json`

结构示例：

```json
{
  "users": {
    "api_demo": {
      "token_sha256": "9d2f30ce92cee1301dbbdc990aed245a781c34717a1bf51a7a368b6f4ae28f50",
      "created_at": "2026-01-23",
      "note": "dev generated"
    }
  }
}
```

说明：

- `users` 的 key 是 API 用户名（仅用于区分与落盘路径）
- 调用时只需要 token（用户名不会作为参数传入）

> 修改 `data/api_users.json` 后通常需要重启服务以生效（取决于当前是否支持热加载）。

---

## 3) 目录结构（多工作区）

API 用户根目录（默认）：`api/users/<api_user>/`

在该目录下包含：

### 3.1 用户级共享目录（prompts / personalization）

```
api/users/<api_user>/shared/
  prompts/
    <name>.txt
  personalization/
    personalization.json        # 默认个性化（主文件）
    <name>.json                 # 命名个性化
```

说明：

- `prompts` 与 `personalization` 是**用户级共享**：不同 workspace 共用同一份配置；
- `/api/v1/prompts` 与 `/api/v1/personalizations` 操作的就是这里的文件。

### 3.2 工作区目录（每个 workspace 独立）

```
api/users/<api_user>/workspaces/<workspace_id>/
  project/                      # 工具读写根目录（容器挂载目录）
    user_upload/                # 上传目录（API 只允许在这里上传/下载）
  data/                         # 对话/备份等数据落盘（工作区独立）
    conversations/
      conv_*.json
    backups/
    prompts -> ../../shared/prompts               # 软链（可能不存在）
    personalization -> ../../shared/personalization  # 软链（可能不存在）
  logs/
```

说明：

- 每个 workspace 都会启动**独立容器**（隔离执行环境）；
- `project/` 与 `data/` 都是 workspace 级：对话文件不会跨 workspace 混用；
- `user_upload/` 也是 workspace 级：不同 workspace 互相不可见。

---

## 4) 并发规则

- 并发限制以 workspace 为粒度：同一 API 用户的同一 `workspace_id` 同时只允许一个任务运行。
- 不同 workspace 可以同时运行多个任务。