Files
pages/docs/design/ja/outbox-delivery.md
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

54 lines
6.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 共通outbox:購読・移行・復旧契約
更新日:2026-09-25。単一インスタンスのSQLiteと既存イベントキューでの初期実装です。タスクの期限日/計画日通知は[正本と同時に作る予約](task-reminders.md)から配信します。outbox購読による汎用変更通知、分散配送、outboxの自動削除は未実装です。
## 責務を分ける
| 要素 | 役割 |
| --- | --- |
| `activity_outbox` | 正本変更と同時に保存する小さなイベント。Domain-local sequence、UUID、型、actor、対象、一意キー |
| `activity_outbox_heads` | Domain・イベント型ごとの最新sequence。INSERT triggerで同じtransaction内に更新 |
| `activity_outbox_checkpoints` | consumer・Domainごとの完了位置。成功後にのみ単調に進める |
| `event_jobs` | 実際の実行・再試行・優先度・ログ・キャンセル。outboxの記録とは別 |
`status`、`attempts`、`next_attempt_ms` 等のoutbox旧列は互換のため残しますが、consumer配信の完了や再試行判定には使いません。旧 `processed` 行も、新規consumerにとっては未処理になり得ます。`CompleteActivityOutboxThrough` は指定したconsumerのcheckpointのみ更新します。
## 購読と負荷
`ActivitySubscription` のconsumer IDとevent type集合は信頼するworkerコードで定義します。HTTP入力から任意の購読を生成しません。現在のCity購読は `page.created`、`revision.created`、`path.renamed`、`path.unlinked`、`object.deleted` です。タスク変更や無関係の拡張イベントだけではCityジョブを作りません。
未処理Domainの発見はheadsとcheckpointの比較で行い、全イベント履歴を毎回検索しません。1回最大100 Domain。イベント取得は型ごとにsequence索引から上限件数を取り、その結果をマージします。1回の最終結果は最大500件、型は最大16種類です。無関係のイベントが大量に入っても、対象イベントの手前を何ページも読み飛ばしません。
同じconsumer IDのまま購読型を増やすと、checkpointより古い新購読型のイベントを取り逃がします。**購読集合の変更時は新しいconsumer IDを使う**ことを契約とします(例:`notifications.tasks.v2`)。再生の開始位置・過去通知の抑止を別途指定します。
Cityは取得した対象イベントの最終sequenceまで、再構成成功後にcheckpointを進めます。並行して追加された後続イベントは次回に残ります。再構成後・checkpoint保存前の停止は再実行になりますが、既存の冪等な再構成で回復します。途中で失敗したbatchの一部だけを成功扱いにしてはいけません。
## タスクの直接接続と既存データ
タスクhead・版・専用ジャーナル・共通outbox・headsを同じtransactionで保存します。どこか一つが失敗したらDBの変更は全体をrollbackします。CASファイルの孤立可能性は従来どおりで、未commitのheadには現れません。
タスクの一意キーはDomainにスコープされた `organizer:{kind}:{uuid}:{version}`。payloadは版番号と変更時刻のみです。作成の再送、旧記録の再生、ジョブ再試行で二重記録しません。
`organizer_activity_bridge` は専用ジャーナルの移行位置です。`task.activity.publish` は1回100件、3秒timeout、既定60秒間隔・priority -5。処理したイベントと移行位置を同時commitします。失敗時は位置を進めません。対象が欠損して種類を判定できない場合はエラー停止し、黙ってスキップしません。タスクの物理削除導入時にはtombstoneを追加する必要があります。
この移行ジョブは拡張のユーザー操作を実行するものではなく、保存済み変更記録の内部保全です。拡張の無効化とは別に、イベント定義のenabledをOFFにできます。既存enabled・intervalの設定は起動時に保持します。`/_/api/v1/event/run` からも既存の管理権限で手動実行できます。ログは件数のみで、個人タスクのタイトルや本文は出しません。
## アップグレードと保全
初回のみ旧outboxを集計してheadsを作成します。この移行と完了マーカーはtransaction内で行い、途中失敗は再実行できます。次回以降の起動で履歴全件を再集計しません。既存checkpointと旧processed行は保持します。
新しいsequenceの採番は保持されたheadsの最大値から行います。将来の履歴整理でsequenceが巻き戻らないための対策ですが、**outboxの自動削除機能を提供するものではありません**。削除可能範囲には全必須consumerの完了確認に加えて、一意キーの再送抑止用tombstoneが必要です。heads・checkpoint・移行位置・正本DBをまとめてバックアップします。
## 残タスク
- [x] タスクの期限日/計画日通知:正本transactionで予約を更新し、配信時に現在権限・版を再検査。旧outboxイベントから予約を復活させない。
- [ ] 汎用の変更通知consumerと購読設定。
- [ ] consumer別の未処理/失敗表示、再生操作、購読変更時のbootstrap。
- [ ] 多数の失敗Domainがある場合の公平なdispatch、consumer別backoff/dead-letter。
- [ ] Outbox保持ポリシー:必須購読者の進捗、sequenceと一意キーの保全、consumer廃止手続き。
- [ ] 分散lease/fencing。現時点でHA時のexactly-onceを保証しない。
## テスト
購読者間の独立、型での絞り込み、ページング、旧processed行の取得、初回移行/再起動、transaction rollback、無関係イベント1200件の中の対象取得、sequence巻き戻り防止を検証します。サーバー側では、タスク変更でCityジョブが作られないこと、ページ変更では作られること、タスク保存全体のrollback、移行の再開/重複抑止、管理者の停止・間隔設定保持を検証します。運用DB・外部カレンダーは使用しません。