# A5 Map Label Integration

## Launch Contract

`pages/index/index?phone=13800138000&link_id=42`

- `phone`: auto-query phone; manual query remains available without it.
- `link_id`: A5 link ID for configuration, business documents and completion files. Defaults to `2x6` when neither `link_id` / `linkId` nor a valid `/h/<id>` scene supplies a link ID.
- Legacy `/h/<id>` scenes and URL Link encoded separators are accepted.
- No corp token, host, package or default short link is used by A5.
- agent-h5 resolves the link from `agentLink.linkId`, `linkId`, then `/h/<id>`.

## Environments

- Development: `TARO_APP_API_A5=https://ag-test.batiao8.com`
- Production: `TARO_APP_API_A5=https://ag.batiao8.com`
- Map reverse geocoding: `TARO_APP_TIANDITU_KEY`.

Requests and uploads use HTTPS. Configure request/upload/download legal domains, including returned file CDN domains and `api.tianditu.gov.cn`. The former corp API origin and x-host environment variables have been removed.

## API Contract

- `GET /h5/link?id=<link_id>`: link configuration and customer service.
- `GET /h5/order?phone=...&page=1&size=20&status=2`: paid orders, filtered to map_label. This follows the H5 first-20 query behavior.
- `PUT /h5/order`: `{ id, biz_info: JSON.stringify(...) }`.
- `GET/POST /h5/file`: `link_id`, `LinkId`, `scene`, `scene_id`; uploads use multipart field `file`.
- `DELETE /h5/file?id=...`: delete a document.
- Business scenes: license `order_biz1`, storefront `order_biz2`, identity `order_biz3`.
- Storefront uploads carry `extra.loc` (front/left/right labels in Chinese).
- Completion scenes: `order_process_gd`, `order_process_bd`, `order_process_tx`.
- Complaint: `POST /api/user/feedback`, matching agent-h5's declared API contract. This route was not found in the local agent-api router. Per the requested temporary UI behavior, only HTTP 404 for this POST is treated as success so the page shows its normal success message and returns. No feedback is persisted in that case. Other HTTP, business and network failures still surface. Remove this fallback when the endpoint is available.

The H5 development proxy removes its `/api` prefix. Mini-program business requests therefore use `/h5/...` directly, without corp signing, token bootstrapping or presigned Qiniu upload.

## Image Upload

WeChat uses `chooseMedia` with `mediaType: ['image']`; other targets retain `chooseImage`. Picking/uploading a photo does not require the page agreement checkbox. Platform privacy authorization still applies, and submitting the completed form still requires agreement. Cancelling the picker does not display an error. Native upload failures retain actionable error information; failed uploads do not offer the unrelated document reload action.

## Verification

- `pnpm test`
- `pnpm build:weapp`
- In agent-h5: `pnpm exec vitest run src/utils/weixinMiniProgram.test.ts src/ui/map_label/utils/miniProgramEntry.test.ts`
- In agent-h5: `pnpm build`

Open the mini-program project in WeChat DevTools, using `dist` as the mini-program root. Set the compile page to `pages/index/index` and use an authorized test phone and matching A5 link ID. Check auto-query, pending-submission status, three required storefront slots, optional license/identity slots, example previews, map return, deletion, resubmission refresh, platform screenshots, PDF opening and complaints.

A5 is the only business flow. Resubmission and complaints use `pages/resubmit/index` and `pages/complaint/index`; map selection and agreements remain shared pages. The former `pages/a5/*` routes have been removed, so external entry links must use `pages/index/index`.

No real customer orders were submitted or modified during implementation verification.