SOTAApp2 - アマチュア無線アワードプログラム管理システム

MyACTの次世代バックエンドWebサービス

SOTAApp2は、アマチュア無線のアワードプログラム（SOTA、POTA）を管理するための高性能・高可用性Webサービスです。ヘキサゴナルアーキテクチャを採用し、Rustで実装されています。

🏗️ システムアーキテクチャ

アーキテクチャ概要

本システムは**ヘキサゴナルアーキテクチャ（Clean Architecture）**を採用し、以下の6つのレイヤーで構成されています：

┌─────────────────────────────────────────────┐
│                    API                      │ ← RESTエンドポイント・認証・バリデーション
├─────────────────────────────────────────────┤
│                  Service                    │ ← ユースケース・ビジネスロジック
├─────────────────────────────────────────────┤
│                  Domain                     │ ← エンティティ・バリューオブジェクト
├─────────────────────────────────────────────┤
│                  Adapter                    │ ← DB・外部API・APRS・ファイルアクセス
├─────────────────────────────────────────────┤
│                  Registry                   │ ← 依存性注入・モジュール管理
├─────────────────────────────────────────────┤
│                  Common                     │ ← 共通ライブラリ・設定・エラーハンドリング
└─────────────────────────────────────────────┘

各レイヤーの責務

🌐 API層（api/）

• 責務: RESTエンドポイント、認証・認可、リクエスト/レスポンス処理
• 技術: Axum、Cloudflare Access(管理画面)、CORS
• 主要コンポーネント:
  • ハンドラー（SOTA、POTA、認証、ヘルスチェック）
  • ミドルウェア（認証、CORS）
  • DTOモデル

🎯 Service層（service/）

• 責務: ユースケース実装、ビジネスルール、トランザクション管理
• パターン: Application Service パターン
• 主要サービス:
  • UserService: ユーザー向け機能
  • AdminService: 管理者向け機能
  • AdminPeriodicService: バッチ処理・定期実行

🏛️ Domain層（domain/）

• 責務: ビジネスエンティティ、バリューオブジェクト、ドメインロジック
• 主要エンティティ:
  • Activation: アクティベーション（Alert/Spot）
  • SOTAReference: SOTA山岳データ
  • POTAReference: POTA公園データ
  • AprsLog: APRS通信ログ

🔌 Adapter層（adapter/）

• 責務: 外部システム連携、データベースアクセス、インフラストラクチャ
• 外部連携:
  • データベース（SQLite/PostgreSQL）
  • APRS-IS（無線データ）
  • 地磁気データAPI
  • SOTA/POTAオープンデータ

🔧 Registry層（registry/）

• 責務: 依存性注入、モジュール構成管理
• 技術: Shaku DI フレームワーク
• 設計: 実行時依存性解決

📚 Common層（common/）

• 責務: 共通ライブラリ、設定管理、エラーハンドリング
• コンポーネント: 設定、エラー型、ユーティリティ

🚀 主要機能

SOTA（Summits on the Air）管理

• 山岳データベース管理
• アクティベーション予告（Alert）・運用報告（Spot）
• ログアップロード・進捗管理

POTA（Parks on the Air）管理

• 公園データベース管理
• アクティベーション・スポット管理

リアルタイム通信

• APRS-IS連携によるリアルタイム位置情報
• WebSocket対応予定

データ管理・分析

• 地磁気データ取得・分析
• CSVインポート・エクスポート
• 統計・レポート機能

🛠️ 技術スタック

コアテクノロジー

• 言語: Rust 2021 Edition
• Webフレームワーク: Axum 0.8
• データベース: SQLite / PostgreSQL（SQLx）
• 認証: Cloudflare Access(管理画面)
• DI: Shaku
• 非同期: Tokio
• ログ: tracing

外部連携

• APRS: aprs-message クレート
• 地理情報: geographiclib-rs、maidenhead
• スケジュール: tokio-cron-scheduler

インフラ

• コンテナ: Docker / Docker Compose
• デプロイ: Fly.io
• CI/CD: GitHub Actions（想定）

📋 開発ガイドライン

レイヤー別メンテナンス方針

ユースケース	主要メンテナンス対象	変更頻度	注意点
新機能追加	Service → API → Domain	高	ドメイン変更は慎重に
外部API変更	Adapter	中	インターフェース維持
UI/UX改善	API（ハンドラー・モデル）	高	DTOとドメインの分離
パフォーマンス	Adapter → Service	中	N+1問題、キャッシュ
セキュリティ	API（認証）→ Common	低	認証・認可ロジック
データ移行	Adapter（migrations）	低	スキーマバージョニング
設定変更	Common	中	環境変数・設定ファイル

開発フロー推奨事項

1. ドメインファースト: 新機能はDomainからスタート
2. テストファースト: 各層でユニットテスト実装
3. 依存性の方向: 内側→外側の依存のみ
4. インターフェース設計: traitによる抽象化
5. エラーハンドリング: anyhow + thiserrorによる構造化

コーディング規約

// ✅ 良い例: トレイトによる抽象化
#[async_trait]
pub trait UserService {
    async fn find_user(&self, id: UserId) -> AppResult<User>;
}

// ✅ 良い例: 型安全性
pub struct SummitCode(String);
impl SummitCode {
    pub fn new(code: String) -> Self {
        // バリデーション
        Self(code)
    }
}

// ❌ 悪い例: 直接的な依存
// Service層からAdapter実装に直接依存

🚀 開発環境セットアップ

詳細な開発環境構築手順は docs/development-setup.md を参照してください。

クイックスタート

git clone https://github.com/jl1nie/sotaapp2.git
cd sotaapp2
cp .env.example .env  # 編集してAPIキー等を設定
makers build && makers migrate run && makers run

📊 API エンドポイント

本番環境: https://sotaapp2.fly.dev

ヘルスチェック

エンドポイント	説明
GET /api/v2/health	サーバーヘルスチェック
GET /api/v2/health/db	データベース接続確認

アクティベーション API

エンドポイント	パラメータ	説明
GET /api/v2/activation/alerts	pat_ref (必須)	アラート一覧取得
GET /api/v2/activation/spots	pat_ref (必須), hours_ago	スポット一覧取得
GET /api/v2/activation/aprs/track	pat_ref (必須), hours_ago	APRSトラック取得

パラメータ例:

• pat_ref=JA - 日本のアクティベーション
• pat_ref=JA,HL - 日本と韓国
• hours_ago=24 - 過去24時間

地磁気データ API

エンドポイント	説明
GET /api/v2/propagation/geomag	最新の地磁気指数（A/K指数）

レスポンス例:

{
  "date": "2025-12-26",
  "a_index": 12,
  "k_index": [3.0, 3.33, 2.67]
}

検索 API

エンドポイント	パラメータ	説明
GET /api/v2/search	min_lat, max_lat, min_lon, max_lon	範囲内の山岳・公園検索

パラメータ例:

/api/v2/search?min_lat=35&max_lat=36&min_lon=139&max_lon=140

地図表示 API

エンドポイント	パラメータ	説明
GET /api/v2/map	lat (必須), lon (必須), zoom, label, tile, embed	指定座標を中心とした地図をHTMLで表示
GET /api/v2/map/view	同上	地図描画に必要な情報をJSONで返す（フロントエンド連携用）

パラメータ	既定値	説明
lat	-	緯度（-90〜90）
lon	-	経度（-180〜180）
zoom	15	ズームレベル（1〜19。タイルの最大ズームに丸められる）
label	-	マーカーに表示する名称（100文字以内）
tile	gsi	タイル種別。gsi = 地理院タイル（日本国内のみ）、osm = OpenStreetMap（日本国外はこちら）
embed	false	trueでヘッダを省略（iframe埋め込み用）
refs	true	falseで近傍のSOTA山岳・POTA公園の表示を止める
radius	1000	近傍を探す半径。単位はメートル（1〜10000）

中心の近く（radius以内）にあるSOTA山岳・POTA公園を、近い順に最大20件マーカーで表示します （青 = SOTA、緑 = POTA。ポップアップにコード・名称・標高/所在地・距離）。 /api/v2/map/view では nearby 配列として返します。

パラメータ例:

/api/v2/map?lat=35.360556&lon=138.727778&zoom=13&label=富士山&tile=gsi

ブラウザで開くと、指定座標にマーカーを立てた地図（Leaflet）が表示されます。 マーカーのポップアップには座標とグリッドロケータ（メイデンヘッド）が表示されます。

フロントエンドからの利用

admin/src/lib/api.ts にクライアントヘルパーを用意しています。

import { buildMapUrl, getMapView, hasValidCoordinates } from '$lib/api';

// 1. 別タブで開く / iframeのsrcに指定する
const url = buildMapUrl({ lat, lon, label: summitName });
window.open(url, '_blank', 'noopener');

// 2. iframeに埋め込む（ヘッダ非表示）
const embedUrl = buildMapUrl({ lat, lon, label: summitName, embed: true });

// 3. 自前の地図コンポーネントで描画する
const view = await getMapView({ lat, lon, tile: 'gsi' });
// view.tile.urlTemplate / view.tile.attribution / view.tile.maxZoom を
// Leaflet等にそのまま渡せる。view.externalLinks には外部地図サービスへのリンク。

GET /api/v2/map/view のレスポンス例:

{
  "latitude": 35.360556,
  "longitude": 138.727778,
  "zoom": 15,
  "maidenhead": "PM95ii76",
  "label": "富士山",
  "tile": {
    "kind": "gsi",
    "urlTemplate": "https://cyberjapandata.gsi.go.jp/xyz/std/{z}/{x}/{y}.png",
    "attribution": "<a href=\"https://maps.gsi.go.jp/development/ichiran.html\">地理院タイル</a>",
    "maxZoom": 18
  },
  "mapUrl": "/api/v2/map?lat=35.360556&lon=138.727778&zoom=15&tile=gsi&label=%E5%AF%8C%E5%A3%AB%E5%B1%B1",
  "embedUrl": "/api/v2/map?lat=35.360556&lon=138.727778&zoom=15&tile=gsi&label=%E5%AF%8C%E5%A3%AB%E5%B1%B1&embed=true",
  "externalLinks": {
    "googleMaps": "https://www.google.com/maps?q=35.360556,138.727778",
    "openStreetMap": "https://www.openstreetmap.org/?mlat=35.360556&mlon=138.727778#map=15/35.360556/138.727778",
    "gsiMaps": "https://maps.gsi.go.jp/#15/35.360556/138.727778/"
  },
  "nearby": [
    {
      "kind": "sota",
      "code": "JA/YN-001",
      "name": "Mt.Fuji",
      "nameJ": "富士山",
      "latitude": 35.360556,
      "longitude": 138.727778,
      "distanceM": 0,
      "altM": 3776,
      "points": 10,
      "location": "静岡県富士宮市"
    }
  ]
}

管理コンソール（admin/）のSOTA/POTAリファレンス編集画面には、 編集中の座標を地図で開く「🗺 地図で位置を確認」ボタンを追加しています。

🔧 設定項目

環境変数

変数名	説明	デフォルト
DATABASE_URL	データベースURL	sqlite:sotaapp2.db
CF_ACCESS_TEAM_DOMAIN / CF_ACCESS_AUD	Cloudflare Access のチームのドメインとアプリの識別子(両方そろうと管理画面の署名を検証)	-
HOST	バインドホスト	0.0.0.0
PORT	ポート番号	8080
LOG_LEVEL	ログレベル	info

詳細はdocker-compose.yaml参照。

🧪 テスト

ユニットテスト

# 全テスト実行
makers test

# CI用テスト（fmt-check + clippy-strict + test）
makers ci

Docker E2Eテスト

Dockerイメージに対する包括的なE2Eテストを実行します。

# Dockerイメージをビルドしてテスト実行
makers e2e

# 既存イメージでテストのみ実行
makers e2e-test jl1nie/sotaapp2:latest

# テストサーバー起動（手動確認用）
makers e2e-server
makers e2e-stop

E2Eテストは以下の4フェーズで構成されています：

フェーズ	テスト内容
BUILD	実行ファイル・migrations・staticの存在確認
RUNTIME	SSL/TLS接続・ca-certificates・libssl確認
APP	CLIコマンド（help, migrate等）の動作確認
SERVER/API	サーバー起動・ヘルスチェック・主要APIエンドポイント

詳細は docs/docker-e2e-test-plan.md を参照。

CI/CD

GitHub Actionsで以下が自動実行されます：

• CI Pipeline: fmt, clippy, ユニットテスト
• Build Release: リリースビルド
• Docker Build & E2E Test: Dockerビルド・E2Eテスト

🚀 デプロイ

詳細は docs/deployment-manual.md を参照。

Fly.ioデプロイ

# 通常デプロイ（バックアップ付き）
makers deploy

# バックアップなしデプロイ
makers deploy-no-backup

# Fly.io直接デプロイ
makers fly-deploy

データベース管理

# バックアップ作成
makers fly-backup

# バックアップ一覧
makers fly-db-list

# リストア
makers fly-db-restore /data/backup_YYYYMMDD_HHMMSS.db

# 最適化
makers fly-db-optimize

本番環境設定

• データベース: SQLite（永続ボリューム）
• メモリ: 256MB
• CPU: shared-1x

🤝 コントリビューション

詳しい開発フローは Repository Guidelines を参照してください。

1. Issueまたは機能提案作成
2. フィーチャーブランチ作成
3. 変更実装（テスト含む）
4. プルリクエスト作成

プルリクエストチェックリスト

• テスト追加・更新
• ドキュメント更新
• Lintエラー解消
• APIエンドポイント変更の場合、OpenAPI更新

📄 ライセンス

本プロジェクトは Apache License 2.0 の下で公開されています。

Copyright 2024-2026 Minoru Tomobe (JL1NIE)

📞 サポート

• 📧 Issue: GitHub Issues
• 💬 ディスカッション: GitHub Discussions

---

Happy Coding! 73! 🎯📡