Files
pages/docs/design/ja/task-productivity-contacts.md
Anya Tokugawa e65ca56f92
Build and publish container images / images (push) Successful in 12m27s
feat: add audited work records and controlled digest retries
2026-11-08 02:35:29 +09:00

20 KiB
Raw Permalink Blame History

タスク作成と作業記録と個人アドレス帳

タスクの入口をWeb・CLI・メールで共通化する。タスク、作業記録、既定値、配信設定、連絡先はDomainと本人に属する。既存のタスクAPI・CalDAVを変更せず、個人向けAPIを追加する。管理者であることだけでは他人のデータを読めない。

作成API

基点は /_/api/v1/extension/organizer.tasks/。通常のログインセッションのBearer認証を使う。CalDAV専用資格情報はこのAPIの資格情報ではない。

操作 Methodと相対URI 契約
タスクを作る POST capture UUIDのrequest_id、titleが必須。notes、project_uuid、assignee_uuid、due_on、start_on、planned_on、review_on、estimate_minutes、complexityを指定可能
既定値 GET / PUT preferences PUTはGETしたversionを含める。競合は412
実行中の記録 GET work itemがnullなら停止中
開始 POST work action=start、uuid、task_uuid。開始時刻はサーバーで記録
終了 POST work action=stopとGETで得たitem。versionで条件付き更新
作業一覧 GET work-history?from=YYYY-MM-DD&to=YYYY-MM-DD&limit=50&after=... fromを含みtoを含まない期間と重なる本人の記録。最大367日、1ページ最大100件、取消済みを含む
作業の履歴 GET work-history/{uuid}?before=VERSION 新しい版から最大100件。nextが0なら終了。それ以外は次のbeforeへ渡す
作業の訂正・取消 POST work action=correctまたはcancel、uuid、version、reasonが必須。終了済み・未取消の記録のみ
レポート GET report?from=YYYY-MM-DD&to=YYYY-MM-DD fromを含み、toを含まない。ドメインのtimezone、最大367日
予定を作る POST calendar-capture request_id、calendar_uuid、title、from、to。本人所有・非公開・非共有・外部sourceなしのカレンダー限定

captureは省略した項目に本人の既定値を適用する。日付の空文字は既定値を使わず明示的に解除する。日数は作成日のドメインtimezoneにおける暦日で、0は当日、空欄は未設定。担当者UUIDは計画上の注記であり、所有権の移転や閲覧権限の付与ではない。

Webの新規作成・クイック追加・サブタスク追加でも既定値を読む。サブタスクのプロジェクト・優先度・bucketは親の所属を優先する。既存汎用items APIとCalDAVではクライアント指定を尊重し、新しいcaptureの既定値を暗黙適用しない。

同じrequest_id・同じ要求内容の再送は既存タスクを返す。最初の保存後に既定値やタスクが更新されても作り直さない。同じrequest_idで別内容を送ると412。要求のreceiptとタスクRevisionは同一トランザクションで保存する。captureのJSON入力は2 MiBまで、その他の作成・更新は32 KiBまで。件名300 UTF-8 bytes、メモ16 KiBまで。

メール本文のWiki保存

v0.9.0は任意の wiki_suffix をcaptureに追加する。CLI v0.4.0はML連番なら リスト名/連番、それ以外は YYYY/MM/UUID(Message-IDあり)または YYYY/MM/原文SHA-256(なし)を送る。Dateの記載タイムゾーンの年月を採用し、不正・欠落時のみ初回取り込みUTC年月を用いる。判定はCLIで確定してoutboxに保持する。リスト名はASCII英数字で始まる100文字以内の英数字・._-、連番は先頭ゼロ除去後最大20桁。複数表記は先頭を採用する。不正な表記は年月方式へフォールバックする。

サーバーはMLの2階層または年月の3階層だけを受理し、絶対Path・.・..・予約セグメント・query/fragment・不正年月・不正識別子を拒否する。解決した親Pathの下へ結合し、その完全Pathのread/create/write権限を検証する。衝突は409で、別Message-IDのタスクも部分作成しない。wiki_suffixはwiki_body指定時のみ許可する。省略時は従来の mail-request_id とし、旧receiptのhash・保存先を維持する。新CLIは旧サーバーに暗黙フォールバックしない。既存ページの自動移動、同じ件名・同じ連番の上書きは行わない。設定変更や月替わりで保留要求を書き換えず、異なるオプションでの上書きを拒否する。

v0.8.0ではcaptureに省略可能な wiki_body と wiki_prefix を追加する。wiki_bodyを省略した従来クライアントの契約・receipt hashは変えない。本文を指定した場合、親Pathは要求のwiki_prefix、個人preferencesのwiki_prefix、選択プロジェクトの関連WikiとNotesSubpath(未設定はtasks)の順に解決する。いずれもなければ422 wiki_prefix_required。空の明示指定も拒否する。個人設定はDomain・本人単位で、既存preferences JSONに保存するため新規schema migrationは不要。

本文は256 KiBまでのUTF-8テキスト。H1に件名、preに本文をHTMLエスケープして格納し、波括弧も実体参照にしてマクロを実行しない。v0.8.1、およびv0.9.0以降でwiki_suffixを省略した場合のPathは 親Path/mail-request_id。CLIは接続先・本人・Message-ID(なければ原文SHA-256)からrequest_idを生成するため、Path末尾は件名・日本語の文字数・ML連番に依存しないASCIIになる。Message-ID自体はURLへ露出しない。既存Pathとの競合は409で、既存ページへ追記・上書きしない。新規Wikiのobject/path/revisionとactivity outbox、タスクのPageUUID、capture receiptは同一DBトランザクションで保存する。rollback時に未参照のcontent-addressed Documentファイルが残る可能性は既存DocumentStoreと同様だが、公開可能なページや片方だけのタスクは残さない。

v0.8.0の件名入りPathは自動移動しない。既存receiptの同一要求再送は元のページを返す。CLI v0.3.1は先頭のML連番を除去し、長い自動件名は300 UTF-8 bytes以内に文字境界で省略、変更前のSubjectをWiki本文へ保持する。旧版で保存済みの要求を新しい件名・本文で再作成すると412となるため、通信失敗した要求は保存済みoutboxのretryを使う。v0.8.1ではサーバーAPIの入力フィールド・receipt hash形式を変更していない。v0.9.0ではwiki_suffix未指定時のhashを維持し、指定時はsuffixもhashの対象に含める。

保存前に対象Pathへのread/create/write権限を検証する。個人タスクの所有権はWikiへの権限を付与しない。Wiki本文の公開範囲は保存先のACLに従うため、個人設定UIに注意を表示する。再送は既定値の再解決より前にreceiptを確認し、既定Pathの変更で重複作成しない。成功応答はitemとpage_pathを返し、タスクの既存メモ操作から関連Wikiへ移動できる。

個人設定の既定プロジェクトは保存済みUUIDを選択状態・既定選択状態の双方に反映する。最初の100候補にない場合も本人のitemを取得して名前を表示し、取得できない場合はUUIDを保持して別項目の保存で意図せず解除しない。CLIの本文抽出・再送・NeoMutt設定は独立pages-cliリポジトリを正本とする。

calendar-captureも同じUIDを再利用し、再送で既存予定を上書きしない。時刻は 2026-11-02T09:00 のドメイン時刻、またはオフセット付きRFC 3339。終了は開始後、最大31日。予定内容を取得する前にPersonalLocal制約をロック内で検査する。外部取り込みカレンダーの内容を読まない。

作業時間と達成度

Webのタスク行の▶から開始し、上部の作業記録欄で終了する。CLIは task start UUID / task stop。タイマーはサーバーで継続するので、ブラウザや端末を閉じても止まらない。停止はタスク完了とは別操作。忘れずに終了すること。同一人物で同時に開始できる記録は1件。

/v/plan/dashboard の達成度ウィジェットは完了数、ポイント、作業時間、Pomodoro集中時間を表示する。旧 /v/plan/tasks/report はここへ移動する。配置・保存の契約を参照。ポイントは 1 + ceil(見積分数 / 30) × 複雑度。複雑度は1〜5、未設定の旧タスクは1。見積なしは1ポイント。完了の取消は集計から除外し、再完了するとその日の実績になる。完了済みタスクの見積変更も現在のポイントへ反映される。これは個人の振り返り指標であり、人事評価や客観的生産性の尺度ではない。

深夜をまたぐ作業はローカル日付境界で分割し、夏時間の日も24時間固定にしない。Pomodoroと手動記録は別集計で、両者を合算しない。各系列は最大10,000件で、上限到達時はpartialを返して期間の絞り込みを促す。

作業記録の訂正と取消

2026-11-08に organizer.tasks 0.13.0 としてソース実装。/v/plan/tasks/work で一覧と変更履歴を確認し、開始・終了をインラインで訂正する。タスク一覧とダッシュボードの達成度ウィジェットから移動できる。初期期間はドメイン時刻の今日を含む30日。ページ送りは開始時刻・UUIDのkeysetで行い、一度に全履歴を描画しない。変更履歴も開いた記録だけ取得する。スマホはラベル付き縦配置にし、操作部を44px以上とする。

訂正には start_ms・end_ms、または start・end の日時ペアを渡す。日時文字列はオフセット付きRFC 3339、あるいはドメインのタイムゾーンでの YYYY-MM-DDTHH:mm[:ss]。夏時間移行で存在しない・二通りに解釈できるローカル時刻は422。繰り返される時刻はAPIから明示オフセットを指定する。Webで未変更の時刻は元の瞬間をRFC 3339で送るため、ミリ秒やオフセットを失わない。

開始はUNIX epochより後、終了は開始より後かつ現在以前、訂正後の長さは31日以内。同じ本人の他の未取消記録と重なる区間は、別Domainも含めて412で拒否する。隣接区間は許可し、他Domainの記録内容は返さない。実行中は従来の終了操作を先に行う。reason は前後空白除去後1〜500 UTF-8 bytes、改行・NUL不可。Web入力は160文字まで。

取消は物理削除ではなく cancelled_ms を記録し、作業時間レポートから除外する。タスクの状態・完了ポイントは変更しない。元の時刻と全変更履歴は残る。訂正・取消後の自動復元、過去の記録の新規挿入はこの段階では扱わない。

現在値と監査snapshotは同じwriter transactionで保存する。認可・拡張機能の有効状態をロック内で再検査し、versionが一致しない更新は412。理由・変更前後の時刻・版・変更時刻を記録し、他人の記録を管理者権限だけで操作する経路は設けない。通信結果が不明な訂正・取消の再送もversionを検証し、古ければ412にする。最新値と履歴を再取得して判断する。Webは失敗時に入力を保持し、自動上書きしない。従来の開始・終了の再送契約は維持する。

移行前の記録には過去の編集履歴を捏造しない。初回の変更時に直前の値をbaselineとして捕捉する。baselineのchanged_msは捕捉時刻であり、過去の編集時刻ではない。未変更の旧記録を開いた際は現在値だけをbaselineとして表示する。

プロジェクト別の集計

report の projects 配列にUUID・タイトル・完了数・ポイント・作業時間を返す。ダッシュボードの達成度ウィジェットに表を追加し、日付セルで選んだ日の内訳にも反映する。プロジェクトなしは独立した行とする。所属は現在のタスクから取得するため、過去時点の所属スナップショットではない。Pomodoroはプロジェクト表に合算しない。

集計は既存の上限付き取得結果を再利用し、プロジェクトごとに追加クエリを発行しない。10,000件上限でpartialとなる場合はプロジェクト表も部分集計であり、全件合計とは表示しない。

毎日のメール

/-/sys/config?panel=organizer の個人設定で本人が有効化する。旧 /v/plan/tasks/settings もここへ移動する。送信先は現在の本人のアカウントメールアドレスのみ。管理者のSMTP設定が必要。時刻はHH:mmとIANA timezoneを保存する。task.digest.deliver イベントが60秒周期で期限到来設定を最大20件ずつ処理する。キュー停止・負荷・SMTP遅延で配信時刻が遅れる場合がある。

当日の計画・期限到来タスクを最大100件送る。件名、期限、取り組む日、見積、タスクURLを含め、メモは送らない。送信直前にアカウント状態・同意のversion・送信先を再確認する。メールによる保存・転送の可能性があるため、既定は無効。

SMTPとSQLiteをまたぐexactly-onceは保証できない。送信前にDomain・本人・日付で予約し、結果不明の場合は自動再送しない。翌日は通常通り処理し、過去日の取りこぼしをまとめて送らない。

2026-11-08に organizer.tasks 0.14.0 として配信履歴・当日分の手動再送・詳細90日保持をソース実装。個人設定の折り畳み履歴から操作する。送信済み/結果不明の再送には重複の了承が必要。詳細の保持期限後も日別予約・再送receiptを残し、重複防止を維持する。migration v4とDB外のメール送信を考慮した復旧条件は同設計を参照。

トップ検索コマンド

add task 見積を確認 project:"開発 計画" cost:2h due:2026-11-03 review:2026-11-02 complexity:3
add task 文書を書く start:2026-11-02 planned:2026-11-02
add cal 打ち合わせ calendar:personal from:2026-11-02T09:00 to:2026-11-02T10:00

project: は名前またはUUID、候補を表示する。calendar: は名前・pretty_name・UUID、対象が1つだけなら省略可能。スペースを含む名前は引用符で囲む。工数は2h、30m、1.5hなど整数分に換算できる値。日付はYYYY-MM-DD。

Enterでは確認欄を表示し、「作成」で保存する。通常の検索候補への移動とは分離する。未知のオプション・重複指定・曖昧な名前は拒否。通信失敗時は同じ画面の再試行で同じrequest_idを使用する。トップ検索の入力は再読込をまたぐ永続下書きではない。

個人アドレス帳

画面は /v/plan/contacts、APIは /_/api/v1/extension/organizer.contacts/。拡張機能organizer.contactsを無効化すると読み書きとも停止する。Principal・プロフィール連絡先とは独立し、メール一致による自動アカウント紐付けはしない。

名前、複数メール・電話、所属、メモを編集できる。GET itemsはqとafterで最大100件ずつ検索・取得。POST itemsでUUID付き新規作成、GET items/UUIDで詳細、PUT items/UUIDでversionとIf-Matchを伴う条件付き更新。削除はdeleted=trueの同じPUTで行い、一覧から除外する。「削除済み」へ切り替えて復元できる(一覧APIのdeleted=1、更新時deleted=false)。削除したデータとvCard snapshotは保全される。

POST importは1件のUTF-8 vCard、GET items/UUID.vcfは書き出し。Webは最大2 MiB・200件のファイルを確認後に1件ずつ取り込み、失敗したカード番号を報告する。原子的な一括処理ではなく、成功分は保持する。同じUID・同じ内容は重複登録せず、同じUIDの異なる内容は412。UIDなしは入力バイト列のSHA-256から安定したUIDを補う。

vCard 3.0/4.0のUTF-8を対象とし、fold/unfold、テキストescape、複数のEMAIL/TEL、未知propertyを扱う。未対応propertyは保存・再出力し、PHOTO等の外部URLを取得しない。変更していない編集項目のparameterや繰り返しも保持する。変更した項目は画面の値で置換するため、その項目のTYPE等は外れる。vCard 2.1、ENCODING/CHARSET指定、壊れた行は欠落を起こす前に拒否する。1件64 KiBまで。

vCardの内容はDocumentStore snapshot、現在値と所有者・version・検索用projectionはSQLite、履歴はorganizer_contact_revisionsに保存する。DR snapshotのDocument参照抽出にも連絡先の現在・履歴を含める。一般のWiki/アセットURLに公開するための登録はしない。

2026-11-02に organizer.contacts 0.2.0 として、個人CardDAV提供、変更履歴の確認・復元、全アドレス帳exportを追加した。履歴はGET items/UUID/history と items/UUID/history/VERSION、復元はPOST items/UUID/restore にrevision・version・If-Matchを渡し、新しい版を保存する。GET export.vcf は有効な連絡先のみ、最大5,000件・16 MiBを一括出力する。CardDAVのrootは /_/api/v1/carddav/。専用scope contacts を使い、既存CalDAVのallを拡張しない。接続・同期・移行契約を参照。

移行と後続範囲

managed schemaにtask-productivityとcontactsを追加。task-productivityは既存organizer_items作成後に実行し、旧完了タスクを1回だけ集計projectionへ移す。既存スキーマ定義の改変ではない。切戻しでは旧版のschema checkが新コンポーネントを未知とするため、単に旧イメージを起動できるとは扱わない。データを消して戻さない。

  • 連絡先の共有アドレス帳、外部CardDAV connector、重複候補mergeは別段階。個人CardDAV提供面と外部サービスの取り込みは区別する。
  • 失効Domainで取り残された記録の管理用終了手順、取消済み記録の復元、作業監査履歴の保持期間、担当者への共有・通知は後続。
  • 日次メールの保持期間UI、恒久receiptの圧縮・失効、配信結果のInbox連携は後続。現在は詳細90日、重複防止記録は恒久保持とする。
  • vCard legacy変換・version間変換と履歴保持期間は後続。

利用手順は neomuttとタスクCLI を参照。

作業履歴の移行と検証

task-productivityのmanaged migration v3は、作業記録へのcancelled_ms追加、organizer_work_revisionsの作成、本人別の区間検索index追加を行う。既存の作業時刻・versionは保ち、既存記録は未取消とする。新しい監査データの正本はSQLiteで、アプリのDBバックアップに含める。

反映前に整合したDBバックアップを取得する。旧版は取消済み記録を正しく集計できず、schemaのversionも一致しないため、更新DBに旧イメージを向ける切戻しは禁止する。通常はforward-fixを選ぶ。復旧が必要ならアプリを停止し、移行前のDBと対応するイメージへ一緒に戻す。更新後の書き込みは別途保全・照合してから復旧する。本番反映は別工程。

受け入れ試験は、旧スキーマ移行の反復、本人・Domain分離、readonly・失効・無効化、版競合、重複時間、夏時間の欠落・重複、監査失敗時のrollback、並行訂正、取消による集計除外を対象とする。ブラウザはデスクトップと390px幅で訂正・取消・履歴・412時の入力保持を確認する。既存CLIの開始/終了とCalDAVの契約は変更しない。

2026-11-08の検証結果:go test ./...、go vet ./...、追加した競合・監査試験の -race、変更JSの構文検査が成功。Chromiumの1440px・390pxで、ダッシュボードのプロジェクト別表から履歴へ移動し、訂正・取消・監査表示・競合時の入力保持と横幅の収まりを確認した。すべて隔離fixtureによる試験で、本番移行は未実施。