first commit

2025-12-30 21:47:39 +09:00
commit 0a37314fa8
47 changed files with 6088 additions and 0 deletions
--- a/docs/SPECIFICATION.md
+++ b/docs/SPECIFICATION.md
@@ -0,0 +1,252 @@
+# Super Homework Manager 仕様書
+
+## 1. 概要
+
+Super Homework Managerは、学生の課題管理を支援するWebアプリケーションです。Go言語とGinフレームワークを使用して構築されており、課題の登録・管理、期限追跡、完了状況の管理機能を提供します。
+
+### 1.1 技術スタック
+
+| 項目 | 技術 |
+|------|------|
+| 言語 | Go |
+| Webフレームワーク | Gin |
+| データベース | SQLite (GORM with Pure Go driver - glebarez/sqlite) |
+| セッション管理 | gin-contrib/sessions (Cookie store) |
+| テンプレートエンジン | Go html/template |
+| コンテナ | Docker対応 |
+
+### 1.2 ディレクトリ構成
+
+```
+homework-manager/
+├── cmd/server/           # アプリケーションエントリポイント
+├── internal/
+│   ├── config/           # 設定読み込み
+│   ├── database/         # データベース接続・マイグレーション
+│   ├── handler/          # HTTPハンドラ
+│   ├── middleware/       # ミドルウェア
+│   ├── models/           # データモデル
+│   ├── repository/       # データアクセス層
+│   └── service/          # ビジネスロジック
+├── web/
+│   ├── static/           # 静的ファイル (CSS, JS)
+│   └── templates/        # HTMLテンプレート
+├── Dockerfile
+└── docker-compose.yml
+```
+
+---
+
+## 2. データモデル
+
+### 2.1 User（ユーザー）
+
+ユーザー情報を管理するモデル。
+
+| フィールド | 型 | 説明 | 制約 |
+|------------|------|------|------|
+| ID | uint | ユーザーID | Primary Key |
+| Email | string | メールアドレス | Unique, Not Null |
+| PasswordHash | string | パスワードハッシュ | Not Null |
+| Name | string | 表示名 | Not Null |
+| Role | string | 権限 (`user` or `admin`) | Default: `user` |
+| CreatedAt | time.Time | 作成日時 | 自動設定 |
+| UpdatedAt | time.Time | 更新日時 | 自動更新 |
+| DeletedAt | gorm.DeletedAt | 論理削除日時 | ソフトデリート |
+
+### 2.2 Assignment（課題）
+
+課題情報を管理するモデル。
+
+| フィールド | 型 | 説明 | 制約 |
+|------------|------|------|------|
+| ID | uint | 課題ID | Primary Key |
+| UserID | uint | 所有ユーザーID | Not Null, Index |
+| Title | string | 課題タイトル | Not Null |
+| Description | string | 説明 | - |
+| Subject | string | 教科・科目 | - |
+| DueDate | time.Time | 提出期限 | Not Null |
+| IsCompleted | bool | 完了フラグ | Default: false |
+| CompletedAt | *time.Time | 完了日時 | Nullable |
+| CreatedAt | time.Time | 作成日時 | 自動設定 |
+| UpdatedAt | time.Time | 更新日時 | 自動更新 |
+| DeletedAt | gorm.DeletedAt | 論理削除日時 | ソフトデリート |
+
+### 2.3 APIKey（APIキー）
+
+REST API認証用のAPIキーを管理するモデル。
+
+| フィールド | 型 | 説明 | 制約 |
+|------------|------|------|------|
+| ID | uint | APIキーID | Primary Key |
+| UserID | uint | 所有ユーザーID | Not Null, Index |
+| Name | string | キー名 | Not Null |
+| KeyHash | string | キーハッシュ | Unique, Not Null |
+| LastUsed | *time.Time | 最終使用日時 | Nullable |
+| CreatedAt | time.Time | 作成日時 | 自動設定 |
+| DeletedAt | gorm.DeletedAt | 論理削除日時 | ソフトデリート |
+
+---
+
+## 3. 認証・認可
+
+### 3.1 Web認証
+
+- **セッションベース認証**: Cookie storeを使用
+- **セッション有効期限**: 7日間
+- **パスワード要件**: 8文字以上
+- **パスワードハッシュ**: bcryptを使用
+- **CSRF対策**: 全フォームでのトークン検証
+
+### 3.2 API認証
+
+- **APIキー認証**: `X-API-Key` ヘッダーで認証
+- **キー形式**: `hm_` プレフィックス + 32文字のランダム文字列
+- **ハッシュ保存**: SHA-256でハッシュ化して保存
+
+### 3.3 ユーザーロール
+
+| ロール | 権限 |
+|--------|------|
+| `user` | 自分の課題のCRUD操作、プロフィール管理 |
+| `admin` | 全ユーザー管理、APIキー管理、ユーザー権限の変更 |
+※ 最初に登録されたユーザーには自動的に `admin` 権限が付与されます。2人目以降は `user` として登録されます。
+
+---
+
+## 4. 機能一覧
+
+### 4.1 認証機能
+
+| 機能 | 説明 |
+|------|------|
+| 新規登録 | メールアドレス、パスワード、名前で登録 |
+| ログイン | メールアドレスとパスワードでログイン |
+| ログアウト | セッションをクリアしてログアウト |
+
+### 4.2 課題管理機能
+
+| 機能 | 説明 |
+|------|------|
+| ダッシュボード | 課題の統計情報、本日期限の課題、期限切れ課題、今週期限の課題を表示 |
+| 課題一覧 | フィルタ付き（未完了/完了済み/期限切れ）で課題を一覧表示 |
+| 課題登録 | タイトル、説明、教科、提出期限を入力して新規登録 |
+| 課題編集 | 既存の課題情報を編集 |
+| 課題削除 | 課題を論理削除 |
+| 完了トグル | 課題の完了/未完了状態を切り替え |
+
+### 4.3 プロフィール機能
+
+| 機能 | 説明 |
+|------|------|
+| プロフィール表示 | ユーザー情報を表示 |
+| プロフィール更新 | 表示名を変更 |
+| パスワード変更 | 現在のパスワードを確認後、新しいパスワードに変更 |
+
+### 4.4 管理者機能
+
+| 機能 | 説明 |
+|------|------|
+| ユーザー一覧 | 全ユーザーを一覧表示 |
+| ユーザー削除 | ユーザーを論理削除（自分自身は削除不可） |
+| 権限変更 | ユーザーのロールを変更（自分自身は変更不可） |
+| APIキー一覧 | 全APIキーを一覧表示 |
+| APIキー発行 | 新規APIキーを発行（発行時のみ平文表示） |
+| APIキー削除 | APIキーを削除 |
+
+---
+
+## 5. 設定
+
+### 5.1 設定ファイル (config.ini)
+
+アプリケーションは `config.ini` ファイルから設定を読み込みます。`config.ini.example` をコピーして使用してください。
+
+```ini
+[server]
+port = 8080
+debug = true
+
+[database]
+driver = sqlite
+path = homework.db
+
+[session]
+secret = your-secure-secret-key
+
+[auth]
+allow_registration = true
+
+[security]
+https = false
+csrf_secret = your-secure-csrf-secret
+rate_limit_enabled = true
+rate_limit_requests = 100
+rate_limit_window = 60
+```
+
+### 5.2 設定項目
+
+| セクション | キー | 説明 | デフォルト値 |
+|------------|------|------|--------------|
+| `server` | `port` | サーバーポート | `8080` |
+| `server` | `debug` | デバッグモード | `true` |
+| `database` | `driver` | DBドライバー (sqlite, mysql, postgres) | `sqlite` |
+| `database` | `path` | SQLiteファイルパス | `homework.db` |
+| `session` | `secret` | セッション暗号化キー | (必須) |
+| `auth` | `allow_registration` | 新規登録許可 | `true` |
+| `security` | `https` | HTTPS設定(Secure Cookie) | `false` |
+| `security` | `csrf_secret` | CSRFトークン秘密鍵 | (必須) |
+| `security` | `rate_limit_enabled` | レート制限有効化 | `true` |
+| `security` | `rate_limit_requests` | 期間あたりの最大リクエスト数 | `100` |
+| `security` | `rate_limit_window` | 期間（秒） | `60` |
+
+### 5.3 環境変数
+
+環境変数が設定されている場合、config.iniの設定より優先されます。
+
+| 変数名 | 説明 |
+|--------|------|
+| `PORT` | サーバーポート |
+| `DATABASE_DRIVER` | データベースドライバー |
+| `DATABASE_PATH` | SQLiteデータベースファイルパス |
+| `SESSION_SECRET` | セッション暗号化キー |
+| `CSRF_SECRET` | CSRFトークン秘密鍵 |
+| `GIN_MODE` | `release` でリリースモード（debug=false） |
+| `ALLOW_REGISTRATION` | 新規登録許可 (true/false) |
+| `HTTPS` | HTTPSモード (true/false) |
+| `TRUSTED_PROXIES` | 信頼するプロキシのリスト |
+
+### 5.4 設定の優先順位
+
+1. 環境変数（最優先）
+2. config.ini
+3. デフォルト値
+
+---
+
+## 6. セキュリティ
+
+### 6.1 実装済みセキュリティ機能
+
+- **パスワードハッシュ化**: bcryptによるソルト付きハッシュ
+- **セッションセキュリティ**: HttpOnly Cookie
+- **入力バリデーション**: 各ハンドラで基本的な入力検証
+- **CSFR対策**: Double Submit Cookieパターンまたは同期トークンによるCSRF保護
+- **レート制限**: IPベースのリクエスト制限によるDoS対策
+- **論理削除**: データの完全削除を防ぐソフトデリート
+- **権限チェック**: ミドルウェアによるロールベースアクセス制御
+- **Secure Cookie**: HTTPS設定時のSecure属性付与
+
+### 6.2 推奨される本番環境設定
+
+- `SESSION_SECRET` と `CSRF_SECRET` を強力なランダム文字列に変更
+- HTTPSを有効化し、`HTTPS=true` を設定
+- `GIN_MODE=release` を設定
+- 必要に応じて `TRUSTED_PROXIES` を設定
+
+---
+
+## 7. ライセンス
+
+AGPLv3 (GNU Affero General Public License v3)