Refactor architecture into eight components and consolidate reliability work
Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
This commit is contained in:
1 parent
9dd425f765
commit
d5d21b7841
302 files changed
+20037
-3492
No files matched your search
@@ -0,0 +1,117 @@
|
||||
# エディタ改善サブプロジェクト
|
||||
|
||||
状態:E1–E5 の初期実装と回帰検証完了。E6 は未実装・後続ゲート。
|
||||
既存 HTML 正本・不変 Revision・Page UUID・言語別 head を維持する。
|
||||
本書は `html-editor.md` の挿入パーツ設計を含むエディタ横断の実行計画。
|
||||
|
||||
2026-11-01:文書変換と情報保全の実装を `internal/grammaratur` へ分離。
|
||||
通常変換・保護変換の契約と既存APIは維持する。
|
||||
[コンポーネント命名と責務](component-names.md) に移行境界を定義する。
|
||||
|
||||
## 優先順位と完了条件
|
||||
|
||||
1. **E1 編集内容の保全**:端末内下書き、認証切れ/通信断/権限失効の区別、
|
||||
再認証後の明示的な保存再開、保存完了を待つ `:wq`、二重保存防止。
|
||||
2. **E2 保存競合**:言語別 head を DB トランザクション内で比較する CAS。
|
||||
同一箇所を変更していないと確定できる範囲だけ自動マージし、その他は
|
||||
基点/自分/最新の内容を表示して手動調整。相手の編集を無条件に上書きしない。
|
||||
3. **E3 操作改善**:モバイルで Vim を使わない、macro 補完時の終端重複を防ぐ、
|
||||
HTML/Markdown の切替で未保存データを捨てない、少数の挿入コンポーネント。
|
||||
4. **E4 履歴・言語**:旧 Revision を作業バッファに読み込み、確認保存で新 Revision。
|
||||
BCP 47 の明示言語は暗黙に `und` へフォールバックして上書きしない。
|
||||
翻訳は同じ Page UUID の別言語として分岐し、URL Path を別 Page にしない。
|
||||
5. **E5 変換保全**:HTML→Markdown→HTML の構造比較。不一致なら HTML を
|
||||
`{=html}` 保護フェンス内に保持する。projection 展開結果を正本や下書きへ保存しない。
|
||||
6. **E6 共同編集(後続)**:サーバーをまたぐ presence、選択範囲、CRDT/OT、
|
||||
編集セッションと永続化境界。単なる同時保存やポーリングを共同編集と呼ばない。
|
||||
|
||||
## 保存と下書きの契約
|
||||
|
||||
- 正本の保存単位は Page UUID × canonical language。開始 head(空も有効)を
|
||||
`base_revision_uuid` で渡す。比較と Revision 追加は同一 write transaction。
|
||||
- 旧クライアントの base 未指定は移行互換として残す。UI は必ず base を指定する。
|
||||
全入口の必須化・hosted editor/CLI 追従は後続ゲート。
|
||||
- 401 は再ログイン、403 は権限の再確認。変換 API の失敗時には Markdown を
|
||||
HTML として保存しない。リダイレクト/非 JSON のログイン応答も成功にしない。
|
||||
- 保存要求中の編集は別の dirty 状態として保持する。保存成功したスナップショット
|
||||
と現在内容が一致するときだけ下書きを削除する。応答喪失時は head 比較で回復する。
|
||||
- 下書きは origin・Domain・Principal・Page・language 単位。別ユーザーの下書きを
|
||||
自動表示しない。サーバー同期はしない。端末を共有する場合の平文保存リスクを明記。
|
||||
- 端末ストレージは容量制限・拒否・プライベートモード・ブラウザー終了で失われ得る。
|
||||
保存失敗を明示し、テキストのダウンロード導線を用意する。下書きには保存時刻、
|
||||
形式、基点 Revision と基点内容を保持し、期限とサイズの上限を設ける。
|
||||
- 復旧候補がある場合は無条件に server autosave しない。復元/破棄をユーザーが選ぶ。
|
||||
再接続だけで公開 Revision を自動更新しない。
|
||||
|
||||
## 初期実装の API・UI と制限
|
||||
|
||||
- `POST /_/api/v1/revisions/save`:任意の `base_revision_uuid` を追加。
|
||||
このエディタは常に指定し、409 を競合として処理する。`editor_principal_uuid` も照合し、
|
||||
編集中に別アカウントへ切り替わった状態で保存しない。旧クライアントの無条件保存は残る。
|
||||
- `GET /_/api/v1/editor/state?uuid=…&lang=…`:対象 Domain・Page の読取権限を検証。
|
||||
`metadata=1` は本文ファイルを読み込まず head を取得。`revision=…` は対象 Page の
|
||||
過去本文を取得する。非表示タブでのポーリングは停止し、表示時は30秒間隔。
|
||||
**これは保存済みの別更新検出であり、未保存の同時編集者 presence ではない。**
|
||||
- `POST /_/api/v1/editor/convert`:作業中 HTML を安全な authoring Markdown に変換。
|
||||
`POST /_/api/v1/render/markdown` の `authoring:true` で保護フェンスを元の HTML に戻す。
|
||||
`projection:true` と併用したプレビューでは従来の sanitizer・macro 展開を適用する。
|
||||
- 変換できない HTML は文書全体を保護する保守的な実装。フェンスは
|
||||
`` ```{=html} `` 形式(本文にバッククォートがある場合はそれより長い区切り)。
|
||||
任意の属性、コメント、未知要素、表の結合、画像キャプション、コード内空白を保持。
|
||||
フェンス内を編集でき、外側に Markdown を追記できる。通常のコードフェンス内にある
|
||||
`{=html}` サンプルは HTML として実行しない。保全は実行許可を与えるものではない。
|
||||
- 自動マージは各版を1つの変更範囲として比較する保守的方式。重複・隣接・同一挿入点は
|
||||
手動確認へ回す。自動再保存は3回まで再照合し、それ以上は確認画面へ移行。
|
||||
ファイル形式が変わった場合は自動マージせず退避と再読込を案内する。
|
||||
- 下書きは `localStorage`。UTF-8 JSON 全体で2 MiBまで、復元対象は7日以内。
|
||||
起動時に期限切れを削除するため、ブラウザーを開かない期間の物理削除は保証しない。
|
||||
Domain/Principal/Page/language/tab ごとに分離し、他タブの下書きを一括削除しない。
|
||||
IndexedDB・サーバー同期・暗号化は未実装。保存失敗時はダウンロードを案内する。
|
||||
- `+` は挿入・下書き、`文` は言語の編集・分岐、`↶` は旧リビジョンを作業バッファへ
|
||||
読み込む。復元は明示保存で新 Revision を追加し、旧 Revision を書き換えない。
|
||||
履歴は50件ずつ追加取得し、現在言語で絞り込む。分岐は翻訳生成ではなく本文のコピー。
|
||||
- 挿入は子ページ・表・画像キャプション・補足・コード・引用の6種の初期パレット。
|
||||
画像 URL 等のプレースホルダーは編集が必要。ファイルピッカー、図形・外部 widget の
|
||||
パラメータ編集、プラグインによる挿入パーツ登録は既存の HTML editor 設計に残る。
|
||||
- touch/coarse pointer + hover 不可の端末ではデスクトップの Vim 設定を上書きせず、
|
||||
当該編集セッションだけ通常入力にする。実機 iOS/Android の IME は別途受入試験。
|
||||
|
||||
## 次段階の実装順序
|
||||
|
||||
1. **E6a presence**:編集中リースの共有ストアと認可付き API、別端末を含む表示。
|
||||
管理者にだけ見える監視ではなく、同じ Page/language を編集できる参加者に限定する。
|
||||
2. **E6b realtime**:下記 CRDT 詳細設計・採用ライブラリ・同時変換ルールを確定した後に
|
||||
feature flag 付きで実装。現時点の CAS を最終コミット時の保護として残す。
|
||||
3. **E5b / E3b**:HTML ブロック単位の保護、hosted editor/CLI への保護フェンス対応、
|
||||
アセットピッカーと拡張挿入パーツ。通常の Markdown だけを扱う外部エディタへ
|
||||
このフェンスを無断で渡さない。既存の外部エディタ変換経路は本変更の対象外。
|
||||
4. 保存 API の旧クライアント移行と base 必須化、下書き大容量化・明示破棄 UX、
|
||||
共有端末ポリシー、モバイル実機テスト。
|
||||
|
||||
## 共同編集の詳細設計 TODO
|
||||
|
||||
- presence キーは Domain × Page UUID × language × Principal × tab session。
|
||||
TTL 付きリース、退出、バックグラウンド抑制、権限失効時の購読停止を定義。
|
||||
- API は `/_/api/v1/editor/` 配下に置く。WebSocket/SSE は origin・認証・対象 Page の
|
||||
read/write を接続時と継続時に検証。本文や利用者名を未認可者へ漏らさない。
|
||||
- 本文 CRDT は authoring source(HTML/Markdown の混在規則と基点を含む)を同期し、
|
||||
projection HTML を同期しない。言語・形式の不一致を同一 room に混在させない。
|
||||
- SQLite に毎キー入力を記録しない。スナップショット間隔・増分上限・圧縮・GC・
|
||||
HA 配信基盤と Revision commit 境界を定義。offline 分岐復帰・undo と IME を検証。
|
||||
- Yjs/Automerge 等は権限、再接続、肥大化、ライセンス、bundle サイズを比較する。
|
||||
この選択とサーバー共有状態を未設計のまま本番へ有効化しない。
|
||||
|
||||
## 検証・展開ゲート
|
||||
|
||||
テスト用 DB と合成文書だけを用いる。実データ・外部カレンダーにはアクセスしない。
|
||||
保存 CAS、空 head、言語分離、旧 Revision 復元、認証失効、別 Principal、通信断、
|
||||
変換失敗、保存中の追記、再試行、複数タブ、モバイル、IME、macro 終端、未知 HTML の
|
||||
round-trip を検証する。CRDT と複数インスタンス presence は別途負荷・安全性試験。
|
||||
本番反映・リリース採番は実装検証の後に行い、既存リリースタグは変更しない。
|
||||
|
||||
初期回帰試験:`TestEditorRevisionCAS`、`TestEditorResilienceAPI`、
|
||||
`TestAuthoringRoundTrip` / `TestAuthoringProtectedHTML`、`assets/editor/editor-core.test.mjs`。
|
||||
実ブラウザーは `PAGESWIKI_BROWSER_TEST=1` で `TestEditorResilienceChromium` と
|
||||
`TestHTMLProjectionChromium`。通信断、401、応答喪失、競合 UI、自動マージ、保存中の追記、
|
||||
変換失敗、下書き復元、旧版復元、言語分岐、マクロ補完、モバイル判定、テーマ、
|
||||
authoring/projection の分離を合成データで検証する。
|
||||
Reference in new issue
Block a user