m1m02530125 commited on
Commit
df01c4b
·
1 Parent(s): 2a4c6ac

docs: CLAUDE.mdにプロジェクト概要・アーキテクチャ・開発コマンド・規約を追加

Browse files
Files changed (1) hide show
  1. CLAUDE.md +83 -0
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
  コード変更後は必ずコミット&プッシュをセットで行う。