fix: file lock

API.md

@@ -75,8 +75,9 @@
 
 ### 3.1 `GET /api/v1/workspace-tree`
 
-列出当前用户在 workspace 内的**目录树**(从 `StorageObjects.relative_path` 派生)。
+列出当前用户在 workspace 内的**目录树**。
 
+- **来源**: 显式 `StorageObjects` 行 (`object_type='directory'`,见 §3.2) **并入** 从 `Scripts.relative_path` 派生的祖先目录,**去重**。空目录(只有显式行、没有文件)也会出现。
 - **鉴权**: workspace 成员
 - **请求体**: 无
 - **响应**:
@@ -95,7 +96,7 @@
 
 ### 3.2 `POST /api/v1/workspace-directories`
 
-创建一个**逻辑目录**(对象存储上是隐式前缀,无需落对象)。
+创建一个**目录**。后端会落一行 `StorageObjects(object_type='directory', storage_backend='rustfs', storage_uri='inline://directory/{path}', visibility='private')`,因此空目录也能在 §3.1 树里出现并保留下来。
 
 - **请求体**:
   ```json
@@ -104,11 +105,23 @@
     "parent_path": "scripts"
   }
   ```
+  | 字段 | 必填 | 说明 |
+  |---|---|---|
+  | `directory_name` | 是 | 目录名(单段,不能含 `/`) |
+  | `parent_path` | 否 | 父目录相对路径,空字符串或缺省表示用户根目录 |
+
+- **父目录存在性校验**: 必须在 `StorageObjects` 存在 `relative_path == scoped_prefix/{parent}` 的行,或 `relative_path` 以 `scoped_prefix/{parent}/` 开头。否则 **404**。
+- **同名冲突**: 已有 `relative_path` 完全相等的行(无论 file / directory) → **409**。`uk_storage_workspace_path(workspace_id, storage_backend, path_hash)` 唯一索引保证幂等。
 - **响应 201**:
   ```json
   {
     "request_id": "...",
-    "data": {"path": "scripts/etl", "name": "etl", "parent_path": "scripts"}
+    "data": {
+      "storage_object_id": "01HXY...",
+      "path": "scripts/etl",
+      "name": "etl",
+      "parent_path": "scripts"
+    }
   }
   ```
 
@@ -199,6 +212,7 @@ multipart/binary 形式上传大文件(走 server-proxied PUT,详见 §九)。
 | `script_type` | `python` \| `notebook` | |
 | `visibility` | enum | |
 | `status` | `active` \| `deleted` | |
+| `is_locked` | boolean | 是否锁定。`PUT /scripts/{id}`(§3.8) 受此字段门禁;可通过 §3.16 切换 |
 | `relative_path` | string \| null | 例如 `users/alice/scripts/etl/train.py` |
 | `content_hash` | string \| null | SHA-256 十六进制 |
 | `size_bytes` | int | |
@@ -268,6 +282,32 @@ multipart/binary 形式上传大文件(走 server-proxied PUT,详见 §九)。
   }
   ```
 
+### 3.16 `PATCH /api/v1/scripts/{script_id}/lock`
+
+切换脚本的 `is_locked` 状态。**只切换锁**,不修改脚本内容。
+
+- **鉴权**: admin 或 `owner_user_id == 当前用户`(沿用 `require_script_modify_access`)。其余一律 **404**。
+- **请求体**:
+  ```json
+  {"is_locked": true}
+  ```
+  | 字段 | 必填 | 说明 |
+  |---|---|---|
+  | `is_locked` | 是 | 目标状态。`true` 锁定;`false` 解锁 |
+- **响应 200**: `data` 为更新后的 `ScriptPayload`(§3.10)。
+  ```json
+  {
+    "request_id": "...",
+    "data": { "...ScriptPayload 字段...": "is_locked: false" },
+    "meta": {}
+  }
+  ```
+- **行为**: 行级锁 (`SELECT ... FOR UPDATE`) 防止并发切换;提交后立即生效,影响后续 §3.8 `PUT /scripts/{id}` 的门禁判定。
+- **错误码**:
+  | 码 | 含义 |
+  |---|---|
+  | 404 | 脚本不存在 / 非当前用户无权访问(不区分,避免暴露存在性) |
+
 ---
 
 ## 四、调度