Android — konvence adresářů na telefonu (`AVAX/`)¶

Status: ZÁVAZNÉ (2026-06-08). Platí pro všechny AVAX Android aplikace. SSOT pro to, kam aplikace ukládají soubory na telefonu. Důvod: s rostoucím počtem apps by samostatné top-level složky (avaxhotline/, avaxs3/, …) dělaly v telefonu nepořádek. Jeden root AVAX/ to sjednotí.

0. Princip¶

Všechno, co AVAX appky na telefonu zapisují, leží pod jediným kořenem AVAX/. Žádná aplikace si NEdělá vlastní top-level složku v rootu úložiště.

1. Struktura¶

AVAX/                                  ← jediný viditelný root pro vše AVAX
├── aplikace/                          ← instalační soubory (APK) — spravuje AVAXs3 distribuce
│   ├── app-avaxs3/
│   │   └── app-avaxs3.apk
│   └── app-hotline-capture/
│       └── app-hotline-capture.apk
└── <slug>/                            ← per-app data/pracovní adresář (každá app svůj)
    ├── app-hotline-capture/           ← např. nahrávky <callId>.m4a + <callId>.json
    └── …

Pravidla¶

AVAX/aplikace/<slug>/<slug>.apk — instalační soubory. Stahuje sem AVAXs3 (feature „Aplikace", spec android-app-distribution.md). Každá app svůj podadresář <slug>/ → přehled i při mnoha aplikacích.
AVAX/<slug>/ — pracovní/datový adresář konkrétní aplikace. App si pod ním dělá co potřebuje (nahrávky, exporty, cache k zálohování).
<slug> = kanonický slug aplikace z AVAX katalogu (např. app-hotline-capture, app-avaxs3). Stejný slug jako v apps.slug / package mapping.
Nikdy top-level složka mimo AVAX/ (žádné /storage/emulated/0/avaxhotline/).

2. Base path + scoped storage¶

Kanonický base = Environment.getExternalStorageDirectory()/AVAX/ (viditelné v správci souborů, uživatel má pořádek).

Apps s MANAGE_EXTERNAL_STORAGE (all-files access) píší do AVAX/ napřímo.
Apps bez all-files access (scoped storage, Android 11+): použij Documents/AVAX/… přes MediaStore/SAF, nebo app-scoped Android/data/<pkg>/files/AVAX/<slug>/ když viditelnost není nutná.
Logická cesta AVAX/<…> je závazná, fyzický base se řeší per app dle potřebné viditelnosti/oprávnění.

3. Helper (doporučený vzor)¶

Každá app si drží jeden helper pro base, ať se cesta nešíří natvrdo:

object AvaxPaths {
    const val SLUG = "app-hotline-capture"
    fun root(): File = File(Environment.getExternalStorageDirectory(), "AVAX")
    fun appDir(): File = File(root(), SLUG).apply { mkdirs() }          // AVAX/<slug>/
    fun installerDir(slug: String) =                                    // AVAX/aplikace/<slug>/
        File(File(root(), "aplikace"), slug).apply { mkdirs() }
}

4. Migrace existujících apps¶

app-hotline-capture: Constants.CAPTURE_DIR z …/avaxhotline → AVAX/app-hotline-capture/. Jednorázový move starých souborů (best-effort) + nová cesta. Viz handoff.
app-avaxs3: stažené APK do AVAX/aplikace/<slug>/ (až bude „Aplikace" screen).

5. Související¶

docs/spec/android-app-distribution.md — §5 instalace ukládá APK do AVAX/aplikace/<slug>/.
docs/spec/avaxs3-sync.md — folder sync (zálohuje libovolné složky telefonu).
Skeleton: tools/avax-app-template/docs/ANDROID_DEVICE_LAYOUT.md (kopie pravidel pro vendory).

Android — konvence adresářů na telefonu (AVAX/)¶