gt-agent-company/openspec/changes/add-agent-distribution-code/design.md

Context

The Uni-app frontend already obtains the authenticated user through GET /api/auth/me. That user includes user_type and shop_id; GET /api/admin/shops/{shop_id} returns the shop's distribution_code. The home page currently has an agent-only “提现管理” shortcut, and src/static/icons/分销码.png is present as an untracked user-supplied asset.

Goals / Non-Goals

• Goals: expose a role-restricted shortcut after withdrawal management and show the current shop's distribution code as a scannable QR code.
• Non-Goals: change backend contracts, generate or rotate distribution codes, or expose another shop's code.

Decisions

• Use the current authenticated user's shop_id from /api/auth/me; do not hardcode a shop ID or accept one from the page URL.
• Fetch the shop record through a typed shop-detail API method and encode the returned distribution_code value itself in the QR code.
• Generate/render the QR code locally with a Uni-app-compatible solution. Do not send distribution codes to a remote QR-generation service.
• Add a dedicated page, use the supplied icon for the home shortcut, and re-check the current user type on the page so direct navigation does not bypass the agent-only UI.
• Show a clear unavailable/error state when the account has no shop_id, the shop response has no distribution code, or the request fails.

Risks / Trade-offs

• QR rendering APIs differ across Uni-app targets. Select a local renderer compatible with the project's supported H5 and mini-program builds and verify it in the target runtime.
• The supplied icon is currently untracked; implementation must preserve and use it without replacing or deleting it.