# 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`
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, or bug-diagnosis path, update the corresponding document in the same commit.
7. 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.

## 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/app/api/style-presets/route.ts`, `src/lib/style-preset-store.ts`. Image panels allow multiple active submissions and keep active job cards inside the results column. |
| 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` |
| 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/app/api/gallery/*`, `src/app/api/creation-history/route.ts`. Gallery/detail image previews show actual ratio and natural resolution in the upper-right badge. History also refreshes on `miaojing_auth_updated` after login/account switch. |
| Local files/downloads | `src/lib/local-storage.ts`, `src/app/api/local-storage/[...path]/route.ts` | `src/app/api/download/route.ts` |
| 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`. Export includes `_media` for local-storage assets; import restores media, remaps custom IDs, runs in a transaction, and dedupes works by URL/source URL/media SHA. |

## 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` and preserve path traversal checks.
- 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.
