文件夹同步协议参考（/api/progress/*）

本插件复刻了「进度」单页应用自带的「本地文件夹服务器」协议。原版 app.js 在 http://127.0.0.1（或 localhost）页面下自动调用同源接口；插件在 DSH webserver 上实现服务端，界面代码零改动。

会话解析优先级：?session= 查询参数 → Referer 里的 ?session= → cookie dsh_progress_session。无会话返回 501（原版应用识别为「不支持文件夹同步」，退化为仅本地存储）。

所有响应为 JSON；错误形如 { ok: false, error: "…" }（load 用 { found: false, error }）。

GET /api/progress/load

读取当前会话项目的快照。

• 200 { found: true, snapshot } — snapshot 为 schemaVersion 3 快照（见 docs/data-model.md）
• 200 { found: false } — 尚无数据文件（.progress/progress.json）
• 501 { found: false, error } — 无法解析会话（无 session / 会话无 cwd）

POST /api/progress/save

写入快照 + 客户端生成的「项目文件夹」包文件。

请求体：

{
  "snapshot": { /* schemaVersion 3 快照，含 storageRevision { id, updatedAt, source } */ },
  "files": [ { "path": "相对路径", "encoding": "utf8 | base64", "content": "…" } ],
  "baseRevision": "客户端上次已知的 revision id（可为空）",
  "force": false
}

响应：

• 200 { ok: true, revision } — 已写入
• 409 { ok: false, error: "conflict", snapshot } — baseRevision 与服务器当前 revision 不一致，附带服务器快照；原版应用会应用服务器快照解决冲突
• 400 { ok: false, error } — 请求体非法

包文件落盘到 .progress/package/<路径>（拒绝绝对路径与 .. 穿越）。

POST /api/progress/upload

上传每日记录附件（原始字节为请求体，Content-Type 为文件类型）。

查询参数：project（项目名）、date（YYYY-MM-DD）、name（文件名）。

响应 200 { ok: true, name, type, size, path, url } —— url 为回读地址 /api/progress/file?session=<id>&p=<相对路径>，原版应用直接用它渲染图片/链接。

GET /api/progress/file

回读附件。查询参数：session、p（.progress/files/ 下的相对路径，拒绝穿越）。

GET /api/progress/info

存储信息（侧边栏标题栏与诊断用）：

{ "ok": true, "value": { "exists": true, "path": "…/.progress/progress.json",
  "items": 4, "boardDays": 0, "comments": 0, "revision": "…", "sessionId": "…" } }

GET /progress/*（静态托管）

原版界面三件套 + 动态 folder-data.js（注入会话 id 与项目名，作用域隔离 localStorage）。 prefix 路由注册为 /progress（不带尾斜杠——宿主匹配规则为 startsWith(prefix + '/')，带尾斜杠会导致永不命中，落进 SPA fallback 的 404）。