Files
pages/docs/design/ja/tasks-implementation.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

106 lines
13 KiB
Markdown
Raw 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.
# タスク管理拡張:実装契約と次段階
更新日:2026-09-25。個人用タスク・プロジェクト、明示ONの期限日/計画日通知、個人ローカルカレンダーへの時間枠、永続化Pomodoroを実装。0.7.0で[日別計画・親子グループ・Wikiメモ](task-daily-notes.md)を追加(2026-09-25 07:07 JST本番反映済み)。共有・一般のカレンダー予定通知・CalDAVタスク同期の完成を意味しません。[タスク通知の契約](task-reminders.md)、[時間枠とPomodoro](task-planning-focus.md)も参照してください。
## 今回利用できる機能
2026-09-25追記:`0.8.0`で[個人タスクのCalDAV/CLI連携](task-caldav.md)を実装。専用資格情報、限定VTODO、vdirsyncer/Todoman同期、ETag/CASに対応。2026-09-26 00:24 JST本番反映済み。時刻付き期限・繰り返し・共有・フルCalDAV適合は未対応。
- 今日:ドメインのタイムゾーンにおける今日の計画、今日が期限または期限超過の未完了タスク。
- 取り込み箱/Backlog/いつか:取り込んだものを消さずに整理先を変更。
- 見直し:見直す日を迎えたもの、または30日間変更されていない未完了タスク。
- プロジェクト:名前とメモ、関連Wiki、所属タスクの一覧。タスクは一つのプロジェクトへ所属、または未所属。
- タスク:件名、プレーンテキストのメモ、状態、優先度、分単位の見積もり、期限、取り組む日、見直す日、関連Wiki。
- 完了/再開、アーカイブ/復元。完了取消でも過去の版は残る。初版は物理削除を提供しない。
- タイトル絞り込みとカーソルページング、変更履歴の版番号・日時表示。
- 日本語/英語、既存テーマ、デスクトップの左ナビとモバイルの横ナビ・全画面編集モーダル。
取り組む日は日付のみであり、カレンダーの時間枠ではありません。予定イベントの複製や外部カレンダーの読み取りは行いません。プロフィールメニューの「タスク」とカレンダー画面から到達できます。
## URIとAPI
| 用途 | URI |
| --- | --- |
| 今日 | `/v/plan/today` |
| 全未完了 | `/v/plan/tasks` |
| 整理先 | `/v/plan/tasks/{inbox,backlog,someday,review,done,archived}` |
| プロジェクト | `/v/plan/projects`、`/v/plan/project/{uuid}` |
| タスク詳細・新規 | `/v/plan/task/{uuid}`、`/v/plan/task/-/new` |
| API一覧・作成 | `/_/api/v1/extension/organizer.tasks/items` |
| API取得・置換 | `/_/api/v1/extension/organizer.tasks/items/{uuid}` |
| 最近50版の履歴 | `/_/api/v1/extension/organizer.tasks/items/{uuid}/history` |
`/v/plan` のカレンダー既定ビューは変更しません。既存カレンダーの広いprefixよりタスクの厳密なルートを優先します。プロジェクトは初版ではUUID URIです。pretty nameを後付けしても同一性はUUIDを維持します。
一覧GETは `kind=task|project`、`view`、`project`、`q`、`limit`、`before` を受け付けます。既定60件、上限100件。作成はPOST、更新はPUT、`If-Match: "{version}"` 必須。ヘッダーなしは428、古い版は412。UUIDをクライアントで生成し、同内容の作成再送は同じ版を返します。異内容の再送は競合です。成功時は `item` と現在読める `page_path`、ETagを返します。一覧はメモ本文を省略するため、編集やクイック完了前に必ず詳細を取得します。
## 保存と復旧の境界
`organizer_items` はDomain・所有者・UUID・種類・検索用メタデータ・現在版を保持します。本文を含む型付きJSONは既存Document StoreへSHA-256で保存し、同じJSONをDBにも保持します。`organizer_revisions` は版からDocumentへの参照、`organizer_changes` は後続処理用の小さな変更ジャーナルです。head更新・履歴・変更ジャーナルは同じSQLiteトランザクションです。
これは通常のWiki Objectではありません。Wiki Objectに直接載せると、既存の汎用閲覧・リンク操作・削除経路すべてにタスク所有権の導入が必要になるため、初版は専用の権限境界に隔離します。Wikiとの関連はPageのObject UUIDです。Pathは読むたびに同じドメイン内の閲覧可能なaliasから解決し、renameへ追従します。関連ページの権限が失効しても、タスクを読む権限がWikiを読む権限を上書きしません。
**タスクDBは捨てられるキャッシュではありません。** 所有権・current head・版参照を含むSQLiteとDocument Storeを一緒にバックアップします。単独ファイルから全メタデータを復元するインポート/再構築ツールは未実装です。DBロールバック前に保存されたCASファイルは孤立する場合がありますが、headには現れません。将来のCAS GCでは `organizer_revisions.document_hash` もmark対象に含める必要があります。
2026-09-24追記:共通outboxへの接続を実装しました。タスク/プロジェクト保存は `organizer.task.changed`/`organizer.project.changed` を同一transactionに追加します。本文・件名・期限・Wiki Pathは複写せず、対象UUID・actor・版番号・変更時刻を記録します。Cityは必要なイベント種別のみ購読し、他consumerの完了状態を変更しません。
旧 `organizer_changes` は削除せず、`task.activity.publish` が1回100件・3秒上限で既存記録を共通outboxへ移行します。既定60秒間隔・低優先度・再試行3回で、イベント設定画面から停止・間隔変更・手動実行が可能です。既存の設定値は再起動で上書きしません。新規保存分も同じ一意キーで確認するため二重イベントを作りません。これはデータ移行・修復用の内部ジョブで、タスク拡張のON/OFFとは独立して停止できます。通知送信やカレンダー読み取りはしません。
変更記録の保存は通知の配信完了ではありません。タスク期限日/計画日の予約は、正本と同一transactionで更新し、[別の配信ジョブ](task-reminders.md)で現在権限・最新状態・重複防止を検査してInboxへ送ります。移行された旧版outboxイベントから通知予約を再構築しません。汎用の購読者向け変更通知と保持期間は次段階です。[購読・復旧契約](outbox-delivery.md)も参照してください。
## 権限と制限
- 登録済みPrincipalと現ドメインの有効membershipが必須。配置先がlocalの有効Domainだけで保存・取得する。legacy認証モードでも匿名は利用不可。
- 初版は個人所有。domain_adminも他人のタスク一覧・詳細・履歴を取得できない。
- activeは読み書き、readonlyは読み取りのみ。失効・suspended membership・無効Domainは拒否。保存時に同じwriterトランザクションでも再検査する。
- `organizer.tasks` は既存のシステム拡張設定で無効化可能。UI/APIを閉じ、保存層でも無効化を検査。データは削除しない。
既存CLIの対話シェルでも `extension organizer.tasks off`/`extension organizer.tasks on` で切り替え可能。
- Wiki関連付けは同ドメインの実在Pathと現在の読み取り権限が必要。参照先が削除・非公開化されればリンクは表示しない。
- プロジェクトは自分の同ドメインのもののみ指定可能。アーカイブされたプロジェクトへの新たな振り分けは不可。既存の所属タスクを勝手に消したりアーカイブしない。
- 件名300 UTF-8 bytes、メモ16 KiB、JSONリクエスト32 KiB、一覧100件、履歴50件、API処理5秒の上限。権限ごとのキャッシュを混在させずno-store。
- メモはプレーンテキスト。HTML/JSとして実行しない。プロジェクト選択は名前で検索、最大100候補。任意の本文全件取得や全カレンダー取得は行わない。
## 次の実装順序
### T2:Backlogと協働の改善
- [x] アーカイブ一覧でタスク/プロジェクトを切り替え、プロジェクト詳細の設定から復元。
- [x] 日別/明日の計画、昨日以前からの持ち越しの明示的な再割当て、親子グループ順・展開、Wikiメモの新規作成/閲覧/編集。
- [ ] 任意の並べ替え、日別キャパシティ表示。期限を勝手に変更しない。
- [ ] 複数選択の整理/プロジェクト振り分け、チェックリスト、保存検索、ラベル。
- [ ] 一覧のタイトル部分一致が大規模化した場合のFTS索引。操作ごとの件数・時間・失敗数の拡張別監視。
- [ ] 機械可読export/import、ジャーナルと版の保持・復旧手順。
- [ ] collection単位の所有者/編集者/閲覧者。担当への指定と閲覧権限を分離。プロジェクトとWikiの権限を混同しない。
### T3:カレンダーと通知
- [x] イベント種別とconsumerごとのoutbox進捗、タスク変更の原子的な記録、既存ジャーナルの限定バッチ移行。
- [x] 個人タスクの期限日/計画日の明示ON通知。原子的予約・取消、限定バッチでのInbox配信、現在の権限による表示。
- [x] `organizer_time_blocks`:task UUID、calendar UUID、event UIDで関連付け。個人非公開localのみ、現在時刻・ETag取得、同一要求の再試行、関連解除。dueと時間枠を分離。
- [x] Todayへタスクに関連した個人local時間枠を当日限定で投影。現在の予定日時で集計し、重複・件数制限・参照不可を明示。外部取り込み内容は扱わない。
- [ ] カレンダー通知を共通Inboxへ追加。タスク分の予約更新/取消・権限再検査は実装済み。
- [x] タスク通知は発火時刻索引から最大100件を取得。一意キーは通知機会(日付・時刻・zone・種類)、版番号は現在版照合に使う。タイトル変更では再送しない。
- [ ] 通知設定:ドメイン既定+個人既定+個別上書き、quiet hours、過去の大量未配信は要約、Inboxと赤丸の挙動は既存設計へ統一。
### T4:Pomodoro・日課
- [x] focus sessionをタスクから独立した記録にし、開始/休止/再開/終了/中断を監査。1ユーザー1つのactive sessionを条件付き更新で保証。
- [x] ブラウザ表示はサーバーの終了予定時刻・残時間から復元し、毎秒DB書き込みをしない。別端末・リロード・バックグラウンドで継続可能。終了は組み込みイベントからInboxへ通知。
- [x] 集中25分/休憩5分の初期値を画面で変更。通知はInboxのみで、OS通知はしない。
- [x] Todayに未完了タスク見積もり・時間枠・記録済み集中時間を別集計。休止・休憩を除外し、日付またぎを分割。
- [ ] 個人既定値・反復サイクル・長い休憩、期間別実績、旧集中履歴の限定バッチ再構築。
- [ ] 日課テンプレートと日付別instance。完了から次回生成するルールは一意キーで再実行可能にする。繰り返しタスクを単一レコードの日時上書きで消費しない。
### T5:標準連携・高度な管理
- [x] 個人タスクの限定VTODO/CalDAV、専用資格情報UI/API、vdirsyncer/Todoman同期試験。カレンダーVEVENTの完了とタスク完了を同一視しない。[契約・残件](task-caldav.md)。
- [ ] 時刻付き期限・繰り返し・共有・sync-token・追加クライアントの互換性。
- [ ] 親子タスク/依存循環検出、週次レビュー、チケットqueue/受付番号/workflow。
- [ ] モバイルのオフラインキューと競合UI、ショートカット、押下しやすい複数操作。
## 受け入れ試験
`internal/server/tasks_test.go` は個人/Domain境界、readonly・membership失効、kill switch、版競合、作成再送、完了取消の履歴、保存途中のロールバック、日付検証、ページング、プロジェクト参照、Wiki rename追従を検証します。
`PAGESWIKI_BROWSER_TEST=1` の `TestTasksChromium` は隔離されたDB・HTTPサーバーでデスクトップ/モバイルの実操作を検証します。運用中の外部カレンダー・予定本文にはアクセスしません。