# Device Mapper Usage

This tool builds a cross-platform lookup index from `workspace/brands/*.md`.

## 1) Build index

```bash
python3 tools/device_mapper.py build
```

Output file: `dist/device_index.json`

## 2) Query from command line

```bash
python3 tools/device_mapper.py find --name 'iPhone14,5' --brand Apple
python3 tools/device_mapper.py find --name 'M2102J2SC' --brand Xiaomi
python3 tools/device_mapper.py find --name 'L55M5-AD' --brand Xiaomi
```

## 3) JSON structure

- `records`: normalized device records
  - `device_name`: standard marketing name
  - `brand`: normalized brand
  - `manufacturer_brand`: manufacturer-level brand
  - `market_brand`: market sub-brand
  - `device_type`: `phone | tablet | wear | tv | other`
  - `aliases`: all searchable aliases
- `lookup`: normalized alias -> candidate `record.id[]`
- `brand_aliases`: normalized brand aliases to filter by app-provided brand
- `brand_management`: brand governance metadata

## 4) App-side integration

1. Load `dist/device_index.json` into memory.
2. Normalize input `name` and optional `brand`.
3. Use `lookup[normalized_name]` to fetch candidate records.
4. Normalize brand via `brand_management`.
5. Filter records by normalized manufacturer or market brand when needed.
6. Return first candidate or all candidates.

Normalization rule:

- lower-case
- keep only `[0-9a-z\u4e00-\u9fff]`
- remove spaces, hyphens, underscores and punctuation

## 5) Device type mapping

Supported categories:

- `phone`
- `tablet`
- `wear`
- `tv`
- `other`