Skip to content

📝(docs): Add requirements document for /projects/new page #3726

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

📝(docs): Add requirements document for /projects/new page #3726

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
197 changes: 197 additions & 0 deletions docs/specifications/projects-new-page.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
# プロジェクト作成ページ要件定義書

## 1. 目的

GitHubリポジトリをLiamプロジェクトとしてインポートし、データベーススキーマの可視化・管理を可能にする。

## 2. 対象ユーザー

- Liamに登録済みのユーザー
- GitHub Appをインストール済み、またはこれからインストールするユーザー
- 組織に所属しているユーザー

## 3. 機能要件

### 3.1 認証・アクセス制御

**要件ID**: REQ-001

**説明**: 認証済みユーザーのみがページにアクセスできる

**受け入れ基準**:

- 未認証ユーザーがアクセスした場合、ログインページへリダイレクトされる
- 有効なセッションを持つユーザーのみがページを閲覧できる
- 組織IDが取得できない場合、ログインページへリダイレクトされる

### 3.2 GitHub Appインストール

**要件ID**: REQ-002

**説明**: ユーザーがGitHub Appを自身のアカウントまたは組織にインストールできる

**受け入れ基準**:

- "Install GitHub App"ボタンが表示される
- ボタンクリックでGitHub Appインストールページが新しいタブで開く
- インストール後、ページを再読み込みすると新しいインストールが選択肢に表示される

### 3.3 インストール選択

**要件ID**: REQ-003

**説明**: ユーザーがGitHub Appをインストールしたアカウント・組織を選択できる

**受け入れ基準**:

- インストール済みのアカウント・組織がドロップダウンメニューに一覧表示される
- 各項目にはアカウント名または組織名が表示される
- 初期状態では"Select installation"と表示される
- インストールを選択すると、そのアカウント名が表示される

### 3.4 リポジトリ一覧表示

**要件ID**: REQ-004

**説明**: 選択したインストールに紐づくリポジトリ一覧が表示される

**受け入れ基準**:

- インストール選択後、自動的にリポジトリ一覧が取得される
- ローディング中は"Loading repositories..."と表示される
- リポジトリが存在する場合、リポジトリ名のリストが表示される
- リポジトリが存在しない場合、"No repositories found"と表示される
- エラーが発生した場合、"Error: {エラーメッセージ}"と表示される
- 最大100件のリポジトリが表示される

### 3.5 プロジェクトインポート

**要件ID**: REQ-005

**説明**: ユーザーがリポジトリを選択してプロジェクトを作成できる

**受け入れ基準**:

- 各リポジトリに"Import"ボタンが表示される
- ボタンクリックでプロジェクト作成処理が開始される
- 処理中はボタンが無効化され、"Importing..."と表示される
- 作成成功後、自動的に作成されたプロジェクトページへ遷移する
- 作成失敗時、エラーメッセージがコンソールに出力される

Comment on lines +75 to +80
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Surface project import failures to users.

Acceptance criteria only require console logging on failure, leaving the user without in-product feedback and conflicting with NFR-003’s usability goal. Add a visible error state or toast so users understand the failure and recovery options.

🤖 Prompt for AI Agents 
docs/specifications/projects-new-page.md around lines 75 to 80: Acceptance
currently only logs import failures to the console; change the spec to require
visible in-app error feedback (e.g., toast or inline error state) when project
import fails. Update the flow to (1) show a dismissible error toast or inline
error message with a clear failure reason and a suggested recovery action (retry
or contact support), (2) re-enable the Import button after failure so the user
can retry, and (3) still log the detailed error to console/telemetry for
debugging; adjust acceptance criteria and UI states to reflect these changes.

## 4. 非機能要件

### 4.1 パフォーマンス

**要件ID**: NFR-001

- リポジトリ一覧の取得は5秒以内に完了する
- プロジェクト作成処理は10秒以内に完了する
- ページ初期表示は3秒以内に完了する

### 4.2 セキュリティ

**要件ID**: NFR-002

- プロジェクトは必ず組織に紐付けられる
- ユーザーは自身がアクセス権限を持つリポジトリのみをインポートできる

### 4.3 ユーザビリティ

**要件ID**: NFR-003

- UIは直感的で、追加の説明なしで操作できる
- ローディング状態が明確に表示される
- エラーメッセージはユーザーにとってわかりやすい内容である

## 5. ユーザーフロー

### 5.1 標準フロー（GitHub App既インストール）

1. ユーザーが `/projects/new` にアクセス
2. "Select installation" ドロップダウンをクリック
3. インストール済みのアカウント・組織を選択
4. リポジトリ一覧が自動的に表示される
5. インポートしたいリポジトリの"Import"ボタンをクリック
6. プロジェクトが作成され、プロジェクトページへ自動遷移

### 5.2 代替フロー（GitHub App未インストール）

1. ユーザーが `/projects/new` にアクセス
2. "Install GitHub App"ボタンをクリック
3. GitHub Appインストールページで対象アカウント・組織を選択してインストール
4. `/projects/new` に戻る（手動でページ遷移またはリロード）
5. 標準フローの手順2以降を実行

### 5.3 エラーフロー

**認証エラー**:

- 未認証の場合: ログインページへ自動リダイレクト

**リポジトリ取得エラー**:

- エラーメッセージが画面に表示される
- ユーザーは別のインストールを選択可能

**プロジェクト作成エラー**:

- エラーがコンソールに出力される
- ユーザーは再度"Import"ボタンをクリック可能

## 6. 画面構成

### 6.1 レイアウト

- ページタイトル: "Add a Project"
- GitHub Appインストールボタン
- インストール選択ドロップダウン
- リポジトリ一覧セクション（インストール選択後に表示）

### 6.2 リポジトリアイテム

各リポジトリアイテムには以下が含まれる:

- リポジトリ名
- "Import"ボタン（または"Importing..."）

## 7. データ要件

### 7.1 入力データ

- ユーザーの認証情報（Supabaseセッション）
- GitHubインストール情報
- 選択されたインストールID
- 選択されたリポジトリ情報

### 7.2 出力データ

- 作成されたプロジェクトID
- 作成されたリポジトリレコードID

### 7.3 外部システム連携

- GitHub API: インストール情報・リポジトリ情報の取得
- Supabase: ユーザー認証、プロジェクト・リポジトリデータの永続化

## 8. 制約事項

- リポジトリ一覧は最大100件まで表示
- GitHub APIのレート制限に従う
- インターネット接続が必要
- GitHubへのアクセス権限が必要

## 9. 将来の拡張可能性

- リポジトリ検索機能の追加
- リポジトリのソート・フィルタリング機能
- ページネーション（100件以上のリポジトリ対応）
- リポジトリプレビュー機能（READMEや統計情報の表示）
- 複数リポジトリの一括インポート
- プライベート vs パブリックリポジトリの識別
- リポジトリの最終更新日時の表示

## 10. 成功基準

- ユーザーが5分以内にプロジェクトをインポートできる
- エラー発生率が5%以下
- ユーザーがサポートドキュメントなしで操作を完了できる