device-voice-h5/openspec/changes/update-phone-bind-association-flow/proposal.md

Why

The August 2026 customer API document (docs/产品迭代8月份/11.md) freezes the customer-side authentication contracts used by H5. The behavioral contract changes are:

• need_bind_phone widens to a three-state decision: no main phone, or main phone exists but the current asset is unassociated -> true; already associated -> false; global switch off -> always false. The frontend still uses it only to decide whether to guide the user into phone verification.
• POST /api/c/v1/auth/bind-phone becomes idempotent: when the account already has a main phone, submitting the same main phone plus a valid code creates the association instead of rejecting it.
• POST /api/c/v1/auth/change-phone migrates all valid phone-asset associations in one transaction and rolls back the whole operation on the 10-asset limit or an existing same-asset relation.

The current H5 bind page starts with an empty phone input and has no prefill. Existing users who have a main phone but whose current asset is unassociated are guided to verify, yet every submitted number is rejected - a deadlock. Homepage-gate and login routing must also follow the widened need_bind_phone semantics instead of raw bound-phone presence.

What Changes

• Bind page prefills the phone input with the account main phone from GET /api/c/v1/asset/info -> bound_phone and allows sending a bind_phone verification code to that number
• Bind submission treats bind-phone as idempotent for the account main phone; other numbers show the backend msg and keep the user on the page
• Keep the existing bind-completion flow: ordinary entry returns back, mandatory login-gate entry triggers the manual re-login flow
• change-phone keeps the old/new phone and verification-code inputs with the change_phone_old / change_phone_new send-code scenes; failures show backend rollback copy (10-item limit and same-asset conflict) and keep the user on the page
• Login and homepage entry keep need_bind_phone as the only phone-verification guide signal and follow the three-state semantic
• send-code request/response stays unchanged (cooldown_seconds); the new verify-asset fields miniapp_app_id / oa_app_id are a backend confirm item, not consumed yet

Capabilities

New Capabilities

• phone-bind-association-prefill: Define bind-page prefill of the account main phone and idempotent bind submission behavior
• phone-change-migration: Define change-phone transaction-migration behavior and backend rollback copy display

Modified Capabilities

• index-phone-bind-gate: Widen the bind-phone gate to the three-state need_bind_phone semantic

Impact

• Affected code: pages/bind/bind.vue, pages/change-phone/change-phone.vue, pages/index/index.vue, pages/login/login.vue
• API module: api/modules/auth.js unchanged - endpoints and response shapes already match 11.md
• Backend contract deltas (per 11.md): bind-phone idempotency, change-phone transactional migration, three-state need_bind_phone
• Backend decisions (confirmed 2026-09-15):
  • need_bind_phone stays wechat-login-only; asset/info and verify-asset do not add the field. The homepage gate keeps evaluating the per-entry association state via asset/info.bound_phone.
  • No new prefill field: bind-page prefill keeps using asset/info.bound_phone.
  • verify-asset's new miniapp_app_id / oa_app_id are not consumed; H5 login keeps using /api/c/v1/wechat/appid, and /api/c/v1/auth/wechat-login remains the login authority.