# 文件夹同步协议参考（/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

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

请求体：

```jsonc
{
  "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

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

```jsonc
{ "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）。