Files
pages/docs/design/ja/priority-ux-20261031.md
T
Anya Tokugawa d5d21b7841
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s
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.
2026-11-01 15:23:31 +09:00

135 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 最優先:日常操作・ブラウザ・エディタ・CLI(2026-10-31)
ユーザ指定の次期開発最優先。従来の機能追加より先に進める。ただし認可、正本の保全、競合検出を省略しない。本番反映とローカル検証済みは区別する。
## 実装順と受け入れ条件
### 1. ホームとファイルブラウザ
- [x] ホームで他の入力欄にフォーカスしていないとき、文字入力でグローバル検索へ移る。最初の文字を失わず、IME開始・修飾キー・モーダル・選択中テキストを妨げない。中央検索、検索+ブックマーク、従来トップバーを対象とする。実機IMEでの入力確定は下記受け入れ残件。
- [x] ブラウザに `/` 始まりのアドレス欄を設け、絶対/相対Path、`cd`、`vi`、`view` を扱う。URLのquery/hashや外部URLと混同せず、同一Domain内のPathとして解決する。シェル実行はしない。
- [x] ブラウザから名前を指定して新規文書エディタへ進む。既存Pathでは既存文書を編集する。
- [ ] 後続:エディタの新規作成をGET時ではなく明示的な保存時へ遅延する。既存エディタはGET時にPage/Pathを作成するため、今回のナビゲーション追加ではその契約を維持する。UUIDを必要とする下書き/競合/言語/保存APIを合わせて変更する。
- [x] 未作成Pathに仮想フォルダとして潜れる。空フォルダの実体は作らず、そこから作成/アップロードへ進む。現在Pathを貼り付け先など既存操作と共有する。
- [x] キーボード移動、空フォルダ、特殊文字、日本語、ルート境界、読み取り専用アカウントからの作成拒否、既存の複数選択/ドラッグ操作をfixture検証する。
### 2. エディタと表示
- [x] カーソル/選択範囲/現在行をテーマに合わせる。Vimの実際のmode-changeで通常/挿入/置換/選択の状態とカーソル色を更新。`A` 等の移行もfixture確認済み。
- [x] ライトモードで背景・文字・構文色・ガター・補完UIをテーマ化。生成されたLezerクラス名への依存を除去し、意味タグによる構文色へ移行。既存のエディタ復旧試験も通過。
- [x] PlainTextの初期実装:ブラウザの新規文書ダイアログで指定、または `/e/-/{path}?edittype=plain`。既存の `text/plain` は自動選択。保存・プレビューは文字列のまま、HTML/マクロとして実行しない。下書き・競合処理にplainを追加し、異なる形式の下書きを自動復元しない。
- [ ] PlainText後続:既存Wiki HTMLとの形式変換は損失確認・保存MIME・過去版復元の意味を確定してから。現在は409で拒否し、既存HTMLの原本と履歴を変更しない。Domain既定形式と外部アダプタのPlainText設定も後続。
- [x] codeブロックのテーマ対応装飾、ブロック内の横スクロール、インラインcodeの区別、印刷時の折り返しCSS。300px幅での局所overflowをChromium検証。実機モバイルと印刷の目視確認は残件。
### 3. テーマ・アカウント・連絡先
- [x] 共通ナビの◐からプリセットを選択、リロードせず切替。host限定Cookieに保持し、Domain既定に戻せる。登録済みテーマのみ許可。Domain設定/アカウントの全端末設定ではなくブラウザ上書き。失敗時は現在テーマを保持する。
- [x] 絶対セッション期限:設定→セッション、5〜43200分、既定1440分。Domain単位で新規ブラウザ/APIログイン(OIDC/LDAPを含む)に適用。発行時にDBの期限を固定し、Cookie/APIのexpires_inにも反映。既存セッションの期限とCalDAVアプリパスワードは変更しない。管理者認可とサーバ側失効をfixture検証。
- [ ] 無操作タイムアウトとアカウント別の短縮上書き:background pollingを人間の操作とみなさないactivity契約、再認証、既存セッションへの即時適用を別途設計する。
- [x] 電話連絡先の初期実装(2026-11-01ローカル検証済み、本番未反映):本人編集、独立した公開範囲、表示用文字列と正規化した `tel:` リンク。公開は明示確認とプロフィール/ドメイン上限に従う。クリックなしで発信しない。
### 4. Cityの表示名
- [x] 検索結果/ホーム・ビューア検索サジェストのCityリンクは設定詳細ではなく閲覧導線にする(2026-11-01本番反映済み)。対応するPathにPageがあればそのページ、なければそのPathのディレクトリ一覧へ。仮想未整理Spotは実在しない `/_undefined` ではなく親Streetを入口とする。タイトルリンクとPathリンクを統一し、認可、Domain分離、特殊文字のエンコードを維持する。管理詳細への明示的なリンクは残す。
- [x] 初期対応:生成済みSpotの既定プレースホルダー名 `Undefined` を閲覧時の表示から外し、親Streetのタイトル(未設定なら名前)を使用する。独自タイトルは保持し、UUID/識別名/Path境界は書き換えない(2026-11-01本番反映済み)。
- [ ] 「子Spotがあるならカルチエ名」という案の階層対応は別途確定する。現行はQuartier > Street > SpotでSpotを入れ子にできないため、今回の表示変更では昇格/再配置/権限境界の変更をしない。
### 5. セッション付きCLI/TUI
- [x] HTTPクライアント初期版 `pages-cli`/コマンド `pages`(2026-11-01ホストのユーザーPATHへ配置済み。実ユーザログインは未実施):configureによる接続先・既定プロファイル・言語管理、パスワード/TOTP、Bearer保持・失効、ls/cd/cat/view/get、既存Page edit/put、Path補完、メモリ内履歴、検索候補、ブラウザ引き継ぎ。詳細と原設計整合は [遠隔CLI](remote-cli.md)。既存DB直アクセスCLIは変更しない。
- [ ] 既存 `data/pageswiki-cli` を拡張する専用起動コマンドとセッション保持。履歴や資格情報に0600相当の保護と失効/ログアウトを設ける。
- [ ] `Ctrl+P` のfuzzy検索と、ローカル `$EDITOR` 編集。現在版/ETagを保持してアップロード時の競合を検出し、上書き・差分・キャンセルを選べるようにする。
- [ ] パスワード認証に加え、ターミナルにURLを表示するブラウザ認証(OIDC)。既存Web認証と同じ本人性/MFA制約を適用し、短命・単回の認可コード+PKCEやdevice-flow相当の仕様を検討する。URLや履歴に長期トークンを含めない。
- [ ] ターミナル表示が難しい内容はブラウザに引き継ぐ。short linkは認証を迂回しない内部リンクとし、公開share link発行とは分離する。自動公開しない。
## チェックポイントと進捗
### 2026-11-01:コマンドバーと共通シンタックス色(本番反映済み)
- ブラウザのPathアドレス欄をtopbarへ移設。1100px以下では非表示。左下に独立した `cd` / `vi` / `view` バーを常設し、入力欄などにフォーカスがない状態の文字入力を最初の1文字から引き継ぐ。
- 共通ナビのあるホーム以外の画面では `g` でバーを表示、Escで閉じる。ホームのtype-to-searchは維持。フォーム、モーダル、テキスト選択、修飾キー、編集中のCodeMirror/Vimの `g` は奪わない。ブラウザのEscはバーを消さず入力をクリア。
- Tab/Shift+TabでPathを補完・候補巡回。候補が1件のフォルダは再度Tabで配下を補完。相対Path、日本語、空白、`#` / `?` / `%` をそのまま扱い、Enter時にsegment単位でURLエンコード。シェル実行はしない。入力欄末尾以外/コマンド未入力時のTabは通常のフォーカス移動。
- `path-picker?mode=children&path=...&prefix=...` を追加。親Path自身にPageが存在しても親へ戻らず配下を取得。名前専用SQLでRevision本文やプレビューを読み込まない。Domainと既存Path認可を維持。DB処理2秒、候補走査1000件、認可後最大250件、UI最大100件。上限時は絞り込みを促し、入力変更・Esc時はfetchを中止して古い結果を捨てる。prefixはASCII英字を大小区別せず照合し、それ以外はSQLiteの文字比較に従う。
- モバイルのブラウザは中央一覧を優先。サイドバー/プレビューはボタンでオーバーレイ表示し、デスクトップの表示設定は変更しない。
- CodeMirrorエディタ、コードファイルの読み取りビューア、文書中のコードブロックで `pw-syntax-*` とテーマの `--editor-*` 色を共有。Markdown内の対応言語のfenceも構文解析。全プリセットの切替、読み取りビューアとの色一致を確認。
- Wiki本文・編集Preview・ブラウザPreview・公開ページ/公開ブログの言語指定付きコードブロックは、見えてきたものから1ブロックずつ遅延処理。32,768文字超と未対応言語は原文のまま表示し、正本・HTML保存データは変更しない。大きいコードファイルは既存のwindowed viewerを維持。新規CDN・外部ライブラリは追加しない。
- Chromium 1440px/375pxでコマンド入力/補完/キャンセル/ナビゲーション/レスポンシブ/Vim保護/コード原文保持/動的Preview追加を確認。ホーム3種・エディタ復旧の既存回帰も通過。実機IMEの確定とiPhone Safariのソフトウェアキーボードは未確認。
- 開始時ソース:`.deployment-backups/dev-command-20261101/source-before.tar.gz`。2026-11-01 07:14 JST頃、fix2をベースに対象ファイルだけを差し替えた `pageswiki-app:command-20261101` をapp/app2へ反映。電話連絡先/SQLite初期接続の後続変更は含めない。[反映記録](../../operations/deployments/2026-11-01-command-ux.md)を参照。
2026-10-31:上記チェック済み項目はローカル実装・fixture検証済み。本番未反映。新たなDBテーブル/migrationはない。セッション期限は既存Domain configに保存する。
2026-11-01:上記UXを本番app/app2へ反映済み。既存の保存基盤変更も含むため、隔離コピーでmigration/backfillを確認し、旧イベント索引の採用不具合を修正して反映した。Docker実行基盤の版ずれによる一時停止と復旧、切替直前の整合バックアップ、イメージ識別子・検証結果は [本番反映記録](../../operations/deployments/2026-11-01-priority-ux.md) を参照。
- 開始時のHEAD:`9dd425f7658b2eecb1152ec8d457d6224142f9fc`。既存の未コミット変更を含むソースを退避済み。
- バックアップ:`.deployment-backups/dev-priority-20261031/source-before.tar.gz`。
- 検証済みの区切り:同ディレクトリの `source-after-ux.tar.gz`。ハッシュと復元時の注意は同ディレクトリの `README.md` に記録する。
- SHA-256:`8fa6864eeeaa89b3019c06f9c1975a13f380731efa033df810870fb04c4f94e2`。
- 対象はGit管理対象と非ignoredの新規ソース。`.git`、秘密設定、本番DB・Document実体、コンテナイメージは対象外。本番の復元用バックアップではない。
- 復旧時は別ディレクトリに展開して対象ファイルを比較・復元する。新規追加ファイルは個別に退避する。既存のユーザ変更を失う `git reset --hard` は使わない。
- 本番へのデプロイ、DB変更、外部サービスへの接続はこの段階では行わない。
### 検証
- `go test ./...`:通過(opt-in browserを除く全パッケージ)。
- Chromium:ホーム3レイアウトの入力検索、他入力/モーダル/修飾キー、IME開始イベント、仮想Path移動、新規Wiki/PlainText作成、既存ドラッグ選択、テーマ変更、Vimモード、PlainText保存とリテラルプレビュー、既存の下書き復旧・競合処理。
- Node:パス正規化/URLエンコード/外部URL拒否、編集coreのmerge/draft検証。
- 編集bundle再ビルド、`git diff --check`。Index Whiteのエディタをスクリーンショットでも確認。
- 本番・実機Safari/iPhone・日本語IMEの確定動作・印刷・カスタムテーマ全種類は未確認。
## 後続実装の境界と状態
### 連絡先
まず `/u/{username}/_/edit` の本人連絡先を対象とし、オーガナイザーの汎用連絡先帳/CardDAVとは区別する。電話番号はDomain+Principalで保存し、既定private。プロフィール全体をpublicにしただけで電話番号を公開しない。独立した公開確認と上位公開制限を適用する。
表示文字列と正規化済みの電話番号を分離する。`tel:` の値はサーバが組み立て、入力された任意URIをそのまま採用しない。サービスコード/制御文字/改行/スキーム混入は初期版では受理しない。スマホでタップしたときだけOSへ委譲し、自動発信や外部の番号検証サービスへの送信はしない。
保存先はmanaged schema moduleとして追加し、本人更新と状態確認をtransaction内で行う。公開profile投影、API、検索、exportで非公開値を漏らさないfixtureを先に用意する。
2026-11-01実装:`profile-contacts` component v1、Domain+Principalを主キーとする。Principalや認証API/継承データには電話番号を追加しない。プロフィール画面のみ専用の認可済み取得を使い、非公開の番号はdomain_adminにも出さない。管理者の閲覧権限を本人の同意と扱わない。
- `/u/{username}/_/edit#contact` の独立フォームで本人のみ更新。CAS versionで古いフォームは409。activeの本人とactiveのDomain membershipをtransaction内で検査し、readonly/suspended/他Domainからの更新を拒否。
- 既定private、domain/publicはプロフィール公開範囲でさらに制限。publicの新規設定・番号の差し替えは確認チェックが必要。ドメイン公開の撤回/プロフィール非公開への変更を次の読み取りから反映する。
- 電話番号は3〜15桁、先頭の+、表示用の空白・ハイフン・括弧に限定。内線、URIパラメータ、サービスコード、制御文字、任意スキームを拒否。空欄保存は番号を消去してprivateに戻す。
- JA/ENの説明・フォーム・保存後アンカーを追加。デスクトップ1440px/375pxで実ブラウザの入力・保存・telリンク・フォーム幅を検証。iPhoneの電話アプリ起動そのものは未検証。
- store/HTTPで本人・匿名・他メンバー・管理者・越境・公開確認・公開撤回・競合・不正番号を検証。個人情報の本文を監査ログへ追加しない。CardDAV、住所録、複数番号、内線は後続。
- **本番反映済みfix2にはこの機能を含めない。** 次回リリースでは追加componentの適用と、旧版への切り戻し条件を別途検証する。
### 新規DBの初期接続競合(後続修正、本番未反映)
全体回帰で `TestSQLMigrationLedgerConcurrencyAndChecksum` がまれにSQLITE_BUSYとなることを確認。診断メッセージをmigration connection取得/BEGINに分け、2,000回の反復で接続取得段階の失敗を再現した。`sql.Open` がlazyのため、最初の並行接続でWALへの切替が競合していた。
`db.Open` 内で5秒上限のPingを完了してからプールを公開し、初期接続失敗時はCloseして返す。migrationのBEGIN IMMEDIATE/checksum/transaction境界は変更しない。修正後の同テスト2,000回が成功。既にWALで稼働している本番DBのジョブ競合修正とは別件として扱う。
### Cityの名称規則
現行の未整理Spotは `name` の `-undefined` や `/_undefined` によって識別され、Street直下Pageの収容にも使われる。`city-estates.js` のラベルだけを書き換えても、API・パンくず・詳細・検索に別名が残る。
2026-11-01実装・本番反映済み:内部ID/境界と `display_title` を分離。生成Spotで既定名(空、識別名自身、Undefined等)の場合のみ親Street表示名へ射影し、独自タイトルは維持する。生成由来かどうかの永続フラグはないため、既存と同じ識別名suffix/仮想Path規則を使用する。通常Spotに意図的に付けた `Undefined` は変更しない。[反映記録・切り戻し](../../operations/deployments/2026-11-01-city-pages-cli.md)。
- 地図ラベル、パンくず、ディレクトリ、整理モーダル、詳細見出し、検索・サジェスト、ページ上の所属リンク、Cityマクロで同じ規則を使用。管理用識別名/Pathはそのまま残す。
- 匿名地図は公開用に縮退させた名前から再計算し、認証済み投影のカスタムタイトルを再利用しない。所属リンクはSpotに加えて親Street/Quartierの閲覧権限も確認する。共有ナビゲーションキャッシュを表示名処理で変更しない。
- 検索導線は `NavigationPath` と `HasPage` により本文/ブラウザ一覧へ分岐。検索結果のタイトルとPath、サジェストのURLを統一。`/_undefined` は親Streetへ案内し、無関係な先頭Pageをポータルにしない。
- 遷移先の `/v/browser/{path}` はDomain全体のreadではなく対象Pathのreadで認可し、各子要素も個別に検査する。対象Pathを読めない利用者は403。匿名公開の一覧は従来の公開ナビゲーション処理を維持する。検索から本文/一覧を実際に開くHTTP試験を追加。
- Pageの存在判定は既存Path索引のDomain+完全一致で検索SQL内に含める。本文、Revision、City全体の展開、結果ごとの追加HTTP/DB呼び出しは不要。候補上限/タイムアウト/親階層の認可を維持。EXPLAIN QUERY PLANでPath全走査がないことをfixture検査。
- 検索画面は700px以下で検索欄をナビアイコンの下段に置き、プロフィールアイコンによる横はみ出しを解消。390pxと1440pxのブラウザ試験・モバイルスクリーンショットで確認。
- 全Goテスト、Cityラベル(通常/popup)・整理操作・名前付き詳細遷移・検索表示(desktop/mobile)のChromium試験が成功。公開キャッシュ撤回、別Domain、親ACL、特殊文字、生成名と手動タイトル保持を検査。本番データ/外部カレンダーは使わない。
- 復旧点:`.deployment-backups/dev-city-20261101/source-before.tar.gz`(SHA-256 `2675aff20450d24eb0fe1707ea5f3a38ee26c9bdf20dec1a29926d52ef5af4bf`)。DB/設定変更なし。別ディレクトリへ展開して差分復元する。前からある未コミット実装をまとめて取り消さない。
- 検索CSSの変更前は同ディレクトリの `search-css-before.tar.gz` に別途保全(このファイルは着手時にHEADと同一)。変更後は `source-after.tar.gz`。範囲とハッシュは同ディレクトリのREADMEを参照。
ユーザの「子Spotがあるならカルチエ名」という案は、現行のSpotをネストしない制約と区別する必要がある。今回の対応では昇格/再配置はせず、空の仮想要素を生成し直さない。
### リモートCLI
現行 `data/pageswiki-cli` はSQLite/Document Storeへ直接アクセスする運用CLI。shell、補完、履歴、`$PAGER`/`$EDITOR` は既にあるが、Web認証を受けるリモートクライアントではない。Webユーザの認可をSQLite直アクセスへ継ぎ足さず、HTTP transportを持つ別コマンド(仮称 `pageswiki remote`)として段階導入する。
2026-11-01:試作名 `data/pageswiki-remote` から、ユーザ指定によりサブプロジェクト `pages-cli`/実行名 `pages` へ整理。`pages configure` と既定値により通常操作のprofile/lang引数を不要とした。以下は全体計画であり、Ctrl+P、OIDCハンドオフ、新規作成、強制上書きの対話選択、short linkは未実装。[初期版の範囲・制限・検証](remote-cli.md)を参照。
1. パスワード+TOTPの既存JSONログイン、失効/logout、接続先・Principal・Domain別セッション保存。秘密情報はコマンド引数/履歴/ログへ出さず、保存先0700・資格情報0600相当、TLS検証必須。
2. `ls/cd/view/get/edit` と現在Pathの保持。検索は認可付き・件数制限・キャンセル可能なAPIを使用し、`Ctrl+P` のfuzzy選択へ接続。端末の制御シーケンスは本文/タイトルから除去する。
3. `$EDITOR` は引数を分離して起動し、shellへ未検証Pathを連結しない。取得時のRevisionを保存し、CAS書込・409時の差分確認・一時ファイルの保持/削除を実装する。Wiki HTMLと編集Markdownは既存authoring変換APIを使い分ける。
4. OIDCはブラウザ側で既存ログイン/MFAを完了し、短命・単回・認証先/クライアント紐付きのハンドオフでCLIへ交換する。長期BearerをURLへ載せない。確認画面、CSRF/PKCE相当、リプレイ拒否、発行上限、poll backoffを含めてから実装する。
5. 表示できないオブジェクトは認証を維持した短い内部URLでブラウザへ引き継ぐ。公開share linkは自動発行しない。別originへのredirectにBearerを転送しない。
初期の遠隔アクセス試験は偽サーバと一時データのみ。本番資格情報や外部取り込み済みカレンダーの内容をテストに使わない。