ABService

WebService/Site implementation for my own use

技術スタック

• バックエンド: Quarkus（Reactive）/ Java（Amazon Corretto）/ Gradle
• データベース: PostgreSQL（Flyway・Hibernate Reactive Panache）
• オブジェクトストレージ: S3互換（本番はS3、開発はMinIO）
• フロントエンド: Astro + Svelte（管理画面・公開画面とも静的ビルド）
• インフラ: AWS（EC2 + CloudFront + RDS + S3）/ Docker Compose（ローカル）

固定バージョンの運用方針は CONTRIBUTION.md の「技術スタックの固定と昇格」、実際の版は backend/gradle.properties / backend/build.gradle / backend/gradle/wrapper/gradle-wrapper.properties が正。

設計と規約

現行の構造・スキーマ・APIの正は実装（実クラス / backend/src/main/resources/db/migration/ / 静的解析の設定）であり、ドキュメントには再記述しない。

• docs/ARCHITECTURE.md - 構成・境界・経路（CloudFrontのパスベースルーティング、認証方式、アセットの経路）
• docs/DECISIONS.md - 設計判断の記録（なぜその構造にしたか）
• docs/CODING_GUIDELINES.md - 設計上の意図と、静的解析で強制しているルールの索引
• docs/STATUS_AND_ROADMAP.md - 開発状況（残タスクは GitHub issue が正）
• backend/TEST_GUIDE.md - テスト分離規約
• docs/README.md - ドキュメント記述規約（何を文書に書き、何を書かないか）

本番デプロイと復旧

ABService 側の構築・配布・ロールバック機構の技術的な操作と契約は infra/README.md を正とします。設定項目と実行コマンドはそこを入口に参照してください。

実環境での作業順序・停止条件・切替判断・証跡は、非公開の運用リポジトリ（ABAffairs）を正とします。実環境の設定値・投入する本文や画像もそこで管理します。公開リポジトリには実ドメインやアカウント固有値を置かず、秘密値は Git に保存しません。

開発側の依存関係とリリース阻害条件は ロードマップ #224・各 issue・milestone、v1.0 のスコープは #132 を正とします。進捗は各 issue と milestone で管理します。CI 通過と本番受け入れは別で、実環境での配信・復旧・監視の確認が必要です。

開発

ビルドとテスト

# バックエンドのビルド
cd backend
./gradlew build

# テスト実行
./gradlew test

# 開発モードで起動
./gradlew quarkusDev

コード品質

PR の CI は変更箇所と workspace の依存関係から検査対象を選ぶ。レビュー時は集約チェック CI gate を確認する。対象外の検査のスキップは許容するが、対象の検査の失敗・中断・スキップは通さない。GitHub 側で必須チェックを指定する場合も CI gate を使う。選択と判定の検査は node --test scripts/ci-policy.test.mjs。

main と手動実行は全件を検査する。本番デプロイは引き続き main の CI 成功を前提とする。

ABServiceでは以下のLinting/フォーマットツールを使用しています：

• Checkstyle: Google Java Style Guideに基づくコードスタイルチェック＋独自ルール
• Spotless: 自動コードフォーマッタ（Eclipse JDT）
• PMD: 独自XPathルール（機能的スタイル強制）＋組込の不要変数検出
• ArchUnit: アーキテクチャ制約（レイヤー依存方向・配置・戻り値契約など）をテストで強制

注意: SpotBugs は現在未導入です。再導入の判断と受け入れ条件は issue #193 が正です。

コード品質チェック

# すべてのコード品質チェックを実行
./gradlew check

# Checkstyleのみ実行
./gradlew checkstyleMain checkstyleTest

# Spotlessフォーマットチェック
./gradlew spotlessCheck

コードフォーマット

# コードを自動フォーマット
./gradlew spotlessApply

build は整形を当てません（検査は check の spotlessCheck）。ビルドが tracked ファイルを書き換えると、同じ入力で作業ツリーが変わり、git bisect や「作業ツリーが汚れているか」の判断に副作用が出るためです。整形が崩れているときは spotlessApply を明示的に実行します（コミット前は pre-commit の spotlessCheck が気付かせます）。

Git Hooks

コミット前に自動でコード品質チェックを実行できます（Java 25 が必要です）：

# プロジェクトルートで実行（初回のみ）
./scripts/setup-git-hooks.sh

導入されるhooks:

• pre-commit: 品質ゲート（Spotless / Checkstyle / PMD / ユニット+ArchUnit テスト）を実行

core.hooksPath=.githooks を設定し、バージョン管理された検査専用フックを有効にします。 フックは整形や再ステージを行いません。Java の変更はステージ前に backend/gradlew -p backend spotlessApply で整形してください。 GitHub API など Git フックを経由しない反映でも、.githooks/pre-commit と同じ品質ゲートを事前に実行してください。

Hooksをスキップする場合（非推奨）:

git commit --no-verify
git push --no-verify

レポート

コード品質チェックのレポートは以下に生成されます：

• Checkstyle: backend/build/reports/checkstyle/
• PMD: backend/build/reports/pmd/
• Spotless: コンソール出力

SpotBugsについて

SpotBugs は現在このプロジェクトでは未導入。再導入（PMD 組込ルールセットと併せたバグパターン検出）の検討は issue #193。