Phase 8
States, Permissions & Failure Guidelines

Introduction

状態を、色だけで伝えない

Knowledge OSでは、資料の追加、文字の読み取り、検索準備、AI接続、外部送信、権限確認など、複数の処理が並行して動きます。

同じ「処理中」でも、資料登録中なのか、Local AIの起動中なのか、検索準備中なのかによって、利用者が待つべきか、別の操作ができるかが異なります。

この章で定義するもの

01 — State Principles

1状態設計の原則

状態表示に必要な6要素

02 — Processing States

2処理状態

処理状態カードの例

処理中の操作ルール

• 処理対象だけを操作不可にする。
• 他の資料閲覧や検索は可能な限り維持する。
• 中止できる場合のみ「中止」を表示する。
• 中止した場合に残るデータを説明する。

03 — Connection States

3接続状態

接続状態の表示場所

• 常時表示は、現在利用中のAI処理方式だけにする。
• 問題がある場合は、関連画面内と設定画面に表示する。
• ホーム全体を接続エラー画面へ置き換えない。
• 利用可能な代替機能を案内する。

04 — Document States

4資料状態

資料一覧での表示

• 通常状態ではステータスを過度に表示しない。
• 要確認・失敗・重複候補のみ目立たせる。
• 状態は資料名より強くしない。
• 状態ラベルは1件につき原則1つを主表示する。

状態が複数ある場合

「登録済み」「読み取り要確認」「検索準備中」など複数状態を持つ場合は、最も対応が必要な状態を主状態として表示します。

05 — Permission States

5権限状態

権限UIのルール

• 権限のない操作をPrimaryボタンで表示しない。
• 完全に隠すか、理由付きで無効表示するかを画面目的に応じて決める。
• 無効ボタンだけを表示して理由を隠さない。
• 管理者権限が必要な場合は、誰に確認すべきか案内する。
• APIから返る権限エラーを、そのまま技術文で表示しない。

06 — Failure & Recovery

6失敗・復旧状態

失敗の分類

エラー文の構造

1. 何を完了できなかったか
2. 何が残っているか・失われていないか
3. 利用者が次にできること

再試行ルール

• 再試行によって重複登録されないようにする。
• 成功済みの処理を再実行しない。
• 同じ失敗が続く場合は別の対応を案内する。
• 再試行回数を無制限に自動実行しない。

復旧操作

07 — State Priority

7状態の優先順位

1つの対象が複数状態を持つ場合、利用者の対応が必要な状態を優先して表示します。

優先順位

1. 権限なし・安全上の停止
2. 失敗・元ファイルなし
3. 要確認・重複候補
4. 処理中・起動中
5. 処理待ち・更新待ち
6. 一部完了
7. 完了・登録済み
8. 未処理・未設定

複数状態の表示方法

• 主状態は1つだけ大きく表示する。
• 補助状態は小さなラベルまたは詳細欄に表示する。
• 状態ラベルを横に大量に並べない。
• 利用者の対応が必要な状態を優先する。

画面全体の状態

画面全体をエラーやLoadingに置き換えるのは、主要コンテンツを一切表示できない場合に限ります。

• 関連資料取得失敗でも、資料本文は表示する。
• AI接続失敗でも、通常検索と資料閲覧は残す。
• OCR利用不可でも、元資料の閲覧は残す。

08 — State Transitions

8状態遷移

標準的な処理遷移

再処理遷移

失敗または要確認の状態から再処理する場合は、前回結果を保持したまま再処理を開始します。

• 失敗 → 再処理可能 → 処理待ち
• 要確認 → 修正 → 再処理可能
• 中止 → 再処理可能
• 完了 → 再処理は通常表示しない

禁止する遷移

• 処理中から説明なしに未処理へ戻る
• 失敗状態を自動で完了へ変更する
• 要確認を利用者確認なしに完了へ変更する
• Local AI失敗時に自動でクラウドAIへ切り替える
• 中止後に処理が裏で継続する

09 — Visual Language

9色・アイコン・文言

色の標準

Lucide Iconsの標準

文言の標準構造

状態見出し：
資料の内容を確認しています

説明：
この処理には数分かかる場合があります。

操作：
［処理を中止］

次の操作：
完了すると、検索とAIへの質問を利用できます。

10 — Cursor Rules

10Cursor向け実装ルール

共通指示

Knowledge OS Design Principles v1.0.0
Phase 8「States, Permissions & Failure Guidelines」に従って実装してください。

必須条件：
- 状態は文字・色・Lucide Iconを組み合わせて表示する
- 色だけで状態を表現しない
- 状態名だけでなく、説明と次の操作を表示する
- 通常、Loading、Empty、Success、Partial Success、Warning、Errorを実装する
- 一部失敗を全失敗として扱わない
- 画面全体を不要に操作不能にしない
- 利用可能な代替機能を残す
- 権限エラーを技術コードのまま表示しない
- 再試行時に重複処理が起きないようにする
- 主状態は1つに絞り、補助状態は詳細表示にする
- 状態遷移を型として定義する
- 未定義状態へ到達した場合の安全なフォールバックを用意する

実装前に整理すること

• 対象機能が持つ状態一覧
• 各状態から実行可能な操作
• 状態遷移図
• 失敗時の復旧方法
• 画面全体を止める条件
• 操作履歴へ記録する状態変化

完了報告に含めること

• 追加・変更した状態
• 状態型の定義場所
• 状態ごとの表示
• 状態遷移
• 再試行・中止の動作
• 未定義状態の扱い
• テスト結果

11 — Types & Components

11状態型と共通コンポーネント

推奨型定義

export type ProcessingStatus =
  | "not_started"
  | "queued"
  | "processing"
  | "completed"
  | "partially_completed"
  | "needs_review"
  | "failed"
  | "cancelled"
  | "retry_available";

export type ConnectionStatus =
  | "local_ai_connected"
  | "local_ai_stopped"
  | "cloud_ai_not_configured"
  | "api_key_invalid"
  | "offline"
  | "runtime_starting"
  | "model_missing"
  | "ocr_unavailable";

export type DocumentStatus =
  | "registered"
  | "text_extracted"
  | "needs_text_review"
  | "search_preparing"
  | "duplicate_candidate"
  | "source_file_missing"
  | "index_update_pending";

export type PermissionStatus =
  | "view"
  | "edit"
  | "delete"
  | "admin_only"
  | "denied"
  | "read_only";

共通コンポーネント

components/
└── states/
    ├── AppStatusBadge.vue
    ├── AppStatusMessage.vue
    ├── AppLoadingState.vue
    ├── AppErrorState.vue
    ├── AppPartialSuccessState.vue
    ├── AppPermissionNotice.vue
    ├── AppConnectionStatus.vue
    └── AppRecoveryActions.vue

共通状態定義

状態ごとの色、アイコン、標準文言、操作は、画面コンポーネント内へ直接記述せず、共通定義へまとめます。

export const processingStatusDefinition = {
  processing: {
    label: "処理中",
    icon: "LoaderCircle",
    tone: "primary",
    defaultMessage: "処理しています…",
  },
  needs_review: {
    label: "要確認",
    icon: "TriangleAlert",
    tone: "warning",
    defaultMessage: "内容の確認が必要です",
  },
};

禁止する実装

• 各画面で状態ラベルを個別定義する
• 文字列比較だけで複雑な状態遷移を管理する
• 状態型にない値をanyで通す
• 未定義状態を何も表示せず無視する
• UIコンポーネント内で状態遷移を直接実装する

12 — Review Checklist

状態・権限・失敗レビュー

状態表示

• 状態名が具体的である。
• 説明文がある。
• Lucide Iconがある。
• 色だけに依存していない。
• 次の操作が分かる。

操作可能範囲

• 処理中でも利用可能な機能が残っている。
• 利用不可の理由が表示される。
• 権限のない操作が誤って実行されない。
• 中止後の状態が明確である。

失敗・復旧

• 失敗の原因が利用者向けに説明されている。
• 元データへの影響が表示される。
• 再試行が重複処理を起こさない。
• 一部成功と全失敗が区別されている。
• 復旧不能時の代替手段がある。

状態遷移

• 状態型が定義されている。
• 許可される遷移が明確である。
• 利用者確認が必要な遷移を自動化していない。
• 未定義状態のフォールバックがある。

権限

• 閲覧・編集・削除権限が分離されている。
• 管理者のみの操作が明確である。
• 権限エラーを技術用語で表示していない。
• 読み取り専用で可能な操作が分かる。

Definition of Done

Phase 8の完成条件

• 処理状態が共通型として定義されている。
• 接続状態が共通型として定義されている。
• 資料状態が共通型として定義されている。
• 権限状態が共通型として定義されている。
• 各状態に色・アイコン・文言・操作が定義されている。
• 状態表示が共通コンポーネント化されている。
• 一部完了・要確認・中止・再処理可能が実装されている。
• 再試行時の重複防止がある。
• 権限エラーの利用者向け表示がある。
• 未定義状態の安全な表示がある。
• 主要な状態遷移テストがある。

Closing

状態は、システムから利用者への説明です

システム内部では、待機、接続、解析、保存、権限確認など、多くの処理が行われています。

利用者が知りたいのは技術的な内部状態ではなく、「今どうなっているか」「何ができるか」「次に何をすればよいか」です。

最終原則

1. 状態を具体的な日本語で示す。
2. 色だけで状態を伝えない。
3. Lucide Iconsに統一する。
4. 次の操作を必ず示す。
5. 一部失敗を全失敗にしない。
6. 利用可能な機能を不必要に止めない。
7. 権限エラーを技術用語で表示しない。
8. 状態遷移を型として管理する。
9. 再試行で重複処理を起こさない。
10. 未定義状態を無視しない。

Knowledge OS Design Principles v1.0.0
Phase 8 — States, Permissions & Failure Guidelines
System-wide State and Recovery Design Rules