# Android Resource Mapping Rules

This document defines how to build the Android resource inventory and the Android ↔ HarmonyOS mapping markdown written to `resource_mapping_path`.

## 1. Purpose

The standard conversion report explains what the pipeline did. The mapping markdown serves a different purpose: it is an audit-friendly document for humans who need to review Android resources, understand their role, identify likely source ownership, and inspect how each Android resource maps to HarmonyOS output.

The mapping markdown MUST be produced for every run.

---

## 2. Two Required Data Sets

Build and retain two parallel data sets throughout the pipeline.

### 2.1 Android Resource Inventory Records

One inventory record per Android resource item.

Required fields:
- `android_resource_path`
- `android_resource_name`
- `function`
- `screens`
- `source_category`
- `type_category`
- `status`
- `notes`

### 2.2 Android ↔ HarmonyOS Mapping Records

One mapping record per conversion outcome.

Required fields:
- `android_resource_path`
- `android_screens`
- `android_source_category`
- `android_type_category`
- `harmony_target`
- `mapping_kind`
- `notes`

A single Android resource may produce multiple mapping records.

---

## 3. Path Rules

### 3.1 File-Based Android Resources

Use the Android file path directly.

Examples:
- `app/src/main/res/drawable/home_login_btn.png`
- `app/src/main/res/mipmap-xxxhdpi/logo.png`
- `app/src/main/res/xml/file_paths.xml`
- `feature_home/src/main/res/drawable/bg_header.xml`

### 3.2 `values/*.xml` Resources

`values` resources MUST be recorded at entry granularity, not only file granularity.

Format:
- `file_path#tag/name`

Examples:
- `app/src/main/res/values/strings.xml#string/app_name`
- `app/src/main/res/values/colors.xml#color/primary`
- `app/src/main/res/values/dimens.xml#dimen/page_margin`
- `app/src/main/res/values/arrays.xml#string-array/province_names`
- `app/src/main/res/values/plurals.xml#plurals/items_count`

### 3.3 Android System Resources

Android framework resources do not have a project-local file path. Record the reference itself as the path.

Examples:
- `@android:color/white`
- `@android:dimen/app_icon_size`
- `@android:drawable/ic_menu_close`

### 3.4 Runtime Remote Resources

Remote resources are not Android `res/` files. Record them using code location plus the remote identifier when possible.

Examples:
- `app/src/main/java/com/example/home/HomeBanner.kt:88 -> https://...`
- `app/src/main/java/com/example/api/BannerDto.kt:35 -> remote_image_url`

If only the code location is known, record that and explain the limitation in `notes`.

---

## 4. Resource Name Rules

### 4.1 File Resources

Use the Android resource name without qualifiers or extension.

Examples:
- `drawable/home_login_btn.png` → `home_login_btn`
- `mipmap-anydpi-v26/ic_launcher.xml` → `ic_launcher`

### 4.2 `values` Resources

Use the XML entry's `name` attribute.

Examples:
- `<string name="app_name">` → `app_name`
- `<color name="primary">` → `primary`

### 4.3 System Resources

Use the framework resource name after the slash.

Examples:
- `@android:color/white` → `white`
- `@android:dimen/app_icon_size` → `app_icon_size`

---

## 5. Function Field Rules

The `function` field should be short, concrete, and useful to a reviewer.

Recommended inference priority:

1. **Explicit semantic name**
   - If the resource name clearly indicates its role, use that.
   - Examples:
     - `logo` → `App logo`
     - `ic_back` → `Back icon`
     - `home_header_bg` → `Home header background`

2. **Usage-site evidence**
   - If the resource is referenced from a known screen or component, use that context.
   - Examples:
     - `Login page close icon`
     - `Home tab selected background`

3. **Resource type evidence**
   - For XML drawables, infer from root element or role.
   - Examples:
     - `<shape>` → `Shape background`
     - `<selector>` → `State selector drawable`
     - `<layer-list>` → `Layered background`

4. **Directory-role evidence**
   - `mipmap` often means launcher or app icon resources.
   - `font` often means app font resource.
   - `xml` often means configuration resource.

5. **Conservative fallback**
   - If the exact role is uncertain, do not invent specifics.
   - Examples:
     - `Image resource (inferred from filename)`
     - `Color resource used by UI styling`
     - `Configuration XML resource`

If the function is inferred rather than certain, mention the evidence in `notes`.

---

## 6. Screen Attribution Rules

The `screens` field identifies which Android screen(s) use the resource.

This is a best-effort static analysis field. Use evidence; do not fabricate certainty.

### 6.1 Screen Candidates

Build the candidate screen set from:
- Activities
- Fragments
- Compose screen / page / route files
- Navigation graph destinations
- Launcher entry activity

### 6.2 Direct Reference Rule

If a screen file directly references:
- `R.drawable.xxx`
- `R.mipmap.xxx`
- `R.string.xxx`
- `R.color.xxx`
- `R.font.xxx`
- `R.xml.xxx`

then attribute the resource to that screen.

### 6.3 Layout-Indirection Rule

If:
- a screen uses a layout file, and
- that layout file references resources,

then attribute those resources to that screen.

### 6.4 Shared-Component Rule

If a shared component references a resource and that component is used by multiple screens:
- record all known screens, or
- use `Common` when the list is too broad to be helpful.

### 6.5 Global-App Rule

Use one of the following fixed labels where appropriate:
- `Launcher` — launcher icon, round icon, adaptive icon
- `Global` — app-wide theme or identity resource
- `Common` — shared across many screens
- `Unknown` — insufficient evidence

### 6.6 Output Format

The `screens` field may contain:
- a single screen, e.g. `HomeScreen`
- a comma-separated list, e.g. `HomeScreen, LoginScreen`
- one of the labels: `Launcher`, `Global`, `Common`, `Unknown`

---

## 7. Source Category Rules

The allowed source categories are:
- `应用自身资源`
- `项目内模块资源`
- `第三方库资源`
- `Android 系统资源`
- `运行时远程资源`

### 7.1 应用自身资源

Use when the resource is confirmed to come from the app module itself.

Typical evidence:
- path under `app/src/.../res`
- path under the main application module
- source `res/` fallback found it directly in the app module

### 7.2 项目内模块资源

Use when the resource comes from another local module in the same Android project.

Typical evidence:
- path under another local module such as `common/src/.../res`, `feature_xxx/src/.../res`
- local Gradle project dependency indicates the module belongs to the same repository

### 7.3 第三方库资源

Use when the resource likely comes from an external dependency.

Typical evidence:
- resource exists only in the decoded APK, not in project source modules
- resource prefix matches common library conventions such as `abc_*`, `mtrl_*`, `design_*`, `material_*`
- build dependencies indicate a matching library

If the category is inferred, say so in `notes`.

### 7.4 Android 系统资源

Use when the reference starts with `@android:`.

### 7.5 运行时远程资源

Use when the asset is not packaged in `res/` and is instead fetched or constructed at runtime.

Typical evidence:
- URL-based image loading
- server-driven icon/image fields
- WebView / HTML / remote content assets

---

## 8. Type Category Rules

The primary required categories are:
- `drawable`
- `mipmap`
- `layout`
- `values`
- `xml`
- `font`

For required rows that do not originate from a concrete Android resource directory — such as runtime remote resources, resolved Android system references, and placeholder outputs created only to satisfy HarmonyOS references — normalize them into the closest review-friendly category instead of inventing a new top-level type category. In practice:
- value-like references (`string`, `color`, `dimen`, `integer`, `bool`, `array`, `plurals`) should use `values`
- runtime remote resources should use `xml` unless there is stronger evidence they behave like media assets
- placeholder media outputs should use `drawable`

### 8.1 Normalization Rule

For qualified directories such as `drawable-hdpi`, `mipmap-anydpi-v26`, `values-zh-rCN`, strip qualifiers and record the base type.

Examples:
- `drawable-hdpi` → `drawable`
- `mipmap-anydpi-v26` → `mipmap`
- `values-night` → `values`

### 8.2 `values` Rule

Even though `values/*.xml` entries have different subtypes (`string`, `color`, `dimen`, etc.), the required `type_category` remains `values`.

### 8.3 Other Android Types

If the original Android type is not one of the six required categories (`raw`, `menu`, `anim`, `animator`, `color`, etc.), do NOT mislabel it. Use:
- the closest required category only if it is truly correct, otherwise
- keep the row in scope and explain the original Android type in `notes`

Recommended fallback in `notes`:
- `Original Android type: raw`
- `Original Android type: menu`

### 8.4 Lottie Animation Special Case

Lottie JSON files live under Android `assets/` (passthrough) or `res/raw/` (raw type). Both normalize to HarmonyOS `rawfile/`. Record them with `type_category = raw` and identify the Lottie subtype in `notes` (`Lottie animation JSON`). Do NOT invent a new top-level `lottie` type category.

For each Lottie row:
- `source_category` follows the normal rules. Local Lottie under app/module `assets/` or `res/raw/` → `应用自身资源` or `项目内模块资源`. Runtime URL (`lottie_url` or code loading a `Uri`) → `运行时远程资源`.
- `screens` MUST identify the Activity/Fragment that plays the animation, using the evidence sources listed in `references/lottie-conversion-rules.md` (XML host layout → hosting Activity/Fragment, factory-call enclosing class, or picker navigation target). The `Screens` value is the Android host; the proposed HarmonyOS page name goes into `notes` as `page=<PageName>` (or into an optional `Suggested HarmonyOS Page` column if the mapping template exposes one).
- `function` should describe the animation's role, e.g. `Refresh loading animation`, `Splash intro animation`, `Wave background animation`.

See `references/lottie-conversion-rules.md` for the complete Lottie handling rules.

---

## 9. Mapping Kind Rules

Suggested `mapping_kind` values:
- `direct copy`
- `rename`
- `svg conversion`
- `layered-image conversion`
- `generated media`
- `merged into json`
- `lottie migration` — Lottie JSON copied from Android `assets/` or `res/raw/` to `rawfile/lottie/<normalized>.json`. Use in place of plain `direct copy` for Lottie assets so the row is easy to filter.
- `unmappable`
- `fallback applied`
- `placeholder created`
- `system resource resolved`
- `remote resource (no local target)`

Use the simplest accurate label.

---

## 10. One-to-One, One-to-Many, and Many-to-One Handling

### 10.1 One-to-One

Example:
- `res/drawable/home_login_btn.png` → `entry/src/main/resources/base/media/home_login_btn.png`

Emit one mapping row.

### 10.2 One-to-Many

Example: adaptive icon XML may produce:
- layered-image JSON
- generated solid-color PNG background

Emit multiple mapping rows that share the same Android resource path.

### 10.3 Many-to-One

Example: multiple Android `values` files merge into one Harmony JSON file.

Still emit one mapping row per Android source entry.

Examples:
- `res/values/strings.xml#string/app_name` → `resources/base/element/string.json#app_name`
- `res/values/app_strings.xml#string/login_title` → `resources/base/element/string.json#login_title`

### 10.4 No Harmony Target

When there is no valid Harmony target, use:
- `harmony_target = N/A`

And explain the reason in `notes`.

Examples:
- layout XML has no direct ArkUI equivalent
- remote resource is runtime-only
- unresolved third-party resource had no extracted target

---

## 11. Required Markdown Output Structure

The markdown written to `resource_mapping_path` MUST contain the following sections.

### 11.1 Title

```md
# Android Resources ↔ HarmonyOS Resources Mapping
```

### 11.2 Metadata

Include bullets for:
- `android_project_dir` (Android project path)
- `harmony_project_dir` (HarmonyOS project output path)
- Resource source
- Resource source path
- Decode result
- Generation timestamp

### 11.3 Android Resource Inventory

Use a markdown table with at least these columns:
- `Android Resource Path`
- `Resource Name`
- `Function`
- `Screen(s)`
- `Source Category`
- `Type Category`
- `Status`
- `Notes`

### 11.4 Android → HarmonyOS Mapping Details

Use a markdown table with at least these columns:
- `Android Resource Path`
- `Android Screen(s)`
- `Android Source Category`
- `Android Type Category`
- `HarmonyOS Target`
- `Mapping Kind`
- `Notes`

Every mapping row MUST include the Android-side screen/source/type fields.

### 11.5 Unmapped / Unmappable / System / Remote Summary

Include a compact summary table or grouped bullets covering:
- resources with no direct HarmonyOS equivalent
- Android framework resources
- library-only resources inferred from dependencies or APK
- runtime remote resources

### 11.5.1 Lottie Animation Table

If the project contains any Lottie animation JSONs (identified by structure signature per `references/lottie-conversion-rules.md`), include a dedicated table listing every detected animation. Required columns:

- `Android Source` — full path (e.g., `assets/AndroidWave.json`, `res/raw/lottielogo.json`, or `(remote) https://...`)
- `Target Rawfile Path` — `rawfile/lottie/<normalized>.json` or `N/A`
- `Host Activity/Fragment` — the Android class that plays the animation (or `Global` / `Launcher` / `Unknown`)
- `Host Layout / Loader` — the layout XML with `lottie_fileName` / `lottie_rawRes`, or the Kotlin/Java call site
- `Suggested HarmonyOS Page` — proposed ArkUI page name (e.g., `PlayerPage`)
- `Notes` — rename records, collision disambiguation, remote URL, or "no static references found"

This is the audit surface used by the HarmonyOS developer to wire `@ohos/lottie` calls to the correct pages. Never omit a detected Lottie asset from this table.

### 11.6 Quick Findings

Provide short bullets highlighting review-relevant findings, such as:
- launcher icons coming from `mipmap`
- probable third-party library assets such as `abc_*` / `mtrl_*`
- resources found only in the decoded APK
- likely causes of icon or logo mismatches

---

## 12. Required Fallback Labels

Never leave required fields blank.

Use these fallback values where necessary:
- `screens` → `Unknown`
- `source_category` → best-evidence category; if still unclear, use `第三方库资源（推断）` or explain uncertainty in `notes`
- `type_category` → base Android type if valid, otherwise use the closest valid category only if correct and explain the original type in `notes`
- `harmony_target` → `N/A`
- `function` → conservative descriptive fallback

---

## 13. Hard Requirements

- Never silently omit an Android resource that the pipeline observed.
- `values` resources must be recorded at entry granularity.
- Mapping rows must preserve Android-side screen/source/type metadata.
- Unmappable, library-only, system, and remote resources must still appear in the mapping markdown.
- If a judgment is inferred rather than proven, say so in `notes`.