docs: add registration page improvement design spec

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/superpowers/specs/2026-05-15-register-page-improvement-design.md

@@ -0,0 +1,184 @@
+# Registration Page Improvement Design
+
+**Date**: 2026-05-15
+**Branch**: feat/registration-page
+**Status**: draft
+
+## Scope
+
+Full-stack improvements to the registration page covering UI/UX, engineering quality, and visual polish. The existing `register.vue` (146 lines) works correctly but has accumulated technical debt and UX gaps.
+
+## Architecture: Component Decomposition (Approach B)
+
+Split the monolithic `register.vue` into focused components with clear data flow.
+
+### File Structure
+
+```
+app/pages/register.vue                  # Page shell (~60 lines)
+app/components/register/
+  RegisterForm.vue                       # Main form with submission logic (~120 lines)
+  PasswordInput.vue                      # Password field with show/hide toggle (~40 lines)
+  PasswordStrength.vue                   # Real-time strength indicator (~35 lines)
+  CaptchaField.vue                       # Captcha SVG + refresh + input (~50 lines)
+packages/shared/auth-schema.ts          # Shared Zod schema (client + server)
+```
+
+### Data Flow
+
+```
+register.vue
+  │  Owns: captchaToken, captchaSvg, toast
+  │  Provides: fetchCaptcha()
+  │
+  └─ RegisterForm
+       │  Props: captchaSvg, captchaToken
+       │  Emits: refresh-captcha, success, error
+       │  Uses: useHttpFetch → POST /api/auth/register
+       │  Internal: loading state
+       │
+       ├─ PasswordInput (x2: password + confirmPassword)
+       │    Props: modelValue, label, placeholder, disabled
+       │    Emits: update:modelValue
+       │    Internal: showPassword toggle
+       │
+       ├─ PasswordStrength
+       │    Props: password (computed from form values)
+       │    Output: score 0-4, label text, color-coded bar
+       │
+       └─ CaptchaField
+            Props: svg (v-html), loading
+            Emits: refresh
+```
+
+## Component Specifications
+
+### PasswordInput
+
+| Prop | Type | Default | Purpose |
+|------|------|---------|---------|
+| modelValue | string | required | v-model binding |
+| label | string | "密码" | Field label |
+| placeholder | string | "请输入密码" | Placeholder |
+| disabled | boolean | false | Disable during submission |
+
+| Emit | Payload | Purpose |
+|------|---------|---------|
+| update:modelValue | string | v-model update |
+
+States: default, showing password, focused (ring), error (red border + message), disabled.
+
+### PasswordStrength
+
+| Prop | Type | Purpose |
+|------|------|---------|
+| password | string | Password to evaluate |
+
+Scoring algorithm:
+- **Empty**: Nothing rendered
+- **Weak (1)**: Only digits or only letters, < 8 chars — red 1/4 bar
+- **Fair (2)**: Letters + digits, >= 8 chars — amber 2/4 bar
+- **Strong (3)**: Upper + lower + digits, >= 10 chars — green 3/4 bar
+- **Very Strong (4)**: Upper + lower + digits + special chars, >= 12 chars — emerald 4/4 bar
+
+### CaptchaField
+
+| Prop | Type | Purpose |
+|------|------|---------|
+| svg | string | SVG markup rendered via v-html |
+| loading | boolean | Show spinner, disable input during refresh |
+
+| Emit | Payload | Purpose |
+|------|---------|---------|
+| refresh | none | Request new captcha |
+
+States: default (SVG + input + refresh button), refreshing (spinner + dimmed), load error (error message + retry link).
+
+### RegisterForm Lifecycle
+
+1. **Idle**: Form editable, submit button enabled
+2. **Validating**: Client-side Zod via UForm, field-level errors
+3. **Submitting**: Button shows loading spinner + "注册中...", all inputs/buttons disabled
+4. **Failure**: Field-level errors (via setFieldError) or generic toast
+5. **Success**: Card content replaced with success state (check icon + "注册成功" + "去登录" link)
+
+## Schema Deduplication
+
+Extract the Zod schema from both `register.vue` (client inline) and `server/utils/auth/validation.ts` into a single shared module:
+
+```
+packages/shared/auth-schema.ts
+  exports: registerSchema
+  used by: client (UForm validation), server (safeParse)
+```
+
+## HTTP Client Consistency
+
+Replace raw `$fetch` in register.vue with `useHttpFetch` from `app/utils/http/factory.ts`, matching the pattern used elsewhere in the app. The `useHttpFetch` composable auto-unwraps the `{ code, message, data }` envelope.
+
+## Error Handling
+
+### Response Format Extension
+
+Existing envelope unchanged. Add optional `field` in `data` for field-level errors:
+
+```json
+// Username conflict → field-level
+{ "code": 1, "message": "用户名已存在", "data": { "field": "username" } }
+
+// Captcha wrong → field-level
+{ "code": 1, "message": "验证码错误", "data": { "field": "captchaText" } }
+
+// Captcha expired → field-level
+{ "code": 1, "message": "验证码已过期", "data": { "field": "captchaText" } }
+
+// Unknown → generic toast
+{ "code": 1, "message": "服务器内部错误", "data": null }
+```
+
+### Error Layers
+
+| Layer | Scenario | Handling | UI |
+|-------|----------|----------|-----|
+| Client validation | Format, length, mismatch | UForm + Zod, no request | Field-level red text |
+| Server business | Duplicate username, wrong captcha | API returns field code | setFieldError or toast |
+| Network | Timeout, offline, 500 | try/catch on useHttpFetch | Toast "网络异常，请稍后重试" |
+| Mount failure | Captcha load fails | try/catch in onMounted | "加载失败，点此重试" in captcha area |
+
+## Success Flow
+
+After successful registration, instead of navigating to `/login?registered=1` (which does not exist yet), show an inline success state within the card:
+- Green check icon
+- "注册成功" heading
+- Link/button: "去登录"
+
+The existing redirect behavior is kept as a fallback once the login page exists.
+
+## Testing Strategy
+
+### Unit Tests (Vitest)
+- `auth-schema.ts`: Zod validation pass/fail for various inputs
+- `PasswordStrength`: Scoring logic for each strength level
+- `server/utils/auth/validation.ts`: Server-side schema validation
+
+### Component Tests (@nuxt/test-utils + @vue/test-utils)
+- `PasswordInput`: Show/hide toggle, v-model binding, disabled state
+- `PasswordStrength`: Renders correct color and label for each password input
+- `CaptchaField`: SVG rendering, refresh emit, loading state
+- `RegisterForm`: Form validation, submission flow, disabled state during loading
+
+## Visual Polish
+
+- Optimize card vertical centering and form field spacing
+- Softer card shadow and border radius
+- Add "已有账号？去登录" + home page links below the form
+- Captcha refresh button shows rotation animation during loading
+
+## What's NOT Included
+
+- Login page (separate feature)
+- Session/JWT creation on registration (separate feature)
+- Email verification (separate feature)
+- Social login (separate feature)
+- Rate limiting (separate feature, needs infrastructure decisions)
+- Captcha storage migration from in-memory Map (low traffic, Map is sufficient for now)