zhangjianjun
/
corp-mp
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
corp-mp/docs/a5-integration.md

3.4 KiB
Raw Blame History

A5 Map Label Integration

Launch Contract

pages/a5/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.
  • 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=http://ag-test.batiao8.com
  • Production: TARO_APP_API_A5=http://ag.batiao8.com

HTTP is configured as requested for regular requests. File uploads always use HTTPS on the same A5 host because WeChat uploadFile requires it. Before a WeChat release, verify the HTTPS gateway and certificate and update the environment value for all requests. Configure request/upload/download legal domains, including returned file CDN domains. HTTP is not a release-ready WeChat endpoint.

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/a5/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. Revisit the original index to verify it still uses the corp service.

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