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

22 KiB
Raw Permalink Blame History

カレンダー拡張:正本・CalDAV・Plan UI

更新:2026-09-22。既存の「予定・iCalendar・CalDAV・連絡先」のうちカレンダー部分を具体化する。連絡先、タスク、メール、招待配送は別サブプロジェクト。

1. 判断と実装状態

正本を SQLite に置かない。カレンダー単位の manifest と月別 iCalendar ファイルを正本とし、DB は消して再構築できる検索索引に限定する。Wiki Page の HTML 化や revision に予定を埋め込まない。

初期実装は 限定された CalDAV メソッド実装。完全な CalDAV サーバーの適合性を宣言しない。DAV: 1 のみ返し、calendar-access、calendar-schedule、sync-token は未対応のまま広告しない。

項目 初期実装
正本 カレンダーの manifest、月ごとの VCALENDAR/VEVENT
検索 SQLite に domain/calendar/UID・開始/終了・ETag を索引化
日時 UTC DATE-TIME、終日 DATE、DTEND は排他的
保存 未知の VEVENT property を保持。UI編集は対象フィールドのみ更新
並行更新 強い ETag の条件付き更新、競合時412、無条件更新428
UI 年・月・週・日・起点31日一覧・水平タイムライン、詳細・作成・編集・削除
共有 所有者、ユーザー単位 read/write、明示的な匿名公開
無効化 system extension organizer.calendar の既存スイッチ

ローカルCRUDと正本の1予定表現では、RRULE/RDATE/EXDATE/RECURRENCE-ID、TZID/VTIMEZONE、floating時刻、DURATION、VALARM、VTODO、METHOD による scheduling を入力拒否する。外部購読に限り、検証済みのVTIMEZONE/TZIDと単一RRULEを有限期間のUTC/DATE予定へ射影する。受理後に検索から消えたり、繰り返しが単発予定に化けたりしないことを優先する。例外予定などの未対応が残るため、一般のカレンダーアプリを無制限に接続できる段階ではない。

2. URI

UI

  • /v/plan:最後に開いた表示種別の現在日。表示履歴がなければ現在週。
  • /v/plan/cal/yyyy:年。
  • /v/plan/cal/yyyy/mm:月。
  • /v/plan/cal/yyyy/mm/dd:日。
  • 同上の /week:月曜から日曜、その日を含む週。
  • 同上の /events:その日から31日間の一覧。
  • 同上の /timeline:その日の時間を左から右に配置。
  • 同上の /new:その日を初期値に新規予定ダイアログ。
  • /v/plan/event/{UID}:予定詳細。
  • /v/event/new、/v/event/{UID}/edit:指定どおり作成・編集。
  • /v/calendar:/v/plan への互換入口。

複数カレンダー選択は ?calendar=work,personal のように pretty_name をコンマで連結する。各名は個別にURLエンコードし、区切りのコンマはそのままとする。表示設定ダイアログで複数選択・自分の既定値を保存できる。既定値はドメイン内のユーザー単位で、内部UUIDの配列をファイル preferences/{principalUUID}.json に保存する。無指定時は可視な既定値を使い、未設定・すべて失効した場合のみ可視な先頭カレンダーへフォールバックする。既定値による移動ではクエリを追加しない。匿名利用は個人設定を持たない。

pretty_name はドメイン内で一意(大文字小文字だけ違う名前も重複)。Unicode NFCの文字/数字、-、_ が使用でき、空白・コンマ・スラッシュ・UUIDそのものは不可。最大120バイト。別途 name は自由な表示タイトルとして保持する。月別iCalendar正本の NAME(RFC 7986 §5.1)、CalDAV collectionのdisplaynameにはpretty_nameを使う。VEVENT単体のUID/ETagやDAV資源hrefは名前変更の影響を受けない。名称の重複チェックはドメイン単位のlockで直列化する。

旧データのpretty_nameは calendar-{UUID} を安全な初期値とし、歯車から変更可能。旧UUIDクエリは互換受付してpretty_nameへ置換する。UUIDを保持する既定設定と予定所属はrenameに追従する。外部に配布した旧pretty_nameリンクのリダイレクトは未提供。

UIDはカレンダー内で一意。別カレンダー間に同じUIDがあり得るので、生成する詳細リンクはその予定のpretty_nameを1つだけ含める。複数表示の新規予定では、書込可能なカレンダーから作成先を選ぶ。Wiki Pathのrenameは予定UIDに影響しない。

プロトコルと管理API

CalDAV入口:/_/api/v1/caldav/。既存のジョブ /_/api/v1/event/ と混同しない。

2026-09-26更新:organizer.calendar 0.2.0で専用Basic認証・共通principal探索・初回全件同期・CLI resource名を追加。予定・タスク共通CalDAVが追加契約。以下の旧仕様に対しcollectionのDepth 1、上限付き全件REPORT、CLI指定filename、JSONイベント取得の?resource=が追加される。UTC/DATEに限定する書込プロファイルは維持する。

URI 操作
DAV root OPTIONS、PROPFIND Depth:0/1(可視カレンダー)
/{calendarUUID}/ PROPFIND Depth:0、REPORT calendar-query / calendar-multiget
/{calendarUUID}/{base64url(UID)}.ics GET/HEAD、PUT、DELETE
/_/api/v1/extension/organizer.calendar/calendars GET一覧、POST作成
同上 /{calendarUUID}/settings PUT 設定/DELETEカレンダー、manifest version必須
同上 /{calendarUUID}/events GET ?uid=、POST作成/編集
/_/api/v1/extension/organizer.calendar/event?uid= 可視カレンダーからUID解決。複数一致は409

UIDは任意のテキストなのでDAVのファイル名へ直接使わずbase64urlにする。絶対URLのhrefや別カレンダーへのmultigetは受理しない。全件無制限のDepth:infinityやREPORTは提供しない。現在は作成を管理JSON APIで行い、MKCALENDAR/PROPPATCH/ACLは後続。

3. ファイルと障害復旧

documents/calendars/{domainUUID}/{calendarUUID}/
  calendar.json
  .lock
  2026-09.{sha256}.ics
  2026-10.{sha256}.ics

calendar.json は名前・所有者・公開設定・メンバー・version・月→ファイルSHA-256対応を持つ。月別ファイルは世代ごとに不変。VEVENTは開始月へ収納し、月をまたぐイベントは分割しない。

変更順序:カレンダーのプロセス間lock取得 → 現manifestとETagを確認 → 変更月の新ファイルを書きfsync → manifestをatomic renameしてディレクトリfsync → 未参照の旧世代を清掃。

9月から10月へ予定を移動する場合も、両月の新ファイルを準備してからmanifestを一度だけ置換する。中断した未参照ファイルは次の成功時に清掃する。過去世代を無限に保持する履歴設計にはしない。正本バックアップはmanifestとその参照先を一組で取得し、稼働中はlockと協調する必要がある。

DB表は calendar_index_state、calendar_month_cache、calendar_event_cache。manifest versionが変わったときだけ、hashが変わった月を索引へ反映する。DB反映前の中断は次回アクセスで修復する。DBだけが最新になりファイルが古い状態を正本とはしない。復旧時は3表を一緒に破棄し、正本から再構築する。

手動でICSを書き換える運用は未提供。hash名のファイルを直接編集しない。キャッシュ再構築時にはSHA-256を検証する。正本ファイルのACLは0600、ディレクトリは0700。HAの複数ノード同時書込やネットワークFSのロック保証は別途検証する。

4. 取得・キャッシュ・負荷

フロントエンドは対象期間の calendar-query でgetetagのみ取得。タブ内メモリのETagと一致する予定は再取得しない。変更分だけJSONの予定投影を取得し、同時取得は最大4件。独自にREPORTへ304を返す実装はしない。ICS GETではIf-None-Match/304を利用可能。

月をまたぐ予定は開始月のファイル列挙ではなく、DBの開始/終了の重なりで取得する。ゼロ時間の予定は開始時点が期間内なら一致。DATEとUTC日時を表示時に混同しない。UIの時刻入力・表示・日境界はドメイン設定のタイムゾーンを用い、正本はUTCで保存する。DSTで存在しない時刻や二重になる時刻をドラッグ操作で暗黙補正せず、編集画面で再指定させる。DATEの検索境界差を補うためUIのREPORTは前後1日を加え、描画時に絞る。

週・日ビューは67〜400%の6段階で時間軸を拡縮する。100%以下は15分、200%は10分、300〜400%は5分単位で移動・リサイズする。予定中央のドラッグは長さを保った移動、上端は開始、下端は終了の変更である。同時刻帯で重なる予定は最大同時数分の等幅laneへ配置する。短い予定には操作可能な最低表示高を確保し、その表示領域同士も衝突しないlaneへ分ける。保存成功時はAPI応答の予定だけをタブ内集合へ反映してlaneを再計算し、期間REPORTや予定全件を再取得しない。時間列の空白をドラッグすると設定タイムゾーンの選択範囲を入力済みの新規予定ダイアログを開き、クリックだけでは作成しない。

上限:ドメイン256カレンダー、1資源256KiB、XML64KiB/深さ12、月5000件/16MiB、期間370日、結果5000件、multiget200件、lock待機5秒。超過は部分成功にせずエラー。ETagだけのREPORTは本文をparseしない。永続ブラウザキャッシュや共有CDNへの予定保存は行わない。権限を確認してから304・本文を返す。

5. 権限

カレンダー所有者が名前・公開設定・collaboratorを管理する。collaboratorは同じドメインの有効なユーザーで、read または write。writeには予定作成・変更・削除を含むが、共有設定の変更は含まない。readonlyアカウントの書込は不可。グループ共有・所有権移管・管理者による復旧は後続。

カレンダー全体の削除も所有者だけが行う。設定ダイアログで全予定を含む完全削除を確認し、DELETE .../settings に現在のmanifest versionを渡す。古いversionは412とし、削除対象の外部同期ジョブはqueuedなら取消、runningなら取消要求を付ける。正本ディレクトリを原子的に不可視化して削除し、SQLiteの3索引表を消す。ユーザー既定値に残ったUUIDは毎回の可視性検査で除外される。実行済みジョブ履歴とログは監査情報として削除しない。

匿名公開はカレンダー全体を対象とし、説明・場所を含めて公開する旨をUIで告知する。既存のドメイン公開上限がpublic、ドメイン有効、authorization_mode=enforcingのときだけ有効。上限を閉じれば次の取得から匿名アクセスを拒否する。公開範囲の狭い予定を混在させるには別カレンダーを使う。VEVENTのCLASSだけをアクセス制御として扱わない。

Page公開とは別の正本なのでCityのSpot/Pathへ暗黙に従属させない。将来Pageへの関連付けをしてもPage参照権限と予定権限は別途評価する。

6. RFC対応の検証と残タスク

基準:RFC 5545 / RFC 4791。パーサーは github.com/emersion/go-ical を固定バージョンで使用し、アプリ側でDTSTART必須、UTC/DATE、排他的DTEND、UID、不支持property、制御文字、必須項目を追加検証する。出力はCRLF・UTF-8を分断しない75octet折返し。ライブラリ採用だけをRFC適合の証明にはしない。

  • 単発UTC/終日、未知property保持、月境界、同時更新、キャッシュ再構築、公開取消の回帰テスト。
  • Plan各ビュー、期間REPORT、差分取得、設定・予定ダイアログ、所有者限定のカレンダー完全削除。
  • 外部購読用のTZID/VTIMEZONE(IANA、主要Windows名、定義内のSTANDARD/DAYLIGHT)と夏時間fixture。
  • ローカル正本でのTZID/VTIMEZONE/floating対応、DURATIONの暦日演算。
  • bounded recurrence展開、EXDATE/RDATE、RECURRENCE-ID例外、時間範囲オーバーラップ、件数・本文量・対応頻度によるCPU/メモリ上限。
  • 標準XML precondition/error、PROPFIND/PROPPATCH/MKCALENDARの適合性、principal discovery、/.well-known/caldav、Depthと未知filterの完全な検証。
  • アプリ専用の失効可能なCalDAV credential、権限のread/writeスコープ、クライアント適合試験(現状は既存session Bearer)。
  • collection sync-token、tombstone保持と期限切れの再同期。現状は期間REPORTが正しい集合を返す。
  • バッチmultigetの単一索引snapshot化、大量calendarの一覧ページング、UI期間ごとのvirtualization。
  • 専用ジョブとしてreindex/検証/容量統計、イベント資源監視、管理者向けバックアップ・restore・所有権復旧。
  • グループcollaborator、イベントごとのvisibility、承認Inbox、共有変更監査、変更通知。
  • 招待・参加回答・リマインダーはCRUDとは別のevent/scheduler連携。iTIPメール配送を無断で有効にしない。
  • 外部ICSの条件付きGET購読、外部CalDAVの期間REPORT/差分multigetによるread-only同期(下記制約あり)。
  • 外部連携のdiscovery、OAuth、sync-token、取得期間の設定、競合UI付きの双方向同期。

完全なCalDAV適合性・繰り返し対応の完了までは「一般クライアント互換」の完了チェックを付けない。

7. 今回の検証記録

  • go test ./internal/calendar ./internal/server -run 'TestCalendar|TestPolicyForRequest':成功。
  • Chromium:月・週・timeline・詳細の描画、設定タイムゾーン、400%/5分ズーム、中央移動、上下端リサイズ、重複予定の等幅配置、ダイアログによる作成/編集/削除、カレンダー名の変更、ETag一致時の本文再取得抑止を確認。
  • 全体テストは TestConfigBookmarksSaveAndPanelRegistry が既存設定画面の config-form-table に横スクロールコンテナがないとして失敗。カレンダー画面には当該テーブルは追加していない。別UIタスクとして調査・是正する(テストを緩めない)。

8. 時間軸の操作

終日の入力・詳細表示では終了日を含む。同日開始・同日終了で1日の予定を作成できる。保存時だけ終了日にUTC暦日を1日加算し、編集・表示時には1日戻す。正本ICSとAPIのDTENDはRFC 5545の排他的境界を維持する。既存データの移行・外部予定の書換は不要。

トップバーはCity・直近の予定・通知・プロフィールの並び。直近の予定は既定カレンダー(未設定なら先頭1件)の今日から31日間を最大20件表示する。GET /_/api/v1/extension/organizer.calendar/upcoming?date=yyyy-mm-dd はログイン必須、毎回権限確認、no-store、5秒上限、カレンダー毎20件の本文取得上限を設ける。モーダルを開いたときだけ取得し、閉じたら中断する。通知と予定は背景スクロールを抑止した中央モーダルで、Escape/閉じるボタンに対応する。

日・週ビューは縦の時間軸、timelineは横の時間軸に予定を表示する。従来の週リストは /v/plan/cal/yyyy/mm/dd/week/list とし、先頭行に曜日を表示する。日・週の尺度は40/60/90/120 px/時から選択できる。

最後に開いた年・月・週・週リスト・日・timeline・予定一覧の表示種別だけをPrincipal単位でブラウザへ保存する。予定本文、カレンダー名、選択日、資格情報は永続化しない。予定の新規作成後は詳細画面へ遷移せず、作成を開始した表示種別と基準日へ戻して再取得する。新規作成専用URLから開始した場合も、保存済み表示種別(未保存なら週)へ戻る。

書込可能な予定の移動ハンドルをドラッグすると15分単位で日時を変更する。日・週では上下キー、timelineでは左右キーでも移動可能。期間の長さを保持し、Escapeでドラッグを取消す。存在しない/曖昧なローカル時刻への日・週移動を拒否する。保存は既存ETag付きAPIを通し、競合時には上書きしない。終日・外部読取専用の予定にハンドルは表示しない。ブラウザ試験で縦横の実マウス操作とキーボード操作を検証する。

9. 外部カレンダーの読み取り同期

新しい空のカレンダーを作り、所有者が「外部同期」ダイアログでICS URLまたはCalDAVコレクションURLを設定する。取得間隔は1分〜7日、手動同期・停止を提供する。外部同期を停止しても、取得済み予定と読み取り専用属性は保持する。双方向同期や、既存のローカル予定への混在取込は行わない。公開・collaborator設定は取込先の設定に従うため、私用フィードは非公開カレンダーで利用する。

  • API:PUT /_/api/v1/extension/organizer.calendar/calendars/{UUID}/source で設定、同じURIへの POST で手動キュー投入。所有者限定、設定更新はmanifest version必須。
  • 組込イベント calendar.source.sweep が60秒ごとに期限を確認し、calendar.source.sync を低優先度・カレンダー単位の重複抑制付きでキューへ投入する。実行状態・ログは既存イベント管理に統合。UIを開く必要はない。間隔は次回取得の目安でありキュー混雑により遅れる。
  • ICS:ETag/Last-Modifiedを条件付きGETに利用する。304では予定を再書込しない。
  • CalDAV:過去90日〜未来275日のREPORTでgetetagを取得し、変更分のみ100資源単位のcalendar-multigetで取得する。期間外はローカル投影に保持しない。コレクションURLを直接指定し、discoveryはまだ行わない。
  • 完全な応答を検証してから全月snapshotとmanifestを更新する。取得失敗、未対応形式、部分的なmultiget、途中で変わったETagでは前回の予定を保持。正常な空集合は削除として反映する。安定したUID順で保存し、応答順の変化による書換を避ける。
  • 上限:ICS本文8MiB、CalDAV各応答8MiB・予定本文合計8MiB、5000件の射影予定、ジョブ50秒。Outlookで約10秒かかる応答を許容するため、response header 25秒・HTTP全体45秒とする。2.6MiB超・4500件の合成fixtureを回帰試験に含める。
  • Outlook公開ICSの METHOD:PUBLISH、X-WR-CALNAME、VTIMEZONE/TZID、単一 RRULE、Microsoft固有X-propertyを受理する。主要Windows TZIDはIANAへ対応付け、それ以外はSTANDARD/DAYLIGHTとTZOFFSETTOの遷移を同期期間について解決する。RRULEは過去90日〜未来275日の各予定へ安定UIDで展開し、内部正本はUTC/DATEのまま維持する。X-MICROSOFT-CDO-ALLDAYEVENT:TRUE のローカル午前0時境界はDATEの終日予定へ変換する。
  • Outlookが出力する DTSTART == DTEND の時刻予定はゼロ時間予定として保持し、同じ境界のMicrosoft終日予定だけは排他的終了を翌日に正規化する。終了が開始より前、またはDATEとDATE-TIMEが混在する場合は予定内容をログへ出さず同期全体を失敗させる。
  • 外部購読の解析済みプロパティ値・パラメータに混入したC0(タブを除く)、DEL、C1制御文字は正本化の前に除去し、予定へ X-PAGESWIKI-SANITIZED:CONTROL-CHARACTER 相当の印を残す。ローカルCRUDの厳格な入力検証は緩和しない。NUL、不正UTF-8、制御文字を含むUIDは同一性・構文破壊を避けるため購読全体を拒否する。
  • RDATEとEXDATE(DATE/DATE-TIME、複数値)、RECURRENCE-IDによる移動・内容変更・取消を親RRULEへ合成する。例外の出力UIDは元のRECURRENCE-IDから安定生成し、移動後も同一インスタンスとして扱う。EXDATEと変更例外が同一回を指す場合は明示的な変更例外を優先する。
  • 購読射影が親RRULEを省略し、RECURRENCE-ID 付きの変更回だけを含む場合は、取消回を無視し、DTSTARTを持つ回を元のRECURRENCE-ID由来の安定UIDで単発射影する。親がないためDTEND省略時の長さは推測せずゼロ時間予定とする。
  • RDATEのPERIOD、RECURRENCE-IDのRANGE=THISANDFUTURE、DURATION、VALARM、floating時刻はまだ未対応。部分的に欠落させずフィード全体を同期エラーにし、前回snapshotを保持する。現段階でOutlookの全機能や一般プロバイダへの完全対応は宣言しない。
  • 同期失敗はcompose logへdomain UUID、calendar UUID、protocol、処理段階、安全化した理由を出す。購読URL、認証情報、UID、タイトル、説明、場所、ICS本文はログへ出さない。
  • HTTPS/443の公開アドレスのみ許可する。接続時DNS検証と接続IP固定、プライベート/loopback/link-local等の遮断、リダイレクト再検査、環境proxy無効によりSSRFを防ぐ。認証付きリダイレクトは同一origin限定。
  • 任意のBasic認証資格情報は既存認証鍵を用いた暗号化とdomain/calendar束縛で保存し、APIに再表示しない。URLに購読トークンを含む場合は保護された0600のmanifestに保存される。URL/認証情報をジョブpayloadに入れず、取得エラーを秘匿化する。バックアップには正本に加えて認証暗号鍵も必要。

実プロバイダ接続試験、より広いiCalendar形式、資格情報更新・失効の監査、同期専用の容量/CPU指標、取得対象の管理者allowlistは後続タスクとする。