NianAIGC/findings.md

Findings & Decisions

Requirements

• User asked: "了解整个项目" — inspect and understand the whole project, then explain it clearly.
• Expected output: concise but useful project map in Chinese, including purpose, stack, structure, runtime flow, commands, and notable risks.

Research Findings

• Top-level project is not a Git repository; git status --short returned "fatal: not a git repository".
• Root contains orchestration/docs files plus a removed extracted runtime application directory.
• removed extracted runtime/node_modules is present, so dependencies appear already installed for the embedded runtime app.
• The initial full file scan showed many bundled media assets under removed extracted runtime/public, especially starter/planning/Seedance examples.
• README.md states this was extracted from the 智念助手 desktop app into an independent 智念创作助手 project.
• The project is based on an existing extracted runtime Next.js standalone runtime; original source was deleted, so this is not a full source restoration.
• Root package.json only orchestrates scripts: start/dev call removed runtime start script, health calls scripts/health-check.mjs, and info calls removed runtime info script.
• Runtime package uses Next ^15.1.4, React ^19.0.0, Supabase client, Ali OSS, lucide-react, TypeScript, Vitest, and ESLint, but it is treated as generated runtime.
• Runtime state should be written to root .runtime/, not under removed extracted runtime.
• removed runtime start script loads .env and .env.local, optionally bundled .env.runtime only when ZHINIAN_LOAD_BUNDLED_ENV=1.
• Startup creates .runtime/data, .runtime/uploads, and .runtime/generated-results, then launches removed extracted runtime/server.js with NODE_ENV=production.
• Health check targets /api/desktop/health and expects JSON with appId: "removed-runtime" and ok: true.
• .env.example shows the real generation path depends on Seedance / Volcengine Ark plus Aliyun OSS configuration.
• Extraction notes confirm copied assets include Next standalone server runtime, .next output, runtime node_modules, public/reference media, content manifests, and planning cases; secrets, user uploads, generated results, and Electron host/process manager code were excluded.
• npm run info succeeded and reports runtime app id removed-runtime, bundle timestamp 2026-05-14T04:01:58.653Z, entry server.js, and size 949,760,759 bytes.
• App routes include: /, /studio, /studio/[mode], /planning, /projects, /projects/[id], and /billing.
• API routes include: /api/assets, /api/assets/upload, /api/billing, /api/desktop/health, /api/generations, /api/generations/[id], /api/generations/[id]/retry, /api/projects, /api/projects/[id], /api/prompt/assemble, and /api/reference-templates.
• File-serving routes expose runtime uploads and generated results via /uploads/[...path] and /generated-results/[...path].
• Creation modes currently report one mode: video_studio / 宣传片创作台, editor type storyboard_cards.
• Starter catalog has 14 cases across storefront_avatar_storyboard, music_sync_ad, and creative_remix; planning cases include five visible categories such as short-video promo and premium-brand.
• Compiled API code reveals a local JSON store at app-state.json with users, assets, projects, generation_jobs, and credit_transactions.
• The default local user is demo-merchant / demo@localmerchant.ai with 9999 demo credits.
• /api/projects returns projects with their jobs; project creation is coupled to generation creation and deducts credits based on duration/resolution/ratio.
• /api/assets/upload accepts multipart file, role, and optional promptLabel; it stores to Ali OSS when OSS env is complete, otherwise writes to local uploads and records an asset.
• /api/prompt/assemble builds a Chinese Seedance-style video prompt from shop/project details, selected template, storyboard, and optional avatar/outfit selection.
• Seedance client defaults: base URL https://ark.cn-beijing.volces.com/api/v3, model doubao-seedance-2-0-260128, ratio 9:16, duration 15, resolution 720p.
• Real generation creation posts to /contents/generations/tasks; query uses /contents/generations/tasks/{id}.
• Missing SEEDANCE_API_KEY causes a user-facing error and the project/job path refunds credits after marking the job failed.
• Health response includes services.seedanceConfigured and services.objectStorageConfigured.
• GET /api/generations/:id reads a local job, polls Seedance when provider_job_id exists, and backs up successful result videos to OSS or local generated-results.
• POST /api/generations/:id/retry loads the original project settings and re-runs the generation creation flow.
• GET /api/projects/:id returns one project with jobs; DELETE /api/projects/:id removes the project, jobs, and related credit transactions.
• GET /api/assets returns local assets for the demo owner; GET /api/billing returns demo user and credit transactions.
• GET /api/reference-templates?mode=... returns starter templates filtered by mode.
• Content definition has one canonical creation mode: video_studio, product name 宣传片创作台, editor type storyboard_cards, reference-first workflow, and six asset slot labels.
• Starter catalog contains 14 selectable templates and 85 local asset records from the Seedance guide plus local promo examples.
• Template categories represented in content are storefront_avatar_storyboard, music_sync_ad, and creative_remix; docs say legacy mode arguments are accepted for compatibility.
• Planning page content has five planning cases: 短视频宣传类, 剧情宣传类, 热门玩梗类, 卡通 IP 类, and 品质高级类.
• Avatar presets currently include one default digital-human model and one default outfit pairing.
• Runtime verification passed: npm run info succeeded, npm start launched Next on http://127.0.0.1:3000, and npm run health returned ok: true.
• Health verification reports seedanceConfigured: false and objectStorageConfigured: false, matching the empty local env configuration.
• Direct curl verification with --noproxy '*' returned 200 OK for /studio, {"projects":[]} for /api/projects, one template for /api/reference-templates?mode=video_studio, and the demo billing user.
• Starting the runtime created .runtime/data/app-state.json with the demo user and initial credit transaction.

Technical Decisions

Decision	Rationale

Issues Encountered

Issue	Resolution
git status cannot run because the project root has no .git metadata	Treat this as a plain project folder and avoid Git-based assumptions
zsh treats [id] in file paths as a glob pattern	Quote bracketed Next.js dynamic route paths when reading them
Initial plain curl calls hit a local proxy and returned 502/empty output	Use curl --noproxy '*' for localhost verification

Resources

• Project root: /Users/inmanx/Documents/zhinian-creation-assistant
• Runtime app: /Users/inmanx/Documents/zhinian-creation-assistant/removed extracted runtime
• Root README: /Users/inmanx/Documents/zhinian-creation-assistant/README.md
• Runtime README: /Users/inmanx/Documents/zhinian-creation-assistant/runtime/README.md
• Startup script: /Users/inmanx/Documents/zhinian-creation-assistant/removed runtime start script
• Health script: /Users/inmanx/Documents/zhinian-creation-assistant/scripts/health-check.mjs
• Runtime info script: /Users/inmanx/Documents/zhinian-creation-assistant/removed runtime info script
• Extraction notes: /Users/inmanx/Documents/zhinian-creation-assistant/docs/EXTRACTION_NOTES.md
• App paths manifest: /Users/inmanx/Documents/zhinian-creation-assistant/removed extracted runtime/.next/server/app-paths-manifest.json
• Compiled projects API: /Users/inmanx/Documents/zhinian-creation-assistant/removed extracted runtime/.next/server/app/api/projects/route.js
• Compiled upload API: /Users/inmanx/Documents/zhinian-creation-assistant/removed extracted runtime/.next/server/app/api/assets/upload/route.js
• Compiled prompt assembly API: /Users/inmanx/Documents/zhinian-creation-assistant/removed extracted runtime/.next/server/app/api/prompt/assemble/route.js
• Compiled generation polling API: /Users/inmanx/Documents/zhinian-creation-assistant/removed extracted runtime/.next/server/app/api/generations/[id]/route.js
• Compiled generation retry API: /Users/inmanx/Documents/zhinian-creation-assistant/removed extracted runtime/.next/server/app/api/generations/[id]/retry/route.js
• Creation modes JSON: /Users/inmanx/Documents/zhinian-creation-assistant/removed extracted runtime/content/seedance-starter/creation-modes.json
• Starter catalog JSON: /Users/inmanx/Documents/zhinian-creation-assistant/removed extracted runtime/content/seedance-starter/catalog.json
• Planning cases JSON: /Users/inmanx/Documents/zhinian-creation-assistant/removed extracted runtime/content/removed planning case manifest.json
• Runtime local state file: /Users/inmanx/Documents/zhinian-creation-assistant/.runtime/data/app-state.json

Visual/Browser Findings

• 2026-05-29 UI polish verification:
  • /create, /create?mode=video, /assets, and /settings were checked during the product polish work.
  • 375, 768, 1024, and 1440 width checks showed no horizontal overflow after the compact header and mobile control changes.
  • The video duration dropdown on /create?mode=video exposes only 4 秒 through 15 秒.
  • The header logo loads from public/logo/zhinian-logo.png; after the final branding pass it has no border, background, or box shadow.

2026-05-29 UI/UX and Branding Findings

• The current source app is now a Web app in the repository root, not the old removed extracted runtime standalone-only flow described in the earliest findings.
• GSAP is used through lib/ui/motion.ts rather than directly sprinkled across components.
• The UI direction is a professional creation workspace, not a marketing landing page.
• Visible English eyebrows/descriptions were removed from module headers per user preference.
• Topbar should remain compact and avoid horizontal scrolling below it.
• Product name is now 智念AIGC平台.
• Logo source folder: /Users/inmanx/Documents/icon/logo.
• Current logo asset: public/logo/zhinian-logo.png.
• Current logo was generated from /Users/inmanx/Documents/icon/logo/2d5b992caa14db16f594c4933e92e37e.png by removing the white background and cropping whitespace.
• Avoid using the white transparent logo on the light topbar unless the topbar itself becomes dark; wrapping the logo in a dark frame changes the brand feel.

2026-05-29 Seedance Findings

• Official Volcengine Ark "创建视频生成任务 API" docs say Seedance 2.0 duration supports integer seconds in [4, 15], or -1 for model-chosen duration.
• Seedance 2.0 and Seedance 1.5 Pro support adaptive ratio behavior.
• Supported ratios include 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, and adaptive.
• Supported resolutions include 480p, 720p, and 1080p, but Seedance 2.0 fast does not support 1080p.
• frames is not supported for Seedance 2.0 / Seedance 1.5 Pro, so the current app should continue using integer duration.
• generate_audio defaults true in the API and remains enabled in the app payload.

2026-05-29 Operational Findings

• For localhost verification, continue using curl --noproxy '*' because local proxy settings can interfere with direct checks.
• Before running npm run build, stop the dev server (screen -S zhinian-dev-ui -X quit and pkill -f 'next dev --hostname 127.0.0.1 --port 3000') to avoid stale Next dev chunk issues.
• After build verification, restart the dev server in screen session zhinian-dev-ui on 127.0.0.1:3000.

2026-05-29 Deployment Findings

• Server one-command deployment is now bash scripts/deploy.sh.
• Docker Compose service name is zhinian-aigc.
• Docker Compose defaults to exposing host port 3000; set APP_PORT in .env.local or shell to change it.
• NEXT_PUBLIC_APP_URL should be set to the public domain or server URL in production so generated local file URLs are correct.
• Persistent runtime data is bind-mounted through ./.runtime:/app/.runtime; this folder should be backed up on real servers.
• .env.local is intentionally used as the compose env_file and remains ignored by Git.
• Current local machine does not have the Docker CLI available, so Docker build was not run here; script syntax, app tests, production build, and local health were verified instead.

2026-05-29 Public API and Task Management Findings

• User confirmed multi-task support should be task management logic, not an external message queue.
• Public API v1 now uses ZHINIAN_API_KEYS, supporting Authorization: Bearer <key> and X-Zhinian-Api-Key.
• Task creation and provider execution are now split: submit routes enqueue GenerationJob records; Worker ticks claim and process jobs.
• generation_jobs now carries external client, idempotency, priority, attempts, lock, schedule, timing, and webhook fields.
• Supabase/Postgres production mode expects the claim_generation_jobs function from supabase/schema.sql for atomic task claiming.
• Local JSON mode serializes task claiming through the existing local write queue and is intended for single-instance development.
• Worker execution can run as npm run worker, npm run worker:once, or the zhinian-worker Docker Compose service.
• Internal Worker processing goes through /api/internal/worker/tick protected by ZHINIAN_INTERNAL_WORKER_TOKEN in production.
• API v1 routes are /api/v1/capabilities, /api/v1/assets, /api/v1/jobs, /api/v1/jobs/:id, /api/v1/jobs/:id/cancel, and /api/v1/openapi.json.
• Local verification created a public API job and processed it to succeeded through npm run worker:once in mock mode.
• Public API asset access now includes /api/v1/assets/:id and /api/v1/assets/:id/download.
• Uploaded and generated assets created through public API flows are tagged as api-client:<clientId> so integrations can query and download their own results later.
• OpenAPI is generated dynamically from the current deployment origin at /api/v1/openapi.json.
• Operations handoff docs live in docs/DEPLOYMENT.md; partner API docs live in docs/API.md.

2026-05-29 Image Tuning Findings

• Jimeng image generation supports the current scale parameter, so UI presets should submit numeric text-influence values for that engine.
• EvoLink image generation does not use Jimeng scale; the per-request engine-aware control should submit EvoLink quality instead.
• Current local /api/health reports image.generate using EvoLink, so /create should show 生成质量 options rather than 文本影响.

2026-05-29 Account Login / SSO Findings

• User requested account login before release so the project is safe to use.
• Provided SSO guide recommends OAuth2 Authorization Code for Web SSO: redirect to ${AUTH_BASE}/oauth2/authorize, receive code and state, then exchange code server-side at ${AUTH_BASE}/oauth2/token.
• OAuth client defaults in the guide use client_id=customPC and scope=server; client_secret must stay on the server.
• Access tokens are JWTs; resource services should verify locally with JWKS from ${AUTH_BASE}/oauth2/jwks rather than calling auth on every request.
• Minimum JWT checks from the guide: RS256 signature, exp, nbf/iat, issuer https://pig4cloud.com, OAuth client id, scope/authority requirements.
• Logout endpoint is DELETE ${AUTH_BASE}/token/logout, but local session deletion remains required because existing JWTs may stay valid until exp.
• Current app has no login middleware or session helper; pages are client components under a global shell.
• Current local data store defaults all assets/jobs to DEFAULT_OWNER_ID = "demo-merchant", so account login must also address per-user owner IDs for first-party UI APIs.
• Public API v1 already has separate API key auth through ZHINIAN_API_KEYS; SSO should preserve that server-to-server surface.
• First-party UI APIs that currently need session ownership include /api/assets, /api/assets/upload, /api/assets/:id/*, /api/generations/image*, /api/generations/video*, and /api/settings.
• Generation services already accept optional ownerId, so route handlers can pass the authenticated owner without rewriting provider dispatch or worker logic.
• Retry helpers currently preserve the original request payload; they need to override ownerId on retry so a user cannot retry another user's job if they know the id.
• /uploads/* and /generated-results/* serve local runtime files directly; middleware should protect these paths for cookie-authenticated browser sessions.
• /api/v1/* and /api/internal/worker/tick must remain outside browser SSO middleware because they use API keys and worker tokens.
• Implemented browser SSO with signed HttpOnly zhinian_session cookies; middleware validates the signed session instead of exposing JWTs to client JavaScript.
• JWT access tokens are verified in the callback using RS256 and configured JWKS, with issuer, client id, expiry, not-before, issued-at, and scope checks.
• Local file routes now resolve storagePath back to an asset record and require the current owner to match before serving bytes.
• Public API v1 remains API-key based and can still read/download its assets through public API routes even when browser SSO protects the Web UI.

2026-05-29 Password Captcha Login Findings

• User provided live auth configuration and a password grant sample; real secret values remain only in the ignored local environment file.
• ${AUTH_BASE}/code/image?randomStr=... returns a PNG captcha image.
• The password grant sample successfully returns a JWT access token, refresh token, expected client/user claims, tenant id, and server scope.
• The local /api/auth/password endpoint verified the returned JWT with JWKS and created a signed browser session for the authenticated user.
• Browser form login with the displayed math captcha succeeded and redirected to /create; the topbar showed the authenticated username and logout button.
• Logout cleared the session and returned to /auth/login?loggedOut=1.

2026-05-29 Standalone Login Page Findings

• Login routes under /auth/* should not render the shared app topbar; the login page is a standalone entry surface.
• The login page now intentionally presents only the NIANXX logo, 智念AIGC平台, and the account/password/captcha form.
• The visible 统一认证中心 OAuth entry was removed from the login page after user feedback.
• The standalone login page uses the existing GSAP motion helper layer (runScopedMotion, revealChildren, pulseFeedback) for consistent app motion.
• Browser viewport checks passed at 1280x800 and 390x844: no topbar, no SSO link text, logo and platform name present, login panel present, and no horizontal overflow.

2026-06-09 Repository and Runtime Status Findings

• The current repository root is a Git checkout on main tracking origin/main.
• The remote is https://git.nianxx.cn/wangxuming/NianAIGC.git.
• The workspace was overwritten from remote and is currently clean at d98e58a docs: update public api docs.
• The project uses npm (package-lock.json) and Next.js dev startup through npm run dev.
• Local Node version during verification was v22.22.1, satisfying the package.json >=20 engine.
• During startup verification, ports 3000, 3001, and 3002 were already occupied by local Node/Next processes or listeners; use a confirmed-free alternate port rather than assuming 3000.
• npm run dev -- --hostname 127.0.0.1 --port 3003 successfully started the current project and reached Next Ready in 2.9 seconds.
• A smoke request to http://127.0.0.1:3003/ returned 307 Temporary Redirect to /auth/login?next=%2F, confirming the login-protected app flow.
• Current status check on 2026-06-09 found no next dev / next-server process and no listener on 3003; the project is verified startable but not currently running.

2026-07-01 Account ID Partitioning Findings

• First-party browser APIs already pass the authenticated session user id into asset and generation flows.
• Public API v1 currently authenticates by clientId:key, but jobs and assets are still created with ownerId = DEFAULT_OWNER_ID.
• Public API listing/detail access filters with externalClientId and api-client:<clientId> tags, which works as an access check but keeps all API account data in one default owner partition.
• The data store and Supabase schema already support owner_id indexes and idempotency uniqueness by (owner_id, external_client_id, idempotency_key), so the change can be made by deriving a stable account owner id from the API client id.
• Job detail and cancel routes currently check only externalClientId; they should also require the account owner id so a client id collision cannot cross account partitions.
• Implemented owner derivation as publicApiOwnerId(client), yielding api:<sanitizedAccountId>.
• Public API job creation, idempotency lookup, job listing/detail/cancel, asset upload/register/list/detail/download now use the derived API account owner.
• Documentation now states that ZHINIAN_API_KEYS uses 账号ID:key and that records are partitioned under api:<账号ID>.

2026-07-01 Password Login Captcha Finding

• origin/main is up to date at d98e58a; relevant history includes ce358df 修改认证中心对接方式 and 288e31d 移除验证码输入框.
• Current components/auth-login-panel.tsx does not render captcha controls and submits only username, password, and next.
• Current app/api/auth/password/route.ts no longer requires captcha; it only forwards code and randomStr if they are present in the request body.
• Current local .env.local points password login at https://onefeel.brother7.cn/ingress/auth with client id customPC.
• A local login probe with fake credentials returned 验证码不能为空; a direct token request to the configured auth center with the same non-secret dummy credentials also returned 验证码不能为空.
• Therefore the observed captcha error is coming from the configured auth center instance, not from the current AIGC frontend or password route validation.
• The operations SSO guide defaults external projects to OAuth client app/app, recommends adding token-flow clients to security.ignore-clients, and notes customPC is a special platform-user compatibility client that skips AES password decrypt.
• Dummy token probes showed app/app reaches normal credential validation (用户名或密码错误) while customPC is intercepted by captcha validation on the current auth center instance.
• Updated the project defaults, docs, .env.example, and local .env.local to use app/app plus ZHINIAN_AUTH_PASSWORD_ENC_KEY=thanks,pig4cloud.
• After restarting the dev server, local /api/auth/password with dummy credentials returns 用户名或密码错误, confirming the captcha interception is bypassed for the configured client.

2026-07-01 Internal RBAC / Account Management Findings

• Initial requested guide /Users/inmanx/Desktop/organization-external-api.md was missing; updated guide /Users/inmanx/Desktop/organization-external-api(1).md is available and has 1310 lines.
• Existing JWT session already stores authorities and scope on AuthUser, making it suitable for internal RBAC.
• Before the RBAC change, navigation exposed 创作, 结果, 日志, and 设置 to every logged-in user.
• Before the RBAC change, middleware only checked whether a user was authenticated and did not distinguish ordinary users from administrators.
• Before the RBAC change, /api/settings checked requireAppUser() but not admin permission.
• Before the RBAC change, /api/logs relied on middleware authentication only and did not call requireAppUser() or admin checks inside the route.
• RBAC now hides admin navigation for ordinary users and protects /logs, /settings, /accounts, /api/logs, /api/settings, and /api/admin/*.
• Updated guide covers organization, department, role, member, and enterprise user operation APIs.
• Organization/member APIs are served by basic-capability-services-biz; enterprise user management APIs are exposed by hotel-staff-server-biz.
• Member list APIs remain @Inner and require header from: Y.
• Enterprise user APIs require Authorization and a token with administrator role 1; otherwise they return 仅管理员角色允许调用.
• Account creation should use /adminOrganization/organizationMember/addOrganizationMemberAndCreatePlatformUser to create the enterprise user and bind the organization member in one call.
• Password maintenance is available through /adminPcUser/resetPlatformUserPassword, with tenantId, numeric userId, newPassword, and optional mustChangePassword.
• Updated /Users/inmanx/Desktop/organization-external-api(2).md confirms the external member list path is /adminOrganization/organizationMember/organizationMemberList through hotelStaff; only the basic service internal /organizationMember/organizationMemberList path needs from: Y.
• The updated hotelStaff member-list proxy is reachable from the app, but the current login token can still be rejected by the upstream service with 仅管理员角色允许调用.
• Local RBAC allow-listing ceshiop as a platform admin only controls this app's pages and APIs; it does not grant upstream hotelStaff administrator role 1 inside the authentication center token.
• Account management now treats upstream member-list administrator denial like a recoverable member-list-only limitation: the page can still load configured organization data and keep account creation/password maintenance available when those upstream endpoints allow the token.
• The updated organization guide exposes department creation at POST /organizationGroup/createOrganizationGroup with organizationId, groupName, optional groupDesc, and optional parentId.
• The account page can create a department from the member form and then refresh/select the created department, so admins do not need to leave account management before creating members.

2026-07-02 Image Template Findings

• User requested image-generation templates with selection-time effect preview and preset prompt support.
• This should be account-managed data, not global environment configuration.
• Existing browser image generation API already uses requireAppUser() and submits ownerId: user.id, so template APIs should use the same owner boundary.
• Template configuration should remain inside the image generation module rather than the global settings page.
• The create page already keeps image/video prompt state client-side, detects the active image engine from /api/health, and submits prompt, materials, size, force-single, and engine-specific tuning to /api/generations/image.
• Implemented image templates with fields for name, category, description, preset prompt, preview image URL, width/height, force-single, and sort order.
• New first-party routes are /api/image-templates and /api/image-templates/:id; both require the app user and use the authenticated user id as owner id.
• Local JSON state now normalizes imageTemplates; Supabase deployments need the new image_templates table from supabase/schema.sql.
• Browser verification used a temporary auth-disabled dev server to create one demo template, confirm the /create left template rail and template application behavior, then deleted the demo template.
• Final dev server was restarted with the normal .env.local auth-enabled environment on 127.0.0.1:3001.

2026-07-02 Large Auth Session Finding

• A new real account could receive a successful /api/auth/password response and still be redirected back to /auth/login?next=/create, which indicates the browser did not persist a valid session rather than an upstream password failure.
• The session cookie stores the signed session plus access token so the app can forward the current login token to organization/staff APIs.
• Accounts with larger JWT or authority payloads can exceed a single browser cookie's practical size limit; splitting zhinian_session into chunked cookies keeps the same signed payload while allowing middleware and server helpers to reassemble it.
• Settings no longer exposes a template tab.
• In image mode, /create now renders a left vertical 模板选择 rail with an icon 添加模板 button and thumbnail/name-only template cards.
• The add-template entry opens an in-module template form modal; it is not exposed from settings.
• Clicking a template selects it and brings its preset prompt, image size, and force-single value into the generation console on the right.
• Desktop and narrow browser verification confirmed the template picker is an independent left-side panel beside the generation panel, not a child of the generation panel, with no horizontal overflow.
• The image/video/edit mode switch is now contained by the generation panel, not placed above or across the far-left template module.
• Template preview image upload now uses the same /api/assets/upload route as workbench materials, so configured OSS storage is reused instead of accepting a manually typed preview URL.
• New template configuration no longer exposes category or remark fields; the user-facing free text field is 简介, backed by the existing template description data.
• Template preset prompts can contain @图片1 style placeholders. The generation console parses those tokens and shows missing upload slots below the prompt.
• Placeholder upload slots bind the uploaded asset to the exact requested token, so clicking the @图片2 slot creates/updates the @图片2 material instead of relying on upload order.
• Material labels are preserved after removal to avoid silently breaking prompt references created by templates.
• UI/UX skill guidance for the add-template modal was applied as a focused SaaS workspace form: strong preview region, fewer visible decisions at once, clear bottom actions, and responsive stacking on narrow screens.
• While editing a template prompt, parsed placeholder chips are shown below the textarea so users can confirm which upload slots the template will request after selection.
• Image templates now store the target image generation engine in settings.engine, with Jimeng using settings.scale and Image2/EvoLink using settings.quality.
• First-party image generation now accepts a per-request engine override and passes it into submitImageJob(), so template engine choices are honored by the provider payload.
• The generation console exposes the current image engine selector; applying a template updates this selector plus the matching parameter control.
• Material placeholders now require an explicit number, so @图片1 and @图2 create upload slots while bare @图片 or @图片这种普通文字 stay plain prompt text.
• Template prompt editing includes explicit placeholder insertion controls for image/video/audio slots, making the placeholder confirmation action deliberate instead of relying on unfinished @ typing.
• Existing image templates can be reopened from the top-right edit action on each template card and saved through the account-scoped PATCH route.
• The template rail is intentionally wider on desktop and each card separates image preview, template selection, and template editing into distinct controls.
• Clicking a template thumbnail opens a larger preview dialog; choosing from that dialog applies the template and closes the preview.
• Typing @ in prompt editors now opens a temporary material draft slot instead of immediately writing a partial token into the prompt body.
• A material draft is confirmed into the prompt only by Enter or explicit option selection; confirmed values are inserted with text boundaries so subsequent Chinese text is not absorbed into the token.
• The temporary draft slot is shared by the generation prompt and template preset prompt; invalid text such as 图片这种普通文字 stays in the slot and does not create upload requirements.
• Confirmed numbered tokens keep using the existing visual token overlay, placeholder chips, and missing upload-slot UI.
• The temporary material draft slot should remain visually inside the prompt editor surface, not below the input, so @ entry feels like an inline editing affordance.
• Template preset prompts use the same token overlay as the generation prompt; confirmed placeholders such as @视频1 are visibly colored inside the input area before saving the template.
• The image template rail now uses a wider desktop/tablet track (390-480px desktop, 315-375px tablet) and stacks above the generation panel on mobile so reference previews stay browseable.
• Template thumbnails use a 4:3 viewport with contained images, allowing both 9:16 and 16:9 reference images to be inspected without cropping.
• Template card application now requires the explicit 选择模板 button; thumbnail clicks open preview and template name/description text no longer selects the template.
• The template rail remains visible in image and video generation modes; only the image-editing modes (局部重绘, 智能超清) use the standalone editor layout without the template rail.
• Template cards are fixed compact items (138px x 184px) inside the rail list, so each template has a consistent smaller footprint.
• The template rail height is synchronized from the right generation panel through a ResizeObserver; the rail body is split into fixed header/action rows and a scrolling template-list row.
• The scrollbar belongs only to .image-template-rail-list; 模板选择 and 添加模板 stay outside the scroll container.
• Template rail cards now use their preview image as a full-bleed card surface with object-fit: cover.
• Template card title, intro, and select action sit inside a bottom floating frosted-glass overlay; the select button remains the only action that applies the template.
• The zoom icon was removed from template cards, while the edit icon remains on the top-right corner above the image.
• Selected template cards use a heavier layered shadow and slight upward transform to create stronger depth.
• The template intro/description field is no longer part of the create/edit template UI or card display; old stored descriptions may still exist in data but are ignored by this surface.
• The template edit icon now sits inside the card's frosted-glass overlay instead of on the image corner.
• Template selection is a toggle: the first click captures the current right-side image generation state and applies the template; clicking the selected template again restores that snapshot and clears the active template state.
• The compact full-bleed template card target is 132px x 176px; the widened desktop rail should fit three cards per row.
• The card footer uses a two-row frosted-glass grid: title spans the first row, while the select/cancel button and edit icon share the second row to avoid cramped text or overlap.

2026-07-02 Create Task Module Findings

• The creation console can reuse existing first-party APIs for a task list: /api/generations/image, /api/generations/video, and /api/assets.
• GenerationJob already has the needed task fields: prompt/name fallback, status, created/updated timestamps, capability, and output asset ids.
• Generated task thumbnails can be resolved by mapping GenerationJob.outputAssetIds to assets from /api/assets; queued/running tasks need a placeholder when no output asset exists yet.
• The existing results page already has a task view and detail panel, so the create-page 查看详情 action deep-links to /assets?view=tasks&taskId=<id> instead of creating a separate task page.
• Desktop create layout now supports three independent modules: left template rail, center generation console, and right task module. At narrower widths the task module drops below the main modules, and at mobile widths all modules stack without horizontal overflow.
• The right task module now targets 560-640px on desktop/wide screens so task name, status, elapsed time, and 查看详情 can stay on one horizontal row.
• Queued/running jobs without output assets should render a clear 生成中 thumbnail placeholder instead of a generic empty asset icon.
• Completed image-task thumbnails are preview actions inside /create; clicking them opens the same large asset-preview surface while 查看详情 remains the route to the full task page.