# Auth Identity Payment Foundation Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Rebuild the auth identity, profile binding, payment routing, and OpenAI advanced scheduler foundation on top of a clean `origin/main` branch while preserving historical compatibility for existing email users and historical LinuxDo users.
**Architecture:** A unified identity foundation centered on durable provider subjects (`email`, `linuxdo`, `oidc`, `wechat`) and transactional pending-auth sessions; backend-owned payment source routing behind stable frontend methods (`alipay`, `wxpay`); compatibility-first migration/backfill before feature enablement.
- [ ] Preserve login continuity for existing email users and historical LinuxDo users.
- [ ] During migration, backfill historical LinuxDo synthetic-email users into explicit LinuxDo identities before first post-upgrade login.
- [ ] Keep existing email login and add third-party login/bind for `linuxdo`, `oidc`, and `wechat`.
- [ ] On first third-party login:
- identity exists: direct login.
- identity does not exist: start pending-auth flow.
- local email binding is required only when system config says so.
- upstream provider email verification never counts as local email verification.
- [ ] When user-entered and locally verified email already exists:
- offer bind-existing-account after local re-authentication.
- offer change-email-and-create-new-account.
- when email binding is mandatory, do not allow bypass without changing to another email.
- [ ] On first third-party login or first third-party bind, provider nickname/avatar must be presented as independent replace options for the current nickname and avatar. They are not auto-applied.
- [ ] Source-specific initial grants must support per-source defaults for balance, concurrency, and subscriptions.
- [ ] Default grant timing: on successful new-account creation.
- [ ] Optional grant timing: on first successful bind for the configured source.
- [ ] Migration/backfill must never trigger first-bind or first-signup grants retroactively.
- [ ] Avatar profile supports:
- direct URL storage.
- image data URL upload compressed to `<=100KB` before storing in DB.
- explicit delete.
- [ ] Admin user management must expose and sort by `last_login_at` and `last_active_at`.
- [ ] WeChat login rules:
- WeChat environment uses MP login.
- non-WeChat browser uses Open/QR login.
- canonical identity uses `unionid`.
- when `unionid` is unavailable, fail the login/bind flow under the approved option-1 policy.
- [ ] Payment UI rules:
- user-facing methods stay `支付宝` and `微信支付`.
- backend decides whether each method routes to official provider instance or EasyPay.
- at runtime, each visible method may only have one active source.
- [ ] Alipay rules:
- PC: in-page QR.
- mobile browser: jump to Alipay payment.
- [ ] WeChat Pay rules:
- PC: in-page QR.
- WeChat H5: MP/JSAPI first, fallback to H5 pay.
- non-WeChat H5: H5 pay, or prompt to open in WeChat when unavailable.
- [ ] Payment success pages are informational only; actual fulfillment depends on webhook or server-side reconciliation.
- [ ] OpenAI advanced scheduler is available but default-disabled.
## Hard Technical Constraints From Audit
- [ ] Browser-based third-party auth must use Authorization Code + PKCE `S256`.
- [ ] OIDC identity primary key must be `(issuer, subject)`, not email.
- [ ] Email equality must never auto-link accounts.
- [ ] Bind-existing-account must require explicit local re-authentication and TOTP verification when enabled.
- [ ] OAuth redirect URI must be fixed server config, exact-match, and never derived from user input.
- [ ] User-supplied redirect may only choose a normalized same-origin internal route after completion.
- [ ] WeChat canonical identity must be `unionid`; `openid` remains channel/app-scoped support data only.
- [ ] Every payment order must snapshot the selected provider instance and reuse that exact instance for callback verification, reconciliation, refund, and audit.
- [ ] Frontend must not receive first-party bearer tokens through callback URL fragments in the rebuilt flow.
- [ ] Public payment result polling must not expose order data by raw `out_trade_no` alone; use authenticated lookup or signed opaque result token.
## Baseline Notes
- [ ] Current clean branch head when this plan was written: `721d7ab3`.
- [ ] Baseline backend verification on clean `origin/main`: `cd backend && go test ./...` passes.
- [ ] Baseline frontend verification on clean `origin/main`: `cd frontend && pnpm test:run` currently fails in unrelated existing suites. New work must add targeted tests and avoid claiming full frontend green until those baseline failures are addressed separately.
- [ ] Existing migration directory currently ends at `107_*`; this rebuild reserves `108` through `111`.
- grant-tracking columns/tables required to prevent double-award
- [ ] Add uniqueness/index rules:
- one canonical identity per `(provider, provider_subject)`
- one channel record per `(provider, provider_channel, provider_app_id, provider_channel_subject)`
- one adoption decision per pending session
- [ ] Preserve null-safe compatibility defaults so historical rows remain readable before backfill finishes.
- [ ] Add explicit rollback blocks only where safe; never repeat the destructive pattern observed in old `112_update_pending_auth_sessions.sql`.
### Task 2. Materialize historical identities before runtime
- [ ] Implement `backend/migrations/109_auth_identity_compat_backfill.sql` to backfill:
- existing email users into `auth_identities(provider=email, provider_subject=normalized_email)`
- historical LinuxDo users into `auth_identities(provider=linuxdo, provider_subject=linuxdo_subject)`
- historical synthetic-email LinuxDo users into explicit LinuxDo identity rows by parsing legacy email mode and legacy provider metadata
- profile/channel rows from historical `user_external_identities`-style data when present in upgraded databases
- [ ] Write migration report output in `backend/internal/repository/auth_identity_migration_report.go` so production can inspect unmatched rows instead of silently skipping them.
- [ ] Set `signup_source` and provider provenance when recoverable from historical data. Do not flatten everything to `email`.
### Task 3. Provider default grant and scheduler config migration
git commit -m"feat: add auth identity foundation schema"
```
## Phase 2: Backend Identity Flow Rebuild
### Task 5. Build a single repository contract for identity lookups and grants
- [ ] Implement `backend/internal/repository/user_profile_identity_repo.go` with transactional helpers for:
- get user by canonical identity
- get user by channel identity
- create canonical + channel identity together
- bind identity to existing user after verified re-auth
- record one-time provider grant award
- record adoption preference decisions
- update `last_login_at` and `last_active_at`
- [ ] Add repository contract coverage in `backend/internal/repository/user_profile_identity_repo_contract_test.go`.
- [ ] Enforce dual-write for email registration/login so `users.email` and `auth_identities(provider=email, ...)` stay consistent from this phase onward.
### Task 6. Rebuild transactional pending-auth service
- [ ] Implement `backend/internal/service/auth_pending_identity_service.go` and tests to own these flows:
- create pending session from third-party callback
- verify local email code
- create new account from pending session with correct `signup_source`
- bind pending identity to existing account after password/TOTP re-auth
- apply configured provider defaults on the correct trigger only once
- store provider nickname/avatar candidates and user opt-in replacement decisions independently
- [ ] Keep pending session payload normalized:
- provider identity fields live in typed columns/JSON structure
- avoid the old branch’s mixed `metadata` and `upstream_identity_payload` ambiguity
- [ ] Do not call plain email registration helpers from this flow. The old feature branch bug where pending third-party signup fell back to `RegisterWithVerification` must not reappear.
### Task 7. Rebuild provider callback adapters
- [ ] Refactor these handlers to thin adapters over the shared pending-auth service:
- persist channel identity by `(channel, appid, openid)`
- persist canonical identity by `unionid`
- hard-fail when `unionid` is absent under the approved product policy
- [ ] Replace callback URL fragment token delivery with backend session completion or one-time exchange code consumed by `frontend/src/stores/auth.ts`.
### Task 8. Rebuild auth endpoints and profile binding endpoints
- [ ] Harden `frontend/src/views/user/PaymentResultView.vue` and `frontend/src/api/payment.ts` so result polling uses an authenticated order lookup or signed opaque token, not a raw public `out_trade_no` query.
### Task 16. Rebuild payment frontend views
- [ ] Rebuild `frontend/src/views/user/PaymentView.vue`, `frontend/src/views/user/PaymentQRCodeView.vue`, and `frontend/src/stores/payment.ts` so:
- only two buttons are shown to user: `支付宝` and `微信支付`
- frontend does not leak official-vs-EasyPay distinction
