kiyo561/voice_controlled_device
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e4d9cabd763ab2167aaa4cfddd770d6932c8bfa3
voice_controlled_device/docs/04_review_report.md
T

11 KiB
Raw Blame History

整合性・仕様検証レポート

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 画面へ安全にフォールバックすることを確認すること。
Reference in New Issue View Git Blame Copy Permalink