update panel

ReinLoop/features.md

@@ -5,7 +5,8 @@
 ## 约定
 
 - 业务服务端地址由 `REINLOOP_API_URL` 指定，未设置时使用
-  `REINLOOP_SERVER_URL + /api`。
+  `REINLOOP_SERVER_URL + /api`；默认地址为
+  `https://ReinLoop.dominatedconvergence.com/api`。
 - 新许可证的设备标识为 `<company_code>/<production_line_code>`，在代码中通过
   `api.the_folder` 使用。旧许可证才回退到 `REINLOOP_DEVICE_ID`。
 - 所有服务端业务请求均使用 `POST /api`，通过请求体的 `type` 字段分发。
@@ -67,11 +68,28 @@ RL 模式下，`ControlEngine` 使用模型根据流量、当前压力和压力
 | --- | --- | --- |
 | 初始化一轮采集 | `DataCollector.reset()` | 清空 Episode 缓存。 |
 | 记录控制点 | `DataCollector.record_step(cycle_count, current_pressure, target_pressure, valve_opening, kp, ki, kd, q_in, v)` | 目标压力变化时自动切分 Episode。 |
-| 停止后异步上传 | `DataCollector.finalize_and_upload(flow, vol)` | 分片上传 Pickle 数据和 manifest 到 `<deviceId>/data_record/...`。 |
-| 上传凭证与直传 | `DataCollector._upload_to_cos(data_bytes, filename, folder)` | 内部接口；先请求上传凭证，再将对象直传。 |
+| 停止后异步上传 | `DataCollector.finalize_and_upload(flow, vol)` | 分片上传 Pickle 数据和 manifest 到 `<deviceId>/data_record/data_<flow>SLM_<volume>L`。清单含 `data_type: "control_episode"`、`run_id`、分片元数据和总 Episode 数。 |
+| 申请上传地址并上传 | `DataCollector._upload_to_server(data_bytes, filename, folder)` | 内部接口；先向 ReinLoop 云服务器申请一次性上传地址，再以 multipart 上传文件。 |
+| 上传结果通知 | `DataCollector.set_upload_complete_callback(callback)` | 注册 `callback(success, manifest, error)`；在后台上传线程完成时调用。 |
 
 上传地址通过服务端 `uploadDataFile` 获取。单个 Episode 数据文件超过约 5 MB 时会自动拆分。
 
+### 控制数据服务端约定
+
+控制数据上传目录固定以 `<deviceId>/data_record/` 为前缀；每次停止控制会上传
+若干 `.pkl` 分片和一个同名时间戳的 `_manifest.json`。服务端在接收二步上传的文件后，
+应保留文件元数据，并向管理端提供以下仅管理员可调用的接口：
+
+| `type` | 请求字段 | 成功响应 | 服务端行为 |
+| --- | --- | --- | --- |
+| `listControlFiles` | `deviceId`、可选 `page`、`pageSize` | `files`、`total`、`page`、`pageSize` | 仅返回 `folder` 以 `<deviceId>/data_record/` 开头的记录；每条至少有 `fileID`、`fileName`、`folder`、`uploadTime`、`size`。 |
+| `getControlFileDownload` | `fileID` | `fileID`、`fileName`、`url` | 仅允许下载控制数据目录内的文件，并返回短期签名下载 URL。 |
+| `deleteControlFile` | `fileID` | `deletedCount` | 仅允许删除控制数据目录内的文件；同时删除文件本体及对应元数据。 |
+
+上述三个接口必须校验管理端令牌，并根据 `fileID` 对应记录的目录验证设备边界，不能仅信任
+调用方传入的设备标识。Panel 可直接展示 JSON manifest；`.pkl` 为 Python pickle 二进制，
+应仅供下载，不应在管理端进程中反序列化。
+
 ## 系统辨识
 
 | 功能 | 接口 | 返回或行为 |