共通規約 Conventions

Parky プロジェクト全体で守るべき共通ルールです。DB設計・コード・運用まで含みます。

Shared rules across the Parky project — covers DB design, code, and operations.

1. コードマスター方針1. Code-master strategy

ステータス・カテゴリ・種別などの列挙値は、日本語ラベルではなく コード値（英語小文字スネークケース）で DB に保存します。 表示ラベルは codes テーブル（コードマスター）で管理し、クライアント側で解決します。

Enum-like values (status, category, type…) are stored as lowercase snake_case code values, not Japanese labels. Display labels come from the codes table and are resolved client-side.

codes schema

category_id   -- 分類ID (e.g. 'admin_status')
code          -- コード値 (e.g. 'active')
display_label -- 表示名 (e.g. '有効')
lang          -- 言語コード (default 'ja')
sort_order    -- 表示順
is_deleted    -- 削除フラグ

フロントエンドでは useCode() フックで取得し、 code.label('admin_status', value) で表示名に変換、 code.options('admin_status') でドロップダウン選択肢を生成します。

Frontends use a useCode() hook: code.label('admin_status', value) → label, and code.options('admin_status') → dropdown options.

カテゴリの代表例: admin_status, user_status, vehicle_type, session_status, notif_type, notif_status, notif_target, admin_notif_category, device_type, lot_status, lot_structure, payment_method, payment_status, badge_category, theme_part_category, ticket_status, article_status, review_status, boost_status, revenue_channel ほか多数（実測で 50 以上）。 実際の完全なカテゴリ一覧は codes テーブルの SELECT DISTINCT category_id FROM codes で取得する。

Representative categories: admin_status, user_status, vehicle_type, session_status, notif_type, notif_status, notif_target, admin_notif_category, device_type, lot_status, lot_structure, payment_method, payment_status, badge_category, theme_part_category, ticket_status, article_status, review_status, boost_status, revenue_channel, and many more (50+ total). For the full list query SELECT DISTINCT category_id FROM codes.

2. ソフトデリート方針2. Soft delete

ユーザーが直接操作する削除は ソフトデリート（deleted_at カラム）を使います。 完全削除は「ゴミ箱」画面からのみ実行可能にします。

User-initiated deletes use soft delete via a deleted_at column. Hard deletes are only possible from a Trash UI.

3. リンクテーブル（多対多）3. Link tables for M:N

エンティティ間の多対多・参照関係はリンクテーブル（中間テーブル）で持ち、 冗長な外部キーやデータコピーを避けます。

Many-to-many relations live in link tables — no redundant foreign keys or duplicated data.

例: parking_sessions は user_id + parking_lot_id で app_users と parking_lots を参照します。

Example: parking_sessions references app_users and parking_lots via user_id + parking_lot_id.

4. べき等性4. Idempotency

すべてのスクリプト・SQL・マイグレーション・シード・データ操作はべき等でなければなりません。

• SQL: CREATE TABLE IF NOT EXISTS / INSERT ... ON CONFLICT DO UPDATE
• SQL: CREATE TABLE IF NOT EXISTS / INSERT ... ON CONFLICT DO UPDATE
• スキーマ変更はテーブル単位のマスターファイルに追記/上書き（バージョン番号のついたファイルは作らない）
• Schema changes append to per-table master files — no versioned filenames.
• 一時ツールは処理完了後に削除する。繰り返し使うものだけ scripts/ に残す。
• Throw-away tools are deleted after use; keep only reusable ones under scripts/.

5. 環境変数・シークレット5. Env vars & secrets

• 本番 .env は直接編集せず、.env.example をコピーして値を埋める
• Never edit production .env directly — copy .env.example and fill values.
• Claude に渡したいがGit管理したくない情報は .claude/context/ に置き、.gitignore 対象にする
• Secrets/context for Claude live under .claude/context/ and are gitignored.
• シークレットをコード内・CLAUDE.md 内にハードコードしない
• Never hardcode secrets in source or in CLAUDE.md.

6. 命名規則6. Naming

• DBテーブル・カラム: snake_case
• DB tables and columns: snake_case.
• リンクテーブル: owner_table_singular + related_table_plural（例: parking_lot_tags）
• Link tables: owner_singular + related_plural (e.g. parking_lot_tags).
• TypeScript/Dart: 型は PascalCase、関数・変数は camelCase
• TypeScript/Dart: types in PascalCase, fns/vars in camelCase.
• ブランチ: dev が統合先。個別作業は feature/... / fix/...
• Branches: integrate into dev. Use feature/... / fix/... for work.

7. コミット・デプロイ7. Commits & deploy

• コミットメッセージは日本語で、変更内容と目的が分かるように書く
• Commit messages are written in Japanese, with clear intent and reason.
• 修正が完了したらコミット＋プッシュまで自動で行う
• When a fix is ready, commit and push automatically.
• デプロイは GitHub Actions 経由のみ。直接 scp/rsync はしない
• All deploys go through GitHub Actions — no manual scp/rsync.

8. 一時作業ファイル8. Scratch outputs

• 一時的なダンプ・解析結果は .work/{プロジェクト}/ に出力（サブフォルダ必須）
• Scratch outputs go under .work/{subfolder}/ (never at the root).
• ファイル名は YYYY-MM-DD_HH-MM_{日本語名}.{ext}
• Filenames: YYYY-MM-DD_HH-MM_{ja-name}.{ext}.