Add stable media URLs for artifacts and uploads

docs/persistence.md

@@ -14,7 +14,6 @@
 
 所以 `popiartServer` 不再重复持有：
 
-- 本地 artifact blob store
 - 本地 artifact metadata table
 - 本地 job_logs table
 
@@ -23,6 +22,7 @@
 - `sessions`
 - `jobs`（更准确说是 job refs）
 - `skill_routes`
+- `media blobs + metadata`
 
 ## 当前关系
 
@@ -30,14 +30,16 @@
 session -> jobs
 jobs    -> result_refs_json
 project -> skill_routes
+media   -> local files + metadata json
 ```
 
 其中：
 
 - `session` 保存 PopiArt 登录态和对应的 `PopiNewAPI token`
 - `jobs` 保存 skill 语义、用户归属、上游引用和同步结果引用
-- `result_refs_json` 保存同步能力的返回引用，例如 `data_url` 或远端 `url`
+- `result_refs_json` 保存同步能力的结果引用；新结果会优先 re-host 到本地 media store
 - `skill_routes` 保存项目级路由覆盖
+- `media` 保存稳定 URL 所需的本地文件与元数据
 
 ## 存储位置
 
@@ -66,7 +68,10 @@ POPIART_SQLITE_PATH=./data/popiart.db
 2. `JobRepository`
 3. `RouteRepository`
 
-没有单独的 blob storage 抽象。
+本地开发版没有对象存储依赖，但现在有一个轻量 media 存储层：
+
+- blob 文件保存在 `POPIART_DATA_DIR/media/blobs/`
+- metadata JSON 保存在 `POPIART_DATA_DIR/media/meta/`
 
 ## SQLite Schema
 
@@ -141,15 +146,24 @@ CREATE TABLE skill_routes (
 ### 完成同步结果 job
 
 1. 如果 `PopiNewAPI` 直接返回同步结果，例如 `b64_json` 或 `url`
-2. `popiartServer` 只把它转换成 `result_refs_json`
-3. `GET /jobs/:id/artifacts` 时再从 `result_refs_json` 派生 artifact 列表
+2. `popiartServer` 会先把结果 re-host 到本地 media store
+3. 再把本地 `local_path + media_id + stable url` 写进 `result_refs_json`
+4. `GET /jobs/:id/artifacts` 时再从 `result_refs_json` 派生 artifact 列表
 
 ### 拉取 artifact
 
 1. server 从 `artifact_id` 反推出 `job_id + result index`
 2. 读取 `jobs.result_refs_json`
-3. 如果是 `data_url`，直接解码并流式返回
-4. 如果是远端 `url`，server 代理下载并返回
+3. 如果是本地 `local_path`，直接读取本地文件并流式返回
+4. 如果是旧的 `data_url`，直接解码并流式返回
+5. 如果是旧的远端 `url`，server 代理下载并返回
+
+### 读取 media
+
+1. `POST /v1/media/upload` 会把本地文件写入 `media/blobs/`
+2. server 同时写一份 metadata JSON 到 `media/meta/`
+3. `GET /v1/media/:id` 返回 media 元数据
+4. `GET /v1/media/:id/content` 返回可供模型或客户端直接 fetch 的稳定内容路径
 
 ## 当前边界
 
@@ -157,7 +171,8 @@ CREATE TABLE skill_routes (
   - `session` 会保留
   - `job ref` 会保留
   - `artifact` 通过 `result_refs_json` 继续可读
+  - 新 `media` 文件和 metadata 会继续可读
 - 已存在的 `pending/running` job 仍然不会自动恢复执行
 - 视频类 `upstream_task` 路径只预留了字段，后续再接 `PopiNewAPI` task 查询
-- 对同步图像结果来说，`data_url` 仍然会落在 SQLite 的 `result_refs_json`
-  这是当前 `PopiNewAPI` 没有统一 file id 的现实折中，但已经不再有本地 artifact 表和 blob store
+- 旧数据里仍可能存在 `data_url` 或上游 `url`
+- 新写入路径优先落本地 media store，从而给 artifact 补出稳定 `url`