furu04/Super-HomeworkManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

first commit

Browse Source
This commit is contained in:
furu04
2025-12-30 21:47:39 +09:00
commit 0a37314fa8
47 changed files with 6088 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

419
docs/API.md Normal file
View File

@@ -0,0 +1,419 @@
# Super Homework Manager API ドキュメント
## 概要
Super Homework Manager REST APIは、課題管理機能をプログラムから利用するためのAPIです。
- **ベースURL**: `/api/v1`
- **認証方式**: APIキー認証
- **レスポンス形式**: JSON
---
## 認証
すべてのAPIエンドポイントはAPIキー認証が必要です。
### APIキーの取得
1. 管理者アカウントでログイン
2. 管理画面 → APIキー管理へ移動
3. 新規APIキーを発行
### 認証ヘッダー
```
X-API-Key: hm_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```
### 認証エラー
| ステータスコード | レスポンス |
|------------------|------------|
| 401 Unauthorized | `{"error": "API key required"}` |
| 401 Unauthorized | `{"error": "Invalid API key"}` |
---
## エンドポイント一覧
| メソッド | パス | 説明 |
|----------|------|------|
| GET | `/api/v1/assignments` | 課題一覧取得 |
| GET | `/api/v1/assignments/:id` | 課題詳細取得 |
| POST | `/api/v1/assignments` | 課題作成 |
| PUT | `/api/v1/assignments/:id` | 課題更新 |
| DELETE | `/api/v1/assignments/:id` | 課題削除 |
| PATCH | `/api/v1/assignments/:id/toggle` | 完了状態トグル |
---
## 課題一覧取得
```
GET /api/v1/assignments
```
### クエリパラメータ
| パラメータ | 型 | 説明 |
|------------|------|------|
| `filter` | string | フィルタ: `pending`, `completed`, `overdue` (省略時: 全件) |
### レスポンス
**200 OK**
```json
{
"assignments": [
{
"id": 1,
"user_id": 1,
"title": "数学レポート",
"description": "第5章の練習問題",
"subject": "数学",
"due_date": "2025-01-15T23:59:00+09:00",
"is_completed": false,
"created_at": "2025-01-10T10:00:00+09:00",
"updated_at": "2025-01-10T10:00:00+09:00"
}
],
"count": 1
}
```
### 例
```bash
# 全件取得
curl -H "X-API-Key: hm_xxx" http://localhost:8080/api/v1/assignments
# 未完了のみ取得
curl -H "X-API-Key: hm_xxx" http://localhost:8080/api/v1/assignments?filter=pending
# 期限切れのみ取得
curl -H "X-API-Key: hm_xxx" http://localhost:8080/api/v1/assignments?filter=overdue
```
---
## 課題詳細取得
```
GET /api/v1/assignments/:id
```
### パスパラメータ
| パラメータ | 型 | 説明 |
|------------|------|------|
| `id` | integer | 課題ID |
### レスポンス
**200 OK**
```json
{
"id": 1,
"user_id": 1,
"title": "数学レポート",
"description": "第5章の練習問題",
"subject": "数学",
"due_date": "2025-01-15T23:59:00+09:00",
"is_completed": false,
"created_at": "2025-01-10T10:00:00+09:00",
"updated_at": "2025-01-10T10:00:00+09:00"
}
```
**404 Not Found**
```json
{
"error": "Assignment not found"
}
```
### 例
```bash
curl -H "X-API-Key: hm_xxx" http://localhost:8080/api/v1/assignments/1
```
---
## 課題作成
```
POST /api/v1/assignments
```
### リクエストボディ
| フィールド | 型 | 必須 | 説明 |
|------------|------|------|------|
| `title` | string | ✅ | 課題タイトル |
| `description` | string | | 説明 |
| `subject` | string | | 教科・科目 |
| `due_date` | string | ✅ | 提出期限（RFC3339 または `YYYY-MM-DDTHH:MM` または `YYYY-MM-DD`） |
### リクエスト例
```json
{
"title": "英語エッセイ",
"description": "テーマ自由、1000語以上",
"subject": "英語",
"due_date": "2025-01-20T17:00"
}
```
### レスポンス
**201 Created**
```json
{
"id": 2,
"user_id": 1,
"title": "英語エッセイ",
"description": "テーマ自由、1000語以上",
"subject": "英語",
"due_date": "2025-01-20T17:00:00+09:00",
"is_completed": false,
"created_at": "2025-01-10T11:00:00+09:00",
"updated_at": "2025-01-10T11:00:00+09:00"
}
```
**400 Bad Request**
```json
{
"error": "Invalid input: title and due_date are required"
}
```
### 例
```bash
curl -X POST \
-H "X-API-Key: hm_xxx" \
-H "Content-Type: application/json" \
-d '{"title":"英語エッセイ","due_date":"2025-01-20"}' \
http://localhost:8080/api/v1/assignments
```
---
## 課題更新
```
PUT /api/v1/assignments/:id
```
### パスパラメータ
| パラメータ | 型 | 説明 |
|------------|------|------|
| `id` | integer | 課題ID |
### リクエストボディ
すべてのフィールドはオプションです。省略されたフィールドは既存の値を維持します。
| フィールド | 型 | 説明 |
|------------|------|------|
| `title` | string | 課題タイトル |
| `description` | string | 説明 |
| `subject` | string | 教科・科目 |
| `due_date` | string | 提出期限 |
### リクエスト例
```json
{
"title": "英語エッセイ（修正版）",
"due_date": "2025-01-25T17:00"
}
```
### レスポンス
**200 OK**
```json
{
"id": 2,
"user_id": 1,
"title": "英語エッセイ（修正版）",
"description": "テーマ自由、1000語以上",
"subject": "英語",
"due_date": "2025-01-25T17:00:00+09:00",
"is_completed": false,
"created_at": "2025-01-10T11:00:00+09:00",
"updated_at": "2025-01-10T12:00:00+09:00"
}
```
**404 Not Found**
```json
{
"error": "Assignment not found"
}
```
### 例
```bash
curl -X PUT \
-H "X-API-Key: hm_xxx" \
-H "Content-Type: application/json" \
-d '{"title":"更新されたタイトル"}' \
http://localhost:8080/api/v1/assignments/2
```
---
## 課題削除
```
DELETE /api/v1/assignments/:id
```
### パスパラメータ
| パラメータ | 型 | 説明 |
|------------|------|------|
| `id` | integer | 課題ID |
### レスポンス
**200 OK**
```json
{
"message": "Assignment deleted"
}
```
**404 Not Found**
```json
{
"error": "Assignment not found"
}
```
### 例
```bash
curl -X DELETE \
-H "X-API-Key: hm_xxx" \
http://localhost:8080/api/v1/assignments/2
```
---
## 完了状態トグル
課題の完了状態を切り替えます（未完了 ↔ 完了）。
```
PATCH /api/v1/assignments/:id/toggle
```
### パスパラメータ
| パラメータ | 型 | 説明 |
|------------|------|------|
| `id` | integer | 課題ID |
### レスポンス
**200 OK**
```json
{
"id": 1,
"user_id": 1,
"title": "数学レポート",
"description": "第5章の練習問題",
"subject": "数学",
"due_date": "2025-01-15T23:59:00+09:00",
"is_completed": true,
"completed_at": "2025-01-12T14:30:00+09:00",
"created_at": "2025-01-10T10:00:00+09:00",
"updated_at": "2025-01-12T14:30:00+09:00"
}
```
**404 Not Found**
```json
{
"error": "Assignment not found"
}
```
### 例
```bash
curl -X PATCH \
-H "X-API-Key: hm_xxx" \
http://localhost:8080/api/v1/assignments/1/toggle
```
---
## エラーレスポンス
すべてのエラーレスポンスは以下の形式で返されます：
```json
{
"error": "エラーメッセージ"
}
```
### 共通エラーコード
| ステータスコード | 説明 |
|------------------|------|
| 400 Bad Request | リクエストの形式が不正 |
| 401 Unauthorized | 認証エラー |
| 404 Not Found | リソースが見つからない |
| 500 Internal Server Error | サーバー内部エラー |
---
## 日付形式
APIは以下の日付形式を受け付けます（優先度順）：
1. **RFC3339**: `2025-01-15T23:59:00+09:00`
2. **日時形式**: `2025-01-15T23:59`
3. **日付のみ**: `2025-01-15`（時刻は23:59に設定）
レスポンスの日付はすべてRFC3339形式で返されます。
---
## Rate Limiting
アプリケーションレベルでのRate Limitingが実装されています。
- **制限単位**: IPアドレスごと
- **デフォルト制限**: 100リクエスト / 60秒
- **超過時レスポンス**: `429 Too Many Requests`
```json
{
"error": "リクエスト数が制限を超えました。しばらくしてからお試しください。"
}
```
設定ファイル (`config.ini`) または環境変数で制限値を変更可能です。

252
docs/SPECIFICATION.md Normal file
View File

@@ -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)