NianAIGC/task_plan.md

# Task Plan: EvoLink Image Engine Settings

## Goal
Add EvoLink GPT Image 2 as a selectable image creation engine in the settings flow, while preserving the existing Jimeng/Volcengine image engine and the current task/asset workflow.

## Current Phase
Complete - latest update: Standalone Login Page Polish

## Phases

### Phase 1: Trace Current Settings and Provider Flow
- [x] Restore project planning context
- [x] Inspect settings API and settings panel
- [x] Inspect image generation submission/sync flow
- **Status:** complete

### Phase 2: Add EvoLink Provider Adapter
- [x] Create EvoLink image client with submit/query helpers
- [x] Add provider selection helpers and payload mapping
- [x] Route image job submission/sync through selected provider
- **Status:** complete

### Phase 3: Expose Engine Settings
- [x] Add settings fields for image engine and EvoLink credentials/model options
- [x] Update settings status/capability display
- [x] Document new env vars
- **Status:** complete

### Phase 4: Verification
- [x] Add or update focused tests
- [x] Run relevant tests/build checks
- [x] Browser-check the settings UI
- **Status:** complete

### Phase 5: Full Product UI/UX and Motion Polish
- [x] Add GSAP as the frontend motion dependency
- [x] Add a scoped client motion utility layer with reduced-motion handling and cleanup
- [x] Refresh global design tokens, focus states, navigation, mobile layout, and core page hierarchy
- [x] Polish `/create`, `/assets`, `/settings`, and image editing flows without changing backend APIs
- **Status:** complete

### Phase 6: Header and Module Cleanup
- [x] Compact the top title bar
- [x] Remove visible English module eyebrows and helper descriptions
- [x] Remove right-side title badges from modules
- [x] Reduce mobile horizontal scrolling in the lower create controls
- **Status:** complete

### Phase 7: Seedance API Limits Alignment
- [x] Verify official Seedance docs for current duration, ratio, and resolution constraints
- [x] Change video duration from free numeric input to official `4` to `15` second choices
- [x] Add server-side normalization for duration, ratio, and resolution
- [x] Document Seedance duration, ratio, and fast-model resolution restrictions
- **Status:** complete

### Phase 8: Product Branding
- [x] Replace generated text mark with logo assets from `/Users/inmanx/Documents/icon/logo`
- [x] Rename product surfaces to `智念AIGC平台`
- [x] Remove logo frame/background after visual feedback
- [x] Verify desktop and mobile header rendering
- **Status:** complete

### Phase 9: Server Deployment Support
- [x] Add Dockerfile for production image builds
- [x] Add Docker Compose service with runtime persistence and healthcheck
- [x] Add setup/deploy scripts
- [x] Document one-command server deployment in Chinese README
- [x] Verify shell syntax, unit tests, production build, and local health
- **Status:** complete

### Phase 10: Task Management and Public API v1
- [x] Extend generation job fields for task ownership, idempotency, locking, retry, timing, and webhook delivery
- [x] Split task creation from provider execution so page/API submits enqueue only
- [x] Add task management service, worker loop, API key auth, webhook delivery, and OpenAPI output
- [x] Add `/api/v1` capabilities, assets, jobs, cancel, and openapi routes
- [x] Add Docker Compose worker service, npm worker script, docs, and env examples
- [x] Add focused tests and run verification commands
- **Status:** complete

### Phase 11: Deployable Handoff and Integration Surface
- [x] Add operations-facing deployment documentation
- [x] Add partner-facing API integration documentation
- [x] Expand OpenAPI output for task, asset, upload, download, and webhook flows
- [x] Add authenticated public asset detail and download endpoints
- [x] Tag API-generated assets by client for stable follow-up access
- [x] Verify real HTTP API calls, Worker task processing, tests, and production build
- **Status:** complete

### Phase 12: Engine-Aware Image Tuning
- [x] Replace the free text-influence slider with user-facing option presets
- [x] Detect the active image generation engine from `/api/health`
- [x] Send Jimeng `scale` only when the active engine is Jimeng
- [x] Send EvoLink `quality` only when the active engine is EvoLink
- [x] Verify tests, production build, and desktop/mobile create-page layout
- **Status:** complete

### Phase 13: Account Login and SSO Protection
- [x] Trace existing page/API access and data ownership boundaries
- [x] Add OAuth2 Authorization Code login, callback, logout, and current-user session helpers
- [x] Verify JWT locally with JWKS and validate issuer/client/scope claims
- [x] Protect browser pages and first-party UI APIs while preserving public API key and worker endpoints
- [x] Thread authenticated owner IDs through assets and generation jobs
- [x] Add focused tests, docs, env examples, and run verification
- **Status:** complete

### Phase 14: Password Captcha Login
- [x] Verify auth captcha endpoint and password grant response shape without printing tokens
- [x] Add `/api/auth/captcha` proxy and `/api/auth/password` session-issuing login endpoint
- [x] Add account/password/captcha form to `/auth/login`
- [x] Verify login creates a session and logout returns to the login page
- **Status:** complete

### Phase 15: Standalone Login Page Polish
- [x] Remove the shared top bar from `/auth/*` pages
- [x] Keep only the logo, platform name, and account login form on the login page
- [x] Remove the visible unified-auth/SSO login entry from the login page
- [x] Apply the existing GSAP motion helper layer to the standalone login layout
- [x] Verify desktop and mobile login layout has no horizontal overflow
- **Status:** complete

## Key Questions
1. How should the selected image engine be stored and exposed in settings?
2. Which current capabilities should EvoLink handle first?
3. How do EvoLink task statuses map to the local GenerationJob statuses?
4. How can the fallback/mock behavior remain friendly for local development?

## Decisions Made
| Decision | Rationale |
|----------|-----------|
| Keep planning files in the project root for this exploration | The planning-with-files skill requires persistent context for multi-step repository research |
| Keep Jimeng as the default image engine | Preserves current behavior unless the user opts into EvoLink |
| Treat EvoLink as a provider inside the existing async job/asset pipeline | EvoLink returns async task ids and result URLs, matching the current job sync architecture |
| Use GSAP through local helpers instead of scattering animation calls in components | Keeps motion cleanup, reduced-motion behavior, and animation timing consistent |
| Keep UI polish scoped to frontend surfaces and avoid backend API/schema changes | Matches the requested product polish while preserving current workflows |
| Follow official Seedance 2.0 duration range `4~15` seconds in the UI | Prevents the user from selecting values the API rejects |
| Preserve `-1` Seedance auto duration only in backend/env normalization, not in the default UI dropdown | Keeps the UI predictable while still supporting advanced configuration |
| Use the black/blue transparent NIANXX logo on the light top bar | Makes the logo visible without adding a frame that changes the brand feel |
| Use Docker Compose as the primary server deployment path | Gives server operators one command, persistent local runtime data, and a restart policy |
| Implement multi-task support as task management, not an external message queue | Matches user preference and keeps deployment simpler for this server product |
| Use API Key auth for public API v1 | Fastest stable server-to-server integration model for other AI systems |
| Use OAuth2 Authorization Code for the browser UI login | Matches the provided SSO guide and keeps `client_secret` on the server |
| Derive first-party owner ids from verified JWT claims as `auth:<clientId>:<user_id/sub>` | Gives logged-in users isolated assets and jobs without changing the storage schema |
| Keep `/api/v1/*` outside SSO middleware | Existing partner integrations authenticate with API keys and must not be redirected to browser login |
| Add password grant login as a first-class browser login path | The provided auth service currently accepts `customPC` password login with image captcha while `/oauth2/authorize` returns 400 for the local callback |
| Hide the unified-auth/SSO entry from the login page | The user wants a focused branded login screen with only logo, platform name, and the account login form |

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| `git status --short` failed because this is not a Git repository | 1 | Continue as a plain project folder and inspect files directly |
| zsh expanded unquoted `[id]` route paths | 1 | Quote bracketed route paths |
| Initial `curl` requests hit a local proxy and returned 502/empty output | 1 | Re-ran direct requests with `curl --noproxy '*'` |
| Browser text wait hit a transient detached element after clicking the EvoLink tab | 1 | Re-read page body and confirmed the EvoLink settings tab rendered correctly |
| `npm start` failed when `.next` contained only dev cache and no production `BUILD_ID` | 1 | Added `prestart` to build automatically and pinned `next start` to `127.0.0.1:3000` |
| Settings page briefly showed a client exception after rebuilding while the old production server was still running | 1 | Restarted the production server on the fresh build and confirmed the status page rendered |
| `npm run build` failed after Seedance settings update because TypeScript narrowed fast-model resolution choices too aggressively | 1 | Changed resolution `includes` checks to readonly string arrays and rebuilt successfully |
| Running `npm run build` while an old dev server was active caused stale Next dev chunks in prior verification | 1 | Stop dev server before production builds, then restart it afterward |
| White transparent logo was invisible on the light top bar unless wrapped in a dark frame | 1 | Switched to the black/blue logo variant, generated a cropped transparent PNG, and removed frame/background styling |
| Current local machine does not expose Docker CLI | 1 | Verified script syntax, Next build, tests, and health locally; Docker build should be run on the deployment server |
| Docker CLI is still unavailable while validating Phase 10 | 1 | Verified npm tests, production build, local health, API v1 calls, and worker tick locally; Compose container startup should be validated on the deployment server |

## Notes
- EvoLink docs: submit `POST /v1/images/generations`, query `GET /v1/tasks/{task_id}`, completed task exposes `results[]`.
- EvoLink `resolution` is only effective when `size` is a ratio, so the adapter maps current UI dimensions to supported ratio values where possible.
- Engine selection now lives in the settings status tab as per-capability assignments: image generate and inpaint are configurable, upscale and video are fixed to their current engines.
- Current local dev server convention: screen session `zhinian-dev-ui`, `127.0.0.1:3000`, logs at `/tmp/zhinian-dev-server.log`.
- Before production build verification, stop the dev server first to avoid stale `.next` dev chunk references.
- Latest product name is `智念AIGC平台`.
- Current header logo asset is `public/logo/zhinian-logo.png`, generated from `/Users/inmanx/Documents/icon/logo/2d5b992caa14db16f594c4933e92e37e.png`.
- Server one-command deployment entrypoint is `bash scripts/deploy.sh`.
- Docker Compose persists local uploads/results/state through the bind mount `./.runtime:/app/.runtime`.
- Public API v1 endpoints are under `/api/v1` and require `ZHINIAN_API_KEYS`.
- Task processing is handled by `npm run worker` or the `zhinian-worker` Compose service through `/api/internal/worker/tick`.