# 数据模型参考（.progress/progress.json）

单个 JSON 文件，schemaVersion 3，与原版「进度」应用导出格式一致。agent 工具、
HTTP 协议、界面三端共用同一份文件。

## 顶层结构

```jsonc
{
  "appName": "进度",
  "appVersion": "1.1.27",
  "schemaVersion": 3,
  "exportedAt": "ISO 时间",
  "cycleRange": { "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" },
  "theme": { "color": "#007f73", "mode": "default | sci-fi" },
  "language": "zh | en",
  "collaborationRole": "student | teacher",
  "storageRevision": { "id": "uuid", "updatedAt": "ISO", "source": "…" },
  "items": [ /* 安排 */ ],
  "boards": { "YYYY-MM-DD": { "pages": [ /* 画板页 */ ] } },
  "comments": [ /* 协作留言 */ ]
}
```

## 安排（item）字段

| 字段 | 说明 |
| --- | --- |
| `id` | uuid |
| `template` | `general` / `research` / `work` / `study` / `life` |
| `title` / `project` / `owner` / `tags` | 文本 |
| `date` / `endDate` | YYYY-MM-DD，跨日安排按日期覆盖 |
| `startTime` / `duration` | HH:MM / 小时字符串 |
| `priority` | `1`–`5`（低→紧急） |
| `status` | `planned` / `running` / `paused` / `done` |
| `progress` | 0–100 |
| `predecessorId` / `predecessorIds` | 前置安排（甘特依赖边） |
| `starred` | 突出难题 |
| `reminderAt` / `reminderEnabled` / `reminderTriggeredAt` | 提醒 |
| `objective` / `samples` / `reagents` / `variables` / `steps` / `observations` / `results` / `nextAction` | 九步记录文本 |
| `dailyRecords` | `{ "YYYY-MM-DD": { text, updatedAt } }` |
| `resultFiles` | `[{ id, name, type, size, src, path, storage, date, width, height, createdAt }]` |
| `createdAt` / `updatedAt` | ISO 时间 |

## 画板页（board page）

`{ title, text, drawing, images[], canvasImages[], strokes[], createdAt, updatedAt }`
——文字由 agent 工具读写；手写笔迹/图片由界面负责。

## 留言（comment）

`{ id, itemId, date, author, message, createdAt, updatedAt }`

## 修订与并发

每次写操作 `bumpRevision`：生成新 `storageRevision.id` 并更新 `exportedAt`。
界面保存时携带其已知的 `baseRevision`，与服务器当前 id 不一致返回 409 + 服务器快照
（界面应用快照解决冲突）。同一进程内所有写操作经互斥链串行。

## 目录布局

```
<项目>/.progress/
  progress.json          规范快照（本文件）
  files/                 附件（/api/progress/upload）
  package/<项目名>/      界面生成的「项目文件夹」包（安排.json/记录.md/画板.json/项目数据.json/html查看器）
  export/                progress_export 默认输出目录
```