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.
This commit is contained in:
1 parent
288e6e94ac
commit
c1175d389f
699 files changed
+110197
-4117
No files matched your search
@@ -0,0 +1,61 @@
|
||||
# アクティブ通知とWeb Push
|
||||
|
||||
更新:2026-09-25。実装・隔離fixture検証済み。同日05:59 JSTに本番2インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)。実機Push受信確認は未実施。
|
||||
|
||||
## UIと設定
|
||||
|
||||
通知ベルを開いたInboxの「⚙ 通知設定」に集約する。アカウント・ドメイン・ブラウザごとにlocalStorageへ保存し、他ユーザの設定を継承しない。通知本文はlocalStorageに保存しない。
|
||||
|
||||
| 状態 | 動作 |
|
||||
| --- | --- |
|
||||
| フォーカス中 | 右下に8秒で消えるトースト。最大3個。入力フォーカスを奪わない。既定ON |
|
||||
| 別タブ・別ウィンドウ/タブ終了 | 明示的に許可した端末へWeb Push。OSの通知UIを使用 |
|
||||
| 再訪 | 前回訪問以降の未読がある場合、設定ONならInboxを自動表示。既定OFF |
|
||||
| ダイアログ・入力を操作中 | 自動Inboxは保留し、次の確認時まで待つ |
|
||||
|
||||
新着は30件ずつ取得し、Inboxは「さらに表示」でページングする。訪問watermarkはサーバー時刻を使う。Web Locksと通知UUIDの短い履歴(最大200個)で複数タブのトーストを抑制する。Web Locks非対応時はbest effort。
|
||||
|
||||
音は「なし/ソフト/チャイム/ベル」と音量・試聴。Web Audioはブラウザの自動再生制限に従い、利用者の操作後に有効になる。カスタム音はフォーカス中のページ通知用。背景/タブ終了時の音はOS設定で決まり、サイト側から任意の音に置き換えることは保証しない。
|
||||
|
||||
ブラウザの通知許可は設定操作時のみ要求する。HTTPSと対応ブラウザが必要。iOS等はホーム画面への追加など端末側の条件もある。サービス・省電力・通信・キュー待ちに依存するため、定刻到達を保証するアラーム用途ではない。
|
||||
|
||||
## 配信経路と安全性
|
||||
|
||||
`notification_inbox`挿入のDB triggerで`notification_push_queue`へ原子的に追加する。Inboxの全種類(タスク期限・計画日、Pomodoro、アナウンス等)で同じ経路を使う。購読開始前の通知を一斉再送しない。
|
||||
|
||||
`/_/api/v1/notifications/push`:
|
||||
|
||||
- GET: VAPID公開鍵のみ。秘密鍵はDB内部に保存。
|
||||
- POST: PushSubscription、focused、seen(最大30通知ID)。購読更新/閲覧中のack。
|
||||
- DELETE: 現在の利用者が所有する購読を削除。
|
||||
|
||||
購読はDomain・Principal・**元の認証セッションのハッシュ**に束縛する。Bearer tokenは保存しない。配信時にセッション期限/失効、Principal、membership、Domain配置を再確認する。ログアウト後や無効化後は送信しない。最大8購読/利用者・Domain、30日lease(閲覧時に更新)。
|
||||
|
||||
VAPID秘密鍵は`notification_push_keys`に保存するため、DBバックアップを秘密情報として扱う。鍵を失った復旧では再購読が必要。端末の購読URL・鍵・通知本文をログへ出さない。
|
||||
|
||||
送信先はChrome/Chromium FCM、Mozilla Push、Apple Web Pushに限定。HTTPS/443のみ、資格情報・fragmentを拒否し、公開IPをDNS解決後に固定する。proxy環境変数とredirectは使用しない。プライベートIPへの接続は禁止する。Push本文は暗号化された通知UUID/受取人UUID/Domain UUIDのみ。件名・本文をPushサービスへ送らない。OSに表示するのも一般的な「新着通知」のみ。クリック後に通常の認可されたInboxで詳細を表示する。
|
||||
|
||||
Service Workerは`/static/js/notifications-worker.js`、scopeは`/static/js/`。fetch handlerやページキャッシュを持たず、既存のWikiページ/エディタに古い内容を返さない。notificationclickは同一originの`/v/notification`だけを開く。
|
||||
|
||||
## スケジューラと上限
|
||||
|
||||
イベント`notification.push.deliver`、定義`builtin.notification.push`。既定30秒、priority -3。設定画面のイベント設定から停止・間隔変更・手動実行でき、再起動で既存設定を上書きしない。
|
||||
|
||||
- 最大20件/run、全体25秒、送信要求5秒。DB transaction内でネットワーク通信しない。
|
||||
- 60秒のclaim lease。期限切れを再取得できる。クラッシュ時はat-least-onceだが、ブラウザ通知tagを固定し積み上げない。
|
||||
- 429/5xx/通信失敗は指数backoff、最大5試行。404/410は購読を削除。
|
||||
- キューの有効期間24時間、Push側TTL300秒。期限切れキュー削除は最大500件/run、期限切れ購読削除は100件/run。
|
||||
- フォーカスlease90秒。閲覧中は送信を延期し、ブラウザが一覧を受け取った通知のackでキューを消す。表示できなかったままタブが閉じればlease終了後に再評価する。
|
||||
- 前面pollは30秒。Pushが有効な背景タブは定期pollを停止し、Pushと復帰を契機に更新する。
|
||||
- sent/failed集計をイベントログへ記録。再送でもInbox本体は複製しない。
|
||||
|
||||
フォーカスを失う瞬間やネットワーク遅延にはraceがあり、OS通知を完全に抑制する保証はしない。常に通知権限とOSの設定が優先する。
|
||||
|
||||
## 検証・残TODO
|
||||
|
||||
- Go: 原子rollback、claim重複防止、focus延期とack、他人のack拒否、失効後の配信遮断、backoff、購読API認証、公開鍵のみ、送信先とP-256鍵検証、イベント設定保持。
|
||||
- Chromiumの合成fixture: 前面トースト、再訪Inbox、設定モーダルの横幅、既存Inbox既読/バッジ。実通知サービスへは送っていない。
|
||||
- TODO: 実機Chrome/Firefox/Safari/iOSでの購読・閉タブ配信・復帰・logoutを確認。Pushサービス障害テストの拡充、端末一覧/VAPID rotation UI、quiet hours/digest、種類別設定、OS通知の詳細表示opt-in、端末間の個人設定同期。
|
||||
- TODO: expired/revoked購読の清掃メトリクス、Push queue深さ/遅延/失敗コードの管理UI。旧worker購読の移行手順。
|
||||
|
||||
参考:[MDN Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)、[MDN Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)、[webpush-go](https://github.com/SherClockHolmes/webpush-go)。
|
||||
@@ -0,0 +1,43 @@
|
||||
# 2. アドレス・保存・アセット
|
||||
|
||||
状態:基本モデルとローカル保存は実装済み。外部保存・保持管理の一部はTODO。
|
||||
|
||||
## アドレス表
|
||||
|
||||
| 内部指定 | 意味 | HTTP上の主な入口 |
|
||||
| --- | --- | --- |
|
||||
| `path:/manual/start` | ドメイン内の可変な住所 | `/manual/start` |
|
||||
| `uuid:…` | Page/Objectの安定ID | `/o/uuid:…` |
|
||||
| `rev:…` | 特定の不変Revision | `/r/view/…`、`/v/raw/rev:…` |
|
||||
| `sha256:…` | 不変Document | `/_/obj/sha256:…` |
|
||||
| `asset:image:logo` | ドメイン内の編集用HEAD | 管理者向け `/v/raw/asset:image:logo` |
|
||||
|
||||
通常エディタの正規入口は `/e/-/{path}`。従来の `/e/{path}` は互換入口です。生データは `/v/raw/path:/…` 等を使い、通常Pathと紛らわしい `/raw/` を増設しません。別ドメインへのリンクは宛先FQDNを含む絶対URLです。
|
||||
|
||||
## 保存トランザクション
|
||||
|
||||
1. 言語・MIME・保存対象と現在の書き込み権限を検証する。
|
||||
2. 内容のSHA-256を計算し、`documents/sha256/` に不変Documentを永続化する。
|
||||
3. Page、Revision、必要なPathと依存参照を確定する。
|
||||
4. 派生処理へ通知する。共通outboxの全書き込み接続は後続課題。
|
||||
|
||||
Documentを先に書くため、DBのrollbackで未参照blobが残る可能性はあります。逆に、DBだけ確定して正本バイト列が存在しない状態は許しません。SQLiteのbody列は移行互換用で、Document Storeと二つの正本を作りません。
|
||||
|
||||
## アセットの可変HEADと固定参照
|
||||
|
||||
Asset名は `(domain_uuid, asset address)` で一意です。HEAD変更は旧Documentを上書きしません。HTML保存時に `asset:` を解決し、表示用参照をSHA-256へ固定します。編集用の由来は別属性で残し、次回保存時にHEADを再解決します。
|
||||
|
||||
`revision_document_refs` が依存Documentを記録します。過去Revisionの閲覧で最新HEADへ追従しないことが再現性の条件です。CLIと管理画面ではHEADを扱えますが、公開ページの依存物を自動公開する根拠にはなりません。
|
||||
|
||||
## 認可・条件付き操作
|
||||
|
||||
ハッシュURLは現在のDomainで読めるPageや許可された管理操作との関係を検証します。ETagと `X-PagesWiki-Object-UUID`、`X-PagesWiki-Revision-UUID`、`X-PagesWiki-Document-SHA256` は識別情報であり資格情報ではありません。
|
||||
|
||||
Asset更新は条件付き更新を使います。ただし同じ内容でMIME等だけ変わる競合には、HEADハッシュとは別の状態versionを導入する設計が必要です。
|
||||
|
||||
## TODO
|
||||
|
||||
- 保持期限・削除プレビュー・export中の保護を統合したDocument GC。
|
||||
- Assetの状態version、共通監査outbox、依存関係込みの公開レビュー。
|
||||
- 大容量復元のストリーミング、外部Document backend、破損検出とread-repair。
|
||||
- CLIの全書き込みとWebの正本保存契約の統一。CLIは現在も信頼されたローカル管理経路で、HTTP認可を迂回する点を明示する。
|
||||
@@ -0,0 +1,59 @@
|
||||
# 5. 認証・グループ・権限
|
||||
|
||||
状態:パスワード・TOTP・セッション、OIDC、LDAP、SMTPリンク、グループと主要な認可経路は実装済み。全経路の監査完了を意味しません。
|
||||
|
||||
## 認証から認可へ
|
||||
|
||||
認証器はPrincipal identityを証明します。その後、Domain membership、グループ・Role、対象操作のcapability、上位Localityの制限を評価します。OIDCのclaimやメールアドレスだけで管理権限を付与しません。
|
||||
|
||||
Principalにはactive / readonly / suspended / quarantinedの状態があります。membershipや状態の失効は次の要求で反映します。
|
||||
|
||||
LDAPはドメイン単位で設定します。検索用アカウントで`{{username}}`を
|
||||
RFC 4515エスケープして一意なエントリを取得し、そのエントリのユーザーDNで
|
||||
再bindできた場合だけ認証成功です。初回だけローカルの一意なユーザー名または
|
||||
メールアドレスへ連結でき、その後は`entryUUID`やActive Directoryの
|
||||
`objectGUID`など、設定した不変属性とprovider UUIDの組で識別します。DN、表示名、
|
||||
メールアドレスを継続ログインの識別子にはしません。自動作成は任意で、作成時は
|
||||
ローカルパスワードを持たない通常のmemberに限定します。
|
||||
|
||||
LDAP/LDAPS、StartTLS、証明書検証、追加CA PEM、検索Base DNとfilter、属性mapping、
|
||||
既存アカウントの照合項目、保存済み設定によるログインテストを管理画面から設定
|
||||
できます。bindパスワードは暗号化し、利用者パスワードは保存・ログ出力しません。
|
||||
LDAPグループをPagesWikiのグループや権限へ同期する処理は認証と分離し、明示的な
|
||||
mappingだけを適用する後続タスクです。
|
||||
|
||||
## セッションの目的を分離する
|
||||
|
||||
ブラウザはHttpOnlyのホスト限定Cookie、APIは明示的なBearer credentialを扱います。現行はブラウザ用とAPI用のトークン種別を分け、相互に流用しません。「全画面でlocalStorageへBearerを置く」構成にはしていません。
|
||||
|
||||
adapter、federation、認証challenge、将来のshareはそれぞれ別の検証系です。明示された無効なAuthorizationをCookieで救済しません。Cookie経由の変更には同一origin検証、ログアウトにはPOSTを使います。
|
||||
|
||||
OIDCはissuer・署名・claim・state/nonce/PKCE・browser bindingを検査します。SMTPリンクは短命・一回限りのchallengeで、配送遅延をログイン要求に持ち込みません。メール一致とメール所有の証明、外部identityの明示的な連結は引き続き整理が必要です。
|
||||
|
||||
## 権限プロファイル
|
||||
|
||||
| 表示用プロファイル | 許可する内容 | 許可しない内容 |
|
||||
| --- | --- | --- |
|
||||
| read | 閲覧 | 全変更 |
|
||||
| read/write once | 未存在の対象の新規作成・アップロード、閲覧 | 上書き、再編集、削除 |
|
||||
| read/write | 閲覧・作成・更新・rename・link | deleteの暗黙付与 |
|
||||
| upload only | 指定範囲の未存在対象へアップロード | 一覧、閲覧、上書き、削除 |
|
||||
| group admin / user | グループ内の管理上の役割 | それだけを根拠にした本文権限 |
|
||||
|
||||
削除は独立したgrantです。新規作成・uploadの可否は正規化後の最終Pathをトランザクション内で検査します。Pathを先に調べ、後で無条件上書きする実装は禁止です。
|
||||
|
||||
## 管理グループと所有者
|
||||
|
||||
`campus_admin` はキャンパスとドメイン配置、`domain_admin` はDomain設定・アカウント・グループを管理するビルトイングループです。普通のグループ管理者がこれらを自分へ付与できてはいけません。
|
||||
|
||||
Quartier・Spotのco-ownerは公開設定等の委譲された管理者です。所有者であることと、上位が許可していない公開を広げることは別です。
|
||||
|
||||
## TODO
|
||||
|
||||
- 全変更経路で認可versionと更新対象を同一トランザクションに固定する。
|
||||
- 最後の管理者の停止・移管、メール所有、外部identity連結・解除。
|
||||
- OIDC/LDAP外部グループの明示mapping、由来を保持した同期・失効・監査。
|
||||
- 説明可能な権限総覧:付与元、継承、上位制限、対象操作、失効理由を表示する。
|
||||
- PSK継承、adapter、Asset等を含む拒否・競合・再送テストの拡充。
|
||||
|
||||
個人用 `/u/{username}`、グループ用 `/g/{groupname}` は本文領域と `/_/edit` 等の管理領域を区別します。プロフィール画像変更を本文の無制限履歴と混同しません。ユーザー領域の所有者はプロフィール情報・画像・Wiki root・配下のaudienceを個別に狭められます。`private` は通常のDomain read grantより優先し、所有者と復旧権限を持つDomain管理者だけが読めます。匿名公開はDomainのpublic上限を越えられません。
|
||||
@@ -0,0 +1,35 @@
|
||||
# 10. ブログ・日記・公開ドメイン射影
|
||||
|
||||
状態:投稿・登録・カレンダー・同一インスタンス射影・公開記事・RSSは実装済み。コメント、tDiary移行、遠隔射影はTODO。
|
||||
|
||||
## 記事の実体とURL
|
||||
|
||||
ブログと日記は別のシステム拡張ですが、本文は通常Page/Revisionです。Domainごとのprefixに対し `{prefix}/yyyy/mm/dd`、任意keywordがあれば `{prefix}/yyyy/mm/dd/{keyword}` へ作成します。同日複数記事が可能です。
|
||||
|
||||
日付・著者・カテゴリ等はPage UUIDに紐づく記事メタデータです。Path変更で失わず、登録解除でPage本文は消しません。日付はcivil dateで、timezone変更時に過去の記事を勝手に別日へ移しません。
|
||||
|
||||
## 表示と投稿
|
||||
|
||||
月別は `/v/blog/yyyy/mm`、日別は `/v/blog/yyyy/mm/dd`。日記も同様です。`?own` とカテゴリを日付移動で維持します。`/v/blog` は全期間、日記の入口は当月が基本です。日付の旧query入口は正規Pathへ案内します。
|
||||
|
||||
タイトル下は日付とタイトルのコンパクトな一覧、月入力・適用・リセットはカレンダー上の一行です。大量記事では読みやすさとページ送りを優先します。
|
||||
|
||||
`/v/blog/-/new` と `/v/diary/-/new` は認証された投稿画面です。Page、Path、Revision、記事情報、journal、再送receiptを原子的に作成します。既存Pathは409、同じrequest_idの再送は重複作成せず返します。入力変更後の同じID流用も409です。
|
||||
|
||||
## 専用ドメインはコピーではなく射影
|
||||
|
||||
例:元ドメインの `/blog` を `blog.pages.anya.jp/` に表示します。現行は同一Campus・同一インスタンスに限ります。編集は元ドメイン、表示の名称・テーマは表示先ドメイン、専用記事リンクは `/yyyy/mm/dd[/keyword]` です。
|
||||
|
||||
元が非公開なら、射影の設定だけで公開しません。匿名一覧・月件数・記事本文は承認済みまたは自動公開条件を満たす内容に限定します。登録タイトルはPage公開を継承しますが、他の登録メタデータまで無条件に公開しません。設定不整合で別の内容へ黙ってfallbackしません。
|
||||
|
||||
## RSSとX
|
||||
|
||||
専用ドメインの `/rss.xml` は最新20記事を配信し、`content:encoded` に安全化したHTMLを含めます。リンクを絶対URLへ直し、正確な公開状態を再検査します。1記事1 MiB入力、合計8 MiB、5秒の生成制限を持ちます。
|
||||
|
||||
投稿後のXシェアはWeb Intentをユーザーが押す方式です。設定された専用ドメインのURLを選び、未公開なら警告します。投稿完了、公開完了、X投稿完了を同じ状態にしません。既にRSS等へ複製された本文は撤回できません。
|
||||
|
||||
## TODO
|
||||
|
||||
遠隔記事射影の署名・取得・失効、metadata公開範囲、Atom、keyset paging、outbox接続、receipt/孤立データ保持、予約公開、コメント・最近のコメント、tDiary import。
|
||||
|
||||
tDiaryは対応版・入力形式をfixtureで固定し、Ruby/eval/Marshalを実行して取り込む方法は使いません。旧URL、セクション、添付、コメント著者の出典を保持し、重複・部分失敗から再開できる取り込みを設計します。
|
||||
@@ -0,0 +1,70 @@
|
||||
# 予定・タスク共通CalDAV接続
|
||||
|
||||
2026-09-27追記:`organizer.tasks 0.10.0`で[MKCALENDARによるVTODOリスト作成](caldav-task-lists.md)を追加。共通直下のUUIDはVEVENTまたはVTODOリストを表し、種別でハンドラを選ぶ。予定本文の読み込みで判定しない。
|
||||
|
||||
2026-09-26実装。`organizer.calendar 0.2.0`/`organizer.tasks 0.9.0`。01:33 JSTに本番両インスタンスへ反映済み。[反映・検証記録](../../operations/deployments/2026-09-26-common-caldav.md)。
|
||||
|
||||
2026-09-27追記:[OneTask向け互換モード](caldav-onetask-compatibility.md)を実装、10:01 JSTに本番反映。通常は引き続き`calendar-access`を宣言せず、明示ONで発行した資格情報のみ接続判定互換のため宣言する。完全なRFC準拠ではない。実機の同期完了は未確認。
|
||||
|
||||
## 1. 接続と認証
|
||||
|
||||
共通接続先は `/_/api/v1/caldav/`。slash有無ともリダイレクトせずPROPFINDを処理する。rootはcurrent-user-principal/principal-URL/calendar-home-setを返す。Depth 1は許可された予定カレンダー(VEVENT)と個人タスクコレクション(VTODO)を返す。予定とタスクを同じICSリソースに混在させない。
|
||||
|
||||
| 対象 | URI |
|
||||
| --- | --- |
|
||||
| 共通home/principal | `/_/api/v1/caldav/` |
|
||||
| 予定 | `/_/api/v1/caldav/{calendarUUID}/` |
|
||||
| 個人タスク | `/_/api/v1/caldav/tasks/default/` |
|
||||
| 既存タスク専用home(維持) | `/_/api/v1/caldav/tasks/` |
|
||||
| 接続資格情報の発行/一覧 | `POST/GET /_/api/v1/caldav-credentials` |
|
||||
| 失効 | `DELETE /_/api/v1/caldav-credentials/{id}` |
|
||||
|
||||
予定/タスク両画面の⇄ボタンから共通設定を開く。発行時に対象 `tasks`(タスクのみ)、`calendar`(予定のみ)、`all`(両方)とread/write、有効期間を明示選択する。初期選択は開いた画面の対象で、両方を自動付与しない。
|
||||
|
||||
Basicのユーザー名は資格情報ID、パスワードは発行時のみ表示するランダム値。従来と同様、秘密値はSHA-256のみ保存し、閉じたダイアログからも消去する。通常ログインセッションでのみ発行/失効できる。DAV資格情報をWikiやJSON APIのログインとして利用することはできない(匿名公開APIを非ログイン扱いで参照できることとは別)。HTTPSを使う。
|
||||
|
||||
既存の資格情報と旧管理APIは維持。`organizer_dav_scopes`に対応行がない資格情報は必ず`tasks`として扱う。既存資格情報を予定アクセス付きに更新するAPIは設けず、新規発行と旧資格情報の明示失効で切り替える。新規の予定/共通秘密値は`pw_dav_`、既存互換タスク秘密値は`pw_taskdav_`。古いバイナリは`pw_dav_`を拒否するため、切り戻し時にも予定限定資格情報がタスク権限へ化けない。
|
||||
|
||||
## 2. 認可
|
||||
|
||||
- 資格情報をドメイン/所有者/期限/失効状態に結び、principalとdomain membershipの状態も確認する。
|
||||
- Scopeは対象種別の上限であり、他人のカレンダーを共有する権限ではない。既存のカレンダーowner/member/publicポリシーを別途適用する。
|
||||
- 共通homeの探索結果はscopeと有効な拡張機能で絞る。片方の拡張が無効でも、他方の接続設定・探索は動く。
|
||||
- 予定の書き込みは資格情報のwrite許可、active状態、カレンダーのCanWriteを全て必要とする。外部ソース由来カレンダーは従来通り書き込み不可。
|
||||
- 予定変更時はカレンダーmetadata lock内でACLと資格情報の失効・期限・write・scopeを再確認する。タスクは既存のDB transaction内再確認を維持する。
|
||||
- API・DAV応答はprivate/no-store。通常の匿名公開予定の読取経路は維持し、無効なBasic資格情報を匿名扱いにフォールバックしない。
|
||||
|
||||
## 3. 予定のresource名と正本
|
||||
|
||||
Web作成分は従来の`base64url(UID).ics`を維持。CLIが作成する任意の安全なASCIIファイル名(英数字・`.`・`_`・`-`、末尾`.ics`、最大700 bytes)を受理する。UIDとファイル名は別の識別子。
|
||||
|
||||
CLI由来のUID→filenameは`calendar.json`の`dav_names`として保持する。新規resource予約と月別ICSを同じmanifest置換でcommitする。DBだけのaliasにはせず、索引再構築・カレンダー設定変更でも保持する。削除時は対応aliasも削除する。同じcalendar内のUID重複、filename衝突、既存UIDの差替えを拒否する。
|
||||
|
||||
既存のWeb用canonical URLも引き続き解決する。WebビューアはfilenameをUIDとしてbase64 decodeする前提を廃止し、既存JSONイベントAPIの`?resource={filename}`でサーバー側解決する。`?uid=`も維持。ETag一致時には本文を取り直さない。
|
||||
|
||||
新規PUTは`If-None-Match: *`を推奨するが、chroncal互換で完全な新規identityに限り条件なし作成も可能。既存更新にはIf-Match(未指定428、不一致412)を必須とし、並行作成でも上書きしない。DELETEは予定の削除、タスクのアーカイブという既存の意味を維持する。
|
||||
|
||||
## 4. 取得上限と互換性
|
||||
|
||||
- 従来のtime-range付きREPORTとETagを利用したWeb表示を維持する。
|
||||
- 初回同期用の全件calendar-query(VCALENDAR全体、またはVEVENT指定)を追加。metadata lock内で完全なsnapshotを取得し、最大10,000 resource/32 MiBを超えれば507で全体を失敗させる。黙った切り捨てはしない。
|
||||
- PROPFIND Depth 1による予定resource列挙、全項目calendar-data選択にも対応。無制限Depth、部分projection、未対応filterは拒否する。
|
||||
- 1 resource上限256 KiB、multigetは200 href、DAVリクエストは20秒上限。既存のtime-range上限370日も維持する。
|
||||
- sync-collection/sync-tokenは未対応。405を返し、chroncalはcalendar-queryへフォールバックする。完全なCalDAV適合を示すcalendar-accessは広告しない。
|
||||
- 新規予定のiCalendar対応範囲は従来のまま:単独VEVENT、UTC DATE-TIMEまたはDATE。TZID/VTIMEZONE、浮動時刻、繰り返し、VALARMは書き込み未対応。chroncalの`--timezone`で出力されるVTIMEZONEも拒否する。情報を黙って欠落させる変換はしない。
|
||||
|
||||
## 5. 検証と運用
|
||||
|
||||
隔離したfixture、HOME、XDG、DB、資格情報のみでchroncal 0.10.0の共通探索、予定とタスクの取得、予定作成/CLI編集/Web変更取得/削除、タスク作成/完了/Web変更取得/アーカイブを検証。vdirsyncer/Todomanの既存タスク回帰も実施する。
|
||||
|
||||
権限scope、旧資格情報の移行既定値、read-only、失効、アカウント停止、拡張無効化、既存上書き拒否、並行作成、ACL取消、DB索引再構築、取得上限、Webのresource解決を試験する。ブラウザでは予定・タスク両方の設定UI、発行/失効/秘密値消去と、CLI filenameの予定描画を確認する。
|
||||
|
||||
本番の外部取り込みカレンダーの本文を調査・試験に利用しない。反映確認はhealth、未認証の経路、静的資産、エラーログ件数に限定する。
|
||||
|
||||
## 6. 後続TODO・切り戻し
|
||||
|
||||
- [ ] losslessなTZID/VTIMEZONE、繰り返し・例外、アラームのDAV書込契約。正本を拡張する際は外部ICS取り込みの投影と混同しない。
|
||||
- [ ] sync-token/tombstone/変更journalによる大規模差分同期。
|
||||
- [ ] 資格情報ごとのcalendar ID制限、カレンダー作成・属性変更のDAV対応。
|
||||
- [ ] macOS/iOS等のGUI CalDAVクライアント実機検証。
|
||||
- 旧バイナリは追加DB表を無視できるが、calendar manifestを更新すると未知の`dav_names`を失う。**CLIで予定を作成した後は、旧バイナリでカレンダーを編集しない**。緊急切り戻しではカレンダー拡張を無効化して修正版を待つか、整合したDBと正本のバックアップ復元を別途承認の上で行う。DBのみ復元し正本を過去に戻したつもりにしない。
|
||||
@@ -0,0 +1,34 @@
|
||||
# DAVx⁵/Tasks.orgの互換性調査
|
||||
|
||||
2026-09-27。利用者指定の公開ソース`bitfireAT/davx5-ose`を読み、commit `167dc85f211119db6a98596c08f64e5df32ca679`(2026-09-25)を基準に確認。インストール済みアプリのバージョンとは同一と仮定しない。Android実機でDAVx⁵を実行した検証ではない。
|
||||
|
||||
## 同期方式
|
||||
|
||||
- `core/src/main/kotlin/at/bitfire/davdroid/sync/TasksSyncManager.kt`:タスクは`PROPFIND_REPORT`固定。
|
||||
- `resource/remote/BaseWebDavCollection.kt`:Depth 0のPROPFINDでsupported-report-set、sync-token、getctag等を取得する。
|
||||
- `resource/remote/ResponseExt.kt`:sync-tokenを優先し、なければgetctagを使う。両方なければnull。
|
||||
- `sync/SyncManager.kt`のsyncRequired:状態nullは「同期必要」と判断する。両方ないこと自体で同期を拒否しない。
|
||||
- `sync/TaskSyncer.kt`と`resource/remote/CalDavCollection.kt`:VTODOのcalendar-queryを送り、ETagで比較し、必要なリソースをcalendar-multigetする。タスクqueryにtime-rangeは指定していない。
|
||||
- カレンダーは、期間制限やsync-collection未対応の場合PROPFIND_REPORTを選ぶ。未対応のsync-collectionを広告してはいけない。
|
||||
|
||||
したがって、提示された`XTaskApp / CodeSpark / SyncTaskListsSend`の「sync-token or ctag必須」というエラーは、調査したDAVx⁵の同期コードの挙動とは異なる。端末上でどのアプリが直接CalDAV接続しているかを区別する必要がある。
|
||||
|
||||
## PagesWikiとの差分と残件
|
||||
|
||||
- 既存リストの単純VTODO同期に必要なREPORT、ETag、multigetは既存実装にある。実機確認は未完了。
|
||||
- DAVx⁵のリスト新規作成は`DavCollectionRepository.generateMkColXml`でDAV:resourcetypeを常に付ける。現在のPagesWikiの限定MKCALENDARはこれを未対応propertyとして拒否する。VTODO専用で正しいresourcetypeを受理する回帰試験と実装が必要。
|
||||
- 作成時には説明・色・タイムゾーンや複数component-setも付く場合がある。受理する項目は正本保存・PROPFIND往復まで設計し、未知の意味を黙って破棄しない。
|
||||
- 時刻付きVTODO、繰り返し、VALARMはPagesWikiの現行限定プロファイルでは未対応。DAVx⁵が生成できる全タスク形式に対応済みではない。
|
||||
- リストの削除/属性編集、差分sync-tokenも別途残件。
|
||||
|
||||
## 今回の状態
|
||||
|
||||
追加途中だったctagのローカル変更(追加表・更新フック・応答property)は利用者の指示を受け取り下げた。本番には反映していない。取り下げ後の名前付きリスト・認可・原子性テストは成功。本番は0.10.0のまま。
|
||||
|
||||
利用者はTasks.orgを試す予定。DAVx⁵経由ではDAVx⁵のタスクアプリにTasksを選択し、同期対象の既存リストを有効化する。同じアカウントをTasks.org側に直接CalDAVとしても追加すると、Tasks.orgはDAVx⁵データを無視するため二重設定に注意する。初回は件名・日付だけのタスクで両方向を確認し、複雑な形式は分ける。
|
||||
|
||||
## 参照
|
||||
|
||||
- [調査対象の固定commit](https://github.com/bitfireAT/davx5-ose/tree/167dc85f211119db6a98596c08f64e5df32ca679)
|
||||
- [Tasks.org公式:DAVx⁵連携](https://tasks.org/docs/sync_davx5/)
|
||||
- [DAVx⁵公式:タスク連携](https://manual.davx5.com/tasks_notes.html)
|
||||
@@ -0,0 +1,73 @@
|
||||
# OneTaskのcalendar-access判定への互換対応
|
||||
|
||||
最新追記:利用者のスタックトレースにより`SyncTaskListsSend → CreateCalendar → MKCALENDAR`のVTODOリスト新規作成失敗と特定した。[複数タスクリスト実装](caldav-task-lists.md)で対応する。以下の「MKCALENDAR未対応」は0.9系時点の調査記録。0.10.0で明示的なVTODOリスト作成を追加するが、全機能のRFC準拠は引き続き宣言しない。
|
||||
|
||||
## 2026-09-27 接続診断の追記
|
||||
|
||||
利用者のcurl応答で、共通入口の認証済みOPTIONSが204、`DAV: 1, calendar-access`、`X-PagesWiki-CalDAV-Profile: limited-compatibility`となることを確認した。資格情報の再発行を繰り返す段階ではない。別アプリOneCalendarでの追加成功に続いて、**OneTask側も追加できたと利用者から確認された**。追加順序によるものか再試行によるものかは未確定であり、カレンダーを先に追加することを必須手順にしない。アカウント追加とVTODOの同期・更新成功は分けて扱う。
|
||||
|
||||
従来のアクセスログにはHTTPステータスがなく、10:13 JST頃の共通入口PROPFINDが成功したか判定できなかった。CalDAV経路だけ、次の固定分類による診断ログへ置き換える。
|
||||
|
||||
- method、target(home/task_home/task_collection/task_resource/calendar_collection/calendar_resource/well_known)、status、duration、request_id。
|
||||
- auth(none/basic/malformed_basic/bearer/other/multiple)、outcome(未判定・Basic成功/拒否・session成功・匿名・欠落・不正・複数Authorization)。
|
||||
- challengeの有無、限定互換宣言の有無。
|
||||
- 資格情報ID・ユーザ名・秘密値・Authorization値・Cookie・User-Agent・リソース名・query・XML/ICS本文は出力しない。認証拒否の詳細な秘密値照合結果も公開しない。
|
||||
|
||||
認証・ACL・プロトコル応答は変更しない。401なら認証、403なら権限/未対応要求、207ならクライアントの探索解釈を切り分ける。ただし207でも個別propstatは404になり得るため、207だけで必要プロパティが全て成功したと判断しない。認証省略や権限緩和で迂回しない。外部取り込み予定にはアクセスせず、実データ本文なしのログと隔離fixtureで調査を継続する。
|
||||
|
||||
診断ログ追加は10:16〜10:17 JSTにapp/app2へ反映。認証済み共通入口PROPFINDの207を確認。MKCALENDARの404も観測したが、実行アプリはログから特定できない。外部クライアントからのコレクション新規作成は未対応であり、既存タスクの作成・更新とは別課題として残す。未実装のMKCALENDARを成功扱いしない。
|
||||
|
||||
その後「追加はできたが、タスクの中身が見えず`calendar or event not found`」との報告。10:17:27のMKCALENDAR404と同じ文言を既存カレンダーハンドラが返す。10:18:28にはtask_collectionへのPROPFIND207/basic_acceptedも観測。現在のログにタスク本文取得のREPORT/GET失敗はなく、一覧表示の不具合とMKCALENDAR未対応の関係は未確定。「PagesWiki Tasks」が見えるか、エラーが同期時かリスト新規作成時かを利用者へ確認中。未対応メソッドを存在確認より前で拒否して誤解を招く404を避けること、VTODO探索の階層とクライアント相互運用を検証することを残件とする。接続成功のみで同期解決済みにしない。
|
||||
|
||||
2026-09-27実装、10:01 JSTに本番両インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-27-onetask.md)。**OneTaskアカウント追加は利用者確認済み。ただしタスク表示は未解決。互換ONで発行した資格情報が必要。**
|
||||
|
||||
## 原因と今回の境界
|
||||
|
||||
OneTaskはOPTIONS応答に`calendar-access`がない場合、`This CalDav server does not support calendar-access`として探索を停止する。従来のPagesWikiは限定的なCalDAV実装のため`DAV: 1`のみを返していた。これは認証失敗やPROPFINDの失敗ではない。
|
||||
|
||||
[RFC 4791 §5.1](https://www.rfc-editor.org/rfc/rfc4791.html#section-5.1)では`calendar-access`は全MUST要件への対応宣言である。現在のPagesWikiはその全てを実装していない。従って本変更は**RFC完全準拠への変更ではなく、利用者が明示的に選ぶ接続判定の互換モード**である。付加的な独自ヘッダでこのRFC上の意味を変えられるわけではない。通常モードは今まで通り宣言しない。
|
||||
|
||||
## 設定と保存
|
||||
|
||||
カレンダー/タスクの⇄設定で認証情報を発行するとき、「OneTask互換モード(calendar-accessを宣言)」を選ぶ。初期値はOFF。限定実装と未対応機能を同じ画面に明示し、一覧にもOneTask互換と表示する。
|
||||
|
||||
管理API `POST /_/api/v1/caldav-credentials` の追加フィールド:
|
||||
|
||||
```json
|
||||
{"label":"Android OneTask","scope":"tasks","write":true,"days":90,"calendar_access_compat":true}
|
||||
```
|
||||
|
||||
従来APIも同じフィールドを受理する。scope(対象)とwrite(権限)は別のまま。互換設定で予定への権限や書き込み権限を追加しない。既存認証情報は自動変更しない。公開してしまった秘密値を再利用せず、旧認証情報を失効して新規発行する。
|
||||
|
||||
DBには`organizer_dav_compat(credential_id)`を追加。発行と互換フラグを同じtransactionで保存し、資格情報削除triggerで関連行を削除する。secret自体は従来どおりhashのみ。通常のログインセッション以外で発行できない。
|
||||
|
||||
## 応答
|
||||
|
||||
認証成功後、対象domain/owner/資格情報ID/有効期限に対応する互換行がある場合のみ、共通home・task home・task collection/resource・calendar collection/resourceで以下を返す。
|
||||
|
||||
```http
|
||||
DAV: 1, calendar-access
|
||||
X-PagesWiki-CalDAV-Profile: limited-compatibility
|
||||
```
|
||||
|
||||
既存資格情報・互換OFF・Bearer/Cookieセッション・匿名要求は通常のまま。User-Agentから推測して勝手に互換設定を有効にしない。DB確認エラー時は通常応答に倒す。認証・scope・期限の失敗は401のままであり、失敗を成功応答に偽装しない。
|
||||
|
||||
OPTIONSの204は維持。Allowには実装しているメソッドのみを示し、MKCALENDAR・calendar-schedule・sync-token等を追加宣言しない。task collectionのPROPFINDにはcurrent-user-privilege-setとcurrent-user-principalを追加し、読み取り専用をwriteとして返さない。
|
||||
|
||||
## データと検証
|
||||
|
||||
未対応のTZID/日時付きVTODO期限/繰り返し/VALARM/部分projectionやfilterは引き続き明示的に拒否する。互換設定はこれらを変換・削除して保存を通す機能ではない。ETag必須の既存更新とACLも維持する。
|
||||
|
||||
`TestDAVCalendarAccessCompatibility`は報告されたOPTIONSの判定を再現し、その後の探索・取得・更新・削除、通常モード維持、User-Agent偽装無効、read-only、scope、失効・期限、管理API隔離、未対応繰り返し拒否を確認する。これはOneTaskアプリ自体の実行試験ではない。
|
||||
|
||||
chroncalの共通接続fixtureは互換ONで、旧タスク接続とvdirsyncer/Todomanは通常モードで回帰試験する。Chromiumでは設定の初期OFF、明示ON発行、一覧反映、失効、秘密値消去、タスク画面4サイズを確認する。すべて隔離された合成データを用い、本番資格情報・外部カレンダー本文は使わない。
|
||||
|
||||
2026-09-27の結果:全Goテスト成功。chroncal 0.10.0/vdirsyncer実行fixture成功。`TestCalendarChromiumSmoke`と`TestTasksChromium`(1440/1024/390/320幅)成功。JS構文・`git diff --check`成功。本番へのデプロイ、認証情報の発行・失効はこの作業では行っていない。
|
||||
|
||||
## 運用・残件
|
||||
|
||||
- [x] 本番への反映(2026-09-27 10:01 JST)。DBは追加表とtriggerのみで破壊的変更なし。旧バイナリは互換設定を無視するため、切り戻すとOneTaskの接続判定は再び失敗する。
|
||||
- [x] OneTask実機でアカウント追加(利用者報告)。
|
||||
- [ ] OneTask実機で一覧表示・作成・完了・変更・削除を確認する。一覧表示に問題報告があり、接続成功を全操作成功と扱わない。
|
||||
- [ ] 実機で次の要求が失敗する場合は、Authorization・本文を除去したメソッド、対象経路、status、画面エラーを基に限定fixtureを追加する。
|
||||
- [ ] 完全なRFC対応を目指す作業は共通CalDAVの残件(時間帯・繰り返し・filter等)として別途継続する。
|
||||
@@ -0,0 +1,53 @@
|
||||
# CalDAVタスクリスト作成とプロジェクト同期
|
||||
|
||||
**後続仕様**:0.11.0で通常プロジェクトも個別リストへ統一し、条件なし上書きを受理する。以下は0.10.0の記録。[新しい契約・移行と競合通知TODO](task-dav-project-unification.md)を参照。
|
||||
|
||||
2026-09-27。`organizer.tasks 0.10.0`。OneTaskの`SyncTaskListsSend`が`MKCALENDAR`でVTODOリストを作成する実例に対応する。認証エラーではなく、旧実装が未知のリストUUIDをVEVENTカレンダーとして検索し404にしたことが原因。従来の固定リストと認証・ETag・権限を維持し、成功応答だけを偽装しない。
|
||||
|
||||
10:44〜10:45 JSTに本番両インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-27-task-lists.md)。OneTask実機での再同期確認は利用者待ち。
|
||||
|
||||
## 1. 正本とURI
|
||||
|
||||
- `MKCALENDAR /_/api/v1/caldav/{UUID}/`でVTODO専用リストを作成する。要求URIをそのまま維持し、別URIへのリダイレクトは行わない。
|
||||
- 1リストを1つの個人プロジェクトに対応付ける。表示名はプロジェクトのTitle、所属タスクはProjectUUIDで決まる。外部作成分はWebでも同じプロジェクトとして管理できる。
|
||||
- URIのUUIDとプロジェクトのUUIDは別の識別子。正本プロジェクトの`dav_collection`にURIのUUIDを保存し、通常の版・CAS文書・変更journalを使用する。
|
||||
- DBの`organizer_dav_collections`はdomain/pathの一意性・routing索引。プロジェクト正本の情報から再構築できる。通常JSON APIから`dav_collection`を注入・変更できない。
|
||||
- 従来の`/_/api/v1/caldav/tasks/default/`は維持。DAV専用リストを持つプロジェクトのタスクだけを除外し、それ以外の既存タスク・通常プロジェクトは引き続きここに表示する。既存プロジェクトを勝手に外部リスト化しない。
|
||||
- 名前付きリスト内のリソースは`/_/api/v1/caldav/{UUID}/{filename}.ics`。Webで所属プロジェクトを変更すると、元のリストから消え、移動先に同じUID/filenameで現れる。これはCalDAV MOVE対応ではない。
|
||||
- 共通homeおよび旧task homeの探索で、利用者自身の有効な名前付きリストを返す。タスク拡張だけが有効な場合も使える。
|
||||
|
||||
## 2. 作成契約
|
||||
|
||||
[RFC 4791 §5.3.1](https://www.rfc-editor.org/rfc/rfc4791.html#section-5.3.1)に従い、作成は一括成功か全拒否とする。対応範囲は明示的なVTODO component-setとdisplayname。VEVENT/混在/未対応property/不正XMLを黙って無視しない。
|
||||
|
||||
- UTF-8 XML、application/xmlまたはtext/xml。64 KiB、既存XMLの深さ・要素数制限を適用。
|
||||
- component-setはVTODOのみを必須とする。displayname省略時はURI末尾を用いる。表示名の長さ等は既存プロジェクト検証を適用。
|
||||
- 作成成功201+Location、private/no-cache/no-store。既存URIへの再作成は405+DAV:resource-must-be-null。再送で別プロジェクトを増殖させない。
|
||||
- domain/pathは他利用者分も含めて一意。既存VEVENTカレンダーのディレクトリを上書きしない(存在だけ検査し、予定本文は読まない)。
|
||||
- 1利用者・1ドメインにつき最大256リスト。上限超過507。削除済みとしてURIを再利用する契約はまだ設けない。
|
||||
- タスクscopeまたはall、write権限、active membership/principal、拡張有効状態を検証。作成transaction内でも資格情報の失効・期限・権限を再確認する。
|
||||
- 匿名作成・匿名リスト閲覧は不可。他利用者のリストは404、カレンダーだけの資格情報はタスクへ使えない。
|
||||
|
||||
## 3. タスク同期
|
||||
|
||||
PROPFIND/calendar-query/calendar-multiget/GET/HEAD/PUT/DELETEを既存実装と共通化し、リストごとに完全なsnapshotを返す。別リストのhrefをmultigetに混ぜても個別404にする。
|
||||
|
||||
UIDとfilenameの一意性はリスト内。異なるリストでは同名・同UIDを許可する。DB検索索引のみ、正本上のUIDでは許可しないNULを区切りにプロジェクトUUIDを付与し、既定リストの任意UIDと衝突しないようにする。外部ICSや返却URLに索引用の接頭辞は出さない。
|
||||
|
||||
Web編集時もプロジェクトのリストidentityとタスクのDAVメタデータを保持する。既存更新はETagとversion CAS、DELETEはタスクのアーカイブ。write transaction内で所属リストを再確認する。リストをアーカイブした場合、タスクを既定リストへ漏らさず、DAV上ではそのリストを非表示にする。
|
||||
|
||||
## 4. 検証
|
||||
|
||||
- OneTaskの提供したMKCALENDARのXML形状を合成fixtureで再現。201→探索→PUT→GET→REPORT→完了→Web変更→削除。
|
||||
- 二つのリストの同UID/filename、相互混入防止、multigetの範囲制限、Web所属変更、索引再構築。
|
||||
- 他利用者、read-only、calendar-only、匿名、拡張無効、VEVENT URI衝突、並行二重作成、失敗時にプロジェクトを残さないこと。
|
||||
- chroncalの名前付きリスト往復同期。旧固定リスト・共通VEVENT接続・vdirsyncer/Todomanの回帰。
|
||||
- Webタスク/カレンダー画面のブラウザ回帰。実機OneTaskでの最終同期確認は利用者の再試行で行う。
|
||||
- 本番の資格情報・タスク・外部取り込み予定をfixtureに使用しない。観測は秘匿済みログとhealthに限定する。
|
||||
|
||||
## 5. 残件と切戻し
|
||||
|
||||
- リストのPROPPATCHによる名称・色変更、リストDELETE、DAV MOVEは未対応。リスト名はWebのプロジェクトで変更可能。リストDELETEを全タスク削除として仮実装しない。
|
||||
- DTSTART/DUEの時刻、TZID、繰り返し、VALARM、複雑filterは従来の限定VTODO契約を維持。sync-tokenによる差分同期も別件。
|
||||
- OneTaskが追加のproperty・filter・日時形式を送る場合は実要求に基づき、情報を落とさない形で対応を追加する。アカウント追加成功やCLI試験だけでOneTaskの全操作成功とはしない。
|
||||
- **名前付きリスト作成後、0.9系の旧バイナリでプロジェクト/タスクを編集しない。** 未知のdav_collectionが失われたり、旧既定リストへ混入し得る。緊急切戻しはタスク拡張を停止してから行う。DBだけの無断巻戻しでユーザーの新規タスクを消さない。
|
||||
@@ -0,0 +1,15 @@
|
||||
# カレンダー・Cityのジョブ障害是正(2026-09-22)
|
||||
|
||||
## City
|
||||
|
||||
URL自動生成はSpot名をPathの同じ深さから作るが、Spot名の一意制約はStreet内ではなくDomain全体だった。別Streetで同名のSpotやundefinedを生成するとreconcileが失敗し、outboxが未完了のまま再試行されていた。
|
||||
|
||||
Pathによる既存要素の再利用を優先し、新規作成時に名前が衝突する場合のみPath由来の安定hashを識別名に追加する。表示タイトルは維持する。別Pathの要素を名前だけでマージしない。QuartierとStreetの正規化名衝突も同じ方法で回避する。再実行で要素が増殖しないことを合成データで検証する。
|
||||
|
||||
残タスク:手動作成との同時実行競合のリトライ、繰り返し失敗の再投入backoffと警告集約。過去の失敗ログは成功へ改竄しない。
|
||||
|
||||
## 外部カレンダー接続
|
||||
|
||||
DNS検証後に先頭IPだけへ接続していたため、その経路が利用できない場合に失敗した。他の検証済みIPへ再試行し、DNS/TLS証明書/タイムアウト/安全制限をURLやトークンなしで分類する。localhostとprivate IP直指定は設定段階でも拒否する。
|
||||
|
||||
Outlookへの実接続・予定内容の調査は行わない。ユーザー指定により、以降の検証は合成データのみとし、取り込まれた外部予定にはアクセスしない。一般的なOutlookフィードのTZID、有限RRULE、EXDATE/RDATE、移動・取消を含むRECURRENCE-ID、ゼロ時間予定、Microsoft終日予定を有限期間へ射影する。対応外形式は前回snapshotを維持して失敗させ、通信成功と形式対応を混同しない。
|
||||
@@ -0,0 +1,47 @@
|
||||
# 14. 予定・iCalendar・CalDAV・連絡先
|
||||
|
||||
状態:カレンダー部分は2026-09-22にローカル正本・Plan UI・限定CalDAVを実装開始。最新の契約・実装範囲・残作業は [カレンダー詳細設計](calendar-implementation.md) を参照。以下の旧順序/URI案より同設計を優先する。連絡先と外部同期は引き続き設計案。
|
||||
|
||||
## 四つのレイヤー
|
||||
|
||||
| レイヤー | 役割 | PagesWikiでの扱い案 |
|
||||
| --- | --- | --- |
|
||||
| Wiki URL | 人が開く説明・知識への入口 | rename可能なPage Path |
|
||||
| iCalendar | 予定・タスク等の交換形式 | export/import、UIDと元データを保持 |
|
||||
| CalDAV | カレンダー資源を扱うWebDAV拡張 | remote connector、将来の提供面 |
|
||||
| CardDAV / vCard | 連絡先の通信 / データ形式 | 個人・共有address book |
|
||||
|
||||
iCalendarとCalDAVは同義ではなく、`.ics`を配信するだけでCalDAVサーバーにはなりません。vCardとCardDAVも区別します。[RFC 5545](https://www.rfc-editor.org/rfc/rfc5545)、[RFC 4791](https://www.rfc-editor.org/rfc/rfc4791)、[RFC 6350](https://www.rfc-editor.org/rfc/rfc6350)、[RFC 6352](https://www.rfc-editor.org/rfc/rfc6352)。
|
||||
|
||||
## identity対応案
|
||||
|
||||
local item UUID、calendar UID、remote href、Wiki Page UUIDを対応表に持ちます。Wiki renameでUIDを変更しません。remote href変更は移動・再取得として確認し、同じ題名だけで統合しません。ローカル生成UIDはDomain名変更でも維持します。
|
||||
|
||||
予定はevent、タスクはtodo、連絡先はcontactの型付き状態です。説明用Pageは任意の参照であり、毎回ICS/vCardをHTMLへ変換して正本を置換しません。原形式のDocument snapshotを保持し、未対応propertyの欠落を検出します。
|
||||
|
||||
## 予定のモデル案
|
||||
|
||||
開始・終了、終日フラグ、timezone/TZID、繰り返しrule、例外、参加者、状態、source versionを分離します。終日をUTCの時刻に変換せず、時間帯なしの時刻も区別します。無限recurrenceは画面の対象期間内だけ展開し、件数上限を持ちます。
|
||||
|
||||
例外instanceのキーは元seriesとrecurrence identityです。単発の変更・series全体の変更をUIで分けます。参加依頼、回答、メール送信などのschedulingは単純な予定保存とは別の後続機能です。
|
||||
|
||||
## 同期と競合
|
||||
|
||||
connectorはremote ETagとlocal versionを別々に持ち、更新前の値で条件付き操作します。ETagをDocument SHA-256と仮定しません。対応サーバーではcollection sync-tokenを利用する案ですが、無効なtokenからの再同期と未対応時のboundedな全量照合も必要です。[WebDAV同期仕様](https://www.rfc-editor.org/rfc/rfc6578)。
|
||||
|
||||
通信失敗では外部削除と見なさず、tombstoneは確認できた削除だけです。両側で変更された場合はbase/local/remoteを比較し、内容を保存した競合状態へ移します。勝手な最新版上書きはしません。
|
||||
|
||||
## 連絡先
|
||||
|
||||
address bookの所有者・共有範囲、contact UUID、remote UID、複数メール/電話、名称、所属、写真の固定参照を持ちます。人物Principalとcontactは別です。メール一致だけでユーザーへ自動連結しません。重複候補を示し、mergeは変更前をexportできる確認操作にします。
|
||||
|
||||
## URL/API案と実装順
|
||||
|
||||
人向けは `/v/organizer`、APIは `/_/api/v1/extension/organizer.{calendar|contacts}/…` を候補とします。**未実装・未予約**です。DAV提供面はroot discovery、認証、標準メソッドとルーターの衝突を調査してから決めます。Wiki PathをそのままDAV collectionにしません。
|
||||
|
||||
1. ICS/vCard fixture、入出力preview、警告、重複防止。
|
||||
2. local calendar/agenda・連絡先一覧、権限・version試験。
|
||||
3. 選定サーバーに対するread-only connector。
|
||||
4. 限定された双方向同期、最後に必要性が確認できたDAV提供。
|
||||
|
||||
CAL-1:終日・夏時間・例外。CAL-2:UID/href/Path変更。CAL-3:412競合・token失効。CARD-1:複数propertyと未知項目。DAV-1:権限失効・大量collection・app token失効。これらを完了条件にします。
|
||||
@@ -0,0 +1,165 @@
|
||||
# カレンダー拡張:正本・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](https://www.rfc-editor.org/rfc/rfc7986#section-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](caldav-common.md)が追加契約。以下の旧仕様に対し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](https://www.rfc-editor.org/rfc/rfc5545) / [RFC 4791](https://www.rfc-editor.org/rfc/rfc4791)。パーサーは `github.com/emersion/go-ical` を固定バージョンで使用し、アプリ側でDTSTART必須、UTC/DATE、排他的DTEND、UID、不支持property、制御文字、必須項目を追加検証する。出力はCRLF・UTF-8を分断しない75octet折返し。ライブラリ採用だけをRFC適合の証明にはしない。
|
||||
|
||||
- [x] 単発UTC/終日、未知property保持、月境界、同時更新、キャッシュ再構築、公開取消の回帰テスト。
|
||||
- [x] Plan各ビュー、期間REPORT、差分取得、設定・予定ダイアログ、所有者限定のカレンダー完全削除。
|
||||
- [x] 外部購読用のTZID/VTIMEZONE(IANA、主要Windows名、定義内のSTANDARD/DAYLIGHT)と夏時間fixture。
|
||||
- [ ] ローカル正本でのTZID/VTIMEZONE/floating対応、DURATIONの暦日演算。
|
||||
- [x] 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メール配送を無断で有効にしない。
|
||||
- [x] 外部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は後続タスクとする。
|
||||
@@ -0,0 +1,33 @@
|
||||
# カレンダーのスマートフォンUI
|
||||
|
||||
2026-09-25実装。iPhone SE相当の320×568/375×667と667×375横画面を対象。**Chromiumのタッチ・画面サイズエミュレーションで検証済み。Safari/iPhone実機の確認は未実施。** 同日05:59 JSTに本番2インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)。
|
||||
|
||||
## 操作と表示
|
||||
|
||||
- 小さい画面では、表示種別の7リンクをselectにまとめる。今日/前後/日付ピッカーは常時表示。
|
||||
- カレンダー選択・更新・新規予定を残し、追加/設定/外部同期/表示対象は「⋯」メニューへ集約。権限による元の表示制御を引き継ぐ。
|
||||
- 上部の重複ナビと重複見出しを省略。見出し自体はスクリーンリーダー用に維持する。
|
||||
- 週ビューは細い7列にせず、縦画面で約1日、横画面で約2日の幅を確保。曜日/日付ボタンで同じ週の列へ横移動する。見出しの日付を押すと日ビューへ進む。PCの7列表示は維持する。
|
||||
- 月ビューは日付と予定件数を表示し、詳細は日ビューで見る。狭いセルへの件名詰め込みは行わない。
|
||||
- 一覧では日付/件名を優先。場所の列はスマホでは省略し、予定詳細で確認する。
|
||||
|
||||
## タッチ操作
|
||||
|
||||
coarse pointerでは通常、予定の上も空き領域もスクロールとpinch zoomを優先する。指が触れただけで時刻変更・範囲作成を開始しない。タップは予定の詳細へ進む。
|
||||
|
||||
時間グリッドの「編集操作」をONにした場合だけ、移動・開始/終了の伸縮・空き領域の範囲選択を有効化する。ON/OFFはaria-pressedで表現。PCのドラッグ・矢印キー操作は維持する。タイムラインの小さいドラッグハンドルはタッチでは隠し、予定詳細から時刻を編集する。
|
||||
|
||||
## Safariへの配慮
|
||||
|
||||
フォームの文字を16px以上、操作領域を40〜44pxに揃える。画面のzoomを禁止するviewport指定は追加しない。編集ダイアログはVisualViewportのheight/offsetを使い、ブラウザバーやソフトキーボードによる変化を考慮する。pinch zoom中はサイズ更新を停止する。CSSのdvh fallbackとsafe-area insetを併用する。
|
||||
|
||||
スマホのスクロール領域と編集ダイアログはbackdrop blurを外し、テーマの背景色でコントラストを確保する。予定データのキャッシュ/REPORT/ETag/タイムゾーン処理は変更しない。
|
||||
|
||||
## 検証と残TODO
|
||||
|
||||
- 合成ローカルカレンダーで320/375縦・667横、ページ横はみ出し、列幅、日付選択、スクロールと編集gesture切替、月の件数、設定メニュー、編集dialogの収まりを自動検証。
|
||||
- 既存のPC CRUD・ドラッグ・resize・400% zoom・ETag試験を継続。
|
||||
- 外部取り込みカレンダーの内容にはアクセスしない。
|
||||
- TODO: Safari実機でソフトキーボード開閉、画面回転、pinch zoom、背景復帰、長い終日予定、多重重複予定を確認。端末・OSバージョンに応じた調整。
|
||||
|
||||
参考:[WebKitの動的viewport単位](https://webkit.org/blog/12669/new-webkit-features-in-safari-15-5/)、[MDN touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/touch-action)。
|
||||
@@ -0,0 +1,39 @@
|
||||
# 3. キャンパス・ドメイン・連携
|
||||
|
||||
状態:ローカル管理、外部キャンパス参加、署名付き設定配信は実装済み。コンテンツ同期・DRとは別機能。
|
||||
|
||||
## FQDNと配置
|
||||
|
||||
キャンパスの設定値はURLではなくFQDNです。ドメインのホスト指定が短い名前ならキャンパスFQDNのサブドメインとして扱い、FQDNならその値を使います。空のホスト名はキャンパスFQDN自身に対応し、未知Hostの受け皿にはしません。
|
||||
|
||||
表示用FQDNと配置先インスタンスは別の情報です。FQDNを指定しただけでは別インスタンスとは限りません。配置先は承認された候補から選び、同じFQDNの鍵フィンガープリント変更は同じ実体として黙認しません。
|
||||
|
||||
## 設定の所有者
|
||||
|
||||
- キャンパス管理:配下ドメイン、配置、参加トークン、キャンパスの共通情報。
|
||||
- ドメイン管理:Wiki名、テーマ、記事・拡張設定、メンバー、権限。
|
||||
- 外部キャンパス管理:コントローラから受け取った管理項目をローカルで独自に上書きしない。
|
||||
- 秘密:実際に認証・接続するインスタンス側に保持し、一般設定manifestへ混ぜない。
|
||||
|
||||
ドメインの設定は個別です。同じキャンパスに属するだけで記事、グループ、認証セッションを共有しません。
|
||||
|
||||
## 参加と配信
|
||||
|
||||
コントローラ発行トークンで参加要求し、インスタンスidentityを承認します。設定manifestは署名と単調なsequenceを持ち、受信側は適用とcheckpoint更新を同一トランザクションで行います。古いsnapshotへの巻き戻しや同名の別authorityへの置換を拒否します。
|
||||
|
||||
入口設定を含むmanifest v2は、全承認済み配置先の対応能力を事前確認します。対応能力の申告は「適用完了」や「オンライン」の証明ではありません。反映ACKと鮮度の明示はTODOです。
|
||||
|
||||
`--add-external-campus` は通常経路、`--add-external-campus-http` は明示的な開発用HTTP経路です。HTTP許可を一般接続の既定値へ拡張しません。
|
||||
|
||||
## 継承の区別
|
||||
|
||||
キャンパス管理者のローカル継承には、付与元ごとの記録と失効処理があります。独立したローカル付与を消さず、継承を切ったときに派生権限だけを除きます。
|
||||
|
||||
Domain間PSKによるidentity・group継承は設計段階です。署名付き差分、失効、origin競合、鍵交代を含む同期契約と実装が必要です。キャンパスmanifestの配信やローカル管理者継承が完成したことをもって、任意ドメイン間の安全な権限同期が完成したとは扱いません。
|
||||
|
||||
## TODOと合格条件
|
||||
|
||||
- 反映ACK、設定管理の解除、削除ドメインの保持・GC。
|
||||
- 同名・異originのグループ衝突、PSK失効、sequence欠落、鍵交換の試験。
|
||||
- 秘密の外部管理と明示的なローテーション手順。
|
||||
- 別インスタンス記事射影は、取得権限・失効・障害時の閉じ方を設計してから実装する。
|
||||
@@ -0,0 +1,42 @@
|
||||
# 21. 決定事項・矛盾の整理・未決事項
|
||||
|
||||
状態:既存設計の統合と、新規構想の判断台帳。設計案を実装完了に読み替えません。
|
||||
|
||||
## 原資料の読み替え
|
||||
|
||||
| 古い記述・混在 | 現在の読み方 |
|
||||
| --- | --- |
|
||||
| OIDCは形だけ、UserInfoだけを根拠にする | 署名・claim・state/nonce等のhardeningが入っている。詳細契約を優先 |
|
||||
| CookieをやめてBearer一本にする | ブラウザCookieとAPI Bearerを目的分離して併用 |
|
||||
| 匿名ナビゲーション・RSSは未実装 | 限定公開条件で実装済み。全metaや全依存物の公開ではない |
|
||||
| 匿名公開はすべて毎Revision再承認 | 手動公開はそのまま。確認したStreet/Spotのみlive-head自動公開可能 |
|
||||
| 個別記事の一覧登録だけが投稿方法 | 原子的な新規投稿APIと独立画面を追加済み |
|
||||
| 同じCampusなら任意ノードでブログ射影 | 現行の参照型記事射影は同一インスタンスまで |
|
||||
| resourceはブラウザを開いたときだけ記録 | 背景イベントで保存。表示更新と保存間隔は別 |
|
||||
| groupプロフィールのnamespaceが設計のみ | 実装側にgroup画面・APIあり。機能ごとの完了度で読む |
|
||||
| Asset名はinstance全体の名前 | mutable Asset名はDomain-local、Document hashは不変content identity |
|
||||
| イベントキューがあるのでoutboxも完成 | queue、個別journal、transactional outbox配送は異なる |
|
||||
| すべての文書はHTML正本 | 文章の正本HTMLと、バイナリ/固有形式の正本を区別 |
|
||||
|
||||
古い文書は削除せず、初期思想・変更理由・実装の追跡用に保持します。本書とコードが違う場合はまず差分を確認し、設計を理由に現在の安全制約を外しません。
|
||||
|
||||
## 新規ADRの案
|
||||
|
||||
| ID | 提案 | 状態・決めるための条件 |
|
||||
| --- | --- | --- |
|
||||
| ADR-O1 | organizerはtyped metadataと任意Page参照 | タスク初版は専用表+既存CAS Document Store(2026-09-24)。通常のObject閲覧・リンク・削除の権限境界を拡大せず、個人所有を確実に分離する。DBは捨てられる索引ではない。[実装契約](tasks-implementation.md) |
|
||||
| ADR-O2 | task共通部+ticket workflow | 提案。番号・外部依頼者・遷移権限の要件確認 |
|
||||
| ADR-O3 | ICS/vCard入出力→read-only DAV→双方向 | 推奨順。対象サーバー/clientを選んで互換表を作る |
|
||||
| ADR-O4 | FreshRSS正本+PagesWiki connector+newsboat | 第一候補。利用環境・追加運用負荷を確認。内蔵readerは代案 |
|
||||
| ADR-O5 | IMAP read-only、Wikiコピーは明示操作 | 初期設計方針。providerとsampleが実装前提 |
|
||||
| ADR-O6 | HTMLパーツを先行し全面WYSIWYGは保留 | 提案。round-tripと操作改善の評価でgo/no-go |
|
||||
| ADR-O7 | Wiki Pathと外部UID/hrefを分離 | 共通の設計制約。rename fixtureを全connectorで実施 |
|
||||
| ADR-O8 | 外部stateの変更は別段階の明示権限 | 共通の設計制約。既読・削除・送信の監査と確認 |
|
||||
|
||||
## 未決事項
|
||||
|
||||
利用するFreshRSSの有無と版、対象CalDAV/CardDAV client、IMAP provider、taskの共有単位、ticketの依頼者公開範囲、保持期限、外部接続を許可するhost、RPO/RTO、WYSIWYG採用基準です。これらが未決でもlocal fixtureと設計は進められますが、外部サービスを勝手に立ち上げたり資格情報を流用したりしません。
|
||||
|
||||
## 文書運用
|
||||
|
||||
新しい決定には理由・代案・互換影響・試験を残します。変更履歴ledgerと現状の説明を分けます。日本語統合版から詳細原資料へ辿れる対応表を維持し、英語版は同じchapter IDで追従させます。
|
||||
@@ -0,0 +1,61 @@
|
||||
# 11. システム拡張・通知・協働
|
||||
|
||||
状態:信頼済みビルトインcatalogと設定入口あり。任意第三者コードのロードは未実装。
|
||||
|
||||
## アダプタとシステム拡張
|
||||
|
||||
アダプタは特定Documentを開く・編集する役割、システム拡張は活動、通知、コメント、予定、メール、RSS、検索provider等のサービスです。外部サービス連携用URLに汎用管理権限を押し込めません。
|
||||
|
||||
現行catalogは `/_/api/v1/extension/`、個別操作は `/_/api/v1/extension/{id}/…` の系統です。catalogに載っても任意コード実行や権限付与は許可されません。
|
||||
|
||||
## 共通manifest案
|
||||
|
||||
安定ID、版、互換範囲、scope、設定schema、必要capability、outbound host、secret reference、購読event、checkpoint、実行image digest、署名、CPU/メモリ/時間/出力制限を宣言します。
|
||||
|
||||
設定はinstance / Domain / Principalを区別します。ホスト所有のフォームを基本にし、独自UIはsandboxと型付きメッセージに限定します。無効化はデータ消去と別操作です。export、移行、rollback、孤立データの保持期間を必須契約にします。
|
||||
|
||||
## 協働機能の正本
|
||||
|
||||
| 機能 | 保存するidentityと状態 | 漏えいさせないもの |
|
||||
| --- | --- | --- |
|
||||
| 最近編集 | event、actor、Page/Revision、Domain sequence | 現在読めないPageのタイトル |
|
||||
| 最近閲覧 | 本人の閲覧履歴と保持期限 | 他者の私的な閲覧履歴 |
|
||||
| いいね・ランキング | Page、反応者、期間集計、計算版 | 非公開Pageの順位や件数 |
|
||||
| 品質評価 | rubric版、評価者、対象Revision、根拠 | 機械評価を人の決裁と偽る表示 |
|
||||
| inline comment | Revision、範囲、周辺hash、孤立状態 | 改訂後の別文章への誤結合 |
|
||||
| コメントthread | Page、投稿・編集履歴、moderation | 削除・権限失効後の本文 |
|
||||
| 通知Inbox | event、受信者、配送・既読 | 保存時点の権限で固定した本文 |
|
||||
|
||||
通知を開く時点で権限を再評価します。権限を失った相手へ昔のタイトル付きメールを新規送信しません。送信済み外部通知の撤回不能性は別途表示します。
|
||||
|
||||
## 外部検索・埋め込み・テーマ
|
||||
|
||||
ローカル検索にない場合も、検索語を自動でGoogle等へ転送しません。宛先と送信語を示して選択させます。GROWI、PukiWiki、他PagesWikiは個別API契約・資格情報・上限を確認します。
|
||||
|
||||
Spotify/YouTube等のwidgetはprovider許可と同意プレースホルダを使います。文書内の任意scriptを実行しません。時間・日没によるテーマは型付き条件とCSS theme IDを扱い、位置情報を無断取得しません。
|
||||
|
||||
## ネットワーク・資産管理拡張(設計TODO)
|
||||
|
||||
IPアドレス管理(IPAM)、DNSゾーン/レコード管理、機器・ソフトウェア等の資産管理は、通常のWiki本文を直接書き換えるアダプタではなく、監査可能なシステム拡張として設計します。正本はそれぞれ `network_prefix`、`dns_zone`/`dns_record`、`asset_item` の型付きエンティティとし、説明・手順・添付資料だけをPage/Assetへの参照で持ちます。
|
||||
|
||||
| 拡張 | 最初の範囲 | 外部副作用と権限 |
|
||||
| --- | --- | --- |
|
||||
| IPAM | prefix、address、予約・割当、重複検査、CIDR表示 | read/writeを分離し、割当変更は承認と監査を必須化 |
|
||||
| DNS | zone、record、TTL、所有者、検証済みtarget、差分 | zone単位の管理者、DNS providerへのapplyはdry-run→承認→idempotent apply |
|
||||
| 資産 | asset、serial、owner、場所、状態、保証・関連Page | 個人情報・秘密値を本文や検索snippetへ出さず、履歴と廃棄を保持 |
|
||||
|
||||
外部DNSやCMDBへ接続する場合も、secret reference、許可origin、rate limit、最終同期時刻、providerのrevision/etagを保存します。DNSの名前解決やIPスキャンをページ表示中に実行せず、イベントキューのbounded jobにします。削除・再利用・移管はsoft deleteと競合検知を経てから行い、失敗時は外部状態と内部状態の差分を通知Inboxへ送ります。API候補は `/_/api/v1/extension/network.ipam/*`、`network.dns/*`、`inventory.assets/*` とし、schemaが固まるまで実装しません。
|
||||
|
||||
## CSV/表・スライド拡張(設計TODO)
|
||||
|
||||
CSVをPage本文へ複製せず、認可済みの別Documentをテーブルとして投影するmacroを用意します。候補構文は `{{csv:/data/items.csv range=A1:H200 header=true}}` とし、Path、Revision(またはasset hash)、列・行上限、表示モードを正規化してキャッシュキーに含めます。macroは表示時にboundedなProjectionを作るだけで、結果HTMLを正本へ逆流させません。CSV Editorは元Revisionを編集し、表投影とは別の操作・競合・権限として扱います。
|
||||
|
||||
交換形式はRFC 4180互換CSV(UTF-8、CRLF、引用符・改行を含むfield、BOMの扱いを明示)を第一正本とします。複数シート、型、数式、結合セル、書式が必要な場合はODSを別アダプタ/Assetとして扱い、CSVへの不可逆変換を黙って行いません。行数、列数、セル長、総バイト、ネストmacroを制限し、malformed inputは安全なテキスト表示へfallbackします。
|
||||
|
||||
スライドは、Markdown/HTMLの正本からReveal.js互換のProjectionを生成する連携アダプタを設けます。HedgeDoc、Slidevは外部originのホスト型アダプタとして、保存・公開・ユーザー情報をPages Wikiの権限へ自動昇格させず、read-only preview→明示的なimport/saveの順にします。JSを使用できない環境向けには、CSS scroll-snap/`:target`/print CSSだけでページ送りできるCSS-only Slide Editorを別実装します。外部ランタイム停止時は静的HTML/Markdownへ安全にfallbackし、任意script、remote import、iframe権限を本文から許可しません。
|
||||
|
||||
ネットワーク図ではnwdiagを追加候補とします。ソースをbounded parserで検証し、renderer version/theme/document hashをキーに静的SVGをキュー生成します。include、外部画像・font、未知directive、危険なSVG属性は拒否し、renderer停止時はescaped sourceまたは最後に検証済みの静的画像へfallbackします。編集アダプタの保存はone-use ticketと楽観的Revision競合を使い、Kroki経由の場合もorigin、timeout、quotaを明示します。
|
||||
|
||||
## 最初に作る共通部
|
||||
|
||||
outbox、actor provenance、現在権限で絞るprojection、設定のsecret参照、connectorの予算と再試行、export/削除です。機能別に通知・認可・秘密管理を作り直さないことを次章以降の前提にします。
|
||||
@@ -0,0 +1,41 @@
|
||||
# 15. RSSビューア・FreshRSS・newsboat
|
||||
|
||||
状態:設計案。既存のブログRSS「配信」と、本章の外部RSS「購読」は別機能。
|
||||
|
||||
## 選択肢と推奨する試作順
|
||||
|
||||
| 案 | 正本 | 利点 | 追加する責任 |
|
||||
| --- | --- | --- | --- |
|
||||
| PagesWiki内蔵reader | ローカルの購読と状態 | Wiki保存と一体のUI | 取得・既読・同期・client対応を全て持つ |
|
||||
| FreshRSS connector | FreshRSSの購読・既読 | 既存reader資産を利用 | API互換性、権限、cacheと失効 |
|
||||
| newsboat単独の橋渡し | newsboat側の購読・状態 | CLI利用に合わせやすい | ローカル連携経路・export/importの設計 |
|
||||
|
||||
FreshRSSにはGoogle Reader互換APIがあり、APIの有効化と専用passwordを使います。newsboatにはFreshRSS連携が用意され、カテゴリのtag化やstar操作を扱えます。[FreshRSS公式API](https://freshrss.github.io/FreshRSS/en/developers/06_GoogleReader_API.html)、[newsboat公式マニュアル](https://newsboat.org/releases/2.42/docs/newsboat.html#_freshrss)。
|
||||
|
||||
このため最初の候補は **FreshRSSを正本、PagesWikiを読取connector、newsboatを同じFreshRSSのclient** とする構成です。これは設計上の提案で、ユーザー環境のFreshRSS導入・採用決定ではありません。PagesWikiがnewsboatをサーバー上で起動したり、そのSQLiteを共有したりする必要はありません。
|
||||
|
||||
## 読取MVP
|
||||
|
||||
購読一覧、フォルダ、記事一覧、外部原文、Wiki保存を提供します。初期段階では表示しただけでFreshRSSへ既読を送りません。UIには「読取専用・既読は同期していない」と明示します。ブラウザへFreshRSS password/tokenを渡さず、backend connectorがsecret参照を使います。
|
||||
|
||||
最小cache案はsource UUID、remote feed/item ID、title、safe excerpt/body hash、canonical URL、published/updated/fetched時刻、remote state/versionです。IDなしRSSにはfeed単位の保守的な代替キーを使い、題名だけで重複排除しません。Atomはentry IDと更新情報を持つ形式です。[Atom仕様](https://www.rfc-editor.org/rfc/rfc4287)。
|
||||
|
||||
## 既読・star同期を追加する条件
|
||||
|
||||
server-authoritative stateと未送信の操作を分けます。操作ごとのrequest_idで重複を防ぎ、成功応答前に確定済みと表示しません。newsboat等で同時変更された場合、古いローカルcacheをまとめて送り返しません。接続解除・認可失効時は未送信変更を勝手に再送しません。
|
||||
|
||||
FreshRSS APIに条件付き更新がない操作もあり得るため、対応版の実機fixtureで競合動作を確認するまで完全な双方向同期を約束しません。
|
||||
|
||||
## 内蔵fetcherを選ぶ場合
|
||||
|
||||
定期event、条件付きGET、host別同時数、timeout、応答サイズ、展開サイズ、backoffを設けます。XML外部entityを無効にし、feed HTMLを安全化します。redirect/DNSを含むSSRF対策、外部画像の同意、個人購読URLや認証情報の秘匿が必要です。
|
||||
|
||||
OPMLは購読の入出力として扱い、既読・star・全本文のバックアップと同一視しません。importはpreview・追加/置換選択・重複確認を行い、既存購読を黙って削除しません。
|
||||
|
||||
## Wiki保存と権利・公開
|
||||
|
||||
既定はURL、出典、短いメモの保存です。全文保存は取得可能性・利用条件・個人用途等を確認する独立操作とし、feedが短いからといって有料記事を自動取得しません。保存先が自動公開範囲なら内容と添付の公開を明示確認します。
|
||||
|
||||
## TODOと受け入れ
|
||||
|
||||
RSS-1:read-only FreshRSS fixture。RSS-2:安全な一覧と出典付きWiki保存。RSS-3:必要なら既読/star送信。RSS-4:内蔵reader採用判断とOPML。オフライン、欠落ID、巨大feed、未知HTML、同期再送、他user情報、feed削除後の保存Page維持を試験します。
|
||||
@@ -0,0 +1,38 @@
|
||||
# 17. HTMLパーツとWYSIWYGの判断
|
||||
|
||||
状態:設計案。全面WYSIWYG採用は未決定。既存エディタを置換しない段階的改善を第一案とします。
|
||||
|
||||
## 解決したい問題
|
||||
|
||||
表、画像とcaption、引用、注意書き、コード、リンク、macro、埋め込みを毎回手書きする負荷を減らします。単にHTMLを隠すことより、既存文書を壊さず効率よく編集できることを重視します。
|
||||
|
||||
## 段階案
|
||||
|
||||
1. Source+Projection previewを保ち、HTMLパーツ挿入paletteを加える。
|
||||
2. 選択範囲の整形、リンク・表・画像の型付きdialogを追加する。
|
||||
3. 対応するblockだけを視覚編集し、未知blockはread-only islandまたはsource編集へ戻す。
|
||||
4. 完全WYSIWYGはfixture評価と操作上の効果が確認できた場合だけ採用判断する。
|
||||
|
||||
HTMLパーツは安定ID、版、schema、HTML template、preview、許可属性、必要providerを持ちます。挿入時に文書へ具体化するパーツと、動的macroを区別します。パーツ更新で過去Revisionを勝手に書き換えません。
|
||||
|
||||
## 保存契約
|
||||
|
||||
canonical HTMLと編集モデルと安全な表示HTMLは別です。preview展開済みchildren、閲覧者ごとのリンク、署名URL、session値を保存しません。unknownな属性を無言で削除するeditorは、その文書を視覚編集できると表示してはいけません。
|
||||
|
||||
保存は対象Page、編集開始Revision、言語、期待versionを照合し、競合時に選択・差分確認へ戻します。autosaveは下書きと本Revisionのどちらかを明示し、previewしただけで公開headを進めません。自動公開範囲では保存が公開へ直結することを表示します。
|
||||
|
||||
## round-trip fixture
|
||||
|
||||
- children等のmacro、asset provenanceと固定hash、embedded-object。
|
||||
- code/pre、入れ子list、table、caption、非ASCII Path、RTL、複数言語。
|
||||
- 未対応HTML、コメント、アクセシビリティ属性、長文・巨大table。
|
||||
- paste時のscript/event属性/外部参照、安全化後と正本の違い。
|
||||
- undo/redo、IME変換中、選択維持、キーボード、screen reader。
|
||||
|
||||
比較はbyte一致だけでなく、許可した正規化以外の意味・依存参照・未知blockを失わないことを検査します。変更なしで保存した場合に大量diffを作るeditorも不合格候補です。
|
||||
|
||||
## 採用判断の条件
|
||||
|
||||
HTMLパーツだけで主な不便が解決するならそこで止めます。完全WYSIWYGは、round-trip・IME・大規模文書・保守性・ライセンス・bundle負荷を比較したADRを作ってから選びます。特定ライブラリ採用や共同編集CRDTの導入は今回決めません。
|
||||
|
||||
EDITOR-1:fixtureとpalette schema。EDITOR-2:少数パーツの挿入。EDITOR-3:限定block prototype。EDITOR-4:比較評価とgo/no-go。共有編集は別の権限・競合・接続設計を必要とする後続事項です。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 19. 多言語と設計書の配信
|
||||
|
||||
状態:Revision言語とfallback、日英UIの基盤あり。全画面の言語選択・翻訳管理・公開版の対応は継続課題。
|
||||
|
||||
## 同じ知識、同じPath
|
||||
|
||||
Pageは言語中立で、RevisionにBCP 47言語tagを持たせます。同じ章の日本語と英語を別Pageとして増やすのではなく、同じPage UUIDの `ja` と `en` を将来の配信先とします。
|
||||
|
||||
UI locale、本文の言語、Campus/Domainの既定言語は同じ設定ではありません。本文が日本語でも英語UIを使えます。`und` は言語未指定・legacy互換であり、「全言語で同じ内容」という保証ではありません。
|
||||
|
||||
## 解決と権限
|
||||
|
||||
明示指定、Accept-Language、地域tagの基底、Campus/system既定、und等を考慮する既存基盤があります。明示選択のURLや全endpointでの一貫性は別の完成条件です。fallbackで別言語を返す場合には選択された言語を把握できるUIが必要です。
|
||||
|
||||
非公開の日本語Revisionを英語fallbackで漏らしたり、その逆を起こしてはいけません。公開承認は言語headと正確なRevisionの関係を含めて検査します。自動公開ルールでは各言語の現在headも対象になる点を管理者へ示します。
|
||||
|
||||
## 今回の設計書配置
|
||||
|
||||
リポジトリの `docs/design/ja/` に日本語の編集元を置き、章IDをファイル名で安定化します。Wikiは `/lab/pageswiki-dev` を総目次とし、その配下へ同じ章IDで配置します。章番号は題名の表示順であってURL identityにしません。
|
||||
|
||||
配信用にMarkdownをHTMLへ変換し、`ja` Revisionとして保存します。日本語版を理由に既存英語資料を削除しません。Wiki側の公開権限を追加・変更しません。
|
||||
|
||||
英語化は原資料を単に一括アップロードするのではなく、日本語版の章ID・現在状態・決定事項と対応させます。原資料には古い構想が残るため、そのまま最新英語版とは扱えません。
|
||||
|
||||
## 翻訳台帳の案
|
||||
|
||||
`chapter_id, source_lang, source_hash, target_lang, translated_from_hash, reviewed_at, status` を持ち、元章の変更でstaleを検出します。翻訳の自動生成とreview済み公開を分けます。言語を切り替えると別の章に移動しないことを検証します。
|
||||
|
||||
## TODO
|
||||
|
||||
言語選択UI、lang別history/diff、translation stale表示、明示指定とcanonical、Content-Language/Vary/cacheの整合、公開言語別の失効、英語版のreview。これらが整うまでは英語の中間資料はリポジトリで保持します。
|
||||
@@ -0,0 +1,53 @@
|
||||
# PagesWiki 開発設計書
|
||||
|
||||
更新日:2026-09-19。日本語の統合設計版。実装の変更履歴ではなく、現在の境界と次の設計判断を確認するための入口です。
|
||||
|
||||
## この設計書の読み方
|
||||
|
||||
- **実装済み**:利用できる機能の範囲。関連する制約や未監査部分も併記します。
|
||||
- **設計案**:今回具体化した方針。API・テーブル・既定値は、実装や互換性試験で確定させます。
|
||||
- **TODO**:未実装の作業。記述やURL例が存在しても利用可能とは限りません。
|
||||
- **保留**:安全性・運用方式・外部環境の選択が必要で、現時点では着手しません。
|
||||
|
||||
既存の英語・日本語の原資料はリポジトリに残します。初期構想と追記が混在するため、現状の読み取りでは本書の状態表示と、対応実装・テストを優先します。チェック済み項目も製品全体の完成を意味しません。
|
||||
|
||||
## 第I部 基盤
|
||||
|
||||
1. [設計思想と責務の分離](/lab/pageswiki-dev/principles)
|
||||
2. [アドレス・保存・アセット](/lab/pageswiki-dev/address-storage)
|
||||
3. [キャンパス・ドメイン・連携](/lab/pageswiki-dev/campus-federation)
|
||||
4. [Knowledge City と案内図](/lab/pageswiki-dev/knowledge-city)
|
||||
5. [認証・グループ・権限](/lab/pageswiki-dev/auth-permissions)
|
||||
6. [公開・承認・共有・匿名ナビゲーション](/lab/pageswiki-dev/publication)
|
||||
|
||||
## 第II部 利用機能と実行基盤
|
||||
|
||||
7. [ビューア・エディタ・連携アダプタ](/lab/pageswiki-dev/viewer-editor)
|
||||
8. [検索・ツリー・ホーム・設定画面](/lab/pageswiki-dev/navigation-search)
|
||||
9. [イベント・キュー・リソース監視](/lab/pageswiki-dev/scheduler-resources)
|
||||
10. [ブログ・日記・公開ドメイン射影](/lab/pageswiki-dev/blog-diary)
|
||||
11. [システム拡張・通知・協働](/lab/pageswiki-dev/extensions)
|
||||
|
||||
## 第III部 オーガナイザーと編集拡張の設計案
|
||||
|
||||
12. [オーガナイザーの共通モデル](/lab/pageswiki-dev/organizer)
|
||||
13. [タスクとチケット](/lab/pageswiki-dev/tasks-tickets)
|
||||
- [個人タスク・プロジェクトの実装契約と次段階](tasks-implementation.md)(2026-09-24)
|
||||
- [個人タスクのCalDAV/CLI連携](task-caldav.md)(2026-09-26、本番反映済み)
|
||||
- [時間枠とPomodoroの実装契約](task-planning-focus.md)(2026-09-25)
|
||||
14. [予定・iCalendar・CalDAV・連絡先](/lab/pageswiki-dev/calendar-contacts)
|
||||
15. [RSSビューア・FreshRSS・newsboat](/lab/pageswiki-dev/feeds)
|
||||
16. [IMAP取り込みとメールからWikiへの保存](/lab/pageswiki-dev/mail)
|
||||
17. [HTMLパーツとWYSIWYGの判断](/lab/pageswiki-dev/html-editor)
|
||||
|
||||
## 第IV部 運用・実装計画
|
||||
|
||||
18. [性能・保全・外部ストレージ・HA/DR](/lab/pageswiki-dev/operations)
|
||||
19. [多言語と設計書の配信](/lab/pageswiki-dev/i18n)
|
||||
20. [実装順序と受け入れ条件](/lab/pageswiki-dev/roadmap)
|
||||
21. [決定事項・矛盾の整理・未決事項](/lab/pageswiki-dev/decisions)
|
||||
22. [原資料との対応と外部仕様](/lab/pageswiki-dev/sources)
|
||||
|
||||
## 今回の範囲
|
||||
|
||||
今回行うのは設計の再整理と日本語設計書の配置です。オーガナイザー、外部サービス、DAVサーバー、メールアカウント、公開権限の新設は行いません。設計書の配置も匿名公開の許可とは別です。
|
||||
@@ -0,0 +1,38 @@
|
||||
# 4. Knowledge City と案内図
|
||||
|
||||
状態:階層、境界、案内図、URL推論・編集の初期実装あり。自動整理の完全な整合性と大規模化は継続課題。
|
||||
|
||||
## 街の役割
|
||||
|
||||
Domainを一つのKnowledge City、Quartierを学区・街区、Streetを通り、Spotを知識の拠点として扱います。道路交通図ではなく、西洋建築の街区・中庭・入口を手がかりに知識へ到達する案内図です。
|
||||
|
||||
Spotを開くと、その拠点と周囲のPageを探索できます。ポータルPageは説明の入口であって、配下の一覧を失わせる自動転送の代用品にはしません。
|
||||
|
||||
## Path境界と多重参照
|
||||
|
||||
`/life`、`/life/home`、`/life/home/kitchen` をQuartier、Street、Spotへ対応させる例では、子境界は親の厳密な子孫です。同階層境界の重複はprimaryな所属の曖昧さを避けるため制限します。移動・統合では境界と親子関係を一緒に検証します。
|
||||
|
||||
Pageのprimary所属はPathから推論し、明示的なSpot参照は別のグラフ辺として持ちます。他のSpotへ紹介してもPageを複製せず、所属させただけで閲覧権限を与えません。Spotの下へ別のSpotを任意にネストさせる操作は現行モデルの階層ではありません。
|
||||
|
||||
## 案内図の表示規約
|
||||
|
||||
- Domainで生成した街の幾何をQuartier・Streetへ割り当て、ズームで文脈を保つ。
|
||||
- Page数は相対重みだけでなく、少量のStreetを小さくする規模の目安にも使う。
|
||||
- 未整理Pageは黄緑の個別ポイント。意味のない重複Spot名を増やさない。
|
||||
- ラベルは原則水平。未ホバー時は場所を把握でき、ホバー時は対象を強調する。
|
||||
- Spot近接・ラベル重なり・クリックとドラッグの判定を試験する。
|
||||
- メニューはモーダルへ集約し、地図ポップアップは地図中心。ESC、矢印、WASD/HJKLを既存操作と衝突させない。
|
||||
- 戻る・進むはアプリ内の状態遷移として扱い、URLの恒久履歴と同じものだと説明しない。
|
||||
|
||||
## URLからの自動整理
|
||||
|
||||
設計案は「推論結果を無条件に再生成」ではなく、手動編集を保護するreconciliationです。生成元、生成版、手動上書き、除外tombstoneを記録し、同じ入力なら変更なしに収束させます。
|
||||
|
||||
更新トランザクションと共通outboxを接続し、作成・編集・rename・削除を記録します。
|
||||
DomainごとのCity consumerは10秒周期でイベントをdebounceし、URLからの自動計画を
|
||||
背景キューで実行します。成功時だけwatermarkを進め、失敗時は再試行します。完全な
|
||||
所有権・分散consumer・通知配送はTODOです。
|
||||
|
||||
## 性能・認可のTODO
|
||||
|
||||
現在のWorker生成や表示数上限だけでは、サーバー側で全体を読む問題は解決しません。局所的な階層取得、Pageのcursor、directory索引を先に整備します。権限で除外した名前・件数・ポータル・辺をcacheから復活させないことを合格条件にします。
|
||||
@@ -0,0 +1,33 @@
|
||||
# 16. IMAP取り込みとメールからWikiへの保存
|
||||
|
||||
状態:設計案。初期はメール原本を変更しない読取専用取り込み。SMTP送信は別機能。
|
||||
|
||||
## データと識別
|
||||
|
||||
account、mailbox、UIDVALIDITY、UIDを組み合わせてremote identityを持ちます。Message-IDは重複・欠落があるため補助情報に留めます。UIDVALIDITY変更は新しい世代として再照合し、UIDだけで別のメールを上書きしません。[IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051)。
|
||||
|
||||
原MIME/EMLは不変Documentとして保存し、headers、本文part、添付、thread候補を派生metadataへ分けます。メールは私的collectionに属し、必要なものだけWiki Pageへコピーします。メールアドレスとローカルPrincipalを自動同一視しません。
|
||||
|
||||
## 初回取り込みと増分
|
||||
|
||||
フォルダ・期間・件数・サイズを選んでpreviewします。UID範囲を小batchで取得し、Documentとmetadata確定後にcheckpointを進めます。既読を付けない取得方式を使い、初期実装ではSTORE、MOVE、EXPUNGE等の変更操作を行いません。本文取得には非既読化の `BODY.PEEK` 等の意味を検証します。[IMAP仕様](https://www.rfc-editor.org/rfc/rfc9051)。
|
||||
|
||||
切断・timeoutは再試行し、外部の削除とは扱いません。IMAP4rev1互換、OAuth、サーバー固有のlabel/folder挙動は対象providerを選んだ上でfixtureにします。IDLEを採用しても定期照合を残し、全accountで無制限な接続を保持しません。
|
||||
|
||||
## 表示
|
||||
|
||||
既存EML parser/viewerを再利用し、HTMLはinert処理または分離表示にします。remote画像は既定で読み込まない案です。CID参照はそのメールの添付へ限定し、別のprivate Documentを指せません。添付名のPath traversal、巨大multipart、圧縮bombを制限します。
|
||||
|
||||
## Wikiへコピーする操作
|
||||
|
||||
確認画面で、宛先Path、題名、本文形式、添付の選択、出典リンク、公開見込みを表示します。共有メールでも自動公開はしません。`copy_receipt(account,message,destination,request_id)` 等で再送を識別し、Page・Revision・固定添付参照・監査を原子的に確定する案です。
|
||||
|
||||
コピーした後、元メールが消えてもWiki Pageを消しません。逆にmirrorの保持期限削除で、Wikiから参照されるDocumentをGCしません。コピーは既読・移動・削除・返信を同時に実行する操作ではありません。
|
||||
|
||||
privateメールをautomatic公開範囲へ入れると公開されるため、宛先policy versionを確認時と書込時で照合します。公開範囲が変化したら409等で再確認させます。本文を読めることと、外部へ公開できることを混同しません。
|
||||
|
||||
## 運用とTODO
|
||||
|
||||
MAIL-1:read-only小規模fixtureとcheckpoint。MAIL-2:EML表示・添付境界。MAIL-3:copy-to-Wikiとpolicy競合。MAIL-4:保持・export・account解除。双方向既読同期やメール送信は後続の明示選択です。
|
||||
|
||||
認証失敗のbackoff、accountごとの予算、暗号化secret、ログのheader/body秘匿、再取得上限を設けます。UIは最終成功と遅延・失敗を表示し、未取得を「メール0件」としません。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 8. 検索・ツリー・ホーム・設定画面
|
||||
|
||||
状態:検索・children・Tree・ホーム・ブックマーク・設定整理の初期機能は実装済み。大規模索引と共通サイドバーは継続課題。
|
||||
|
||||
## 閲覧の入口
|
||||
|
||||
トップバーの検索はhome PathではなくDomain全体の `/` を基準にします。指定フォルダ内の検索とはモードを分けます。結果は全文だけでなくタイトル・Path・City要素のどこに一致したかを示し、Quartier/Street/Spotを上位にまとめます。
|
||||
|
||||
ファイル種別、拡張子、作成・更新日を候補取得の前に適用します。snippet生成失敗で結果全体を消さず、HTMLをそのまま検索結果へ注入しません。日本語の部分一致・現在Revisionだけの索引は残課題です。
|
||||
|
||||
## childrenとTree
|
||||
|
||||
childrenは現在Pathを既定にし、表示形式は本文macroの `view` 引数ではなくナビゲーションのアイコン操作で切り替えます。仮想フォルダでは設定により配下を表示します。サムネイルは描画を妨げず非同期取得します。
|
||||
|
||||
`/v/tree/{path}` は範囲を限定します。展開・全展開・全折りたたみ状態の保持、複数選択、rename・移動・削除はPath操作と一致させます。一般の子一覧から予約ユーザー領域を混入させません。再帰操作は事前の全対象確認と競合検出が必要です。
|
||||
|
||||
## ホームとブックマーク
|
||||
|
||||
通常トップバー型、中央検索型、検索+セクションカード型を選びます。セクションは手動URL/Path、または指定親の子リンクを表示します。設定は歯車のポップアップで、閲覧画面を編集フォームで埋めません。カード列はviewportに適応します。
|
||||
|
||||
外部ブックマーク連携は、手動登録と同期由来を区別し、同期時にローカル項目を削除しません。
|
||||
|
||||
## 設定画面
|
||||
|
||||
基本・認証・ドキュメント・拡張・運用等のグループとサブパネルを使います。選択したパネルだけ非同期で読み込みます。フォームの入力をpollingで上書きしません。トグルの装飾には実際のlabel・フォーカス・キーボード操作を残します。
|
||||
|
||||
テーブルは一行中心、詳細は展開またはポップアップへ。非JSONの403等をJSON parse errorに置き換えず、元の原因を表示します。
|
||||
|
||||
## TODO
|
||||
|
||||
directory索引と不透明cursor、権限付き検索の十分なrecall、共通サイドバー、個人ブックマーク、関連するテーブルのアクセシビリティ試験。キャッシュは認可結果の長期保存にせず、現在の権限を再評価します。
|
||||
@@ -0,0 +1,42 @@
|
||||
# 18. 性能・保全・外部ストレージ・HA/DR
|
||||
|
||||
状態:単一writerのSQLite運用、限定付きジョブ・cache、バックアップ手段あり。HAと外部保存は別途設計・検証が必要。
|
||||
|
||||
## 現状と性能優先順位
|
||||
|
||||
複数インスタンスがあっても、同じDBを共有するHAではありません。各SQLiteとDocument Storeのauthorityを区別します。コンテンツを読む要求に、全履歴走査、全文body hydration、巨大archive展開、外部接続待ちを持ち込まないことが最優先です。
|
||||
|
||||
| 課題 | 次の修正方向 | 完了を判定する試験 |
|
||||
| --- | --- | --- |
|
||||
| 全Path集計 | directory索引・局所query・cursor | 大階層で候補数とDB時間が限定される |
|
||||
| 全City取得 | shallow projection・遅延Page取得 | 小範囲表示で全体を読まない |
|
||||
| 歴史RevisionのFTS | current-only、安全なplain text索引 | 更新・削除・日本語検索・権限失効 |
|
||||
| 大容量restore | immutable参照再利用・stream | heapがpayloadサイズに比例しない |
|
||||
| decoder | process隔離・重み付き予算 | timeout/cancel/メモリ上限で確実に終了 |
|
||||
| 失効とcache | generation+要求時認可 | 古い一覧からprivate内容を復活させない |
|
||||
|
||||
上限を増やす前にquery planと現実的なデータ量を測ります。公開ページの匿名cacheと認証ユーザーの認可cacheを同一にしません。
|
||||
|
||||
## 保全
|
||||
|
||||
DBだけでなくDocument Store、設定、復旧に必要な鍵を区別してバックアップします。稼働SQLiteを単純copyせず、online backup等の整合した手段を使います。Documentの固定hash検証、参照整合性、戻し手順をfixtureまたは別環境で確認します。
|
||||
|
||||
削除・復元は現行権限、全Path binding、依存参照、保持期限を確認します。バックアップ復元による過去権限復活には運用上の失効再適用が必要です。秘密を一般のWiki設計書やログへ複製しません。
|
||||
|
||||
## 外部ストレージ案
|
||||
|
||||
Document backendはStat/Open/ReadAt/PutIfAbsent/Verify/DeleteUnreferencedを持ち、SHA-256 identityを維持します。S3 key・ETag・URLをDocument identityとみなしません。multipart、短命URL、Range、GC、read-after-write確認を試験します。
|
||||
|
||||
WebDAV/SSHFSの可変ファイルとimmutable CASは別です。最初はread-only connector/import、マウントは専用sidecar等の運用責務としWeb要求でmountしません。SSH host key、outbound制限、secret管理が前提です。
|
||||
|
||||
## ファイル監査
|
||||
|
||||
MWDB/Karton等の接続はpending/clean/suspicious/malicious/error/expiredの状態と、engine・版・hash・時刻・由来を持つ非同期処理を案とします。監査必須の範囲ではcleanがない間のviewer/download/adapterを閉じます。scannerへ機密本文を送る操作には別の送信方針が必要です。
|
||||
|
||||
## DRとHAの順序
|
||||
|
||||
コントローラDRは署名manifest journal、鍵の保全、sequence、昇格epoch、旧leaderのfencingから設計します。記事DBとDocumentの複製は別の責務です。Campus manifestは記事バックアップではありません。
|
||||
|
||||
LB/HAにはsession失効共有、job lease、cache invalidation、uploadのnode非依存、WebSocket drain、proxy origin検証を要します。SQLiteをネットワーク共有して複数writerで動かす構成は採りません。fenced single-writer+replicaか、適切なmetadata backendを先に選びます。
|
||||
|
||||
RPO/RTOは目標値をユーザーと決め、復旧訓練の実測で保証範囲を定めます。現在の構成に無根拠な無停止・無損失を約束しません。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 12. オーガナイザーの共通モデル
|
||||
|
||||
状態:設計案。今回は設計のみで、外部アカウント登録や同期を有効にしません。
|
||||
|
||||
## 目的と最初の範囲
|
||||
|
||||
Wikiの知識と、予定・タスク・連絡先・受信情報を相互に参照できる入口を作ります。メール、RSS、カレンダーの既存サービスを全て置き換えることは初期目標ではありません。
|
||||
|
||||
初期の画面は「今日」「タスク」「予定」「受信情報」「連絡先」を切り替える、薄い集約画面とします。各コレクションの権限で絞り、未読件数すら他者へ漏らさない設計です。共有の通知Inboxと、メール受信箱・RSS未読一覧は別物です。
|
||||
|
||||
## identityの案
|
||||
|
||||
| 概念 | 安定したキー | 別途持つ可変情報 |
|
||||
| --- | --- | --- |
|
||||
| collection | ローカルUUID、Domain、所有Principal/共有scope | 表示名・接続先 |
|
||||
| item | ローカルUUID、kind、collection | status、title、version |
|
||||
| Page参照 | Page UUID、参照Domain | 現在のPath・表示URL |
|
||||
| remote binding | connector UUID、remote collection、remote ID | remote href、ETag、checkpoint |
|
||||
| connector | ローカルUUID、provider、owner、許可scope | secret_ref、health、最終成功 |
|
||||
|
||||
イベント、タスク、メール等を無型の一つのJSON表へ押し込む案は採りません。共通identity・監査を持ち、kind固有の表または厳格schemaを持ちます。Wiki本文が必要なitemだけPage UUIDへ関連付けます。全メールを自動でPageにする必要はありません。
|
||||
|
||||
## 正本を一つ選ぶ
|
||||
|
||||
コレクションごとに `local_authoritative`、`remote_readonly`、将来の `remote_sync` を区別します。最初はlocalまたは読取専用mirrorです。remoteを正本とする項目の編集は、無断でlocal版を作るのではなく、未対応または明示的なcopyとして扱います。
|
||||
|
||||
同期を導入した場合もremote IDとWiki Pathを同一identityにしません。renameはbookmark/DAVのresource identityを再生成する理由になりません。
|
||||
|
||||
## 変更と同期の契約案
|
||||
|
||||
変更には期待versionとrequest_idを要求し、item更新・監査・outboxを同一transactionにします。connectorsは小さなbatchで取得し、保存成功後にcheckpointを進めます。再試行は重複排除し、失敗した一件のせいで全件再取り込みしません。
|
||||
|
||||
削除はtombstoneとして配送可能な期間を持たせます。画面から消したこと、mirror cacheを削除したこと、外部原本を削除したことを区別します。時計だけのlast-write-winsで予定やタスクを無言で上書きしません。
|
||||
|
||||
## 接続安全性
|
||||
|
||||
Domain、Principal、provider、許可host、credential purposeを固定します。リダイレクトとDNS再解決も検証し、無制限の内部ネットワーク取得を防ぎます。秘密はsecret_refだけを設定・ログへ載せます。接続解除はtoken失効、job停止、cache保持・削除の選択を伴います。
|
||||
|
||||
## UI案
|
||||
|
||||
一覧はcompact table、詳細はdrawerまたはdialog、設定は歯車。外部由来・最終同期・未送信変更・競合を区別して表示します。オフラインを「空の予定」と扱いません。Wiki保存時は保存先、出典、添付、公開予定の確認を一つの画面で行います。
|
||||
|
||||
## 受け入れ条件と未決事項
|
||||
|
||||
rename後もitem identity維持、権限失効で次要求から不可視、二重配送で重複なし、同期停止時の未送信保護、個人設定のDomain越境拒否を必須にします。共通itemを独立Object kindにするか拡張表に留めるかはprototypeで決め、DB migrationはその後です。
|
||||
@@ -0,0 +1,53 @@
|
||||
# 共通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・外部カレンダーは使用しません。
|
||||
@@ -0,0 +1,36 @@
|
||||
# 1. 設計思想と責務の分離
|
||||
|
||||
状態:基盤は実装済み。拡張への適用は継続中。
|
||||
|
||||
## 知識の住所と実体を分ける
|
||||
|
||||
PagesWikiは、人には階層と街の案内図を提供し、内部では同じ知識を複数の場所から参照できるシステムです。ファイルシステムのコピーをWikiの基本単位にはしません。
|
||||
|
||||
| 層 | 責務 | 他の層と混同しないもの |
|
||||
| --- | --- | --- |
|
||||
| Campus | ドメイン群の管理・配置・管理方針 | 記事本文の自動複製 |
|
||||
| Domain | FQDN、Path名前空間、設定、権限評価 | インスタンスそのもの |
|
||||
| Quartier / Street / Spot | 知識の整理・案内・管理範囲 | Pageの永続ID |
|
||||
| Page | 言語や表示形式に依存しない知識の実体 | Path、ファイル名 |
|
||||
| Revision | Pageの不変な版、言語、内容参照 | 最新版を指す可変名 |
|
||||
| Document | SHA-256で識別する不変バイト列 | 認可情報 |
|
||||
| Projection | 表示・編集・印刷・検索等の表現 | 別のPage正本 |
|
||||
|
||||
## 守る不変条件
|
||||
|
||||
- `(domain_uuid, path)` が意味上の住所。名前変更してもPage UUIDを変えない。
|
||||
- Page UUID、Revision UUID、Document SHA-256は別物。ハッシュを知っていても読めるとは限らない。
|
||||
- 同じPageを複数箇所で紹介しても、Revision履歴を複製しない。
|
||||
- 言語はRevisionの属性。通常のPathに `/ja/` と `/en/` を強制しない。
|
||||
- 閲覧・編集・公開・管理・委譲は別の許可。ログイン成功だけで本文権限を与えない。
|
||||
- コメント、既読、評価、タスク状態はHTMLへ隠しフィールドとして埋め込まず、型付きメタデータとして持つ。
|
||||
|
||||
## 正本・派生データ・外部コピー
|
||||
|
||||
正本の更新と重要なメタデータはトランザクションで確定させます。検索索引、サムネイル、ランキング、通知は派生データとして再構築可能にします。外部メールやRSSの取り込みでは、外部の原本とWikiへの明示的なコピーを区別します。
|
||||
|
||||
現在、全書き込みが共通outboxへ接続されているわけではありません。「イベント化すべき」という設計契約を実装済みと読み替えてはいけません。
|
||||
|
||||
## 変更の受け入れ基準
|
||||
|
||||
機能ごとに、名前変更、権限失効、再試行、停止・再起動、大きな入力、外部障害を試験します。上限超過時に無制限処理や無認可表示へ切り替えません。通常の閲覧・保存を重いバックグラウンド処理より優先します。
|
||||
@@ -0,0 +1,53 @@
|
||||
# 6. 公開・承認・共有・匿名ナビゲーション
|
||||
|
||||
状態:明示的なRevision公開、Street/Spotの自動公開、匿名ナビゲーションは実装済み。承認者Inboxは受信者単位の保存・既読APIまで実装済みで、承認要求の生成・決裁UI・配送ワーカーはTODO。共有URL管理もTODO。
|
||||
|
||||
## 三つの異なるもの
|
||||
|
||||
1. 公開可能な上限:上位管理者が許可するaudience。下位は狭められるが広げられない。
|
||||
2. 実際の公開:特定Revisionの明示承認、または確認済みの自動公開ルール。
|
||||
3. 認証後のread/write:ユーザー・グループの権限。公開設定を変更しただけで編集者を増やさない。
|
||||
|
||||
`public` という上限を保存しただけで配下全部を公開したと扱いません。
|
||||
|
||||
## 現行の自動公開
|
||||
|
||||
| モード | 動作 |
|
||||
| --- | --- |
|
||||
| inherit | この階層ではルールを追加せず上位に従う |
|
||||
| required | この範囲と配下は手動公開のみ。下位の自動公開で解除できない |
|
||||
| automatic | Street/Spotの現在と将来の対象Page、および各言語の現在headを公開 |
|
||||
|
||||
Domain・Quartierもrequiredの上限制約を設定できます。automaticは有効な公開audienceを必要とし、影響プレビューと明示確認、policy/topology/versionの一致で有効化します。空の範囲にも設定できるため、今後作成する記事も対象になり得ます。
|
||||
|
||||
固定したPath境界のrename、設定した本人の権限失効、Domain/Campus無効化は公開を継続する根拠になりません。境界内への移動も対象になり得るため、importやメールコピーでは公開先の確認が重要です。別名、制限された子範囲、予約領域は現行の除外対象です。
|
||||
|
||||
自動公開の停止と、別途承認したRevisionの撤回は同じ操作ではありません。完全に非公開へ戻す場合はaudienceも制限します。新しい導入・migrationで自動公開を有効にしません。
|
||||
|
||||
影響確認は現在512 Path、ルール列挙128行、公開ナビゲーション20,000件/4 MiB等の上限があります。大きい範囲は分割・ページ送り付き確認の実装が必要です。上限超過を認可成功として扱いません。
|
||||
|
||||
## 匿名表示と共有リンク
|
||||
|
||||
公開Pageは読めるchildren・tree・City・パンくずへ移動できます。構造上必要な仮想親フォルダは、非公開の親本文やタイトルを見せる許可ではありません。通常・詳細・アイコン表示を共通化します。公開画面にダウンロード操作を強調する必要はありません。
|
||||
|
||||
ユーザー領域 `/u/{username}` はCityの通常公開から除外したまま、専用の公開設定を `/u/{username}/_/edit` に実装しています。プロフィール情報、プロフィール画像、ユーザーWikiのroot、配下の既定値をそれぞれ `private` / `domain` / `public` から選べます。配下の個別Pathは既定値より狭い範囲に限って上書きでき、その指定はsubtreeにも効きます。Domainの公開上限がpublicで、有効なCampus/Domainかつ認可がenforcingの場合だけpublicを保存・配信できます。上限を閉じれば次の要求から匿名配信も閉じます。
|
||||
|
||||
これは所有者が明示的に有効化する現在headの自動公開です。通常Pageの固定Revision承認を流用せず、将来の編集も同じ範囲で公開されます。匿名children・tree・browserは当該ユーザー領域だけの公開snapshotを使用し、グローバル匿名treeへ `/u/` を混ぜません。別名を持つObject、UUID/Revision経由、予約 `/_/` 経路では迂回できません。詳細は [user-space visibility contract](../user-space-publication.md) を参照してください。
|
||||
|
||||
将来のshare URLは期限・範囲・目的を限定した単一ページ表示が基本です。ログインセッションや公開ナビゲーション全体への昇格はさせません。Macaroonを含む委譲方式は設計段階で、予約 `/s/` があることは実装済みを意味しません。
|
||||
|
||||
## 承認Inboxの設計と実装状況
|
||||
|
||||
承認要求は対象Revision、依存物、scope、policy version、要求者と期限を固定します。変更された本文に旧承認を流用しません。承認者の現在の権限を決裁時に再検査し、outboxから通知Inboxへ重複排除して配送します。
|
||||
|
||||
状態はdraft → requested → approved / rejected / expired / supersededを案とします。取り消し・公開撤回は別監査イベントです。上位の承認必須設定を下位が解除できないこと、自動公開との優先順位、本人承認の可否を実装前に確定します。
|
||||
|
||||
共通通知Inboxの第一段階として、`notification_inbox`にDomain・受信者・イベント・種別を保存し、同じ組合せを重複排除します。`GET /_/api/v1/notifications` は現在のPrincipalに限定して `unread`、`limit`、`before` のkeyset取得を行い、`POST/PATCH /_/api/v1/notifications/read` は同じDomain・受信者の通知だけを既読化します。通知は権限や承認を付与せず、本文や秘密を保存しません。承認要求からの生成と再表示時の権限再検査は次段階です。
|
||||
|
||||
承認要求の対象(Path/Object/RevisionのハッシュとJSON)、policy version、generation、期限、要求者を`publication_requests`に固定保存し、決裁履歴を`publication_decisions`へ追記します。期限付きpending要求はスケジューラが小さなbatchでexpiredへ遷移させます。レビュアーの現在権限を再検査する決裁APIとInbox UIは、まだ公開していません。
|
||||
|
||||
認証済みのDomain管理者向けに、`POST /_/api/v1/publication/requests`でboundedな対象manifestを登録できます。idempotency keyで再送をまとめ、指定されたレビュアーがDomain管理権限を持つ場合だけInbox通知を作成します。`POST /_/api/v1/publication/requests/{uuid}/decisions`はDomainとgenerationを再検査し、承認・拒否をCASで一度だけ適用します。上位方針の継承、定足数、対象Revisionの現在性検査は、公開運用へ進む前の残タスクです。
|
||||
|
||||
## TODO
|
||||
|
||||
依存Assetと別名の完全な影響レビュー、広域の移動・統合時のfence、ルールGC、承認者・定足数・Inbox、署名付きpolicy配信、share失効管理。RSS読者や外部SNSが既に取得したコピーを遠隔削除できるとは約束しません。
|
||||
@@ -0,0 +1,32 @@
|
||||
# 料理レシピ管理(RECIPE)
|
||||
|
||||
状態:設計TODO。通常のWiki文書を置き換えず、Document/Revisionを正本として
|
||||
レシピ用の構造化メタデータと表示Projectionを重ねる。
|
||||
|
||||
## 基本モデル
|
||||
|
||||
- レシピUUID、タイトル、概要、作者、出典、タグ、料理ジャンル、公開範囲。
|
||||
- 材料は名称・数量・単位・任意の代替材料・アレルゲンを持つ。
|
||||
- 手順は順序、本文、所要時間、温度、器具、画像Asset参照を持つ。
|
||||
- 分量(何人分)、準備時間、調理時間、合計時間、難易度を分離する。
|
||||
- Revisionと同じく変更履歴・差分・権限・監査を持ち、公開承認を迂回しない。
|
||||
|
||||
## 表示と編集
|
||||
|
||||
材料の人数倍・縮小、単位変換、買い物リスト化は表示時の派生値とし、正本の
|
||||
数量を破壊しない。Markdown/HTML本文からの移行はpreviewと警告付きで行い、
|
||||
未知の単位や曖昧な数量は文字列として保持する。画像・動画・PDFのAssetは
|
||||
既存のMIME/権限処理を再利用し、本文への埋め込みは安全なProjectionを通す。
|
||||
|
||||
## 連携と拡張
|
||||
|
||||
JSON-LD Recipe、印刷用カード、買い物リスト、カテゴリ・材料検索を候補とする。
|
||||
外部レシピサイトやメールからの取り込みは、出典URL・取得時刻・著作権表示を
|
||||
保持し、無断公開や大量取得を行わない。栄養計算は外部データの版と不確実性を
|
||||
表示し、医療上の助言とは扱わない。
|
||||
|
||||
## 受け入れ条件
|
||||
|
||||
単位変換で丸め誤差を明示すること、権限フィルタ後の検索結果だけを表示すること、
|
||||
Revision競合・削除・Asset失効を再現できるfixtureを用意すること、共有時に作者・
|
||||
出典・公開範囲を再確認することを条件とする。
|
||||
@@ -0,0 +1,63 @@
|
||||
# 20. 実装順序と受け入れ条件
|
||||
|
||||
状態:2026-09-19再整理。旧Phase番号は原ロードマップとの対応用に残し、実装は依存関係とリスク順に進めます。
|
||||
|
||||
## 優先順
|
||||
|
||||
2026-09-27追記:`organizer.tasks 0.11.1`で[既定タスクリスト名の変更](task-dav-default-list-name.md)を実装し、12:51 JSTに[本番両インスタンスへ反映](../../operations/deployments/2026-09-27-default-task-list-name.md)。PROPPATCH 405を解消し、利用者・domain別の表示名を保存、全探索結果へ反映する。実機再試行は確認待ち。色・アイコン・通常プロジェクトのPROPPATCHは別件。
|
||||
|
||||
2026-09-27追記:`organizer.tasks 0.11.0`の[タスク所属統一と上書き同期](task-dav-project-unification.md)を実装し、12:18 JSTに[本番両インスタンスへ反映](../../operations/deployments/2026-09-27-task-unification.md)。全Webプロジェクトを個別CalDAVリストとして公開し、既定リストはプロジェクトなしに限定。無条件PUT/DELETEはトークン別設定なしで受理し、版履歴を保持する。実機再同期は確認待ち。次の優先タスクは競合候補の保存、Inbox通知、上書き前/受信版の比較・採否選択(同文書のTODO)。反映時に観測したスケジューラclaimの一時的DBロックとディスク容量整理も運用記録へ残した。
|
||||
|
||||
2026-09-25追記:個人タスクCalDAV `0.8.0`を実装・隔離試験済み(2026-09-26 00:24 JST本番反映済み)。専用資格情報UI、VTODO、CLI双方向同期。制約と次段階は[タスクCalDAV](task-caldav.md)に整理。
|
||||
|
||||
2026-09-26追記:[予定・タスク共通CalDAV](caldav-common.md)を実装。共通principal/scope付き資格情報/VEVENT・VTODO探索・CLI同期/両画面の共通設定UI。chroncal実行試験とWeb回帰を実施。後続はTZID/VTIMEZONE等のlossless書込、sync-token、資格情報ごとのcalendar制限。反映状況は運用記録を参照。
|
||||
|
||||
2026-09-27追記:[OneTaskのOPTIONS判定互換モード](caldav-onetask-compatibility.md)を資格情報単位で実装、10:01 JSTに本番反映。OneTask実機の全操作確認は残件。通常モードは維持し、未対応データを黙って変換しない。
|
||||
|
||||
2026-09-27追記:[VTODOの複数タスクリスト](caldav-task-lists.md)を`organizer.tasks 0.10.0`として実装。OneTaskのMKCALENDAR失敗に対応し、リストをWebプロジェクトへ対応付ける。隔離試験では新規作成、リスト別CRUD、権限分離、索引復旧、Web所属変更、chroncalの名前付きリスト同期まで確認。後続:OneTask実機の再同期、PROPPATCH/リストDELETE、時刻付き期限・繰り返し・アラーム、差分同期。反映状況は[運用記録](../../operations/deployments/2026-09-27-task-lists.md)を参照。
|
||||
|
||||
| 優先 | 作業単位 | 前提 | 完了条件 |
|
||||
| --- | --- | --- | --- |
|
||||
| P0-1 | 認可transaction fence | typed target、現行認証 | revokeと同時更新の拒否、全変更経路の棚卸し |
|
||||
| P0-2 | 公開影響と構造変更 | inert HTML、現行公開 | alias/依存/移動/統合で公開を無断拡張しない |
|
||||
| P0-3 | identity lifecycle | 現行Principal/group | 外部連結、メール所有、最後の管理者保護 |
|
||||
| P1-1 | 共通outbox | actor・Domain sequence | 正本との原子性、二重配送、checkpoint復旧 |
|
||||
| P1-2 | City/directory局所化 | 所属モデル、索引 | 部分取得、手動編集保持、boundedなreconcile |
|
||||
| P1-3 | 検索・decode・大容量 | 現行上限と測定 | current-only検索、隔離、stream、cancel |
|
||||
| P2-1 | 通知と承認Inbox | P0、outbox | 現在権限で再表示・決裁・失効 |
|
||||
| P2-2 | HTMLパーツ | round-trip fixture | macro/asset/未知HTMLを壊さない |
|
||||
| P2-3 | local task | extension契約、原子的ジャーナル | 個人タスク/プロジェクト・Inbox通知・個人local時間枠・永続化Pomodoro・Todayの見積/時間枠/集中集約を実装済み。次は計画持ち越し、日課、共有 |
|
||||
| P2-4 | RSS読取・Wiki保存 | connector共通部 | FreshRSS fixtureと安全なcopy |
|
||||
| P2-6 | 料理レシピ管理 | Document/Asset、検索、権限 | 材料・分量・手順・調理時間・人数・タグを構造化し、単位変換と安全な共有を検証 |
|
||||
| P3 | calendar/contact/mail | import/secret/競合契約 | read-only同期、明示copy、障害復旧 |
|
||||
| P4 | 外部書込・DAV提供・HA | 運用選択、試験環境 | 双方向競合、fencing、復旧訓練 |
|
||||
| P2-5 | CSV表macro・ODS境界 | projection/asset権限 | RFC4180 fixture、行列上限、Revision競合、safe fallback |
|
||||
| P3-2 | Slide projection/editor | adapter manifest、CSP | Reveal互換preview、CSS-only編集、HedgeDoc/Slidev隔離 |
|
||||
| P3-3 | IPAM・DNS・資産管理 | typed entity、承認Inbox、outbox | 重複検査、dry-run/apply監査、外部同期差分、soft delete |
|
||||
|
||||
P2以降の順序は利用価値で入れ替え可能ですが、P0の該当安全条件と共通outboxを省略しません。read-only prototypeは、本番への外部送信や公開を伴わない隔離fixtureで並行検証できます。
|
||||
|
||||
## 既に使える機能と残り
|
||||
|
||||
2026-09-25追加(0.7.0、2026-09-25 07:07 JST本番反映済み):[日別計画・持ち越し・親子グループ・Wikiメモ](task-daily-notes.md)。期限を変えない再割当て、親子cursor・補足親、初期Wiki本文とタスク紐づけの原子的作成を実装。日別キャパシティ・一括計画・共有は残件。
|
||||
|
||||
2026-09-25追記(同日05:59 JSTに本番反映済み):タスクのインライン編集、2階層サブタスク、月別日割り工程表、ホーム/Todayモーダル、Inboxのアクティブ通知、スマホカレンダーUIを実装・fixture検証。[タスク一覧の契約](task-inline-schedule.md)、[通知とWeb Pushの契約](active-notifications.md)、[スマホカレンダー](calendar-mobile.md)に上限・安全条件・実機確認の残件を記載。
|
||||
|
||||
- アドレス・不変Revision・Document・Asset:基本実装あり。保持・大容量・外部backendが残り。
|
||||
- Campus/Domain・manifest:基本実装あり。反映ACK、PSK権限同期、DRが残り。
|
||||
- City Map:実装あり。局所取得、reconcile所有権、生成品質が残り。
|
||||
- 認証・グループ:実装あり。全endpoint監査・identity lifecycleが残り。
|
||||
- 匿名公開・children/tree/City:実装あり。大規模影響確認、share、承認Inboxが残り。
|
||||
- ブログ・日記・公開射影・本文RSS:実装あり。遠隔射影、コメント、tDiary等が残り。
|
||||
- オーガナイザー:カレンダーと限定CalDAV、個人タスク/プロジェクト・個別ONのInbox通知、個人local時間枠と永続化Pomodoroあり。[タスク実装契約](tasks-implementation.md)、[時間枠とPomodoro](task-planning-focus.md)参照。一般のカレンダー予定通知・共有・VTODO、RSS購読・IMAPは未実装。
|
||||
- 全面WYSIWYG、native app起動、第三者runtime、vim.wasm改善:判断待ちまたは保留。
|
||||
|
||||
## 共通のDone
|
||||
|
||||
仕様状態、schema/migration、rollbackまたはforward-fix手順、認可拒否、権限失効、version競合、重複再送、payload/行数/時間/並列上限、cancel、i18n、アクセシビリティ、運用メトリクスをそろえます。
|
||||
|
||||
Go全体テストと必要なbrowser fixtureを実施し、実装済み表示とdeployment記録を別々に更新します。外部APIはmockのみでlive接続成功と報告しません。
|
||||
|
||||
## 設計タスク一覧
|
||||
|
||||
次章のADR-O1〜O8を採用判断の単位とします。TASK、TICKET、CAL、CARD、DAV、RSS、MAIL、EDITOR、CSV、SLIDE、IPAM、DNS、INV、RECIPEの各IDは詳細章のTODOと対応します。実装開始時に担当・受け入れfixture・依存issue・見直し日を付けます。規模や納期を根拠なしに確約しません。
|
||||
@@ -0,0 +1,40 @@
|
||||
# 9. イベント・キュー・リソース監視
|
||||
|
||||
状態:永続ジョブ、定期実行、再試行・ログ、背景リソース監視あり。共通outboxの
|
||||
永続 envelope(Domain sequence、idempotency、retry state、pending取得)は実装済み。
|
||||
正本変更との同一transaction接続はPage/Revision/Path/Objectの初期経路で実装済み。
|
||||
2026-09-25:consumerごとのcheckpointとイベント型別取得、タスク/プロジェクトの同一transaction接続、個別ONのタスク期限日/計画日Inbox通知も実装済み。汎用変更通知の配送、outbox保持ポリシー、分散leaseはTODO。
|
||||
|
||||
イベントログは生ログとトレンド用bucketを分離する。`event_log_policies`で
|
||||
イベント種別ごとの保持時間、集約開始時間、bucket幅、最大生ログ件数を指定し、
|
||||
`event_log_buckets`には件数と最初・最後の時刻だけを保持する。生ログの削除は
|
||||
稼働中に安全な条件付きDELETEで行い、workerが書き込み中にテーブルをDROPしない。
|
||||
物理partitionの導入時もrename→新規作成→切替を原子的に行う。
|
||||
|
||||
## 責務
|
||||
|
||||
`/_/api/v1/event/` は実行する処理とタイミング、`/_/api/v1/queue/` は実行要求と状態を扱います。予定、実行中、結果、ログ、キュー設定を区別します。イベントは安全な型付き処理であり、ユーザー入力をそのままshell commandへ変換しません。
|
||||
|
||||
## 前景を優先する
|
||||
|
||||
サムネイル・PDF・archive解析等は背景処理へ送ります。ジョブの同時数、入力・出力、時間、再試行を制限し、通常要求の活動を見ながらclaimします。長い接続だけで背景処理が永久停止しないよう、最低限の進行枠も必要です。
|
||||
|
||||
今後はジョブ件数だけでなくCPU/メモリ重みを管理します。native decoderのhard memory limit、プロセス分離、cancel時の子プロセス停止は別の安全条件です。
|
||||
|
||||
## outboxの実装と残り
|
||||
|
||||
正本変更と `activity_outbox` を同一transactionで記録します。Domain sequence、event UUID、型と版、actor、対象UUID、idempotency keyを含めます。本文や秘密をすべて複写しません。[購読・移行・復旧契約](outbox-delivery.md)を参照してください。
|
||||
|
||||
配送はat-least-onceを前提に、consumerごとのcheckpointと重複排除を使います。処理成功後にcheckpointを進め、途中停止から再試行します。City、通知、検索、集計が個別のHTTP handler callbackへ散らばらないようにします。既存の個別journalがあるだけではこの配送契約の完成ではありません。
|
||||
|
||||
## 運用画面とリソース
|
||||
|
||||
実行モニタはリソースグラフ4列と現在実行中のジョブ。設定は歯車、手動更新はアイコン。完了ジョブは履歴・ログへ統合し、ログは選択時に読みます。履歴期間の既定は1時間で選択を保持します。
|
||||
|
||||
現在値の表示更新、グラフの表示更新、背景の保存間隔は異なる設定です。1秒表示にしても1秒ごとの永続化や精密な瞬間使用率を意味しません。ブラウザを閉じても保存イベントは続きます。以前の「60秒既定」という原資料だけを最新設定の根拠にしません。
|
||||
|
||||
I/Oはプロセスの累積read/write bytes差分を時間で割った値です。再起動・欠測・counter減少は0に補間しません。ホスト全体のIOPS、latency、コンテナ合算と混同しません。
|
||||
|
||||
## TODOと検証
|
||||
|
||||
重み付き予算、dead-letterと安全な再投入、分散lease/fencing、outbox、SNMPv3読取collector。停止中の欠測、長いViewer接続、重いPDF連発、ジョブ再送、log大量化でも閲覧を優先できることを測定します。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 22. 原資料との対応と外部仕様
|
||||
|
||||
更新日:2026-09-19。原資料はリポジトリの `docs/design/` に残します。以下はWiki上のファイル配信URLではなく、ソース資料との対応表です。
|
||||
|
||||
## 原資料の分類
|
||||
|
||||
| 本書の章 | 原資料ファイル |
|
||||
| --- | --- |
|
||||
| 設計思想 | `arch.md`、`access-model.md`、`platform-extension-architecture.md` |
|
||||
| アドレス・保存 | `address-model.md`、`uri.md`、`asset-model.md`、`data-cli.md`、`revision-language-model.md` |
|
||||
| Campus・Domain | `campus-domain-model.md`、`domain-namespace-federation.md`、`federation-manifest-integrity.md` |
|
||||
| City | `knowledge-city-model.md`、`city-immersive-map.md`、`city-organization-ui.md`、`city-read-integrity.md`、`city-review-and-reconciliation.md`、`city-worker-navigation.md` |
|
||||
| 認証・権限 | `auth.md`、`auth-backend.md`、`authorization-groups.md`、`browser-request-security.md`、`campus-admin-revocation.md`、`object-authority-scope.md`、`oidc-verification.md`、`smtp-magic-link-hardening.md` |
|
||||
| 公開・共有 | `locality-publication-ownership.md`、`locality-access-publication.md`、`automatic-publication.md`、`publication-approval-inbox.md`、`public-navigation.md`、`social-link-cards.md` |
|
||||
| Viewer・Editor | `projection-adapters.md`、`html-projection-trust.md`、`projection-metadata-cache.md`、`home-bookmark-sections-vim.md` |
|
||||
| ナビゲーション・import | `navigation-home-sidebar.md`、`configuration-panels.md`、`search-results.md`、`archive-import.md`、`path-mutation-integrity.md` |
|
||||
| Scheduler・拡張 | `event-scheduler.md`、`system-extensions.md`、`platform-extension-architecture.md` |
|
||||
| 日記・ブログ | `diary-blog-plugins.md` |
|
||||
| 新規構想 | `organizer-and-editing-ideas.md`、本書第12〜17章 |
|
||||
| 保全・性能 | `object-list-pagination.md`、`revision-listing.md`、`zombie-gc-integrity.md`、`implementation-status.md` |
|
||||
| 多言語 | `i18n-delivery.md`、`revision-language-model.md` |
|
||||
| 実装計画・履歴 | `implementation-roadmap.md`、`implementation-status.md`、`hardening-execution-2026-09.md` |
|
||||
|
||||
初期draft、詳細契約、実装状況、実行履歴は文書の用途が違います。仕様の全項目を実装済みと判定するためにdraftの文体を使わず、コードとテストの実装単位で確認します。
|
||||
|
||||
## 今回の照合対象の実装
|
||||
|
||||
`internal/store/automatic_publication.go`、`locality_publication.go`、`navigation.go`、`periodicals.go`、`public_periodicals.go`、`groups_inheritance.go`、`city_reference.go`、`revision_store.go`、`internal/server/periodical*.go`、`public_periodical*.go`、`internal/extensions/registry.go`、`data/pageswiki-cli` 等を、状態の混同が起きやすい箇所として確認しました。これは全実装の安全性監査を完了したという意味ではありません。
|
||||
|
||||
## 公式仕様と連携資料
|
||||
|
||||
以下は2026-09-19に確認した設計根拠です。プロトコル対応を実装する際は更新RFC・errata・選定clientの版も固定します。
|
||||
|
||||
- [RFC 5545 — iCalendar](https://www.rfc-editor.org/rfc/rfc5545)
|
||||
- [RFC 4791 — CalDAV](https://www.rfc-editor.org/rfc/rfc4791)
|
||||
- [RFC 6350 — vCard](https://www.rfc-editor.org/rfc/rfc6350)
|
||||
- [RFC 6352 — CardDAV](https://www.rfc-editor.org/rfc/rfc6352)
|
||||
- [RFC 6578 — WebDAV Collection Synchronization](https://www.rfc-editor.org/rfc/rfc6578)
|
||||
- [RFC 9051 — IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051)
|
||||
- [RFC 4287 — Atom](https://www.rfc-editor.org/rfc/rfc4287)
|
||||
- [FreshRSS — Google Reader compatible API](https://freshrss.github.io/FreshRSS/en/developers/06_GoogleReader_API.html)
|
||||
- [newsboat 2.42 — FreshRSS integration](https://newsboat.org/releases/2.42/docs/newsboat.html#_freshrss)
|
||||
|
||||
これらの仕様が存在することと、PagesWikiがその機能を提供することは別です。本書のモデル、MVP順序、table/API案はPagesWiki向けの設計提案として区別します。
|
||||
@@ -0,0 +1,183 @@
|
||||
# 個人タスクのCalDAV/CLI連携
|
||||
|
||||
2026-09-27追記:0.11.0の[所属統一と上書き同期](task-dav-project-unification.md)で、全プロジェクトのリスト化と無条件PUT/DELETEを実装し、12:18 JSTに本番両インスタンスへ反映。以下の条件ヘッダ必須という説明は旧版の契約。明示されたETagの条件は引き続き尊重する。
|
||||
|
||||
2026-09-27追記:`organizer.tasks 0.10.0`の[複数タスクリスト](caldav-task-lists.md)で、OneTaskのMKCALENDARとプロジェクト別同期に対応。以下の固定1コレクション・UIDのdomain/owner一意性は初版の説明。名前付きリストではリスト単位の一意性となり、従来URIは既定リストとして維持する。
|
||||
|
||||
更新:2026-09-26。`organizer.tasks 0.9.0`。01:33 JSTにapp/app2へ[共通CalDAVの本番反映](../../operations/deployments/2026-09-26-common-caldav.md)完了。以前の経緯は[chroncal互換性修正](../../operations/deployments/2026-09-26-chroncal-compatibility.md)、初回0.8.0の反映・バックアップは[初回デプロイ記録](../../operations/deployments/2026-09-26-task-caldav.md)を参照。
|
||||
|
||||
## 1. 目的と境界
|
||||
|
||||
2026-09-26追記:`organizer.tasks 0.9.0`で[予定・タスク共通CalDAV](caldav-common.md)を追加。旧タスク専用URLと資格情報は維持する。以下のタスク専用資格情報の制約は旧資格情報/`tasks` scopeに適用し、予定を扱うには新規に`calendar`または`all`を選んで発行する。
|
||||
|
||||
0.8.1互換性修正(2026-09-26):chroncal 0.10.0の探索・初回同期・作成・完了・Web変更取得・削除を隔離fixtureで検証。末尾slashを除くクライアント向けにhome/collectionのslashなしURIも直接処理し、301によるPROPFIND→GET変換を回避する。返却hrefはslash付きのcanonical形式を維持する。
|
||||
|
||||
Webの個人タスクをサードパーティCLIでも扱う。正本を別に増やすのではなく、既存のTaskRecord・版・変更journal・通知予約を共通で使用する。カレンダー予定のVEVENTとは別のVTODOコレクションを提供する。
|
||||
|
||||
- ドメイン×利用者ごとに一つの固定コレクション。未完了・完了・取りやめを含む。アーカイブは除外する。
|
||||
- プロジェクト自体はVTODO化しない。サブタスクは個別のVTODOとして並ぶ。既存のプロジェクト・親子・Wiki関連・取り組む日・工程終了・見積もりはCLIから消されないが、初版ではCalDAV編集項目ではない。
|
||||
- DESCRIPTIONはタスクのプレーンテキストメモ。関連Wikiドキュメントの本文を取得・公開しない。
|
||||
- 匿名公開、共有タスク、アサイン、外部カレンダー取得は行わない。
|
||||
- `organizer.tasks`無効化時はエンドポイント全体を404にする。`organizer.calendar`の有効化は不要。
|
||||
|
||||
RFC 5545 VTODOの**限定プロファイル**。フルCalDAV適合を意味する`calendar-access`は広告せず、`DAV: 1`と対応するREPORT・VTODO component-setを示す。
|
||||
|
||||
## 2. URI・認証
|
||||
|
||||
| 用途 | URI |
|
||||
| --- | --- |
|
||||
| タスク専用home/principal discovery | `/_/api/v1/caldav/tasks/` |
|
||||
| 固定コレクション | `/_/api/v1/caldav/tasks/default/` |
|
||||
| VTODOリソース | `/_/api/v1/caldav/tasks/default/{name}.ics` |
|
||||
| 専用パスワード一覧/発行 | `GET/POST /_/api/v1/extension/organizer.tasks/dav-credentials` |
|
||||
| 専用パスワード失効 | `DELETE /_/api/v1/extension/organizer.tasks/dav-credentials/{id}` |
|
||||
|
||||
タスク画面の上部ツールバーの **⇄(CalDAV / CLI連携)** で発行・失効する。日本語/英語とテーマに追従する。名前、読み取り専用/読み書き、有効期間を指定。UIは30・90・365日、APIは1〜365日、既定90日。利用者・ドメインごとに有効な資格情報を最大20件に制限する。
|
||||
|
||||
HTTP Basicのユーザー名には発行された**認証情報ID**、パスワードには発行されたランダム秘密値を使用する。普段のログイン名やログインパスワードではない。秘密値は発行時のみ表示し、画面を閉じたらDOMから破棄する。DBには256-bit乱数のSHA-256のみを保存する。専用資格情報では通常のタスクJSON API、認証管理API、Wiki、予定カレンダーにはアクセスできない。
|
||||
|
||||
既存のBearerセッションでもこのDAVにアクセスできるが、CLIの常用は専用資格情報を使う。通常セッションで認証した管理APIのみが新規資格情報を発行できる。失効・有効期限・利用者状態・ドメインmembershipを毎回確認。書き込みでは資格情報の失効・read/write権限をタスク更新transaction内で再確認する。Cookie fallbackやCSRF検査を迂回しない。
|
||||
|
||||
本番接続はHTTPSを使用。専用資格情報をコマンド引数・共有設定・ログへ出さない。以下のAPI発行例は説明用で、実際にはUIを推奨する。
|
||||
|
||||
```json
|
||||
{"label":"Laptop / vdirsyncer","write":true,"days":90}
|
||||
```
|
||||
|
||||
## 3. フィールド対応
|
||||
|
||||
| VTODO | PagesWiki |
|
||||
| --- | --- |
|
||||
| UID | 永続同期ID。Web由来はタスクUUID、CLI作成時は外部UIDを保持 |
|
||||
| SUMMARY | 件名(必須、最大300 UTF-8 bytes) |
|
||||
| DESCRIPTION | タスクの非公開メモ(最大16 KiB) |
|
||||
| STATUS | NEEDS-ACTION ↔ 未着手、IN-PROCESS ↔ 進行中、COMPLETED ↔ 完了、CANCELLED ↔ 取りやめ |
|
||||
| DTSTART;VALUE=DATE | 工程開始日(取り組む日ではない) |
|
||||
| DUE;VALUE=DATE | 期限日 |
|
||||
| PRIORITY | 1=最優先、2〜4=高、5=通常、6〜9=低、0/省略=通常。Webからの出力は1/3/5/9 |
|
||||
| COMPLETED | サーバーが記録した完了時刻(UTC) |
|
||||
| CREATED / LAST-MODIFIED / DTSTAMP | サーバーの作成・更新日時(UTC) |
|
||||
| SEQUENCE | タスクversion−1 |
|
||||
|
||||
既存データを上書きするPUTは、公開した対応項目だけを置換する。PRIORITYの元の数値は同じUI優先度の範囲なら保持。CATEGORIES、LOCATION、URL、CLASS、RELATED-TO、X-*はCLI往復メタデータとして保持するが、初版ではPagesWikiの分類・関係・表示を変更しない。RELATED-TOは親子作成APIではない。PERCENT-COMPLETEは保持するがUIの完了判定はSTATUSを正とする。完了後は100を出力し、状態変更時には旧進捗率をクリアする。
|
||||
|
||||
**現在の制限:** DTSTART/DUEはDATEのみ。UTC・ローカル・TZID付きの時刻指定、VTIMEZONE、RRULE/RDATE/EXDATE/RECURRENCE-ID、DURATION、VALARM、ATTENDEE/ORGANIZER/METHODは明示的にエラーにする。時刻・繰り返しを無断で切り落とさない。DTSTAMPは必須のUTC DATE-TIME。
|
||||
|
||||
VTODOはDUE > DTSTARTを要求する。一方、Webの工程日付と期限は独立しているため、同日または期限以前にできない開始日はDAV射影ではDTSTARTを省略する。元のWeb開始日は保持し、期限が変わらない通常のGET→PUTでも消さない。この状態の開始日編集はWebを使用する。工程開始と既存の工程終了の矛盾は422で拒否する。
|
||||
|
||||
CRLF、TEXTエスケープ、75 octetsでUTF-8境界を壊さないfoldを適用する。1リソース=1 VCALENDAR+1 VTODO、最大32 KiB。未対応の意味論は403の`valid-calendar-data`で理由を返す。
|
||||
|
||||
## 4. 同期・競合・復旧
|
||||
|
||||
- PROPFIND Depth 0/1:home discovery、component-set、リソース一覧、ETag。principal/home-setはタスク専用homeに収束する。
|
||||
- REPORT `calendar-query`:VCALENDAR/VTODO component-filter。`calendar-data`の空要素に加え、明示的な`comp name="VCALENDAR"`+`allprop`+`allcomp`による全項目取得に対応。部分選択・展開・time-range/property-filterは403(未対応条件を無視した結果を返さない)。
|
||||
- REPORT `calendar-multiget`:最大200 href、欠損/別authority/コレクション外hrefは個別404。REPORTのDepth省略に対応。
|
||||
- GET/HEAD:正規化ICSとSHA-256 ETag。If-None-Matchで304。
|
||||
- PUT作成:`If-None-Match: *`を推奨。chroncal互換として完全に新規のhrefへの条件なしPUTも受け付けるが、transaction内のhref/UID一意性で競合作成による上書きを防ぐ。既存リソースの更新とDELETE:最新の強いETagの`If-Match`が必要。旧版は412、既存への条件なし更新は428。アーカイブ済みidentityの条件なし復活も428。DBのタスクversionでもCASする。
|
||||
- PUTでは表現を正規化するため、[RFC 9110 §9.3.4](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.3.4)に従いその応答にETagを付けない。クライアントはGET/multigetで正規化版とETagを取り直す。
|
||||
- DELETEはアーカイブ。タスク版・Wikiメモ・子タスクを物理削除しない。Webで復元すると同じhref・UIDで再登場する。
|
||||
- UIDとhrefは別の識別子。外部UIDをUUID形式に強制しない。href名は安全なASCII英数字、`.`、`_`、`-`、最大128 bytes、末尾`.ics`。同じ利用者・ドメイン内でUIDとhrefをそれぞれ一意にする。既存identityの変更は拒否する。
|
||||
- 完了タスクを一覧から除外しない。黙った件数切り捨ては同期クライアントに削除と誤解されるので禁止する。最大10,000件/正本JSON合計32 MiB、超過時507でコレクション全体を失敗させる。大規模運用はsync-token設計へ進める。
|
||||
- 正本TaskRecord内にCLI由来UID/href/受理したICSを保存する。DBの`organizer_dav_resources`は検索索引兼一意性制約で、既存Webタスクを起動時に登録する。更新はタスク版・journal・通知と同一transaction。
|
||||
- 通常一覧・工程表の応答にはICS全文を含めない。詳細とDAVでのみ取得する。
|
||||
- バックアップは従来どおりDBとCASの両方。`organizer_dav_credentials`もDBに含まれる。個別資格情報の復元時には失効済み秘密値の復活に注意し、必要ならすべて失効する。
|
||||
|
||||
## 5. CLI接続手順
|
||||
|
||||
vdirsyncer 0.21.0 + Todoman 4.7.0で検証。検証用資格情報・DB・HTTPサーバーはすべてfixtureで、本番/外部カレンダーの内容にはアクセスしない。
|
||||
|
||||
### vdirsyncer
|
||||
|
||||
`~/.config/vdirsyncer/config`(0600):
|
||||
|
||||
```ini
|
||||
[general]
|
||||
status_path = "~/.local/state/vdirsyncer/"
|
||||
|
||||
[pair pageswiki_tasks]
|
||||
a = "pageswiki_tasks_local"
|
||||
b = "pageswiki_tasks_remote"
|
||||
collections = ["default"]
|
||||
metadata = ["displayname"]
|
||||
|
||||
[storage pageswiki_tasks_local]
|
||||
type = "filesystem"
|
||||
path = "~/.local/share/pageswiki-tasks/"
|
||||
fileext = ".ics"
|
||||
|
||||
[storage pageswiki_tasks_remote]
|
||||
type = "caldav"
|
||||
url = "https://pages.anya.jp/_/api/v1/caldav/tasks/"
|
||||
username = "発行された認証情報ID"
|
||||
password.fetch = ["command", "pass", "show", "pageswiki/task-caldav"]
|
||||
item_types = ["VTODO"]
|
||||
```
|
||||
|
||||
`password.fetch`は利用するパスワード管理ツールに合わせる。`pass show`の対象にはパスワードだけを保存する。セキュリティ上、設定例には実際のパスワードを埋め込まない。
|
||||
|
||||
```sh
|
||||
mkdir -p ~/.local/share/pageswiki-tasks/default
|
||||
vdirsyncer discover pageswiki_tasks
|
||||
vdirsyncer sync pageswiki_tasks
|
||||
vdirsyncer metasync pageswiki_tasks
|
||||
```
|
||||
|
||||
### Todoman
|
||||
|
||||
`~/.config/todoman/config.py`:
|
||||
|
||||
```python
|
||||
path = "~/.local/share/pageswiki-tasks/*"
|
||||
date_format = "%Y-%m-%d"
|
||||
time_format = "%H:%M"
|
||||
default_list = "PagesWiki Tasks" # metasyncでdisplayname取得後。未取得なら "default"
|
||||
default_due = 0 # 自動的な時刻付き期限を生成しない
|
||||
```
|
||||
|
||||
```sh
|
||||
todo list
|
||||
todo new --due 2026-10-01 "CLIから作成するタスク"
|
||||
vdirsyncer sync pageswiki_tasks
|
||||
todo done 1 # 実際の対象IDに置き換える
|
||||
vdirsyncer sync pageswiki_tasks
|
||||
```
|
||||
|
||||
TodomanはローカルICSを編集し、vdirsyncerがサーバーと同期する。Webの変更を取り込むには先にsyncする。競合時の`a wins`/`b wins`は設定せず、差分確認して解消する。
|
||||
|
||||
## 6. 検証と次段階
|
||||
|
||||
### chroncal
|
||||
|
||||
```sh
|
||||
chroncal account add PagesWiki \
|
||||
--server https://pages.anya.jp/_/api/v1/caldav/tasks/ \
|
||||
--username '発行された認証情報ID' \
|
||||
--auth basic --password-cmd 'pass show pageswiki/task-caldav'
|
||||
chroncal todo list
|
||||
chroncal todo add 'CLIで作成' --calendar 'PagesWiki Tasks' --due 2026-10-01
|
||||
chroncal sync run --account PagesWiki
|
||||
```
|
||||
|
||||
パスワード取得コマンドは手元の秘密管理方式に合わせる。通常運用はOS keyringを使用し、`--allow-plaintext`はセキュリティ上の意味を理解した場合のみ。試験ではユーザーの既存設定・DB・keyringを参照しないよう、全XDGディレクトリとHOMEを一時領域へ分離する。
|
||||
|
||||
差分`sync-collection`は未対応のため405を返し、chroncalは全件`calendar-query`にフォールバックする。これは今回のprincipal探索で発生した405とは別で、同期継続が確認できている。追加クライアント対応のために`sync-token`対応を偽って広告しない。
|
||||
|
||||
```sh
|
||||
PAGESWIKI_CHRONCAL=/usr/local/bin/chroncal go test ./internal/server -run '^TestTaskDAVChroncal$' -count=1
|
||||
```
|
||||
|
||||
### 回帰試験
|
||||
|
||||
実装テスト:任意UID/href、JSON UI更新での保持、完了・復元、stale ETag、同時PUT、別利用者・ドメイン分離、専用資格情報の範囲・失効・expiry・suspended、書き込みtransaction内失効、XML namespace/Depth、未対応条件拒否、UTF-8 fold、機能kill switch。
|
||||
|
||||
実CLI試験:discovery、PROPFINDとVTODO calendar-query両経路、multiget、Web→ローカル取得、Todoman作成・完了、Web変更取得、ローカル削除→アーカイブ、再syncで版が増えないこと。
|
||||
|
||||
```sh
|
||||
PAGESWIKI_VDIRSYNCER=/path/to/venv/bin/vdirsyncer go test ./internal/server -run '^TestTaskDAVVdirsyncer$' -count=1
|
||||
```
|
||||
|
||||
同じvenvに`todo`が必要。ブラウザ試験は4サイズで資格情報発行・失効・閉じた後の秘密値破棄・スクロール幅も検証する。
|
||||
|
||||
残件:時刻付き期限の正本設計、繰り返し・VALARM、標準RELATED-TOの双方向階層同期、共有コレクションACL、property/time-rangeフィルター、sync-token/差分同期、アカウント設定への資格情報管理統合、総合principal/well-known discovery、追加クライアント互換試験。現時点では対応をうたわない。
|
||||
|
||||
規範/参考:[RFC 5545 VTODO](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.6.2)、[RFC 4791](https://www.rfc-editor.org/rfc/rfc4791.html)、[vdirsyncer公式設定例](https://github.com/pimutils/vdirsyncer/blob/main/config.example)、[Todoman設定](https://todoman.readthedocs.io/en/stable/configure.html)。
|
||||
@@ -0,0 +1,73 @@
|
||||
# 日別計画・親子グループ・Wikiメモ
|
||||
|
||||
2026-09-25実装。organizer.tasks 0.7.0。今回の変更は2026-09-25 07:07 JST本番反映済み。
|
||||
|
||||
[本番反映記録](../../operations/deployments/2026-09-25-task-daily-notes.md)。
|
||||
|
||||
## 日別の計画
|
||||
|
||||
| 画面 | URI | 対象 |
|
||||
| --- | --- | --- |
|
||||
| 持ち越し | `/v/plan/tasks/carryover` | 昨日以前の計画日、または昨日以前の期限が残る未完了タスク |
|
||||
| 今日 | `/v/plan/today` | 既存の今日の計画・今日までの期限超過 |
|
||||
| 明日 | `/v/plan/tasks/tomorrow` | ドメインのタイムゾーンでの翌日の計画・期限 |
|
||||
| 任意の日 | `/v/plan/tasks/day/YYYY/MM/DD` | 指定日が計画日または期限の未完了タスク |
|
||||
|
||||
日付ピッカーと前後日の移動を提供する。日別画面のクイック作成/新規作成では選択日を計画日に入れる。カレンダー時間枠の初期日付も日別画面の選択日を優先し、他画面はタスクの計画日があれば利用する。時刻の解釈・DST検証は既存のカレンダーAPIによる。
|
||||
|
||||
持ち越し画面では割り当て先日付を指定し、各行の矢印でその日に変更できる。変更するのは `planned_on` のみ。期限・工程日・子の計画日・カレンダーイベントは自動変更しない。期限超過のタスクは計画を将来に移しても持ち越しに残る。完了や取消済み・archive済みは除外する。完了した日の実績表示はこの画面の対象外。
|
||||
|
||||
APIは既存itemsの `view=day&date=YYYY-MM-DD`、`view=carryover`。指定日が不正なら422。今日と持ち越しの基準日はクライアントではなくサーバーのドメイン時刻で決定する。既存のToday集計・外部カレンダーは変更しない。
|
||||
|
||||
## 親子の一覧
|
||||
|
||||
- UIは `hierarchy=1` で取得。親の作成日時/UUIDをグループキーとし、親→子の順で同じグループに配置する。子はグループ内で新しい順。
|
||||
- cursor比較にもグループキーと親子順位を含める。続きを取得した際はUUID単位で統合し、親・子を重複させない。
|
||||
- 子だけが日付や検索条件に一致したときは、同じDomain・所有者の親を補足表示する。「親」マークは親自体がフィルタ対象ではないことを示す。この補足は親に日付を割り当てたり、Today集計へ追加したりしない。
|
||||
- 親を今日・明日へ入れた場合も、展開操作で日付未設定/別日/完了済みを含む子を取得できる。最初に一致した子だけを表示している場合は「すべてのサブタスク」アイコンを提供する。
|
||||
- 展開はオンデマンド、1回100件。超過時はその親の中で続きを読み込む。親情報は最大100件のバッチ取得とし、一覧の各子について個別APIを呼ばない。
|
||||
- 同一画面での再読込では展開済み状態を保持する。画面間・ブラウザ再起動をまたぐ永続化は未対応。
|
||||
- 未保存の編集がある間は一覧再構築・子の置換を抑止し、編集中の入力を破棄しない。
|
||||
|
||||
グループソートには所有者で限定した自己結合を利用する。出力は既定60/最大100件、APIは既存の5秒上限。極端に大量の個人タスクでソートが支配的になった場合、安定したfamily sort keyの索引化を検討する。全ユーザ・全Domainを読み込む設計にはしない。
|
||||
|
||||
## Wikiメモの保存先と動作
|
||||
|
||||
従来のTaskRecord.notesは個人用の短いプレーンテキストメモとして残す。今回の「メモ表示」「メモ編集」は、通常のWiki Pageへ接続する別の導線。
|
||||
|
||||
プロジェクトの編集画面で次を指定する。
|
||||
|
||||
1. **関連するWikiのPath**:実在する、本人が読めるプロジェクトのページ。
|
||||
2. **Wikiメモのサブ階層**:そのページの配下を表す相対Path。既定は `tasks`。複数階層も指定可。
|
||||
|
||||
例:
|
||||
|
||||
- プロジェクトの関連Wiki:`/projects/pageswiki`
|
||||
- サブ階層:`work/notes`
|
||||
- タスク件名:`通知UIの改善`
|
||||
- 作成先:`/projects/pageswiki/work/notes/通知UIの改善`
|
||||
|
||||
件名を1つのPathセグメントとして扱う。`/\\?#%` と制御文字はハイフンへ変換、単独の `.`/`..`/`_` はUUID付きの安全な名前へ置換する。相対サブ階層の絶対Path、空セグメント、親移動、制御空間 `_` は拒否する。
|
||||
|
||||
既存の関連WikiページUUIDがタスクにあれば、それをメモとして使う。なければ上記の候補Pathを確認し、明示的な確認後に新規作成する。初期本文はHTMLエスケープした件名のH1。表示ボタンからでも未作成なら作成確認→エディタとなる。編集時は利用可能な既定のHosted Editorを優先し、それ以外は標準の `/e/-/...` を利用する。
|
||||
|
||||
初回作成後はタスクの `page_uuid` で関連付ける。Wiki側のrename/移動に追従する。タスク件名やプロジェクトのサブ階層を変えても、既存のメモを自動rename/移動しない。同名ページが既にあれば409で停止し、詳細画面からの明示的な関連付け、または件名の変更を案内する。既存の内容を上書き・自動統合しない。
|
||||
|
||||
プロジェクト未選択/関連Wiki未指定の場合は設定を案内する。プロジェクトの関連ページ自体の新規作成は既存Wikiエディタで行う。リンク済みメモが削除・権限失効した場合、同じPathへ勝手に作り直さない。詳細画面で関連付けを明示的に解除してから再作成する。
|
||||
|
||||
## API・保存・公開の境界
|
||||
|
||||
- `GET items/{uuid}/note`:現在のPath、閲覧/編集URL、linked/exists/writable、TaskRecord、ETag。副作用なし。
|
||||
- `POST items/{uuid}/note`:新規作成と関連付け。`If-Match: "{task version}"`、JSON `{"path":"確認した作成先"}` が必要。欠落428、版/確認先変更412、Path衝突409。
|
||||
- Page、Path、初期Revision、タスクhead/revision/journal、共通outboxを同一transactionで確定する。プロジェクト版と関連Path→UUIDもwriter transactionで再照合。DB失敗時にPageや紐づけだけを残さない。CASファイルは既存仕様どおりrollback後に未参照ファイルとして残る可能性がある。
|
||||
- タスクは個人専用のまま。WikiメモはWiki Pathの公開設定と権限に従う。作成確認でこの違いを明示する。タスク所有権だけでWikiのread/create/writeをバイパスしない。
|
||||
- readonly・他人のタスク・失効membership・無効な拡張を拒否。既存Wikiへの明示リンクは従来のpage_path更新を利用する。
|
||||
- DBスキーマ変更なし。`notes_subpath,omitempty` はプロジェクト正本JSONの追加項目。未指定の既存正本のhashは変えない。旧バイナリでプロジェクト設定を保存するとこの追加項目が落ちるため、運用開始後はforward-fixを推奨する。
|
||||
|
||||
## 検証・残り
|
||||
|
||||
Go fixture:日別/持ち越し条件、親子cursor、補足親の私有境界、日付検証、メモ作成、保存失敗rollback、H1 escaping、同名衝突、確認先変更、UUID追従、readonly、Wiki書込権限を検証。
|
||||
|
||||
Chromium fixture(1440/1024/390/320px):親から日付未設定の子を展開、子の重複防止、明日への作成、時間枠の初期日、持ち越しの割当て、メモ編集ボタンで新規Wikiへ遷移、表示ボタンでViewerへ遷移。外部取り込みカレンダーにはアクセスしない。
|
||||
|
||||
残件:親子の計画日の明示的一括変更、日別キャパシティ、日別の完了実績、親子のドラッグ並べ替え、共有、メモの任意rename/移動のタスクUI統合、実機Safari検証。本番2インスタンスへ2026-09-25 07:07 JSTに反映済み。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 既定タスクリストの表示名変更
|
||||
|
||||
2026-09-27、`organizer.tasks 0.11.1`。**12:51 JSTに本番app/app2へ反映済み。** [反映記録](../../operations/deployments/2026-09-27-default-task-list-name.md)。Tasks.org実機の再試行は利用者確認待ち。
|
||||
|
||||
## 原因
|
||||
|
||||
利用者が既定リスト名を変更するとエラーになると報告。本番の秘匿済みログでは03:39:59 UTCに`PROPPATCH target=task_collection status=405`、認証結果は`basic_accepted`。0.11.0ではリストのPROPPATCHが未実装で、既定名`PagesWiki Tasks`も固定値だった。認証不良や名前の衝突ではない。
|
||||
|
||||
## 変更契約
|
||||
|
||||
- `PROPPATCH /_/api/v1/caldav/tasks/default/`のDAV:displaynameのsetを受理。末尾slashなしも同じリスト。
|
||||
- 表示名は`organizer_dav_default_lists`にdomain/owner単位で保存する個人設定。未設定なら従来の`PagesWiki Tasks`。トークンを交換しても同じ利用者の設定を使用する。
|
||||
- URLやプロジェクトなしという所属の意味は変更しない。架空のプロジェクトは作らない。タスク本文、UID、revision、ETagは変わらない。
|
||||
- 共通CalDAV home、旧task home、既定リスト自身のPROPFINDで同じ保存名を返す。索引再構築でも設定を失わない。
|
||||
- UTF-8で1〜300 bytes、空白だけや制御文字は拒否。XMLテキストとしてescapeして返す。名前をアクセスログへ追加しない。
|
||||
|
||||
## PROPPATCHと認可
|
||||
|
||||
[RFC 4918 §9.2](https://www.rfc-editor.org/rfc/rfc4918.html#section-9.2)の原子的更新・Multi-Statusに従う。全命令を検証後に保存し、正常時は207/property status 200。未対応propertyやremoveは403、無効な名前は409、同じ要求のその他の正常propertyは424で、部分更新しない。複数setは順序どおり解釈する。不正XML・DTD・過大なXMLの制限には共通DAV parserを用いる。
|
||||
|
||||
認証、tasks/all scope、write権限を必要とする。保存transaction内でwriterを取得してから現在のmembership/principal/トークンの失効・期限・scope/拡張の有効状態を再確認する。別domain/ownerへの設定変更はできない。
|
||||
|
||||
## 範囲と残件
|
||||
|
||||
今回の対象は既定タスクリストの名前のみ。通常プロジェクト/MKCALENDARリストのPROPPATCH、色・アイコン・任意dead property、リストDELETEは引き続き未実装。プロジェクトの名称はWebのプロジェクト編集で変更可能。Tasks.orgのupdateCollectionはdisplaynameを個別要求し、その後必要に応じて色・アイコンの別要求を送るため、それらの未対応応答は名前変更の成功とは分けて扱う。
|
||||
|
||||
## 検証
|
||||
|
||||
隔離HTTPテストで、日本語・XML特殊文字の名前、3箇所の探索結果、ETag/本文の不変、プロジェクトが増えないこと、schema再実行後の永続性、OPTIONSのPROPPATCH広告、malformed XML/不正名/未対応property混在の原子性を確認。他owner、別domain、readonly、calendar-only、匿名、失効トークン、拡張無効化も検証する。本番の既定名は変更しておらず、実機の再試行は反映後に必要。
|
||||
|
||||
実施結果:全Goテスト成功。chroncalの既定・共通・名前付き・通常Webプロジェクトの同期試験、vdirsyncer/Todoman試験も成功。追加の名前変更・認可・原子性テストは5回反復成功。
|
||||
@@ -0,0 +1,64 @@
|
||||
# タスクの所属統一とCalDAV上書き同期
|
||||
|
||||
後続0.11.1:[既定タスクリストの表示名変更](task-dav-default-list-name.md)を実装し、2026-09-27 12:51 JSTに本番反映。所属・URLは維持したまま、固定名PagesWiki Tasksを利用者ごとに変更できる。
|
||||
|
||||
2026-09-27。`organizer.tasks 0.11.0`。**12:18 JSTに本番app/app2へ反映済み。Tasks.org Desktop実機の再同期は利用者確認待ち。** [反映・移行確認記録](../../operations/deployments/2026-09-27-task-unification.md)。
|
||||
|
||||
利用者の決定:PagesWikiのプロジェクトと外部タスクリストを統一する。条件なしの書き込みは上書きを受け付け、トークン単位の上書き互換スイッチは設けない。競合を通知してどちらを採用するか選ぶ機能は次段階に実装する。
|
||||
|
||||
## 1. 確認した不整合
|
||||
|
||||
0.10.0では、MKCALENDARで作ったリストのみプロジェクトと一対一に対応し、通常のWebプロジェクトはプロジェクトなしのタスクと同じ既定リストに混在していた。また、既存リソースのPUT/DELETEは条件ヘッダ必須で、直接接続クライアントの無条件更新を428で拒否していた。
|
||||
|
||||
Tasks.org公開ソースの確認対象はcommit `0fde622e917ea2cbb0956c3effe9209c11045a67`。`CaldavSynchronizer.pushTask`は`remote.put(requestBody)`、削除は`remote.delete {}`で条件ヘッダを渡さない。依存するdav4kmp `1.0.0-beta01`(commit `dec7bd10952278c7ac196de111880f00d75d8f3e`)もそれを自動補完しない。本番の秘匿ログに認証成功後のPUT 428が反復していた。ただし、利用者のインストール版と調査したソースが同じか、個々のログがDesktop由来かは未確定。ctag追加による解決ではない。
|
||||
|
||||
- [Tasks.org同期処理](https://github.com/tasks/tasks/blob/0fde622e917ea2cbb0956c3effe9209c11045a67/kmp/src/commonMain/kotlin/org/tasks/caldav/CaldavSynchronizer.kt)
|
||||
- [dav4kmp HTTP処理](https://github.com/tasks/dav4kmp/blob/dec7bd10952278c7ac196de111880f00d75d8f3e/src/commonMain/kotlin/at/bitfire/dav4jvm/ktor/DavResource.kt)
|
||||
|
||||
## 2. 所属・URI契約
|
||||
|
||||
| 正本の所属 | CalDAVリスト |
|
||||
| --- | --- |
|
||||
| `ProjectUUID`が空 | `/_/api/v1/caldav/tasks/default/`。既存表示名PagesWiki Tasksは維持し、意味をプロジェクトなしに限定 |
|
||||
| 通常のWebプロジェクト | `/_/api/v1/caldav/tasks/projects/{projectUUID}/` |
|
||||
| 既存MKCALENDARプロジェクト | `/_/api/v1/caldav/{dav_collection}/`。既存URLを維持 |
|
||||
|
||||
- タスクのUUID、UID、filename、ProjectUUID、版、本文を移行で変更しない。名前やカテゴリから所属を推測しない。
|
||||
- 通常プロジェクトのURLは不変UUIDから導出するため、`dav_collection`を正本へ後付けする必要はない。表示名は常にプロジェクトのタイトル。名称変更でURLは変わらない。
|
||||
- `tasks/projects/`はタスク専用名前空間。予定カレンダーのUUIDと衝突しない。外部取り込み予定は読まない。
|
||||
- リストの新規タスクはそのプロジェクトへ所属する。Webで所属を変更するとリスト間を移る。CalDAVのMOVE実装とは別。
|
||||
- 閲覧できるのは同じdomain/ownerのプロジェクトのみ。アーカイブ済みプロジェクトは探索・アクセスから除外し、そのタスクを既定リストへ流出させない。
|
||||
- リスト全体の完全な探索に現在の256件上限を適用し、超過時に部分リストを返さず507にする。将来の大量プロジェクト向け探索最適化は残件。
|
||||
|
||||
## 3. 移行と古いクライアント
|
||||
|
||||
起動時のEnsureTasksSchemaで、ルーティング索引とタスクのリスト別identity索引を同じDB transactionで再構築する。全プロジェクト(アーカイブ済みも含む)とタスクの現行headから導出し、失敗時は全体をrollbackする。正本・履歴を書き換えず、反復実行でURI/ETagは変わらない。起動時の再構築はタスク数に比例する処理であり、リクエストごとには行わない。
|
||||
|
||||
既定リストから通常プロジェクトへ移った旧hrefは`organizer_dav_legacy_hrefs`に移行メタデータとして記録する。旧hrefへのGETは404、古い未同期PUTによる再作成は409 `task_collection_relocated`。別リストを旧href経由で変更・削除するaliasにはしない。これにより、古い端末の再送で同じタスクがプロジェクトなしに増えることを防ぐ。索引を再構築しても移行メタデータは保持する。
|
||||
|
||||
本番反映前後には未送信の変更を保全し、各端末でリストの再探索・新しいプロジェクトの同期有効化を行う。未同期データがある状態でアカウントやローカルデータを削除しない。409の場合は新しい所属リストを確認して未送信変更を反映する。0.10以下へ安易に戻すと旧既定リストに再混在するため、戻す場合はタスク拡張を停止し移行方針を確認する。
|
||||
|
||||
## 4. 書き込みの現行契約
|
||||
|
||||
- 条件ヘッダなしのPUT/DELETEを全タスクCalDAV接続で受理する。追加のトークン互換設定・User-Agent判定は設けない。既存のOPTIONS calendar-access広告設定とは独立した話。
|
||||
- 最後にcommitした内容を採用する。削除は従来どおりアーカイブ。削除後に無条件PUTが来た場合は同じidentityの新しい版として復元する。
|
||||
- 明示されたIf-Match/If-None-MatchはHTTPの事前条件として尊重し、不成立なら412。Web UI/JSON APIの版チェックは変更しない。
|
||||
- 保存は既存のwriter transactionとversion CASを維持する。条件なし書込の競合時は最新headを取得して最大8回再試行し、CalDAVで表現する項目だけを再適用する。PagesWiki固有の計画日・整理先・関連文書等を古いheadへ巻き戻さない。過度な競合は409で再同期を要求する。
|
||||
- 同時新規作成は同じhrefの1identityへ収束する。別hrefへのUID衝突、UID変更、他利用者へのアクセス、失効トークン、readonly、無効化された拡張は従来どおり拒否。
|
||||
- 新規head、CAS本文、organizer_revisions、organizer_changesは既存の同一保存処理を用いる。上書き前の版は保持される。PUT本文を正規化するためPUT成功応答にETagは付けず、GET/REPORTで取得する。
|
||||
- **この段階では競合通知も採否選択UIもない。** 古い端末の変更が新しい内容を上書きし得ることは、今回採用した動作。
|
||||
|
||||
## 5. 次段階:競合通知と採否選択(未実装TODO)
|
||||
|
||||
1. **比較の根拠と来歴**:書き込み元(Web/DAV、資格情報の非秘密ID)、対象task/domain/owner、受信時刻、base版が分かるか、上書き前/採用後の版を記録する。秘密値や生の本文をアクセスログへ出さない。DTSTAMPや端末時計だけで新旧を決めない。
|
||||
2. **baseが不明な更新**:条件なし要求だけでは競合を厳密に判定できない。直近配信版などの補助記録は参照先を共有する端末もあり確定根拠にならないため、「競合候補」として扱う。全ての通常編集を競合扱いしない検出条件と上限・保持期間を設計する。
|
||||
3. **候補保存とInbox outbox**:上書き前/受信版の参照をhead更新と同じtransactionで保存し、ownerの通知Inboxへ重複抑制付きで配送する。通常のアクティブ通知設定に従い、作業を強制的に遮らない。未解決候補が参照する版をGCしない。
|
||||
4. **比較・選択UI**:「上書き前を採用」「受信版を採用」「現在の内容を維持」を項目差分付きで表示。採用は履歴を戻すのではなく新しいrevisionを作成する。
|
||||
5. **解決の競合**:候補の解決時にも最新headを再確認し、通知後の第三の変更を黙って消さない。owner/domain/現在権限を再検証し、解決済み通知の二重操作を防止する。
|
||||
6. **受け入れ試験**:Webと二つのDAV端末の競合、更新対削除、復元、通信再送、遅延したInbox配送、別domain/owner、権限失効、履歴GC、同一候補の二重決裁。
|
||||
|
||||
## 6. 今回の検証範囲
|
||||
|
||||
合成データで通常プロジェクトの探索・所属、旧索引移行・再実行、URI/ETag維持、古いhref再作成防止、名前変更、他owner隔離、アーカイブの非流出、無条件同時更新・同時作成・削除・復元・履歴保持を検証する。既存の明示ETag競合試験、認可試験、共通CalDAV・CLI同期・Web回帰も継続する。外部取り込みカレンダーや本番の認証情報・本文をテストデータにしない。
|
||||
|
||||
実施結果:`go test ./...`成功。追加の所属・上書き試験は10回反復成功、関連試験の`-race`も成功。実chroncalで既定・共通home・MKCALENDAR・通常Webプロジェクトの各リストを検証し、vdirsyncer/Todomanも成功。ChromiumでタスクUI(desktop/laptop/mobile/mobile-small)とカレンダーUIの回帰試験成功。これらは隔離fixtureの結果であり、Tasks.org Desktopの実機成功や本番反映を意味しない。
|
||||
@@ -0,0 +1,49 @@
|
||||
# インラインタスク、サブタスク、日割り工程表
|
||||
|
||||
更新:2026-09-25。`organizer.tasks` 0.6.0。実装・隔離fixture検証済み。同日05:59 JSTに本番2インスタンスへ反映済み。[反映記録](../../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)。
|
||||
|
||||
## 一覧中心の編集
|
||||
|
||||
0.7.0の追加仕様(2026-09-25 07:07 JST本番反映済み):[日別計画・親子グループ・Wikiメモ](task-daily-notes.md)。以下の0.6.0契約を拡張する。
|
||||
|
||||
件名・状態・取り組む日・期限・見直す日・工程開始/終了を一覧で直接編集する。変更確定/フォーカス移動時に保存する。詳細メモ、通知時刻等は既存の詳細画面へ残す。時間枠ボタンは一覧から直接カレンダー追加モーダルを開く。
|
||||
|
||||
保存は行が取得したversionでIf-Matchを行う。完全なTaskRecordを再取得してから変更項目を合成するが、If-Matchは再取得したversionへ勝手に進めない。他の画面との競合では入力を保持し、行の再読込で明示的に破棄できる。編集中/保存中は一覧の自動再読込で入力を捨てない。
|
||||
|
||||
### コンパクト一覧(2026-09-25追加、06:17 JST本番反映済み)
|
||||
|
||||
[本番反映記録](../../operations/deployments/2026-09-25-compact-task-ui.md)。
|
||||
|
||||
- 幅1024px以上は表に近い1タスク1行。共通見出しの下に完了操作・件名・状態・取り組む日・期限・見直す日・工程開始・工程終了・操作を並べる。行高は通常約34px、行内のmargin/gapは0。サブタスクも列幅を揃え、件名の字下げと親へのリンクで階層を示す。
|
||||
- 利用可能な横幅を使い、列が収まらないPC幅では一覧の内側のみ横スクロールする。入力や操作を折り返さず、ページ全体の横はみ出しを防ぐ。詳細・カレンダー追加・再読込・子の展開・子の追加はラベル付きアイコン操作。
|
||||
- 1024px未満はフィールドラベルを省略しないカード状の配置。日付は2列、入力文字16px以上、タッチ対象44px以上。サブタスクは罫線と字下げで区別する。入力・保存契約はPCと同一。
|
||||
- 保存中/成功の通知はスクリーンリーダー向けstatusに残し、行を増やさない。保存エラー・競合は行の下に本文を表示して入力を保持する。アイコンにはtooltipとアクセシブル名を設け、サブタスクの展開状態をaria-expandedで伝える。
|
||||
- Chromium fixtureで1440px・1024px・390px・320px幅、PC列揃え、タッチ領域、インライン保存、階層表示を検証する。実機Safariのdate入力等は引き続き別途確認が必要。
|
||||
|
||||
## 階層と日付
|
||||
|
||||
`parent_uuid`を持つサブタスクを親の一覧からインライン追加できる。初版は親→サブタスクの2階層。同じDomain・所有者のtaskのみ。自己参照・循環・3階層目・他人の親・新規のarchived親への配置を拒否する。親の完了・archiveは既存の子を完了/archiveしない。
|
||||
|
||||
子は独立した件名、状態、各種日付、見積りを持つ。作成時に親のproject/bucket/priorityをコピーするが、その後の自動継承はしない。Todayの見積もりは各項目独立で加算するため、親と子に同じ工数を二重計上しない運用とする。roll-upは未実装。
|
||||
|
||||
新しい`start_on`/`end_on`は工程のcivil dateで、両端を含む。片方だけならその1日。逆順と366日を超える範囲を拒否する。期限/計画日や実際のカレンダー時間枠は自動変更しない。
|
||||
|
||||
## 工程表とナビゲーション
|
||||
|
||||
- `/v/plan/tasks/schedule`:ドメイン現在月。
|
||||
- `/v/plan/tasks/schedule/YYYY/MM`:月の日割り工程表。日付列に工程のバーを表示、タスク詳細へ遷移。
|
||||
- `?project={UUID}`でプロジェクトを絞り込む。
|
||||
- API:`GET /_/api/v1/extension/organizer.tasks/schedule?month=YYYY-MM&project=...`。
|
||||
- 月最大200件、超過はpartial表示。開始日の索引と366日上限で走査範囲を制限する。メモは返さない。
|
||||
- family API:`items?view=family&parent={UUID}`。100件まで+cursor、完了/archive済みの子も確認できる。
|
||||
- ホームの検索ショートカットへタスク一覧アイコン、上部ナビバーへ「今日のタスク」モーダルを追加。開くまで一覧fetchをしない。
|
||||
|
||||
## Migration、検証、次段階
|
||||
|
||||
DBにparent/start/end列と子一覧・工程表索引を追加する。新フィールドは空ならcanonical JSONから省略するため既存正本のhashを変更しない。工程と親参照は版管理対象。同一transactionで正本参照、投影、履歴、outbox、通知を更新する。
|
||||
|
||||
旧バイナリは新フィールドを保存時に落とすため、新しい階層・工程を利用した後の単純なbinary rollbackは避け、forward-fixを優先する。データごと戻す場合はDBと正本を同じバックアップ時点へ戻し、それ以降の更新が失われることを確認する。
|
||||
|
||||
Goで日付範囲、月またぎ、階層制約、親状態と子の独立性を検証。ChromiumでPC/スマートフォン幅のインライン日付編集、子追加、Todayモーダル、時間枠・Pomodoroの既存操作を検証。
|
||||
|
||||
TODO:日割りバーのdrag/resize、折りたたみ状態保持、子の昇格/別の親への移動UI、親への工数roll-up、日付未設定を工程表から割当てる操作、依存関係・共有・日課instance。時間単位の工程表とは別機能として扱う。
|
||||
@@ -0,0 +1,118 @@
|
||||
# タスクの時間枠とPomodoro
|
||||
|
||||
更新:2026-09-25。`organizer.tasks` v0.5.0 の実装契約。[個人タスクの基本設計](tasks-implementation.md)、[期限日/計画日の通知](task-reminders.md)を前提にします。
|
||||
|
||||
## 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同期は今回の対象外です。
|
||||
@@ -0,0 +1,45 @@
|
||||
# タスク通知:予約・配信・取消
|
||||
|
||||
更新日:2026-09-25。個人タスクの期限日/計画日のInbox通知を実装。カレンダー通知、メール、OS push、集中タイマー、quiet hours、通知の集約は未実装。
|
||||
|
||||
## 操作と既定値
|
||||
|
||||
タスク編集に「期限日にInboxへ通知」「取り組む日にInboxへ通知」と時刻入力を追加する。両方とも既定OFF。通知を選択した日付が必須で、未指定の時刻は09:00。期限は引き続き日付型であり、通知時刻によって時刻付きの締切へ変換しない。プロジェクトには通知を設定しない。
|
||||
|
||||
保存時のドメイン設定のタイムゾーンをサーバー側で取得し、`reminder_timezone` に記録する。APIが指定した別のzoneを信用しない。設定画面のzone変更だけでは保存済み予約を動かさず、タスクの再保存で新しいzoneを適用する。編集画面には保存時に適用するzoneを表示する。
|
||||
|
||||
夏時間で存在しない現地時刻は保存を拒否する。重複する現地時刻はGoのタイムゾーン解決で決まる一方の時刻に固定し、二度送らない。civil date/timeとzoneから解決した発火時刻を予約に保存する。
|
||||
|
||||
## 保存と予約
|
||||
|
||||
`TaskRecord` の追加項目:`notify_due`、`notify_planned`、`reminder_time`、`reminder_timezone`。既存レコードの未指定は通知OFFとし、旧データ移行だけで通知を有効にしない。
|
||||
|
||||
`organizer_reminders` はDomain・task UUID・種類を主キーとし、owner、source version、発火時刻、civil date、zone、通知一意キー、pending/sent/skippedを保持する。`(state,fire_at_ms,...)` の索引から配信対象だけを取得する。
|
||||
|
||||
予約の作成/更新/取消は、タスクhead・履歴・専用ジャーナル・共通outboxと同じtransactionで行う。予約作成失敗で他だけがcommitされることはない。予約自体は正本から導く索引であり、共通outboxの旧イベントを使って非同期に復活させない。これにより、完了・日時変更と旧イベントの遅延配送の競合を避ける。
|
||||
|
||||
完了、取りやめ、アーカイブ、通知OFFで対応する予約を取り消す。タイトル/メモの変更ではsource versionのみ追従し、同じ通知を再送しない。日付・通知時刻・zoneの変更は新しい通知機会になる。
|
||||
|
||||
## 配信と権限
|
||||
|
||||
組み込みイベント `task.reminders.deliver`(定義ID `builtin.task.reminders`)を既定60秒間隔で実行する。最大100予約/回、処理上限3秒、priority -2、再試行3回。スケジューラの停止・同時実行数制御に従い、設定画面で間隔変更・停止・手動実行が可能。起動時に管理者の設定を上書きしない。
|
||||
|
||||
SQLite writer transactionの中で候補取得、現在版・状態、現在所有者、membership、Principal状態、Domainの有効性とlocal配置、拡張の有効性を再検査する。送信可能なのはactiveまたはreadonlyの現所有者のみ。他人の担当指定・共有配送はまだ行わない。
|
||||
|
||||
Inbox挿入と予約のsent更新は同時commit。一意キーはDomain、task UUID、種類、civil date/time、zoneから決定する。タスク版番号は一意キーに入れず、予約のsource version照合に使う。したがって件名変更・完了取消・ワーカーの再試行で、同じ機会の通知を再送しない。
|
||||
|
||||
権限失効・拡張無効化・現行版不一致の場合はskippedとし、再試行を繰り返さない。自動で遡って復活させず、再保存された現在の設定で予約を再評価する。Inboxへすでに入った通知は履歴として残すが、現在読めない件名・リンクは表示しない。
|
||||
|
||||
## 遅延と履歴
|
||||
|
||||
配信対象は発火時刻を過ぎた**同じ現地日付**の予約だけ。スケジューラ停止中などに前日以前となった分はskippedとし、古いBacklog通知を大量に送らない。日付境界直前の通知は、実行遅延で翌日に入ると送られない。時刻ぴったりの配信やOS通知を保証するものではない。
|
||||
|
||||
Inboxには一般的な通知文と対象UUIDだけを保存し、個人タスクの件名・本文を複製しない。API/通知詳細表示時に、現所有者・membership・最新予約と版を照合して現在の件名を取得する。完了/取消/日付変更などで対象予約が一致しなければ、「完了・変更済み、または現在利用できません」と表示し、taskへのリンクを外す。通知一覧の表示にCAS本文は読まない。
|
||||
|
||||
上部ナビの未読赤丸は可視タブで最大1分間隔、またはタブ復帰時に小さな問い合わせで更新する。非表示タブでは定期fetchしない。同じスクリプトが共通ヘッダーと通知ページに読み込まれてもイベントを二重登録しない。既存の「Inboxを開いたとき赤丸を消し、表示した通知を既読にする」挙動は維持する。
|
||||
|
||||
## 検証と後続
|
||||
|
||||
テスト対象:初期OFF、指定日とzoneでの予約、夏時間、存在しない時刻、日付変更・完了・取消・アーカイブ・OFF、権限失効、拡張停止、期限切れ予約、同一機会の重複防止、並列配信、予約/Inbox挿入失敗時のrollback、現時点での件名表示、別所有者への漏えい防止。ブラウザでは通知設定の保存、バックグラウンド配信後の赤丸、Inbox表示まで隔離環境で確認する。
|
||||
|
||||
次段階:個人/ドメインの通知既定値、quiet hours、集約、予約状態の詳細表示、ローカルカレンダーの時間枠との関連付け・予定通知。外部から取り込んだカレンダー内容へのアクセスは、別途許可があるまで行わない。
|
||||
@@ -0,0 +1,105 @@
|
||||
# タスク管理拡張:実装契約と次段階
|
||||
|
||||
更新日: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サーバーでデスクトップ/モバイルの実操作を検証します。運用中の外部カレンダー・予定本文にはアクセスしません。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 13. タスクとチケット
|
||||
|
||||
状態:個人用local taskとプロジェクト、期限日/計画日のInbox通知、個人ローカルカレンダーへの時間枠、永続化Pomodoroを実装(2026-09-25)。個人タスクの限定CalDAV/CLI同期は0.8.0で実装・隔離試験済み、2026-09-26 00:24 JST本番反映済み。共有、チケット、一般のカレンダー予定通知、繰り返し・差分CalDAV同期は設計段階です。[実装契約と次段階](tasks-implementation.md)、[時間枠とPomodoro](task-planning-focus.md)、[CalDAV/CLI](task-caldav.md)を参照してください。
|
||||
|
||||
## 二つの用途
|
||||
|
||||
タスクは「誰が何をいつまでにするか」。チケットは受付番号、責任者、状態遷移、履歴、問い合わせや障害等の業務上の単位です。チケットをそのままカレンダー予定にしません。
|
||||
|
||||
第一案は共通work itemを基盤に、task viewとticket workflowを分けます。チケット固有の公開範囲・番号・遷移が複雑になれば専用表へ分離しますが、認証やコメントは共通基盤を再利用します。
|
||||
|
||||
## データ案
|
||||
|
||||
- 共通:UUID、Domain、collection、kind、title、body_page_uuid、creator、assignee、version、created/updated、archive状態。
|
||||
- タスク:status、priority、start/due、完了日時、checklist、parent task、dependency。
|
||||
- チケット:queue UUID、queue内の単調な受付番号、workflow版、type、labels、watchers、resolution。
|
||||
- 添付:固定Document参照と出典。コメント:共通thread。変更履歴:actor付きevent。
|
||||
|
||||
Path、受付番号、題名はidentityではありません。同じPageに複数work itemが関連しても、暗黙に一つへ統合しません。assignee表示とPrincipalの権限付与も別です。
|
||||
|
||||
## 状態と操作
|
||||
|
||||
最初のtaskはtodo / doing / done / cancelledとし、遷移を監査します。未完了への復帰で元の完了記録を消さず、履歴を残します。チケットはopen / in_progress / resolved / closedを案とし、reopen権限、完了理由、受付担当と解決担当を後で分けられる構造にします。
|
||||
|
||||
create/read/update/assign/transition/comment/manageは概念上分離します。外部依頼者には自分のチケットだけを見せる場合があるため、queue一覧の閲覧とticketの閲覧を分けます。担当にしただけで非公開本文が読めるようにしません。
|
||||
|
||||
## 期限・依存・繰り返し
|
||||
|
||||
期限は日付だけか時刻付きかを明示します。日付のみをUTC午前0時へ変換しません。依存は循環を拒否し、削除済み・閲覧不可の依存先の詳細を表示しません。親子進捗の自動集計は別projectionです。
|
||||
|
||||
繰り返しは第二段階。完了時に次のinstanceを作る方式と、iCalendar recurrenceを扱う方式の対応を先に決めます。完了イベントの二重配送で次回タスクが二つ増えない鍵を必要とします。
|
||||
|
||||
## CalDAVとの関係
|
||||
|
||||
iCalendarにはVTODOがあり、CalDAVはカレンダー資源を扱います。ただしクライアントごとのタスク・繰り返し対応を試験する必要があります。これは「CalDAVだけでチケット管理が完成する」という意味ではありません。[iCalendar](https://www.rfc-editor.org/rfc/rfc5545)、[CalDAV](https://www.rfc-editor.org/rfc/rfc4791)。
|
||||
|
||||
最初はlocal task一覧と期限表示、次にVTODOの明示export/import、最後に選定クライアントとの同期を検討します。workflow、コメント、細かな権限をVTODOへ無理に押し込みません。失われる情報を変換警告に残します。
|
||||
|
||||
## 実装TODO
|
||||
|
||||
- TASK-1:個人local作成/取得/更新、version競合、Page参照、所有者限定一覧は実装済み。削除は復元可能なアーカイブ、物理削除は未提供。
|
||||
- TASK-2:日付の期限/計画/見直し、タイトルフィルタ、archive、個別ONのInbox通知は実装済み。担当共有、通知集約、exportは未実装。
|
||||
- TASK-3:checklist/依存とboundedな一覧・calendar射影。
|
||||
- TICKET-1:queue・番号予約・workflow版・権限付き遷移。
|
||||
- TASK-4:VTODO fixture、未対応property保持、繰り返し・同期の判断。
|
||||
|
||||
同時採番、二重POST、完了取消、夏時間・終日、assignee失効、本文削除を受け入れ試験にします。
|
||||
@@ -0,0 +1,39 @@
|
||||
# 7. ビューア・エディタ・連携アダプタ
|
||||
|
||||
状態:主要形式のビューアとホスト型エディタあり。ネイティブ起動・任意外部コード実行は保留。
|
||||
|
||||
## 正本と表示
|
||||
|
||||
文章はHTMLを正本にし、Markdownは編集・import形式として変換します。Office、PDF、画像、音声、動画、Canvas等のバイナリ・固有形式をすべてHTMLへ不可逆変換する意味ではありません。MIME、拡張子、限定された内容判定でProjectionを選びます。
|
||||
|
||||
拡張子のないテキストも文字コードと先頭内容を限定的に調べます。長いTXT/JSONは部分取得し、行番号・syntax highlight・ミニマップ等はブラウザのDOMやメモリ上限の中で動かします。
|
||||
|
||||
## 対応領域
|
||||
|
||||
CSV、コード、PDF、画像lightbox、音声・動画、ZIP等のarchive、コミック、EML、DEB/PEのメタデータ、Excalidraw等に初期実装があります。Office全般の完全再現や任意archiveの無制限展開を保証するものではありません。
|
||||
|
||||
PDFページ数・archiveメタデータ・サムネイルは原則キューで生成し、未生成ならアイコン・待機状態を返します。一部のentry展開はまだ限定された前景処理で、キャッシュ付き生成への移行が必要です。
|
||||
|
||||
## 連携アダプタ
|
||||
|
||||
アダプタはDocumentの表示・編集を担当します。MIME、対応操作、設定schema、外部origin、リソース上限を宣言します。ランキングやメール収集はアダプタではなくシステム拡張です。
|
||||
|
||||
code-server、vim.wasm等はホスト型連携として扱います。workspaceへの配下展開、HTML/Markdown変換、保存競合、短命なsessionをホスト側で制御し、通常のログインcredentialをそのまま渡しません。vim.wasmのruntime改善は現在保留です。ネイティブvim.exe等への直接受け渡しも保留し、補助アプリ不要で自由起動できるとは扱いません。
|
||||
|
||||
## HTMLの安全性
|
||||
|
||||
Viewer・履歴・印刷・Editor previewはinert allowlistを使い、保存されたscript/style/iframeを通常ページの権限で実行しません。正本バイト列を勝手に変更せず、表示段階の安全化として区別します。埋め込みは登録済みproviderとsandboxによる明示契約が必要です。
|
||||
|
||||
## ビューアのキーボード操作
|
||||
|
||||
通常のViewerでは、`e` 編集、`f` 検索、`v` 表示形式切替、`c` 配下への新規作成、`u` アップロード、`s` 共有リンク、`p` 権限導線を使えます。`Ctrl+↑` は親Path、`Ctrl+↓` は配下一覧、`Ctrl+→` / `Ctrl+←` は前後ページです。入力欄・select・textarea・contenteditable・開いているdialogではショートカットを停止します。
|
||||
|
||||
共有リンクは現在の正規URLをコピーし、X Web Intentをユーザー操作で開く方式です。これは公開権限を付与したり、未公開Pageを自動公開したりしません。権限ダイアログがその画面にない場合、City governanceの案内だけを表示します。
|
||||
|
||||
## Macroと変換の二つのモード
|
||||
|
||||
編集用のHTML→Markdownではchildren等のmacro宣言を保持します。表示・preview・export向けのProjectionでは認可済みの結果を展開します。展開された一覧を保存本文へ逆流させないことがround-tripの条件です。
|
||||
|
||||
## TODO
|
||||
|
||||
変換provider/version・警告・原本保持、未対応構文の欠落検知、draw.io・nwdiag等の統合、widgetの許可・同意・CSP、decoder隔離、プラグイン停止時の安全なfallback。HTML編集の段階的改善は第17章で具体化します。nwdiagはネットワーク構成を記述するソースと、静的SVG/画像としてのProjection、明示的な編集アダプタを分離して設計します。
|
||||
Reference in new issue
Block a user