Skip to content

README.md

Latest commit

 

History

History
86 lines (64 loc) · 9 KB

README.md

File metadata and controls

86 lines (64 loc) · 9 KB
Raw

Code Match Android

Android版Code Matchの独立Gradleプロジェクトです。iOS版と同じ照合契約を、Android標準の操作とJetpack Compose / Material 3で実装します。Android版はストアへ提出せず、手元でreleaseビルドしたAPKを自分の端末へ入れて使う運用です。releaseはカメラ入力に加えて公式Inateck Android SDKによるBLE読取を同梱し、debugはFake scannerを使います。

開発環境

  • Android Gradle Plugin 9.3.2
  • Gradle 9.5.0（Wrapperで固定）
  • Android SDK 37（compile / target）
  • Android 12（API 31）以上
  • JDK 21（ソース／バイトコードの互換性はJava 17）

AGP 9のbuilt-in Kotlinを使うため、Androidモジュールへkotlin-androidプラグインは追加しません。Composeを使うモジュールだけCompose Compiler Gradle pluginを適用します。

モジュール

app/                  # Hilt統合、Material 3 navigation、Android system bridge
core/model/           # framework-free domain model（Android library境界）
core/matching/        # parser / matcher（fixture parity）
core/designsystem/    # Code MatchのMaterial 3 tokensとtheme
core/data/            # Room履歴とPreferences DataStore設定
core/export/          # 日英PDF生成、保存・共有用export
feature/scan/         # 照合状態機械とstateless Compose UI
feature/history/      # 履歴一覧・詳細のadaptive Compose UI
feature/settings/     # scanner、auto-advance、音、言語の設定UI
scanner/api/          # カメラ/BLEから独立したscanner契約
scanner/camera/       # CameraX + bundled ML Kit（QR / Code 128）
scanner/fake/         # 開発用Fakeの隔離先（debug専用）
scanner/ble/          # SDK/UUID非依存のBLE安全コア（release未接続）
scanner/inateck/      # 公式SDK adapter（release専用、binaryはローカル取得）

core/modelとcore/matchingの本体ロジックはAndroid APIに依存しません。共通fixtureは../shared/test-fixturesをテストリソースとしてクラスパスへ追加し、テストからはClassLoader.getResourceAsStreamで読み込みます。アプリアイコンは通常・round・adaptive・monochromeを持ち、Android 13以降のper-app languageにも日本語と英語を公開します。

ビルドとテスト

./gradlew assembleDebug
./gradlew lintDebug testDebugUnitTest
bash scripts/run-connected-tests.sh
./gradlew :app:assembleRelease
mkdir -p tmp
./gradlew :app:dependencies --configuration releaseRuntimeClasspath > tmp/release-dependencies.txt
bash scripts/verify-release-hardening.sh --dependency-report tmp/release-dependencies.txt

公式Inateck SDKのbinaryは固定commitから取得してchecksumを検証し、Git管理外のscanner/inateck/libsとjniLibsへ置きます（再配付ライセンスがないため、Gitやreleaseの成果物へは含めず、手元利用に限ります）。releaseはこのbinaryがないとビルドできません。

bash scripts/setup-inateck-sdk.sh
./gradlew :app:assembleRelease
bash scripts/verify-release-hardening.sh        # 権限・backup除外・FileProvider・Fake/analytics不在・ABI・vendorログ除去・ML Kit registrarの検査
adb install -r app/build/outputs/apk/release/app-release.apk

releaseは既定でdebug keystoreで署名するため、再ビルドしてもそのまま上書きインストールできます。自分のkeystoreで署名する場合は ~/.gradle/gradle.properties などに codematchReleaseStoreFile / codematchReleaseStorePassword / codematchReleaseKeyAlias / codematchReleaseKeyPassword を設定します（keystoreはGit管理外に置く）。releaseはR8でminifyし、SDKのLog/System.out呼び出しを除去し、ABIはSDKに合わせてarm64-v8aだけです。SDKのlibscanner_cmd.so / libinateck_scanner_cmd.soは4KB page alignmentのため、16KB page sizeの端末では動作しません（Pixel 7は4KB）。

Release検証は、まず./gradlew :app:dependencies --configuration releaseRuntimeClasspathで解決済み依存グラフを出力し、その後 生成したAPKとproduction sourceを検査します。ネットワーク／Nearby権限、debug/Fake入口、広すぎる FileProvider、カメラ画像/frameの保存や不意のpayload書き出し、analytics/crash SDKの依存を検出した時は失敗します。 Room、Preferences DataStore、将来のBLE復旧／既知端末状態はcloud Auto Backupと device-to-device transferの両方から除外します。BLE snapshotとversion/profile付き既知端末identityは files/datastore/codematch-ble-symbology.preferences_pbだけを使い、scan payloadや設定値を既知端末envelopeへ含めません。PDF共有で FileProviderが公開するのは専用のcache/codematch-pdf/だけです。

checkerは依存ライブラリを追加せず、lockfile、SBOM、その他の生成物をリポジトリへ 作りません。Gradle dependency verificationとSBOM／ライセンス出力は、依存artifactの 供給元と署名ポリシーを固定してから別途導入します。現時点の再現可能なゲートは Gradle Wrapper validation、release依存グラフ検査、checkerによるAPK/source検査です。

日英リソースはAPKに常に同梱されます（AAB・言語splitは使いません）。キーの欠落はAndroid lintのMissingTranslationでlintDebugが失敗します。

エミュレーターは状態遷移とCompose UIの継続検証に使います。カメラの読み取り完了判定はPixelなどの実Android端末で行います。実端末で行う確認項目、証跡、未実施の扱いは 実機確認ランブック に従ってください。現時点では、このREADMEや自動テストの結果だけでQR/Code 128の実読取、focus、連続箱、BLE通信の成功を宣言しません。

GitHub ActionsのemulatorテストはPixel 7と同じAPI 36で実行し、android/**またはshared/**の変更時だけ動きます。compile/target SDK 37はbuild jobで保証します。

現在の検証境界

到達点と打ち切った確認項目は Android版の到達点 にまとめています。プライバシー・権限・backup・FileProviderの境界は Android版プライバシー境界 を正本とします。公式SDKの固定version、ABI、権限、rawログ対策、scan callbackの評価は Android BLE SDK評価メモ に記録しています。ライセンスが明示されていないためbinaryはGitへ含めず、生成したAPKも配付しません。

Fake scannerの境界

Fake scannerはscanner/fakeへ置き、appからはdebugImplementationだけで参照します。releaseImplementationやimplementationでは参照しないため、リリース依存グラフとAPKにFake入口を含めない構成です。CIのandroid-release-build jobがこの境界を確認します。

scanner/bleには、command直列化、timeout後の停止、完全設定snapshot、復元前Ready禁止、payload正規化と重複抑制を置いています。scanner/inateckは公式2.0.0 SDKのscan/connect/getSettingInfo/setSettingInfoと公式native通知parserをこの安全コアへ接続し、FF01の設定応答と分割scan通知を単一ルーターで分離します。releaseはBLUETOOTH_SCAN（neverForLocation）とBLUETOOTH_CONNECTだけを要求し、legacy Bluetooth・位置情報・広告・ネットワーク権限をtools:node="remove"で除外します（app/src/release/AndroidManifest.xml）。minified releaseはSDKのLog/System.out呼び出しを除去します。BLE診断は直近300件を保持し、設定画面の「接続診断」から共有シート（Quick Share・メール等）またはSAFの保存先へテキストとして書き出せます（段階名のみ、読取値は含まない）。BLE診断は直近300件を保持し、設定画面の「接続診断」から共有シート（Quick Share・メール等）またはSAFの保存先へテキストとして書き出せます（段階名のみ、読取値は含まない）。接続ごとに照明（lighting_lamp_control=2）を適用した後、読取チューニング（qrcode_read_more_codeなど多コード=0、read_inverse_colorなど反転=0、auto_close_mode=20＝赤光約4秒）をinventoryと比較し、差分がある項目だけを書いて再取得で確認します（name/flag対応表はdocs/ios/IMPLEMENTATION_GUIDE.md）。Pixel 7 / BCST-36ではQR→Code 128一致、背景復元、active session中のapp force-stop後の既知端末自動再接続・Ready復帰、手動切断・電源OFF後の再接続、release APKでの照合完了まで実機確認済みです。重複・連続箱・予期しない切断・scanner再起動・timeout・Samsung等の残るゲートは手元利用専用の方針（Issue #57）で打ち切りとし、一覧はdocs/android/STATUS.mdにあります。