opengroupware/docs/product-requirements.md

# Product Requirements Document

## プロダクト概要

### 名前
**シンプルグループウェア** - プロジェクト単位で情報共有・タスク管理を行えるチームコラボレーションツール

### プロダクトコンセプト
- **プロジェクト中心の情報管理**: すべての主要機能（掲示板・チャット・ToDo・ファイル・メモ・カレンダー・ミーティング）がプロジェクトに紐づき、プロジェクトごとに独立して利用できる
- **軽量で扱いやすい技術構成**: Next.js 15 + TypeScript + SQLite(better-sqlite3) で構築し、Prisma を使わず独自SQLラッパーとRepositoryクラスでDBアクセスを実装する。小規模チーム（プロジェクトあたり数十人）で運用できるシンプルさを追求する
- **リアルタイム性と一元管理の両立**: SSEによるリアルタイムチャットを備えつつ、カレンダーでマイルストーン・デッドライン・ToDo・ミーティングを一画面に集約し、チームの進捗を可視化する

### プロダクトビジョン
プロジェクトごとに独立した情報共有空間を提供し、チームが掲示板・チャット・タスク・ファイル・メモ・カレンダー・ミーティングを一つのアプリで完結できるグループウェアを実現する。
軽量なSQLiteベースの構成により、小規模チームでも簡単に導入・運用できる。
リアルタイムチャットとカレンダーによる一元管理で、情報散逸を防ぎ、チームの生産性を高める。

### 目的
- ユーザーを管理できる
- プロジェクトを作成・管理できる
- プロジェクトごとにメンバーを管理できる
- プロジェクトごとに掲示板を使える
- プロジェクトごとにSSEチャットを使える
- プロジェクトごとにKanban形式のToDoを使える
- プロジェクトごとにファイル共有を使える
- ファイルをLightboxで閲覧できる
- プロジェクトごとにMarkdownメモを作成・編集・閲覧できる
- プロジェクトごとにカレンダーを使える
- カレンダーでマイルストーン、デッドライン、ToDo、ミーティングを表示できる
- プロジェクトごとにミーティングを管理できる
- ミーティング作成時に参加メンバーの予定重複を確認できる
- アプリ内通知を使える
- アクティビティログを記録できる
- SQLiteのDBスキーマをSQL Migrationで更新できる
- 管理者がバックアップを作成できる

## ターゲットユーザー

### 主要ペルソナ: 佐藤 健太（32歳、プロジェクトマネージャー）
- 中小規模の開発チーム（5〜30名）で複数プロジェクトを並行管理している
- プロジェクトごとにメンバー構成が変わり、情報共有手段を都度切り替えるのに負担を感じている
- チャット・タスク管理・ファイル共有・ミーティング調整が別々のツールに分散しており、情報を行き来させるのに時間がかかっている
- 各メンバーの予定やタスク期限を一画面で把握し、ミーティングの重複を自動検知したい
- 軽量なツールを自社サーバー（またはローカル）で手軽に運用したい

### サブペルソナ: 山田 花子（27歳、フロントエンドエンジニア / プロジェクトメンバー）
- 複数プロジェクトに所属し、それぞれのToDo期限やミーティング予定を見逃さずに把握したい
- Markdownでメモや議事録を書くことに慣れており、プレビュー付きの編集環境を求めている
- チャットでリアルタイムに相談しつつ、掲示板で非同期的に仕様や決定事項を残したい

## 成功指標（KPI）

### 主要KPI
- **主要ユーザーフローの動作確認**: 認証・プロジェクト作成・掲示板・SSEチャット・Kanban ToDo・ファイル共有・Markdownメモ・カレンダー・ミーティング・通知・アクティビティログ・バックアップのすべてが正常に動作する（リリース時）
- **Unit Test カバレッジ**: SQLラッパー・Migration・全Repository・全ServiceクラスのUnit Testが実装され、`npm test` で全件成功する（リリース時）
- **E2E Test 合格率**: Playwrightによる主要ユーザーフローのE2E Testが実装され、`npm run test:e2e` で全件成功する（リリース時）

### 副次KPI
- **リアルタイム性**: チャットメッセージ送信から他クライアントのSSE受信まで1秒以内（小規模同時接続前提）
- **一覧表示の応答性**: チャット履歴・掲示板・ファイル一覧・Markdownメモ一覧はページネーションされ、1ページあたりの取得が1秒以内
- **バックアップの可用性**: 管理者が1操作でSQLite DBファイルとuploadsディレクトリをZIP化したバックアップを作成・ダウンロードできる

## 機能要件

### コア機能（MVP）

#### 1. ユーザー管理

**ユーザーストーリー**:
システム管理者として、ユーザーの登録・ロール割り当て・有効/無効管理を行いたい。それはシステムへのアクセスを適切に制御するためである。
またユーザーとして、パスワードでログインし、自分のプロフィール・アイコン・表示名を編集したい。それは自分のアイデンティティをチーム内で正しく表現するためである。

**受け入れ基準**:
- [ ] ユーザー登録ができる（名前・メールアドレス・パスワード）
- [ ] パスワードログインができる
- [ ] ログアウトができる
- [ ] プロフィール編集（表示名・メールアドレス）ができる
- [ ] アイコン画像を設定できる
- [ ] アカウントを有効/無効にできる（無効アカウントはログイン不可）
- [ ] ロール（System Admin / Project Admin / Member / Guest）を管理できる
- [ ] 認証必須の画面で未ログイン時はログイン画面へリダイレクトされる
- [ ] ログインしていないユーザーは保護された画面にアクセスできない

**優先度**: P0（必須）

---

#### 2. プロジェクト管理

**ユーザーストーリー**:
プロジェクト管理者として、プロジェクトを作成し、メンバーを追加・削除し、プロジェクト内ロールを設定したい。それはプロジェクトごとに適切な権限でチームを運用するためである。
またプロジェクト管理者として、プロジェクトのステータス（Active/On Hold/Completed/Archived）を管理し、不要になったプロジェクトをアーカイブ・削除したい。それはプロジェクトのライフサイクルを整理するためである。

**受け入れ基準**:
- [ ] プロジェクトを作成できる（名前・説明文）
- [ ] プロジェクト名・説明文を編集できる
- [ ] プロジェクトのステータス（Active/On Hold/Completed/Archived）を変更できる
- [ ] プロジェクトにメンバーを追加できる
- [ ] プロジェクトからメンバーを削除できる
- [ ] プロジェクト内ロールを設定できる
- [ ] プロジェクトをアーカイブできる
- [ ] プロジェクトを削除できる
- [ ] プロジェクト参加者以外はプロジェクト情報にアクセスできない
- [ ] プロジェクトダッシュボードに以下が表示される:
  - 最新チャット
  - 最新掲示板投稿
  - 最新Markdownメモ
  - 未完了ToDo
  - 期限が近いToDo
  - 次回ミーティング
  - 直近のマイルストーン
  - 最近アップロードされたファイル
  - 最近のアクティビティ

**優先度**: P0（必須）

---

#### 3. 掲示板

**ユーザーストーリー**:
プロジェクトメンバーとして、プロジェクト単位で非リアルタイムの情報共有（お知らせ・仕様・議事録・質問・決定事項・トラブル・メモ）をスレッド形式で行いたい。それは重要な情報を後から振り返れる形で残すためである。

**受け入れ基準**:
- [ ] スレッドを作成・編集・削除できる（Markdown本文）
- [ ] スレッドにコメントを作成・編集・削除できる
- [ ] スレッドに添付ファイルを付けられる
- [ ] スレッドをピン留めできる
- [ ] スレッドに重要マークを付けられる
- [ ] カテゴリ（お知らせ/仕様/議事録/質問/決定事項/トラブル/メモ）で分類できる
- [ ] 既読管理ができる
- [ ] スレッドを検索できる
- [ ] 論理削除されたスレッド・コメントは通常取得に含まれない

**優先度**: P0（必須）

---

#### 4. チャット（SSE）

**ユーザーストーリー**:
プロジェクトメンバーとして、プロジェクト内でリアルタイムに短い会話をしたい。それは素早い相談ややり取りを円滑に行うためである。

**受け入れ基準**:
- [ ] プロジェクト別のチャットが使える
- [ ] メッセージを送信できる
- [ ] SSEにより新規メッセージがリアルタイムに他クライアントへ配信される（別ブラウザ/別コンテキストで確認）
- [ ] 接続切断時に自動再接続される
- [ ] SSEイベントはプロジェクト単位で配信される
- [ ] メッセージを編集・削除できる
- [ ] メッセージに添付ファイルを付けられる
- [ ] メンションができる
- [ ] リアクションができる
- [ ] 既読/未読が管理できる
- [ ] チャット履歴を検索できる（ページネーション付き）
- [ ] SSEイベント種別: `chat.message.created` / `chat.message.updated` / `chat.message.deleted` / `todo.updated` / `file.uploaded` / `meeting.created` / `note.updated` / `notification.created` が配信される

**優先度**: P0（必須）

---

#### 5. ToDo / Kanban

**ユーザーストーリー**:
プロジェクトメンバーとして、プロジェクトごとのタスクをKanbanボード形式で管理したい。それはタスクの状態と担当を視覚的に把握するためである。

**受け入れ基準**:
- [ ] Kanbanボードが表示される（標準カラム: Backlog/To Do/In Progress/Review/Done）
- [ ] カラムを作成・編集・削除・並び替えできる
- [ ] タスクを作成・編集・削除できる
- [ ] タスクをドラッグ&ドロップで別カラムへ移動できる
- [ ] タスクに担当者・期限・優先度・ラベルを設定できる
- [ ] タスクにチェックリスト・コメント・添付ファイルを付けられる
- [ ] タスクの完了状態を管理できる
- [ ] 完了したToDoがDoneカラムに表示される
- [ ] タスクをカレンダーに表示できる
- [ ] タスクをマイルストーンと紐づけられる

**優先度**: P0（必須）

---

#### 6. ファイル共有

**ユーザーストーリー**:
プロジェクトメンバーとして、プロジェクト内でファイルをアップロード・閲覧・共有したい。それは資料や画像をチーム内で簡単に扱うためである。

**受け入れ基準**:
- [ ] ファイルをアップロードできる（ローカルファイルシステムに保存）
- [ ] ファイル一覧が表示される（ページネーション付き）
- [ ] フォルダ管理ができる
- [ ] ファイル名変更・削除・ダウンロードができる
- [ ] 画像ファイルをLightboxで閲覧できる
- [ ] PDFファイルをプレビューできる
- [ ] ファイルにコメントを付けられる
- [ ] ファイルをToDo・掲示板投稿・ミーティング・Markdownメモと紐づけられる
- [ ] ファイルアクセスにも権限チェックが行われる
- [ ] アップロードファイルのMIMEチェックが行われる

**優先度**: P0（必須）

---

#### 7. Markdownメモ

**ユーザーストーリー**:
プロジェクトメンバーとして、プロジェクトごとにMarkdown形式のメモを作成・編集・閲覧したい。それは仕様メモやノウハウを構造化して蓄積するためである。

**受け入れ基準**:
- [ ] Markdownメモを作成・編集・削除できる
- [ ] Markdownプレビューが表示される
- [ ] タイトル・タグを設定できる
- [ ] メモをピン留めできる
- [ ] メモを検索できる
- [ ] 作成者・最終更新者・更新日時が表示される
- [ ] ファイル添付ができる
- [ ] 関連ToDo・関連ミーティングを設定できる
- [ ] 対応記法: 見出し・箇条書き・番号リスト・チェックリスト・コードブロック・テーブル・リンク・画像・引用
- [ ] HTML直接入力は無効化され、表示時にサニタイズされる
- [ ] 危険なURLスキームは除外される

**優先度**: P0（必須）

---

#### 8. カレンダー

**ユーザーストーリー**:
プロジェクトメンバーとして、プロジェクト内の予定・マイルストーン・ToDo期限・ミーティングをカレンダー上で確認したい。それはチームのスケジュールを一画面で把握するためである。

**受け入れ基準**:
- [ ] 月表示・週表示・日表示・リスト表示ができる
- [ ] マイルストーン・デッドライン・ToDo開始日・ToDo期限・ミーティング・任意イベントが表示される
- [ ] カレンダーイベントを作成・編集・削除できる
- [ ] イベント種別（Meeting/Deadline/Milestone/Todo/Reminder/Custom）を設定できる
- [ ] メンバー別フィルターができる
- [ ] 種別フィルターができる

**優先度**: P0（必須）

---

#### 9. マイルストーン管理

**ユーザーストーリー**:
プロジェクト管理者として、プロジェクトの重要な節目（マイルストーン）を管理したい。それは進捗の目標を明確にし、完了率を可視化するためである。

**受け入れ基準**:
- [ ] マイルストーンを作成・編集・削除できる
- [ ] 期限・説明文を設定できる
- [ ] 関連ToDoを紐づけられる
- [ ] 関連ToDoの完了率から進捗率が自動計算される
- [ ] 完了状態を管理できる
- [ ] カレンダーに表示される

**優先度**: P1（重要）

---

#### 10. ミーティング管理

**ユーザーストーリー**:
プロジェクト管理者として、プロジェクトメンバーとのミーティングを設定し、参加者の予定重複を確認したい。それはスケジュールの競合を事前に防ぐためである。

**受け入れ基準**:
- [ ] ミーティングを作成・編集・削除できる
- [ ] タイトル・説明・開始日時・終了日時・参加メンバー・場所・ミーティングURLを設定できる
- [ ] アジェンダ・議事録をMarkdownで作成できる
- [ ] 関連ToDo・関連ファイル・関連掲示板投稿・関連Markdownメモを設定できる
- [ ] カレンダーに表示される
- [ ] ミーティング作成時に参加メンバーの予定重複をチェックし、同じ時間帯に他のミーティング・カレンダーイベント・期限の近い重要タスクがある場合は警告する
- [ ] 参加メンバーの予定重複が画面上で警告される

**優先度**: P0（必須）

---

#### 11. 通知

**ユーザーストーリー**:
ユーザーとして、自分に関係する重要な更新（メンション・ToDo割り当て・期限前・ミーティング招待・コメント・プロジェクト追加・ファイル共有・メモ更新）を見逃さないようにしたい。それは必要な対応を迅速に行うためである。

**受け入れ基準**:
- [ ] アプリ内通知が表示される
- [ ] 未読通知一覧が表示される
- [ ] 通知を既読化できる
- [ ] 以下のイベントで通知が作成される:
  - 自分がメンションされた
  - 自分にToDoが割り当てられた
  - ToDoの期限が近い
  - ミーティングに招待された
  - 掲示板にコメントが付いた
  - プロジェクトに追加された
  - ファイルが共有された
  - Markdownメモが更新された
- [ ] 通知が正しいユーザーに作成される

**優先度**: P0（必須）

---

#### 12. アクティビティログ

**ユーザーストーリー**:
プロジェクトメンバーとして、プロジェクト内の変更履歴を時系列で確認したい。それは誰がいつ何を変更したかを追跡するためである。

**受け入れ基準**:
- [ ] 以下の操作がアクティビティログに記録される:
  - ToDo作成・更新・完了
  - ファイルアップロード
  - 掲示板投稿
  - コメント追加
  - Markdownメモ作成・更新
  - ミーティング作成
  - メンバー追加
  - マイルストーン更新
- [ ] アクティビティログがプロジェクト単位で時系列表示される
- [ ] 管理者操作もアクティビティログに記録される

**優先度**: P1（重要）

---

#### 13. 検索

**ユーザーストーリー**:
プロジェクトメンバーとして、プロジェクト内の情報（掲示板・チャット・ToDo・ファイル・カレンダーイベント・ミーティング・議事録・マイルストーン・Markdownメモ）を横断検索したい。それは目的の情報にすばやくたどり着くためである。

**受け入れ基準**:
- [ ] 掲示板・チャット・ToDo・ファイル名・カレンダーイベント・ミーティング・議事録・マイルストーン・Markdownメモを検索できる
- [ ] 検索条件（キーワード・投稿者・担当者・日付・種別・プロジェクト・タグ）で絞り込みできる

**優先度**: P1（重要）

---

#### 14. ダッシュボード

**ユーザーストーリー**:
ユーザーとして、ログイン後に自分に関係する情報を一画面で確認したい。それは今日やるべきことと近日の予定を把握するためである。

**受け入れ基準**:
- [ ] 個人ダッシュボードに以下が表示される:
  - 自分の参加プロジェクト
  - 自分の未完了ToDo
  - 今日の予定
  - 近日中のミーティング
  - 未読通知
  - 期限切れタスク
  - 最近のアクティビティ
- [ ] プロジェクトダッシュボードに以下が表示される:
  - プロジェクト概要
  - 進行中ToDo
  - 期限が近いToDo
  - 最新チャット
  - 最新掲示板
  - 最新Markdownメモ
  - 最近のファイル
  - 次回ミーティング
  - マイルストーン進捗

**優先度**: P0（必須）

---

#### 15. バックアップ

**ユーザーストーリー**:
システム管理者として、SQLite DBファイルとアップロードファイルをバックアップしたい。それはデータ喪失に備えるためである。

**受け入れ基準**:
- [ ] 管理者用バックアップ画面が使える
- [ ] SQLite DBファイルのバックアップを作成できる
- [ ] uploadsディレクトリのバックアップを作成できる
- [ ] DBとuploadsをZIP化できる
- [ ] バックアップファイル一覧が表示される
- [ ] バックアップファイルをダウンロードできる

**優先度**: P1（重要）

---

#### 16. DB基盤（SQLラッパー・Migration・Repository）

**ユーザーストーリー**:
開発者として、SQLiteへのアクセスを共通SQLラッパーで行い、SQLファイルベースのMigrationでスキーマを管理したい。それはDBアクセスを一貫させ、スキーマ変更を追跡可能にするためである。

**受け入れ基準**:
- [ ] 共通SQLラッパー（SELECT複数行/SELECT単一行/INSERT・UPDATE・DELETE/トランザクション/初期設定/接続管理/エラー処理）が実装される
- [ ] 各Repositoryは直接SQLiteライブラリを触らず、共通SQLラッパーを通してSQLを実行する
- [ ] Migrationファイルがファイル名順に実行される
- [ ] 実行済みMigrationは再実行されない
- [ ] 実行済み履歴は `schema_migrations` テーブルに保存される
- [ ] 1ファイルごとにトランザクションが張られ、失敗時はロールバックされる
- [ ] 管理者がMigration状態を確認できる
- [ ] SQLはパラメータバインドで実行される（SQLインジェクション対策）

**優先度**: P0（必須）

---

### 画面構成

#### 共通画面
- ログイン画面
- ダッシュボード
- 通知一覧
- ユーザープロフィール
- 管理者設定
- バックアップ管理

#### プロジェクト内画面
- プロジェクト概要
- 掲示板
- チャット
- ToDo / Kanban
- ファイル
- Markdownメモ
- カレンダー
- マイルストーン
- ミーティング
- メンバー
- アクティビティログ
- 設定

### 今後の機能（Post-MVP）

#### 外部連携・拡張
- 外部カレンダー（Google Calendar等）との同期
- メール通知・Webhook通知
- モバイル専用UIの最適化

**優先度**: P2（今後検討）

## 非機能要件

### パフォーマンス
- 1プロジェクトあたり数十人規模を想定する
- チャットSSEは小規模同時接続を前提とする
- ファイル一覧・チャット履歴・掲示板・Markdownメモはページネーションを行う
- 一覧取得では必要な件数だけ取得する

### ユーザビリティ
- ログイン後、ユーザーはダッシュボードで自分に関係する情報を一画面で確認できる
- プロジェクト内の主要機能はサイドメニューから1クリックで遷移できる
- Kanbanタスクはドラッグ&ドロップで直感的に操作できる

### 信頼性
- DB更新は1ファイルごとにトランザクションを張り、失敗時はロールバックする
- 管理者がSQLite DBファイルとuploadsディレクトリのバックアップを作成できる
- SQLite DBファイル・uploadsディレクトリは永続化される

### セキュリティ
- 認証必須（未ログインは保護された画面にアクセス不可）
- プロジェクト参加者以外はプロジェクト情報にアクセス不可
- ファイルアクセスにも権限チェックを行う
- SQLはパラメータバインドで実行する
- Markdown表示時はHTMLを無効化しサニタイズする
- 危険なURLスキームを除外する
- アップロードファイルのMIMEチェックを行う
- 管理者操作をアクティビティログに記録する

### スケーラビリティ
- Next.jsのEdge Runtimeは使用せず、API Route・Server Actions・DBアクセスはすべてNode.js Runtimeで実行する（SQLite直接扱いのため）
- SQLiteはWALモード・外部キー制約ONで運用する

### 運用・保守
- `.env` で設定管理できる
- SQLite DBファイルを永続化する
- uploadsディレクトリを永続化する
- 管理者がDB Migration状態を確認できる
- 管理者がバックアップを作成できる

## テスト要件

### Unit Test（Vitest）
以下を対象とする:
- SQLラッパー
- Migration実行
- 全Repository（User/Project/ProjectMember/Board/Chat/Todo/File/Calendar/Meeting/ProjectNote/Notification/ActivityLog）
- 全Service（Auth/Project/Chat/Meeting/Schedule/FileStorage/Backup）
- 権限チェック・バリデーション・スケジュール重複判定・通知作成ロジック・アクティビティログ作成ロジック

確認内容:
- 正常にデータを作成・取得・更新・削除できる
- 論理削除されたデータが通常取得に含まれない
- プロジェクト単位でデータが分離される
- 権限がないユーザーは操作できない
- 必須項目不足時にエラーになる
- Migrationがファイル名順に実行され、実行済みは再実行されない
- 予定重複を検出できる
- 通知が正しいユーザーに作成される
- アクティビティログが正しく記録される

`npm test` でUnit Testが実行できること。

### E2E Test（Playwright）
主要ユーザーフローを実際のブラウザ操作で検証する:
- 認証（ログイン・ログアウト・未ログインの保護）
- プロジェクト管理（作成・編集・メンバー追加/削除・アーカイブ）
- 掲示板（スレッド作成・編集・コメント・検索）
- チャット（送信・SSEリアルタイム受信・編集・削除）
- ToDo/Kanban（カラム作成・タスク作成・編集・移動・担当者/期限設定・完了）
- ファイル共有（アップロード・一覧・Lightbox閲覧・PDFプレビュー・削除）
- Markdownメモ（作成・編集・プレビュー・ピン留め・検索・削除）
- カレンダー（ToDo期限・マイルストーン・ミーティング表示・イベント作成/編集）
- ミーティング（作成・参加メンバー設定・予定重複警告・アジェンダ/議事録・関連付け）
- 通知（ToDo担当者・メンション・ミーティング参加者への通知・既読化）
- アクティビティログ（ToDo作成・ファイルアップロード・メモ更新・ミーティング作成の記録）
- バックアップ（作成・一覧表示・ダウンロード）

`npm run test:e2e` でPlaywright E2E Testが実行できること。
Unit TestとE2E Testがすべて成功すること。

## スコープ外

明示的にスコープ外とする項目:
- Prisma等のORMは使用しない（独自SQLラッパー + Repositoryクラスで実装）
- Next.js Edge Runtimeは使用しない（Node.js Runtimeのみ）
- 外部カレンダー（Google Calendar等）との同期（Post-MVP）
- メール通知・Webhook通知（Post-MVP）
- モバイル専用UIの最適化（Post-MVP）
- 外部認証プロバイダ（OAuth/SSO）は使用しない（独自ログイン方式）
- クラウドストレージへのファイル保存は行わない（ローカルファイルシステムのみ）