wangxuming/NianAIGC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d98e58adfa132bb9308c6e7fbd77a914952edb5f
NianAIGC/findings.md
inman 0648874801 Add authenticated login and SSO protection
2026-05-29 15:54:13 +08:00

19 KiB
Raw Blame History

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.