miaojingAI/CODEX_MIAOJING_MEMORY.md

Codex MiaoJing Memory

Last source audit: 2026-05-12, based on git commit 8ee86a9 (Add NewAPI image compatibility and style presets).

This file is the required entry point for Codex work in this repository. Its job is to prevent repeated rediscovery. Every Codex session working on MiaoJing must read this file first, then jump to the referenced index document before editing.

Required Reading Order

1. Read this file.
2. Read docs/codex-miaojing/README.md.
3. Pick the task-specific document:
   • Feature or UI location: docs/codex-miaojing/feature-code-index.md
   • Bug report or regression: docs/codex-miaojing/bug-location-guide.md
   • API contract, route, auth, request body: docs/codex-miaojing/api-reference.md
   • System boundaries, data flow, deployment: docs/codex-miaojing/architecture.md
   • Custom integration keyword such as 元界, Agnes, mozheAPI, or 智能配置 API: also read docs/codex-miaojing/custom-integrations.md and search long-term memory for the keyword before editing.
4. Verify the file paths against current source with rg or direct file reads.
5. Make the smallest scoped code change that fits the existing architecture.
6. For every adjustment or modification, check whether the change affects any project knowledge document. If it changes code location, UI behavior, API behavior, data shape, schema expectation, deployment flow, verification method, bug-diagnosis path, or provider/platform-specific integration logic, update the corresponding document in the same commit.
7. If a custom integration rule is durable across future sessions, write it to long-term memory instead of relying only on chat context.
8. Before finishing new development, classify the production delivery path: admin-console hot update package or admin-console cold update package. Record upgrade, backup, rollback, and health-check implications when the change affects deployable behavior.

Repository Identity

• Product: MiaoJing AI creation platform.
• Stack: Next.js 16 App Router, React 19, TypeScript, PostgreSQL, local file storage, PM2.
• Package manager: pnpm only.
• Primary source directories:
  • Pages and API routes: src/app
  • UI and workflow components: src/components
  • Business logic and stores: src/lib
  • Console module entry points: src/modules
  • Database clients and schema snapshot: src/storage
  • Deployment and maintenance scripts: scripts

Canonical Local Context

• This local clone was reset to origin/main before these docs were written.
• Remote: https://git.toplee.cn/fenglee/miaojingAI.git
• If server deployment is requested later, verify the active runtime tree and PM2 cwd before editing. Do not assume a production tree from memory.
• Production access verified on 2026-05-14 used ssh -p 5238 root@124.174.9.29; PM2 still served the live tree from /opt/miaojingAI through Node under /data/miaojingAI/node/node-v24.15.0-linux-x64/bin, with web/API/console ports 8000/8100/8200. /root/miaojingAI may coexist and must not be treated as live without PM2 confirmation.
• When syncing source into /opt/miaojingAI, preserve production-only runtime files such as .env.local, node_modules, .next, dist, backups, local storage, and the production ecosystem.config.cjs. The repository copy may point at /root/miaojingAI and ports 5000/5100/5200; overwriting production ecosystem.config.cjs breaks the live nginx upstream until restored. Manual source archives must exclude ecosystem.config.cjs, or the deploy must restore the production copy from the pre-sync backup before PM2 reload.
• New-environment migrations must verify database table ownership as well as grants. If LOCAL_DB_URL uses the app user but restored tables are still owned by postgres, runtime compatibility checks can fail with must be owner of table ..., which can make /api/model-config return no systemApis even when backend default models exist.

Fast Routing Map

Use this table before searching.

Task	Start Here	Then Check
Home page, shell, navigation, footer, announcement popup	src/app/page.tsx, src/components/app-shell.tsx, src/components/navbar.tsx, src/components/site-footer.tsx, src/components/announcement-popup.tsx	src/lib/site-config.ts, src/app/api/site-config/route.ts, src/app/api/announcements/route.ts
Create center tabs	src/app/create/page.tsx	src/components/create/*
Text/image generation	src/components/create/text-to-image.tsx, src/components/create/image-to-image.tsx, src/components/create/generation-task-list.tsx	src/app/api/generation-jobs/route.ts, src/app/api/generate/image/route.ts, src/lib/generation-job-*, src/lib/generation-credit-service.ts, src/app/api/style-presets/route.ts, src/lib/style-preset-store.ts, src/lib/layout-composition-skill.ts. Image panels allow multiple active submissions and keep active job cards inside the results column while completed results remain visible. System default model credit deduction is server-side and tied to the selected system_api_configs pricing row. The optional 100 Layout Compositions skill is controlled from admin settings and injects composition guidance into image prompts only when enabled.
Video generation	src/components/create/text-to-video.tsx, src/components/create/image-to-video.tsx, src/components/create/generation-task-list.tsx	src/app/api/generate/video/route.ts. Video panels also allow multiple active submissions and keep active job cards inside the results column.
Reverse prompt	src/components/create/reverse-prompt-panel.tsx	src/app/api/generate/reverse-prompt/route.ts, src/app/api/generate/suggest-prompt/route.ts
Model/provider visibility	src/lib/model-config.ts, src/lib/model-config-types.ts, src/lib/server-api-config.ts	src/app/api/model-config/route.ts, src/app/api/admin/system-apis/route.ts, src/app/api/admin/providers/route.ts, src/app/api/user-api-keys/route.ts
Custom integrations (元界, Agnes, mozheAPI, 智能配置 API)	docs/codex-miaojing/custom-integrations.md first	Then use the feature/bug/API/architecture doc that matches the symptom. Search long-term memory for the exact keyword before changing code. Provider-specific built-in template management such as Agnes AI belongs in the 系统默认模型 flow, not in generic smart import.
User auth/login/register/profile	src/lib/session-auth.ts, src/lib/auth-store.ts	src/app/api/auth/*, src/app/api/profile/*
Admin console	src/app/console/page.tsx, src/app/console/dashboard/page.tsx, src/modules/console/pages/*	src/components/admin/*, src/app/api/admin/*
Canvas (legacy, disabled in UI)	src/app/canvas/page.tsx, src/components/canvas/infinite-canvas-workspace.tsx, src/components/canvas/react-flow-canvas.tsx	/canvas intentionally returns 404 and navbar must not show 画布; legacy source/API files remain only for future cleanup or explicit re-enable work.
Gallery and creation history	src/app/gallery/page.tsx, src/app/profile/page.tsx, src/components/profile/creation-history-tab.tsx, src/components/image-metadata-badge.tsx	src/lib/creation-history-store.ts, src/lib/media-storage.ts, src/lib/gallery-publish-media.ts, src/app/api/gallery/*, src/app/api/creation-history/route.ts. Gallery is server-authoritative: do not merge browser localStorage published/history records into the public gallery feed and do not auto-sync historical local published records on gallery page load. The gallery page must not request the full gallery at once; it uses small /api/gallery pages, browser-visible lazy image loading, and an IntersectionObserver sentinel to append more works as the user scrolls. It keeps a bounded browser localStorage list cache for instant first paint, then revalidates page 0 in the background so new/deleted works replace cached rows quickly. Gallery/detail/history image previews show actual ratio and natural resolution in the upper-right badge and should render `thumbnailUrl
Local/object files/downloads	src/lib/local-storage.ts, src/lib/media-storage.ts, src/lib/media-watermark*.ts, src/app/api/local-storage/[...path]/route.ts	src/app/api/download/route.ts, src/proxy.ts, scripts/storage-sync-to-object.mjs, scripts/rainyun-ros-prepare.mjs. Public URLs stay /api/local-storage/<key> while the backend can be STORAGE_MODE=local, dual, or object; new image originals can be written object-only, while compressed high-quality WEBP thumbnails are local-only under thumbnails/... and must be served from local disk directly. Generated work media is watermarked server-side before display/download for normal users, using public/watermark/miaojing-watermark-logo.png plus MIAOJING AI; display requests for generated image originals may redirect to an existing local thumbnail first so pages do not synchronously watermark multi-megabyte object-backed originals, but downloads still use original media. Do not reintroduce raw object-storage redirects for generated images/videos unless the download route has verified an admin role or a user with profiles.watermark_disabled=true; admins can toggle that flag per user from src/components/admin/user-management-tab.tsx through /api/admin/users. Thumbnail filenames include the resize/quality profile and can be served with long immutable browser cache headers; src/proxy.ts must not override thumbnail or gallery cache headers with global /api no-store. Object-backed non-generated files may redirect to short-lived signed object-storage URLs. When syncing production source, exclude only repo-root /local-storage/, not broad local-storage/, or this source route can be skipped. Rainyun ROS API is a control-plane helper for bucket creation/config generation; runtime file IO still uses S3-compatible OBJECT_STORAGE_*.
Email and policy pages	src/lib/email-service.ts, src/components/site-policy-page.tsx	src/app/api/email/*, src/app/about/page.tsx, src/app/terms/page.tsx, src/app/privacy/page.tsx, src/app/help/page.tsx
Upgrade/deploy/backup	scripts/*, ecosystem.config.cjs	src/app/api/admin/upgrade/route.ts, src/components/admin/system-upgrade-tab.tsx
Data backup/import/export	src/components/admin/data-management-tab.tsx	src/app/api/admin/data-export/route.ts, src/app/api/admin/data-import/route.ts, src/lib/local-storage.ts, scripts/migration-integrity-check.mjs. Export includes _media for storage assets; import restores media through the active storage adapter, remaps custom IDs, runs in a transaction, dedupes works by URL/source URL/media SHA only within the same user_id, and preserves password hashes, encrypted API keys, Manifest paths, and API pricing fields.

Current Known Source Warning

At the time this document was created, the remote source imports @/lib/model-display from:

• src/components/create/text-to-image.tsx
• src/components/create/image-to-image.tsx

But src/lib/model-display.ts is not present after resetting to origin/main. If pnpm run ts-check fails on this import, treat it as a pre-existing source-state issue unless your task is specifically to repair it.

The documentation commit also attempted corepack pnpm run ts-check. It failed before any source edits with:

• missing module/type resolution for ag-psd
• missing module/type resolution for @xyflow/react
• missing @/lib/model-display
• canvas callback implicit-any errors in src/components/canvas/react-flow-canvas.tsx

Before treating ag-psd or @xyflow/react as source bugs, run corepack pnpm install --frozen-lockfile in a clean environment; those may be local dependency-install state. The missing @/lib/model-display file is a source-tree issue at this audited commit.

Required Change Discipline

• Do not bypass auth helpers. Use getAuthenticatedUser, getAuthenticatedUserId, requireAdminUser, or requireAdmin.
• Do not write raw API keys to responses or logs. Use encryption helpers in src/lib/server-crypto.ts and safe mapping functions.
• Do not create ad hoc storage paths. Use src/lib/local-storage.ts, preserve path traversal checks, and keep local/object storage migration compatible with stable /api/local-storage/<key> URLs.
• Do not create a second generation flow without checking src/lib/generation-job-client.ts, src/lib/generation-job-runner.ts, and src/lib/generation-job-worker.ts.
• Do not change admin upgrade behavior without checking both src/app/api/admin/upgrade/route.ts, scripts/admin-upgrade-runner.mjs, scripts/backup-create.sh, and scripts/backup-restore.sh.
• Do not change backup/import/restore behavior without preserving transaction boundaries, media restore behavior, dedupe rules, and pre-restore safety backups.
• Do not change public content rendering without checking both backend persistence (site-config, announcements) and frontend consumers (site-config-sync, policy pages, footer, popup).
• Do not treat a feature as complete until its production update-package path is clear. Hot-update candidates should be limited to payloads the upgrade runner accepts without restart, usually static/public assets. Changes to source code, API routes, server code, dependencies, DB schema or compatibility migrations, environment variables, PM2/runtime config, build scripts, backup/restore scripts, or deployment scripts are cold-update candidates and must preserve package preflight, backup, rollback, rebuild, restart, and /api/health verification.

Documentation Maintenance Rule

Every Codex change must include a documentation impact check. This applies to feature work, refactors, configuration changes, UI copy/behavior changes, API changes, deployment changes, and every bug fix.

If the code or behavior changed in a way that future Codex sessions need to know, update the matching documentation in the same commit. Do not postpone documentation updates.

Required mapping:

• New or changed route: update docs/codex-miaojing/api-reference.md.
• Moved, renamed, or newly important code path: update docs/codex-miaojing/feature-code-index.md.
• Newly discovered regression pattern or repeat bug: update docs/codex-miaojing/bug-location-guide.md.
• New subsystem, persistence model, deployment path, or runtime boundary: update docs/codex-miaojing/architecture.md.
• Changed required Codex workflow, canonical source, validation baseline, or cross-document rule: update CODEX_MIAOJING_MEMORY.md and usually AGENTS.md.

If a code change truly has no documentation impact, state that explicitly in the final response or commit notes. Otherwise, the documentation update is part of the required fix, not optional cleanup.