105 lines
11 KiB
Markdown
105 lines
11 KiB
Markdown
# 整合性・仕様検証レポート
|
|
|
|
## 1. 検証結果サマリ (PASS / FAIL / WARNING)
|
|
**判定**: **FAIL**
|
|
|
|
### 検証サマリ概要
|
|
改訂された仕様書 (`docs/02_specifications.md`) と詳細設計書 (`docs/03_hardware_design.md`)、および前回のレビューレポート (`docs/04_review_report.md`) の指摘事項に対する包括的な比較・検証を実施いたしました。
|
|
|
|
前回の指摘事項のうち「参照ドキュメント `docs/03_hardware_design.md` の存在」については設計書が作成されたことで解消されましたが、**Android 14における `FOREGROUND_SERVICE` のタイプおよび個別パーミッションの未宣言、Bluetoothメディアボタンによるバックグラウンド起動制限（Background Activity Launch restrictions）に対する回避設計の欠落、Gitea CI/CDのコンテナ実行モデルの未定義、APIエラーレスポンス・認証ヘッダー・通信タイムアウト等の未定義、URLエンコード処理の規定不足** などの重要課題が仕様書・設計書の両面で未解決のまま存続しています。
|
|
|
|
さらに、仕様書と設計書の詳細比較検証において、以下の致命的な技術的齟齬・設計欠落が新たに確認されました：
|
|
1. **核心機能である AI サーバー連携 (`NAVIGATE_AI`) コマンドおよびナビ連携モジュールの設計書における完全欠落**
|
|
2. **`ITextToSpeech.speak()` の戻り値シグネチャの直接的矛盾 (`Unit` vs `StateFlow<TtsStatus>`)**
|
|
3. **前処理コンバータ (`KanjiToNumberConverter`) の設計書における完全欠落**
|
|
4. **位置情報パーミッション (`ACCESS_FINE_LOCATION` / `ACCESS_COARSE_LOCATION`) および未読メッセージ読み上げサービス (`AppNotificationListenerService`) の `AndroidManifest.xml` からの脱落**
|
|
5. **対象 OS バージョンの不一致 (Min API Level 26 vs API Level 29)**
|
|
6. **エラー発生時 3秒自動復帰制御の設計書シーケンスにおける欠落**
|
|
|
|
以上の理由により、現時点での検証判定は **FAIL** といたします。開発（Coder）およびテスト（Tester）フェーズへの移行前に、仕様書・設計書の双方向における修正および技術整合性の確保が必須です。
|
|
|
|
---
|
|
|
|
## 2. 齟齬・不一致項目
|
|
|
|
### ① AI サーバー連携 (`NAVIGATE_AI`) コマンドおよびナビゲーション連携モジュールの設計書における完全欠落
|
|
- **仕様書**: 3.3.1 節で AI サーバー通信 API `POST /api/v1/navigate`（リクエスト/レスポンス）、3.3.3 表で `NAVIGATE_AI` コマンド (`.*(ナビ|行きたい|向かう|セット).*`)、3.4 節で NaviCon (`navicon://point...`) および Google Maps (`geo:...`) 連携を主軸機能として明記。
|
|
- **設計書**: `CommandId` Enum (2.2.2-2) に `NAVIGATE_AI` が存在せず、`DomainModule` (2.2.3)、`executor/` パッケージ、クラス図、API 通信クライアント (Retrofit/OkHttp 等) が**設計書から完全に欠落**している。
|
|
|
|
### ② `ITextToSpeech.speak()` メソッドシグネチャ・戻り値の不一致
|
|
- **仕様書**: 3.2.3 節にて「状態変化は `val status: StateFlow<TtsStatus>` に集約。`speak()` は `Unit` を返す」と明記。
|
|
- **設計書**: 2.2.2-1 節のコード定義で `fun speak(text: String, queueMode: Int = 0): StateFlow<TtsStatus>` と定義されており、戻り値型が仕様書と直接衝突している。
|
|
|
|
### ③ 漢数字コンバータ (`KanjiToNumberConverter`) の設計書における完全欠落
|
|
- **仕様書**: 3.3.2 節で正規表現パース前の事前変換処理として `KanjiToNumberConverter`（「三分」「7時」等の漢数字・全角数字をアラビア数字へ変換）を必須定義し、受入基準 (6.2) にテスト項目を指定。
|
|
- **設計書**: クラス図、Domain Layer インターフェース、`CommandParser.parse()` 実装例、`DomainModule` DI 構成、ディレクトリ構成のいずれにも `KanjiToNumberConverter` が存在しない。
|
|
|
|
### ④ 必須パーミッションおよび Service 宣言の `AndroidManifest.xml` における不一致・脱落
|
|
- **仕様書**: 2.2 節で `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`, `BIND_NOTIFICATION_LISTENER_SERVICE` を必須指定し、3.5 節で `AppNotificationListenerService` のマニフェスト定義を指定。
|
|
- **設計書**: 3.4 節 `AndroidManifest.xml` に位置情報パーミッション (`ACCESS_FINE_LOCATION` / `ACCESS_COARSE_LOCATION`) および `AppNotificationListenerService` / `BIND_NOTIFICATION_LISTENER_SERVICE` の宣言が脱落。一方で仕様書一覧にない `SCHEDULE_EXACT_ALARM` が設計書マニフェストに追加されている。
|
|
|
|
### ⑤ 対象 OS バージョン (Min SDK API Level) の不一致
|
|
- **仕様書**: 1.1 / 2.1 節で `Android OS 8.0+ (API Level 26 以上 / Target API Level 34)` と定義。
|
|
- **設計書**: 1.1-1 節で `Android 10.0+ (API Level 29 以上)` と記述されており、最小サポート OS バージョンの仕様が相違している。
|
|
|
|
### ⑥ エラー時 3秒自動復帰制御の設計書における欠落
|
|
- **仕様書**: 4.2 節で `VoiceAppState.Error` 遷移時に `delay(3000)` により 3秒後に自動 `Idle` 復帰すると明確に定義。
|
|
- **設計書**: 3.2 節のシーケンス図および動作説明で正常系フローのみが記載され、エラー時 3秒自動復帰タイマー制御の記述が欠落している。
|
|
|
|
### ⑦ ディレクトリ構造・CI/CD 構成定義の乖離
|
|
- **仕様書**: 5.1 節で `.gitea/workflows/build.yaml`, `docker/Dockerfile`, `docker/entrypoint.sh`, `docker-compose.yml` などの CI/CD・コンテナ構成をプロジェクトルート下に記載。
|
|
- **設計書**: 3.3 節で `voice_controlled_device/` ルート下のアプリコード構造のみを記載し、CI/CD や Docker 関連構成が完全に除外されている。
|
|
|
|
---
|
|
|
|
## 3. 仕様の未定義・検討不足項目
|
|
|
|
### ① Target SDK Version 34 (Android 14) における `FOREGROUND_SERVICE` タイプ・権限の未定義
|
|
- Android 14 (API Level 34) 必須の `android.permission.FOREGROUND_SERVICE` およびサービスタイプ (`foregroundServiceType="microphone|location"` 等)、個別の `FOREGROUND_SERVICE_MICROPHONE`, `FOREGROUND_SERVICE_LOCATION` 権限などの宣言が仕様書・設計書双方のマニフェストから脱落している。
|
|
|
|
### ② Bluetooth メディアボタンによるバックグラウンド起動制限 (Background Activity Launch restrictions) 対策の未設計
|
|
- 画面オフ・スリープ時に `ACTION_MEDIA_BUTTON` や `ACTION_VOICE_COMMAND` から直接 Activity を起動することは Android 10+ OS 制約上不可能である。バックグラウンド常駐 Service + `MediaSessionCompat` による音響受信およびフォアグラウンドサービス制御設計が仕様書・設計書ともに未具体化。
|
|
|
|
### ③ AI サーバー API 仕様における未定義事項
|
|
1. **エラーレスポンス JSON フォーマットの未定義**: 正常系 (`status: "success"`) のみの定義であり、エラー発生時 (`status: "error"`) の JSON 構造（エラーコード、理由メッセージ）が未定義。
|
|
2. **認証・セキュリティヘッダーの欠落**: `POST /api/v1/navigate` リクエストに API キーや Authorization トークンが規定されていない。
|
|
3. **通信タイムアウト & 再試行方針の未定義**: モバイル回線接続時の Connect/Read タイムアウト値および Exponential Backoff リトライ方針が規定されていない。
|
|
|
|
### ④ NaviCon URL スキームの URL エンコードおよびフォールバック条件の未定義
|
|
- `navicon://point?ll={latitude},{longitude}&title={name}` の `title` に対する `UTF-8` URLエンコード規定が未記載。
|
|
- NaviCon 未インストール時に Google Maps アプリ Intent を優先するのか Google Play への誘導を優先するかの判定順序・ロジックが未決定。
|
|
|
|
### ⑤ Gitea CI/CD 実行モデルの詳細定義不足
|
|
- `.gitea/workflows/build.yaml` の Runner タイプ (Docker Runner / Host Runner) やコンテナ環境の紐付け記述が不足しており、ローカル `docker-compose` 環境との完全一致性が担保されていない。
|
|
|
|
---
|
|
|
|
## 4. Coder / tester への引き継ぎ注意事項
|
|
|
|
### 4.1 Coder (開発担当者) への注意事項
|
|
1. **`ITextToSpeech.speak()` のインターフェース実装**:
|
|
- 仕様書の原則に従い、`speak()` の戻り値は `Unit` とし、状態管理は `StateFlow<TtsStatus>` のみで一元化すること。
|
|
2. **`NAVIGATE_AI` コマンド & ナビゲーション連携の実装**:
|
|
- `CommandId` に `NAVIGATE_AI` を追加し、`NavigateAiExecutor` および Retrofit/OkHttp による `POST /api/v1/navigate` 通信クライアント、NaviCon/Google Maps 連携 Intent ロジックを構築すること。
|
|
3. **漢数字コンバータ (`KanjiToNumberConverter`) の組み込み**:
|
|
- 正規表現パース処理の前に必ず `KanjiToNumberConverter` を割り当て、漢数字（「一」「二」「三分」「七時」等）および全角数字をアラビア数字へ変換してから `CommandParser` へ入力すること。
|
|
4. **`AndroidManifest.xml` 権限・サービス宣言の網羅**:
|
|
- 位置情報権限 (`ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`)、`BIND_NOTIFICATION_LISTENER_SERVICE` (および `AppNotificationListenerService`) を追加すること。
|
|
- Android 14 (API 34) 対策として `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_MICROPHONE`, `FOREGROUND_SERVICE_LOCATION` を宣言し、適切なサービスタイプを設定すること。
|
|
5. **エラー時 3秒自動復帰タイマーの実装**:
|
|
- `VoiceAppState.Error` 遷移時は `MainViewModel` 内で Coroutine `delay(3000)` を起動し、3秒後に `VoiceAppState.Idle` へ自動復帰させる制御を組み込むこと。
|
|
6. **URL エンコード処理**:
|
|
- NaviCon URL スキーム生成時、パラメータ `title` は必ず `URLEncoder.encode(title, "UTF-8")` 処理を行うこと。
|
|
|
|
### 4.2 Tester (テスト担当者) への注意事項
|
|
1. **漢数字前処理変換単体テスト (`KanjiToNumberConverterTest`)**:
|
|
- 「三分」「7時」「十五分」「百二十秒」等の漢数字・全角・アラビア数字混合パターンが正確にアラビア数字へ変換されるかをテストすること。
|
|
2. **コマンドパース単体テスト (`CommandParserTest`)**:
|
|
- `NAVIGATE_AI`（「〇〇に行きたい」「ナビ開始」等）を含め、全 7 種のコマンドパターンの抽出正確性をテストすること。
|
|
3. **ViewModel 状態遷移非同期テスト (`MainViewModelTest`)**:
|
|
- Turbine を活用し、`VoiceAppState.Error` へ遷移後、 precisely 3000ms 後に `VoiceAppState.Idle` へ自動復帰する非同期制御をテストすること。
|
|
4. **パーミッション拒否時の堅牢性テスト**:
|
|
- 位置情報権限 (`ACCESS_FINE_LOCATION`) やマイク権限 (`RECORD_AUDIO`) を拒否された状態でアプリおよび音声ナビリクエストがクラッシュせず、エラーメッセージを TTS 読み上げ／ダイアログ表示するか確認すること。
|
|
5. **NaviCon 未インストール端末でのフォールバックテスト**:
|
|
- NaviCon 非インストールの実機/エミュレータにて目的地設定を実行し、Google Maps または Google Play 画面へ安全にフォールバックすることを確認すること。
|