Files
pages/docs/design/ja/task-planning-focus.md
T
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

14 KiB
Raw Blame History

タスクの時間枠とPomodoro

更新:2026-09-25。organizer.tasks v0.5.0 の実装契約。個人タスクの基本設計、期限日/計画日の通知を前提にします。

1. 利用できる画面

/v/plan/today および各タスク画面にPomodoroバーを表示します。集中25分、休憩5分を初期値とし、それぞれ1〜180分の範囲で指定できます。開始/一時停止/再開/終了/中断を提供します。

保存済みタスクの編集ダイアログに以下を追加します。

  • 時間枠をカレンダーへ:カレンダー・開始・終了を指定するモーダル。既存の時間枠の表示、予定詳細への移動、未完了要求の再試行、関連解除。
  • このタスクに集中:タスクに関連付けてPomodoroを開始。タスクに未保存の変更があれば、先に保存するよう促します。

日本語/英語、既存テーマ、PC/スマートフォンに対応します。readonly利用者は状態の表示のみ可能です。完了・アーカイブ済みタスクでは新しい時間枠や関連タイマーを開始しません。タスクに関連付けないタイマーも使えます。

2. 時間枠の意味と境界

タスクの期限日、取り組む日、カレンダーの割当時刻は別の情報です。時間枠の作成・変更・解除によって、タスクの日付・状態・版を自動更新しません。

初版の対象は 自分が所有する、非公開・メンバー未設定・Sourceなしのローカルカレンダー に限定します。公開・共有カレンダー、外部ICS/CalDAV取り込みは除外します。ピッカーはカレンダーのメタデータだけを調べ、外部SourceのURLや資格情報をレスポンスへ含めません。

予定の作成/再取得時は、カレンダーのロック取得後、ICSスナップショットを読む前にこの条件を再検査します。そのためピッカーを開いた後に公開・共有などの設定が変更されても、条件外の予定をタスク連携から読まない設計です。

利用者の明示した方針に従い、新しく作る予定名は Focus time(タスクの件名) とします。作成要求のDB transactionで件名をsnapshot保存し、再試行中にタスク名が変わっても要求の予定名を変えません。改行・制御文字は空白化し、iCalendarのエスケープ/折り返しを適用します。メモ・task UUIDはICSへコピーしません。

後からそのカレンダーを公開・共有した場合、予定に含めたタスク件名も見えることを作成画面に明記します。既存予定の名前は自動変更しません。旧版で作った Focus time や利用者が編集した予定名も、再試行で上書きしません。タスク名の変更による既存予定名への自動同期も行いません。

1タスクにつき有効な関連は最大100件、1枠は24時間以内。フォームはドメインのタイムゾーンを明示し、そのIANA zoneと現地日時を送信します。存在しない夏時間の時刻は拒否します。夏時間終了時の重複時刻はGoのzone解決に従うため、厳密な片側指定が必要なクライアントはRFC3339オフセット付き日時を送ります。

3. 正本と失敗からの回復

予定の正本は従来の月別ICS/calendar manifestです。関連と未完了要求の正本はSQLiteの organizer_time_blocks です。これらを一つの原子的commitであるかのようには扱いません。

  1. DBのwriter transactionで、所有者・現在のmembership・タスクの種類/状態/版・拡張の有効性を確認し、pending要求を記録。
  2. 要求UUIDから決定的に作るevent UIDで、カレンダー側のロック内で「存在すればそのまま、なければ作成」。
  3. DBの関連をactiveへ更新。失敗したらpendingを残し、同じ要求UUIDで再試行。

再試行は既存予定を上書きしません。予定が移動・時刻変更されても、同一calendar UUID+event UIDから現在時刻とETagを取得します。activeな予定が削除されていたら、GETや再試行では再作成せず、利用不可として表示します。

関連解除はunlinked tombstone化で、カレンダーの予定を削除しません。同じ要求の再送は拒否し、関連が復活しないようにします。解除と進行中の作成が競合した場合も、解除した関連をactiveへ戻しません。ただし独立したファイルcommitがすでに進んでいれば、関連のない予定が残る可能性があります。予定削除が必要ならカレンダー画面で確認のうえ実施します。

1つのHTTP要求で全関連のカレンダーデータを走査しません。関連一覧取得はDBのみ。UIは10件ずつ、表示する各関連の現在時刻を逐次取得します。画面を閉じたら続きの取得を止め、各fetchは15秒timeoutです。サーバーの要求処理は5秒timeoutです。

時間枠API

prefix:/_/api/v1/extension/organizer.tasks/

Method / suffix 内容
GET calendars 対象カレンダーのID・名前・pretty_name、ドメインのzone
GET blocks?task_uuid=... 自分のタスクの有効関連一覧(最大100件、初期要求の日時)
GET blocks/{uuid} 現在の時刻・ETag・予定href。参照不可ならavailable:false
POST blocks uuid,task_uuid,task_version,calendar_uuid,start,end,timezoneで作成/再試行
DELETE blocks/{uuid} 関連だけを解除。予定は残す

start/endはRFC3339、またはyyyy-mm-ddThh:mm+IANA timezone。保存はUTCに正規化します。新規作成には現在のタスク版を要求。同じ要求の再試行では、タイトル編集などで版が進んでいても、要求内容が不変でタスクが未完了なら許可します。タスクが完了済みなどの場合は、新規/再試行の作成は止めます。未完了要求自体は一覧から解除できます。

4. Pomodoroの状態と永続化

organizer_focusをセッションの正本、organizer_focus_changesを状態遷移の監査記録とします。タスクの正本・履歴とは分離します。DBをキャッシュとして削除してはいけません。

  • 状態はrunning / paused / completed / cancelled。
  • 1インスタンスの同一Principalにつき、ドメインをまたいでもrunning/pausedは1つだけ。DBの部分UNIQUE索引とwriter transactionで保証。
  • 開始にはクライアントUUID、変更には現在versionを要求。二重開始の再送で開始時刻をリセットしない。古いversionの変更は412。
  • duration、残時間、終了予定時刻を保存し、休止/再開時に計算する。毎秒の書き込みはしない。
  • 異なるドメインに有効なセッションがあれば、そちらで終了させてから新しく開始する。他ドメインのtask UUID等はエラーへ出さない。
  • 権限失効・ドメイン無効化・拡張停止によって他ドメインに取り残された自分のセッションは、新規開始時にrevokedとして中断記録し、利用不能なタイマーが永久に次の開始を妨げないようにする。タスクそのものは変更しない。

GET focusは現在ドメインのactive session、なければ直近のsessionとサーバー現在時刻を返します。POST focusはaction=start/pause/resume/complete/cancel、uuid,versionを受け、開始時にはphase,minutes,task_uuid(任意)を指定します。

ブラウザはサーバー時刻と単調時計を基準に表示を更新し、可視中のみ30秒ごととタブ復帰時にサーバー状態を確認します。非表示中は定期fetchも表示更新もしません。秒表示はDBアクセスを伴いません。別端末での変更は次回取得時に反映され、競合操作は版で拒否します。

終了はタイマーの終了で、タスクの完了ではありません。手動早期終了は残時間を保持します。集中区間は後述のToday画面で日付ごとに集計します。期間別・プロジェクト別の実績ダッシュボードは未実装です。

Todayの見通し(v0.5.0)

GET /_/api/v1/extension/organizer.tasks/todayを追加。日付は任意入力にせず、ドメインのタイムゾーンにおける今日の0時から翌日0時までを対象とします。夏時間の日は固定24時間ではなく、現地日付で区切ります。

  • 未完了タスクの見積もり:今日取り組む、または今日までが期限の未完了タスクの見積分数。現在のToday一覧と同じ定義です。完了済みは含めません。最大100件、超過時は一部集計と表示。
  • 今日の時間枠:activeな関連を持つ個人localカレンダーについて、ロック内で公開・共有・Sourceを再検査してからキャッシュを現行manifestへ合わせ、期間内のeventを関連へJOINします。初期要求の日時では絞らず、後から別の日へ移した予定も現在の日時で判定します。タスクが完了・アーカイブ済みでも、予定が関連付きで残っていれば時間枠に含めます。
  • 記録済みの集中時間:開始/再開から休止/終了までの区間をorganizer_focus_spansへ保存。session更新・監査と同じtransactionなので、失敗時は区間もrollbackします。休憩と休止中の時間は除き、日付境界で切り分けます。実行中の区間は取得時の現在時刻まで、スケジューラの遅延は本来の終了時刻までで打ち切ります。手動中断までに集中した時間は含めます。

時間枠は当日内の合計割当時間と、その和集合による占有時間を別々に計算します。差分を重複として表示します。一般の予定・労働時間帯・空き時間はまだ集計しないため、これを一日の可処分時間や完全なキャパシティ表示とは呼びません。

関連するカレンダーは最大20、各カレンダーの期間内関連は最大100、返す時間枠は全体で最大100、集中区間は最大1000件です。上限超過はpartial flag、参照不可・取得失敗はunavailable件数を返し、不完全な合計を完全な合計のように見せません。本文を表示せず、件名は現在の所有タスクから取得してtextContentで描画します。外部カレンダー内容は読まず、カレンダー拡張停止中は見積もり・集中時間のみ表示します。

UIは初回、手動更新、タスク/時間枠/タイマーの変更、30秒以上後のタブ復帰で取得します。定期的な全カレンダー走査は行いません。重複fetchをまとめ、非表示になれば中断します。秒単位の実績更新ではなく、更新時点の集計と明記します。

移行時は現在runningの区間を現行セッションから補います。旧版ですでに終了・休止した過去区間は自動バックフィルしません。旧履歴の検証付き・限定バッチ再構築はTODOです。区間は索引付きの投影ですが、その再構築機能が完成するまではDBと一緒にバックアップしてください。

5. 終了イベントとInbox

組み込みイベントtask.focus.complete(定義ID builtin.task.focus)を既定60秒・priority -2・再試行3回で登録します。既存設定を再起動で上書きしません。設定画面で停止・間隔変更・手動実行できます。

最大100セッション/回、3秒上限で、state,deadline_ms索引から期限を迎えたrunning sessionを拾います。完了記録・監査・Inbox挿入は同じtransaction。通知の一意キーはセッションUUIDです。再実行でも二重配信しません。

配信時に現在のPrincipal・membership・Domain・拡張の状態を再検査します。無効なら中断扱いで通知しません。終了から24時間以上遅れたものは完了記録だけを残し、古い通知を大量配信しません。手動で終了/中断したセッションにも余分な終了通知は送りません。

Inboxは一般的な「タイマーが終了しました」とタスク画面へのリンクのみ。タスク本文・件名はコピーしません。ブラウザを閉じていてもサーバーが動作中なら処理しますが、終了と同時のOS通知やPushを保証する機能ではありません。既定のイベント間隔とキュー待ちによる遅延があります。

6. 検証と次段階

隔離fixtureで以下を検証します。実際の外部カレンダーの内容は調べません。

  • 時間枠:時差・夏時間gap・古いタスク版・再送・月またぎ移動・予定削除・関連解除・公開/共有後の遮断・件名snapshotとメモ非複製。
  • ファイル保存後のDB更新失敗からの再試行と、外部Sourceの欠損スナップショットに到達しないguard。
  • タイマー:並列開始・版競合・休止再開・重複通知防止・通知挿入失敗のrollback・readonly・失効・拡張停止・遅れた通知の抑制。
  • PC/スマートフォンのChromium:時間枠の作成、予定へのリンク、表示のはみ出し、Pomodoro開始/休止/リロード復元。

残TODO(優先順):

  1. Todayの並べ替え・前日計画の持ち越しと個人キャパシティ設定。期間別/プロジェクト別の実績、旧集中履歴の限定バッチ再構築。
  2. 個人タイマーの既定値、集中/休憩の反復と長い休憩。自動連続開始は明示設定にする。
  3. 時間枠のpending要求の監査/復旧UIを充実させる。永久失敗・tombstone・focus監査の保持/圧縮/exportを設計する。
  4. 個人通知設定とquiet hours、カレンダー予定そのものの通知。
  5. 日課テンプレート・日付別instance、前日計画の持ち越し、複数選択整理。

共有タスク・共同所有カレンダーへの配置・外部カレンダー読み取り・OS通知・CalDAV VTODO同期は今回の対象外です。