Commit ·
df01c4b
1
Parent(s): 2a4c6ac
docs: CLAUDE.mdにプロジェクト概要・アーキテクチャ・開発コマンド・規約を追加
Browse files
CLAUDE.md
CHANGED
|
@@ -1,5 +1,88 @@
|
|
| 1 |
# CLAUDE.md
|
| 2 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3 |
## Git ワークフロー
|
| 4 |
|
| 5 |
コード変更後は必ずコミット&プッシュをセットで行う。
|
|
|
|
| 1 |
# CLAUDE.md
|
| 2 |
|
| 3 |
+
## プロジェクト概要
|
| 4 |
+
|
| 5 |
+
SDU-Shift は飲食店向けのシフト表自動生成ツール。同じバックエンド(DB・モデル・最適化エンジン・出力処理)を、
|
| 6 |
+
|
| 7 |
+
- **デスクトップ版**(PyQt6、`main.py` がエントリーポイント)
|
| 8 |
+
- **Web版**(Flask、`web_app.py` の `create_app()` がエントリーポイント)
|
| 9 |
+
|
| 10 |
+
の2つのインターフェースから利用する構成になっている。詳しい機能・画面仕様は README.md を参照。
|
| 11 |
+
|
| 12 |
+
---
|
| 13 |
+
|
| 14 |
+
## アーキテクチャ / ディレクトリ構成
|
| 15 |
+
|
| 16 |
+
| パス | 役割 |
|
| 17 |
+
|---|---|
|
| 18 |
+
| `main.py` | デスクトップ版エントリーポイント(PyQt6アプリ起動) |
|
| 19 |
+
| `web_app.py` | Web版エントリーポイント。`create_app()` でFlaskアプリを生成しBlueprintを登録 |
|
| 20 |
+
| `auth.py` | Web版の共有パスワード認証(`login_required`デコレータ) |
|
| 21 |
+
| `cache.py` | Flask-Caching インスタンス |
|
| 22 |
+
| `db/database.py` | DB接続層。`Connection`クラスがSQLite/PostgreSQLの両方を抽象化 |
|
| 23 |
+
| `db/repositories.py` | データアクセス関数群(CRUD・集計クエリ) |
|
| 24 |
+
| `db/seeder.py` / `db/seed_data.json` | 初期データ投入 |
|
| 25 |
+
| `models/` | ドメインモデル(`Employee`, `ShiftRequest`, `ShiftAssignment`, `SchedulePeriod` などのdataclass) |
|
| 26 |
+
| `optimizer/solver.py` | CP-SAT (OR-Tools) によるシフト最適化エンジン本体 |
|
| 27 |
+
| `export/` | Excel (`openpyxl`) / PDF (`reportlab`) 出力 |
|
| 28 |
+
| `routes/` | Web版のFlask Blueprint群(employees, shifts, generate, schedule, customers, settings, export, dashboard, auth, help) |
|
| 29 |
+
| `ui/` | デスクトップ版のPyQt6画面 |
|
| 30 |
+
| `templates/`, `static/`, `assets/` | Web版テンプレート・静的ファイル/アイコン等 |
|
| 31 |
+
| `utils/` | 共通定数(`constants.py`)、シフトパターン定義(`shift_patterns.py`)、祝日判定、テーマ、バージョン、ソルバーログなど |
|
| 32 |
+
| `scripts/seed_test_data.py` | 動作確認用のテストデータ投入スクリプト |
|
| 33 |
+
| `scripts/ShiftFormGenerator.gs` | 希望シフト収集用Google Formsと連携するApps Script |
|
| 34 |
+
| `shift_tool.spec` | PyInstallerビルド設定(Windows EXE / macOS .app) |
|
| 35 |
+
| `.github/workflows/build-windows.yml` | mainプッシュ時にWindows/macOS向けビルド&リリースを自動実行 |
|
| 36 |
+
|
| 37 |
+
---
|
| 38 |
+
|
| 39 |
+
## 開発・実行コマンド
|
| 40 |
+
|
| 41 |
+
### デスクトップ版
|
| 42 |
+
```bash
|
| 43 |
+
pip install -r requirements.txt
|
| 44 |
+
python main.py
|
| 45 |
+
```
|
| 46 |
+
DBは `~/.shift_tool/shift_tool.db`(開発環境)に自動作成される。
|
| 47 |
+
|
| 48 |
+
### Web版(開発サーバー)
|
| 49 |
+
```bash
|
| 50 |
+
pip install -r requirements-web.txt
|
| 51 |
+
python web_app.py
|
| 52 |
+
```
|
| 53 |
+
`http://localhost:5000` で起動(`debug=True`)。`DATABASE_URL`未設定時はSQLiteにフォールバック。
|
| 54 |
+
|
| 55 |
+
### Web版(本番相当)
|
| 56 |
+
```bash
|
| 57 |
+
gunicorn 'web_app:create_app()' --bind 0.0.0.0:$PORT --workers 2 --timeout 120
|
| 58 |
+
```
|
| 59 |
+
|
| 60 |
+
### テストデータ投入
|
| 61 |
+
```bash
|
| 62 |
+
python scripts/seed_test_data.py # データを追加
|
| 63 |
+
python scripts/seed_test_data.py --reset # 全データ削除後に追加
|
| 64 |
+
```
|
| 65 |
+
|
| 66 |
+
### Dockerビルド(HuggingFace Spaces向け)
|
| 67 |
+
`Dockerfile` を使用、`app_port: 8080`。
|
| 68 |
+
|
| 69 |
+
---
|
| 70 |
+
|
| 71 |
+
## コーディング規約・注意点
|
| 72 |
+
|
| 73 |
+
- **DB抽象化に従う**: `db/database.py` の `Connection` はSQLiteとPostgreSQL両対応。生のSQLは**SQLite方言**で書く(`?`プレースホルダ、`INTEGER PRIMARY KEY AUTOINCREMENT`など)。`_to_pg()`が自動的にPostgreSQL構文へ変換するため、PostgreSQL固有の構文を直接書かない。
|
| 74 |
+
- **環境変数**:
|
| 75 |
+
- `DATABASE_URL` — 設定時はPostgreSQL(Render)、未設定時はSQLite(デスクトップ/HF Spaces)
|
| 76 |
+
- `APP_PASSWORD` — Web版の共有パスワード認証。空文字なら認証自体が無効になる
|
| 77 |
+
- `SECRET_KEY` — Flaskセッション用シークレット
|
| 78 |
+
- `SOLVER_LOG_PATH` — ソルバーのログ出力先(`utils/solver_logger.py`)
|
| 79 |
+
- **デプロイ先が2系統ある**: HuggingFace Spaces(Docker、SQLite前提)とGitHub→Render(PostgreSQL)。DB方言に依存する変更は両方で動作確認する。
|
| 80 |
+
- **コメント・docstring・コミットメッセージは日本語**で統一する。
|
| 81 |
+
- **自動テストスイートは無し**。`scripts/seed_test_data.py` でテストデータを投入し、デスクトップ/Web両方で手動確認する。
|
| 82 |
+
- **ソルバー変更時**: `optimizer/solver.py` の優先度は `SolverConfig` と `PRIORITY_SCALE`(低=0.1/中=1.0/高=10.0)で調整する。`utils/solver_logger.py` がスタッフ別の割当根拠・ペナルティ内訳をログ出力するため、制約変更後は必ずログで影響を確認する。
|
| 83 |
+
|
| 84 |
+
---
|
| 85 |
+
|
| 86 |
## Git ワークフロー
|
| 87 |
|
| 88 |
コード変更後は必ずコミット&プッシュをセットで行う。
|