@buaa_smat/hometrans 0.1.0 → 0.1.2

package/skills/hmos-resources-convert/references/resource-mapping-rules.md

@@ -0,0 +1,457 @@
+# 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 decompiled 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`
+
+---
+
+## 9. Mapping Kind Rules
+
+Suggested `mapping_kind` values:
+- `direct copy`
+- `rename`
+- `svg conversion`
+- `layered-image conversion`
+- `generated media`
+- `merged into json`
+- `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 path
+- HarmonyOS project output path
+- Resource source
+- Resource source path
+- Build 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.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 decompiled 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`.