コメント: ユーザーと状態モデル

コメントはドキュメントのリビジョンに付随し、削除ではなく非表示をサポートし、コメント投稿者が見えるユーザーのみをメンション可能にし、編集ウィンドウを制限し、モデレーション操作を監査記録に残します。

パッケージの状態: 参照コンテキストは人間によるレビュー準備完了。契約とテストシナリオは完成していますが、採用実装がそれらを通過したという主張はありません。

決定

コメントは特定のドキュメントリビジョンおよび任意のテキストまたはブロック範囲に紐づくスレッド化された会話です。投稿者は制限されたウィンドウ内で編集可能で、それ以降は本文はモデレーションを除き凍結されます。非表示は通常の読者からコメントを隠しつつモデレーターには保持し、削除は別の特権的な経路でありながら監査記録は残ります。メンションはコメント投稿者がそのワークスペースで見えるユーザーにのみ解決されます。モデレーション操作は追記のみです。

範囲

• スレッド作成、返信、編集ウィンドウ、非表示、削除、メンションACL、リビジョンアンカー、モデレーション監査をウェブとバックエンドで。
• すでにメンバーシップと可視性ルールがあるドキュメントコラボレーションの表面。
• 可視ユーザーへのメンション通知トリガー。

このブロックの外

• リアルタイムプレゼンスカーソルとコンフリクトフリーテキスト編集。
• 組織メンバーシップの参加、離脱、移管。ただしメンション可視性のソースとしては含む。

契約

• コメントは document_id、revision_id、任意の anchor、thread_id、返信用の parent_id を保存。
• 編集は投稿者のみが edit_window_minutes 経過前かつモデレーションで非表示でない場合に許可。
• hide はバイトを削除せずに visibility: hidden を設定。通常読者は表示しないが、comments.moderate 権限のモデレーターは読み込む。
• コメント投稿者の可視メンバーシップセット外のユーザーをメンションすると拒否され、通知も発生しない。
• モデレーションイベントは actor、action、reason_code、タイムスタンプを追記し、履歴を書き換えない。
• 返信は親が非表示でもスレッドに残る。親のプレースホルダーは読者に非表示として見え、他ユーザーのプライベートテキストとしては見えない。

実装

• アンカーはリビジョンスナップショットに対して解決。範囲が消失した場合はコメントを削除せずにリビジョン上で孤立フラグを保持。
• メンションACLはディレクトリ検索と同じ可視性グラフで強制し、グローバルユーザーテーブルではない。

障害対応

• リビジョンが消失した場合、新規コメントは revision_not_found で失敗。既存スレッドは履歴として読み取り可能。
• 非表示と編集が競合した場合は非表示が勝ち、編集は拒否。

検証

• 別のプライベートワークスペースのユーザーをメンションし拒否されることを確認。
• 親を非表示にして返信が通常読者に非表示本文を漏らさないことを確認。

このパッケージの実行可能に見える例はフィクスチャと受け入れ契約です。コレクションのルートから python tools/validate.py を実行してパッケージ構造とメタデータを検証し、その後ターゲットリポジトリでシナリオを実装・実行してください。

採用の前提

• example.yaml の名前や数値は採用プロファイルであり普遍的なデフォルトではありません。
• 採用チームはアクター、データクラス、エラー語彙、所有権を自システムにマッピングする必要があります。

参考文献

• 外部の規範的なソースは不要。このパッケージは共同コメントのプロジェクト決定を定義します。