Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,12 +66,12 @@ export APP_VERSION=2.0.0-rc.66
docker compose pull
docker compose --profile operations run --rm migrate
docker compose up -d
curl -fsS http://服务器地址:48731/health/ready
curl -fsS http://127.0.0.1:48731/health/ready
# 4. 首次部署时初始化 Owner 账号
docker compose --profile operations run --rm bootstrap
```

默认访问地址是 `http://服务器地址:48731`。初始化成功后建议从 `.env` 里删掉 `OWNER_PASSWORD`,并删除或轮换 `BOOTSTRAP_TOKEN`。需要 HTTPS 和反向代理时可加 `--profile gateway`,由 Caddy 签发证书并发布入口。
默认只有服务器本机能访问 `http://127.0.0.1:48731`。要让其他设备打开,二选一:把 `.env` 里的 `TASKDOCK_BIND_ADDRESS` 改成 `0.0.0.0`(明文 HTTP,仅限可信网络),或在 `APP_ORIGIN` 填好域名后执行 `docker compose --profile gateway up -d`,由 Caddy 提供 HTTPS 入口。初始化成功后建议从 `.env` 里删掉 `OWNER_PASSWORD`,并删除或轮换 `BOOTSTRAP_TOKEN`。

**网页端**:中枢起来后,浏览器打开你配置的 `APP_ORIGIN` 即可,无需安装。

Expand Down
18 changes: 9 additions & 9 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,29 @@

## v2 资源

v2 不再把 Project/Inbox/category/priority 作为产品模型。`GET /api/v2/tree/children` 返回 Folder 与 Task 的混合直接子项;Folder 的 `aggregate` 由后代 Task 派生,状态顺序为 `IN_PROGRESS → TODO → DONE`。`POST /api/v2/tree/items/move` 使用 `baseVersion`、状态快照和前后锚点保护循环、已归档目标以及并发排序冲突。
v2 不再把 Project/Inbox/category/priority 作为产品模型。`GET /api/v2/tree/children` 返回 Folder 与 Task 的混合直接子项;Folder 的 `status` 是文件夹自身持有的显式三态(默认 `TODO`),`aggregate` 里的 `todoCount/inProgressCount/doneCount/totalCount` 由后代 Task 派生,排序状态顺序为 `IN_PROGRESS → TODO → DONE`。`POST /api/v2/tree/items/move` 使用 `baseVersion`、状态快照和前后锚点保护循环、目标父级以及并发排序冲突。

目录分页:`GET /api/v2/tree/children?parentFolderId=root&limit=100`,`limit` 为 1–200;下一页携带响应的 `nextCursor`,末页为 `null`。游标绑定账户、父目录及账户版本;中途发生写入返回 HTTP 410 `SYNC_CURSOR_EXPIRED`,调用方应保留已展示内容并提供从第一页重新加载,不自动无限重试。排序键为状态组、整数 rank、类型(文件夹优先)、ID。未指定 `limit` 的旧客户端继续得到全部直接子项。

`GET /api/v2/tasks/{id}?view=summary` 只返回 `{ task }`,用于状态切换后保持当前行的位置,不读取备注或关系;省略 `view` 继续返回原有详情。

PostgreSQL 的目录、文件夹选择器及面包屑读取不调用全账户 `prepare()`,不读取备注、步骤或工作流关系;文件夹状态汇总仍需扫描该目录下的活动后代,不能将一级分页当成后代扫描恒定开销。面包屑与内容独立加载。分页不推进全局同步游标;客户端只缓存精确页面成员,未完整 bootstrap 时不能据此构造未读取页或宣称全目录完整。完整本地投影使用独立的 `local.` 游标,绝不发送给服务器。
PostgreSQL 的目录、文件夹选择器及面包屑读取不调用全账户 `prepare()`,不读取备注、步骤或工作流关系;文件夹进度计数仍需扫描该目录下的活动后代,不能将一级分页当成后代扫描恒定开销。面包屑与内容独立加载。分页不推进全局同步游标;客户端只缓存精确页面成员,未完整 bootstrap 时不能据此构造未读取页或宣称全目录完整。完整本地投影使用独立的 `local.` 游标,绝不发送给服务器。

目录归档使用 `POST /api/v2/folders/:id/archive-tree`,响应 `ArchiveOperation`;恢复使用原 operationId,保证逐项精确恢复。归档中心通过 `GET /api/v2/archive-operations` 按顶层归档操作分组返回(含 `rootFolderTitle`、后代 Folder/Task 计数、原本已归档而恢复时需保留的计数,以及可展开的嵌套 Folder 列表);`?includeRestored=true` 才包含已恢复操作,`GET /api/v2/archive-operations/:id` 额外返回该操作的归档 Task 明细与独立归档 Task。整树删除必须先 `POST /api/v2/folders/:id/delete-preview`,再把短时 `confirmationToken` 发送到 `DELETE /api/v2/folders/:id/tree`;预览 fingerprint 变化或令牌过期时拒绝,不物理删除关联 Note、TaskStep、Placement、Workflow Membership 或父级引用。整树删除必须在线执行;离线客户端 fail-closed 并返回 `OFFLINE_TREE_DELETE_FORBIDDEN` 与归档建议,不允许排队执行不可恢复的删除。
整树删除必须先 `POST /api/v2/folders/:id/delete-preview`,再把短时 `confirmationToken` 发送到 `DELETE /api/v2/folders/:id/tree`。预览返回将删除的文件夹、任务、备注、步骤、日程和流程关联计数,以及 `subtreeFingerprint`;fingerprint 变化或令牌过期时拒绝,不物理删除关联 Note、TaskStep、Placement、Workflow Membership 或父级引用。整树删除必须在线执行;离线客户端 fail-closed 并返回 `OFFLINE_TREE_DELETE_FORBIDDEN`,不允许排队执行不可恢复的删除。

批量顺延使用 `POST /api/v2/dates/:localDate/rollover`,只把该日期仍处于活动状态的 Placement 复制到次日,跳过已完成或已归档任务;响应 `{ createdIds, skippedTaskIds, targetDate }`。撤销使用 `POST /api/v2/rollovers/undo`,body 传 `{ placementIds }`。该操作无服务端状态,可跨进程与重启使用;离线时不排队,直接 fail-closed。
批量顺延使用 `POST /api/v2/dates/:localDate/rollover`,只把该日期仍处于活动状态的 Placement 复制到次日,跳过已完成或已删除的任务;响应 `{ createdIds, skippedTaskIds, targetDate }`。撤销使用 `POST /api/v2/rollovers/undo`,body 传 `{ placementIds }`。该操作无服务端状态,可跨进程与重启使用;离线时不排队,直接 fail-closed。

`GET /api/v2/tasks?archived=false&q=...` 支持按任务标题、引用 ID 或备注内容搜索。Task 详情通过 `GET /api/v2/tasks/:id` 聚合 Note、独立 TaskStep、Placement、Workflow Membership 和 Folder path;每个 Placement 同时返回可直接展示的 `timePoint` 日期/事件信息。日期与 Event/Placement 使用 `/time-points`、`/placements` v2 路由;Workflow、Stage、Membership 使用 `/workflows`、`/workflow-stages` 和 `/workflow-memberships`。同一 Task 可以加入多个 Workflow,但同一 Workflow 只能有一个活动 Membership。
`GET /api/v2/tasks?q=...` 支持按任务标题、引用 ID 或备注内容搜索。Task 详情通过 `GET /api/v2/tasks/:id` 聚合 Note、独立 TaskStep、Placement、Workflow Membership 和 Folder path;每个 Placement 同时返回可直接展示的 `timePoint` 日期/事件信息。日期与 Event/Placement 使用 `/time-points`、`/placements` v2 路由;Workflow、Stage、Membership 使用 `/workflows`、`/workflow-stages` 和 `/workflow-memberships`。同一 Task 可以加入多个 Workflow,但同一 Workflow 只能有一个活动 Membership。

v2 设置通过 `/api/v2/settings` 保存 `ROOT/RECENT_FOLDER` 目标;`GET /api/v2/status` 返回 `schemaVersion: 2`、支持的 API/sync 版本和 `minClientVersion`。v2 写入继续要求 `Idempotency-Key`、`X-Client-Id` 和适用的 `baseVersion`。

## 认证

首次部署由部署中枢执行 `docker compose --profile operations run --rm bootstrap`,服务端内部仍使用 `POST /bootstrap` 和 `BOOTSTRAP_TOKEN`,成功后永久关闭;Web、桌面和手机客户端不提供初始化令牌输入。`POST /auth/login` 返回短时 access token;Web refresh token 是 `HttpOnly`、`SameSite=Lax` Cookie:使用 HTTPS 时还会带有 `Secure` 属性,使用 HTTP 时为了让 HTTP 外网地址可用而不带 `Secure`,但密码和会话信息会明文传输,页面会显示安全警告。原生容器应通过平台安全存储持有 refresh token。每次 refresh 都轮换 token,并把 365 天滑动不活动窗口重新计时;旧链重放会撤销该设备会话链。Web Cookie 同样按该窗口重设,但浏览器对持久 Cookie 有约 400 天上限。`DELETE /devices/{id}` 可撤销指定设备的全部会话,`GET /devices` 会标记 `current` 表示当前设备。
首次部署由部署中枢执行 `docker compose --profile operations run --rm bootstrap`,服务端内部仍使用 `POST /bootstrap` 和 `BOOTSTRAP_TOKEN`,成功后永久关闭;Web 和 Android 客户端不提供初始化令牌输入。`POST /auth/login` 返回短时 access token;Web refresh token 是 `HttpOnly`、`SameSite=Lax` Cookie:使用 HTTPS 时还会带有 `Secure` 属性,使用 HTTP 时为了让 HTTP 外网地址可用而不带 `Secure`,但密码和会话信息会明文传输,页面会显示安全警告。原生容器应通过平台安全存储持有 refresh token。每次 refresh 都轮换 token,并把 365 天滑动不活动窗口重新计时;旧链重放会撤销该设备会话链。Web Cookie 同样按该窗口重设,但浏览器对持久 Cookie 有约 400 天上限。`DELETE /devices/{id}` 可撤销指定设备的全部会话,`GET /devices` 会标记 `current` 表示当前设备。

## 写入约定

所有写请求需要合法 UUID `Idempotency-Key` 和 `X-Client-Id`。更新/归档/恢复需要 body 中的 `baseVersion`。服务端重复接收相同 mutation 返回第一次结果,不重复创建 Task 或 Placement。冲突 HTTP 409,错误体固定为:
所有写请求需要合法 UUID `Idempotency-Key` 和 `X-Client-Id`。更新/删除需要 body 中的 `baseVersion`。服务端重复接收相同 mutation 返回第一次结果,不重复创建 Task 或 Placement。冲突 HTTP 409,错误体固定为:

```json
{
Expand All @@ -45,8 +45,8 @@ v2 设置通过 `/api/v2/settings` 保存 `ROOT/RECENT_FOLDER` 目标;`GET /ap
- `/placements/:id/move` 在一个 mutation 中建立目标并软删除来源。
- `/tasks/:id/duplicate` 才创建新的 Task、Note 和引用 ID。
- `POST /time-points/date` 对同一 Owner/localDate 幂等返回同一 Date TimePoint。
- Task status 全局生效,Event 的 `reachedAt/archivedAt` 独立。
- 普通列表默认排除归档和 tombstone;`/search/tasks?includeArchived=true` 可搜索归档任务。
- Task status 全局生效,Event 的 `reachedAt` 独立。
- 普通列表默认排除 tombstone;任务搜索使用 `GET /api/v2/tasks?q=`,覆盖标题、引用 ID 和备注内容。

## 列表与分页

Expand Down
6 changes: 3 additions & 3 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Web/PWA 直接加载 React Web 产物,并通过浏览器的 Fetch、Cookie、I
- `packages/sync-client`:IndexedDB/Dexie v2 schema、v1 outbox 转换、push/pull、冲突记录、tombstone 和重同步。
- `apps/web`:React/PWA 目录树、混合排序、工作流、步骤、日期/Placement 和删除预览界面。
- `apps/mobile`:Capacitor 工程与 `apps/mobile/android` 原生 Compose/Room 客户端;原生客户端不依赖 React 页面来满足 v2 功能。
- `apps/api/src/tree-store.ts`:Owner-scoped v2 目录树、归档操作、Workflow、TaskStep、时间点/Placement 以及内存迁移投影。
- `apps/api/src/tree-store.ts`:Owner-scoped v2 目录树、Workflow、TaskStep、时间点/Placement 以及内存迁移投影。
- `apps/api/src/postgres-tree-store.ts`:PostgreSQL v2 projection 的单查询加载、增量 change-feed 追赶、批量持久化和 v2 change feed 适配。
- `apps/api/src/cache.ts`:可选 Redis 共享限流/冷启动缓存;缓存投影故障回退数据库,认证限流是否允许进程内回退由 `AUTH_RATE_LIMIT_REQUIRE_SHARED` 决定。
- 主题:Web 使用 `prefers-color-scheme`,Android 使用 `Configuration.uiMode` 同步系统栏并向 WebView 派发主题事件;主题是设备运行时状态,不进入账号同步设置。
Expand All @@ -28,8 +28,8 @@ Web/PWA 直接加载 React Web 产物,并通过浏览器的 Fetch、Cookie、I
4. v2 Task 只有一个 `parentFolderId`;旧 `projectId/category/priority` 仅在兼容存储/迁移边界保留,不进入 v2 DTO/UI。
5. 每次版本更新都检查 `baseVersion`;失败返回 `VERSION_CONFLICT` 和服务器快照。
6. mutation receipt、领域写入、版本递增和 change feed 在同一 Store mutation 中提交。
7. Folder 归档为一次有 operationId 的逐实体写入;恢复只恢复该 operationId 写入的边界,不误恢复此前已归档的后代。删除预览的 fingerprint/token 过期或变化时 fail-closed,并为 Folder、Task、Note、Step、Placement、Membership 产生 tombstone。
8. Folder aggregate/status 是由未归档、未删除后代 Task 迭代派生的只读结果,不进入持久化状态或 change feed。
7. 整树删除先由 `POST /api/v2/folders/:id/delete-preview` 生成短时 token 和 subtree fingerprint,再通过 `DELETE /api/v2/folders/:id/tree` 执行;fingerprint 变化或 token 过期时 fail-closed,并为 Folder、Task、Note、Step、Placement、Membership 产生 tombstone。
8. Folder 的 `status` 是文件夹自身持久化的显式三态;`aggregate` 的计数由未删除后代 Task 迭代派生,不进入持久化状态或 change feed。
9. 同一 Task 可进入多个 Workflow;同一 Workflow 内活动 Membership 唯一。TaskStep 的状态和 completedAt 独立于 Task.status。

## ADR
Expand Down
2 changes: 1 addition & 1 deletion docs/BACKUP_RESTORE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## 备份与校验

TaskDock v2 数据升级前必须先完成 PostgreSQL custom dump;本轮新增 migration `0005_v2_structure.sql`、`0006_v2_backfill.sql`、`0007_v2_constraints.sql`。升级顺序是先备份,再让新代码读取旧/新结构,执行 backfill 和约束校验;禁止用 `TRUNCATE`、重建业务表或 destructive migration 替代。必须核对 Project→Folder、Task `reference_id`、Note、Placement、归档边界和用户设置计数后再继续。
TaskDock v2 数据升级前必须先完成 PostgreSQL custom dump;本轮新增 migration `0005_v2_structure.sql`、`0006_v2_backfill.sql`、`0007_v2_constraints.sql`。升级顺序是先备份,再让新代码读取旧/新结构,执行 backfill 和约束校验;禁止用 `TRUNCATE`、重建业务表或 destructive migration 替代。必须核对 Project→Folder、Task `reference_id`、Note、Placement、删除边界(tombstone)和用户设置计数后再继续。

```bash
BACKUP_DIR="$PWD/backups"
Expand Down
2 changes: 2 additions & 0 deletions docs/STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

更新时间:2026-10-13

> 后续变更(2026-11-12):归档机制已在 `2.0.0-rc.26` 移除,本文中归档中心相关条目已失效;文件夹状态在 `2.0.0-rc.62` 改为文件夹自身持有的显式三态。冲突时以 `docs/ARCHITECTURE.md` 和代码为准。

总体发布状态:**FAIL(v2 完成定义未满足,但阻断项已全部关闭)**。本轮已关闭全部已知 P0/P1 源码缺陷,并补齐归档中心、v2 rollover、V2 restore 策略、离线删除 fail-closed、Folder-first 迁移分层、Android 同步恢复等此前遗留项。所有本地门禁、真实 PostgreSQL migration/integration/runtime 门禁与三浏览器 E2E 均为 PASS。

仍未运行、因而继续阻断正式发布的门禁只有环境类项:WebKit、Android 真机/仪器、Docker Compose 与长期双端离线矩阵。这些是环境缺失,不是已知实现缺陷。
Expand Down
6 changes: 3 additions & 3 deletions docs/SYNC_PROTOCOL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 同步协议

协议版本:`2`。v1 仍只作为兼容读取/转换边界存在;客户端按 `hub origin + owner id` 建立 Dexie 数据库,v2 stores 为 folders、tasks、notes、taskSteps、timePoints、placements、workflows、workflowStages、workflowTaskMemberships、archiveOperations、settings、outbox、conflicts、deferredChanges、syncMeta。Android Room 对应版本 4 schema 与显式 `MIGRATION_3_4`。
协议版本:`2`。v1 仍只作为兼容读取/转换边界存在;客户端按 `hub origin + owner id` 建立 Dexie 数据库,v2 stores 为 folders、tasks、notes、taskSteps、timePoints、placements、workflows、workflowStages、workflowTaskMemberships、settings、outbox、conflicts、deferredChanges、syncMeta。Android Room 对应版本 4 schema 与显式 `MIGRATION_3_4`。

v2 使用独立 cursor key/协议状态,不能复用 v1 cursor。服务端 `/api/v2/sync/push` 只接受 `protocolVersion: 2`,v1 push 不会创建 v2 receipt;`/api/v2/status` 明确公布 `schemaVersion`、`supportedApiVersions`、`supportedSyncProtocols` 和 `minClientVersion`。

Expand All @@ -20,10 +20,10 @@ cursor 是不透明十进制字符串。Pull 返回完整实体快照或 tombsto

## v2 快照与实体范围

`GET /api/v2/sync/snapshot` 返回 Folder、Task、Note、TaskStep、TimePoint、Placement、Workflow、Stage、Membership、ArchiveOperation、Settings 的一次一致性快照和对应游标。客户端在一个 IndexedDB/Room 事务中替换 v2 实体,先保留 outbox/conflict/deferred change,再重放 pending after-image;删除 change 保留 tombstone,不物理清除以免破坏恢复和冲突审计。v1 snapshot 不得冒充 v2 snapshot。
`GET /api/v2/sync/snapshot` 返回 Folder、Task、Note、TaskStep、TimePoint、Placement、Workflow、Stage、Membership、Settings 的一次一致性快照和对应游标。客户端在一个 IndexedDB/Room 事务中替换 v2 实体,先保留 outbox/conflict/deferred change,再重放 pending after-image;删除 change 保留 tombstone,不物理清除以免破坏恢复和冲突审计。v1 snapshot 不得冒充 v2 snapshot。

## 冲突

版本不匹配时保留本地意图和服务端快照,不静默覆盖。Note UI 应提供采用本地、采用服务器、合并后保存;Task/Project/TimePoint 展示冲突字段。活动 Placement 重复视为幂等成功;被归档/删除实体上的更新需由用户选择恢复应用或丢弃。
版本不匹配时保留本地意图和服务端快照,不静默覆盖。Note UI 应提供采用本地、采用服务器、合并后保存;Task/Project/TimePoint 展示冲突字段。活动 Placement 重复视为幂等成功;已删除实体上的更新需由用户选择恢复应用或丢弃。

WebSocket `/api/v2/ws` 必须先收到 access-token auth 消息;认证成功只发送 `{ "type": "ready", "protocolVersion": 2 }` 和 `{ "type": "sync.required", "cursor": "..." }`,不传业务正文。断线时由轮询、focus、online 和 Android 回前台兜底。
2 changes: 2 additions & 0 deletions docs/V2_TREE_WORKFLOW_DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@
> 编写基线:master 分支 af98f22;实施者开始前必须重新检查 HEAD、工作区状态和已有变更
> 文档用途:交给后续开发代理作为 v2 的单一产品与工程实施依据
> 发布边界:完成实现和本地验证后先交由用户审查;未经用户明确要求,不部署、不打标签、不创建 Release
>
> 变更提示(2026-11-12):归档机制从 `2.0.0-rc.26` 起移除,整树删除改为预览计数 + 短时确认 token;文件夹状态从 `2.0.0-rc.62` 起改为文件夹自身持有的显式三态(默认 `TODO`),不再由后代任务推导。本文其余部分仍作为当时的实施基线保留,冲突时以 `docs/ARCHITECTURE.md` 和代码为准。

## 1. 文档优先级与规范用语

Expand Down
2 changes: 1 addition & 1 deletion docs/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -1007,7 +1007,7 @@
"get": {
"responses": {
"200": {
"description": "TaskDock v2 GET /v2/tasks; optional archived and q filters (q searches title, reference ID and note content)"
"description": "TaskDock v2 GET /v2/tasks; optional q filter (q searches title, reference ID and note content)"
}
}
},
Expand Down
Loading
Loading