searcher/.codex/skills/wallora-searcher/references/project.md

# Wallora Searcher Project Reference

## Snapshot

- Root: `/Users/luoyangwei/Documents/workspace/wallora.top/searcher`
- Package: `searcher`
- Framework: Next.js `16.2.6` with App Router
- React: `19.2.4`
- Styling: Tailwind CSS v4 via `@import "tailwindcss";`
- TypeScript: enabled
- Package manager: `pnpm`
- Git: this directory is not currently a Git repository
- Intended UI system: shadcn/ui
- Intended data store: Supabase with `wg_` table prefixes for project-owned tables
- Intended image store: Aliyun OSS
- Intended auth foundation: NextAuth plus JWT authorization for public APIs
- Intended API documentation: `swagger.yaml`

## Important Files

- `app/layout.tsx`: root HTML shell, metadata, body layout classes, CSS-variable font tokens
- `app/(site)/page.tsx`: public website home page
- `app/(admin)/admin/login/page.tsx`: public admin login page
- `app/(admin)/admin/(protected)/...`: admin pages that require a NextAuth session
- `app/(admin)/admin/(protected)/gallery/page.tsx`: admin gallery picker with picked/color filters
- `app/(admin)/admin/(protected)/collections/page.tsx`: admin collections CRUD surface
- `components/admin/collections/CollectionsManager.tsx`: create/edit/delete published collections from picked photos
- `app/api/admin/gallery-photos/route.ts`: protected admin gallery list and pick/unpick endpoint
- `app/api/admin/photo-collections/route.ts`: protected admin collection list/create API
- `app/api/admin/photo-collections/[id]/route.ts`: protected admin collection read/update/delete API
- `app/api/v1/gallery/photos/route.ts`: public picked-photo API for waterfall pagination
- `app/api/v1/gallery/photos/[id]/route.ts`: public picked-photo detail API plus favorite/unfavorite shortcut
- `app/api/v1/gallery/collections/route.ts`: public published collection list API
- `app/api/v1/gallery/collections/[slug]/route.ts`: public published collection detail API with paginated photos
- `app/api/v1/auth/register/route.ts`: app user email/password registration
- `app/api/v1/auth/login/route.ts`: app user email/password login and Bearer JWT issuance
- `app/api/v1/users/me/route.ts`: current app user profile from Bearer JWT
- `app/api/v1/users/me/favorites/...`: app user favorites list/add/remove APIs
- `app/api/v1/users/me/settings/route.ts`: app user preferences and download preferences APIs
- `app/(admin)/admin/(protected)/users/page.tsx`: protected admin app user list
- `components/admin/users/UsersManager.tsx`: admin app user list with enable/disable actions
- `app/api/admin/app-users/[id]/route.ts`: protected admin app user status update API
- `app/api/cron/gallery-photos/route.ts`: protected gallery sync trigger endpoint
- `app/globals.css`: Tailwind import, CSS variables for background/foreground, font theme tokens
- `package.json`: scripts and dependencies
- `next.config.ts`: Next.js config
- `public/`: starter SVG assets from create-next-app
- `swagger.yaml`: create or update when public API contracts are introduced or changed
- `supabase/migrations/`: SQL migration scripts, including `wg_` gallery tables
- `scripts/sync-gallery-photos.mjs`: one-shot gallery sync script for server cron/process managers

## Commands

```bash
pnpm dev
pnpm lint
pnpm build
pnpm start
pnpm sync:gallery
```

Use `pnpm format:check`, `pnpm lint`, and `pnpm build` for verification. Use `pnpm sync:gallery` only when intentionally touching the real Supabase database.

## Current Baseline Notes

- The public home page still contains create-next-app starter content unless updated later.
- The admin dashboard uses shadcn `dashboard-01` under `/admin/dashboard`.
- The admin login page uses shadcn `login-03` and NextAuth credentials under `/admin/login`.
- The admin gallery supports picked/unpicked filters, color-family filters, pick/unpick actions, and OSS mirror status.
- The admin collections page supports create, edit, delete, publish/draft status, cover selection, and selecting photos from picked photos.
- Public photo consumption should use `/api/v1/gallery/photos`, which returns picked photos only.
- App photo detail should use `/api/v1/gallery/photos/{id}`. Public callers can omit auth; authenticated callers receive `isFavorited` and can `POST`/`DELETE` the same route to favorite/unfavorite.
- Public collection consumption should use `/api/v1/gallery/collections` and `/api/v1/gallery/collections/{slug}`; collection photos are picked photos only.
- App users register and login with email/password via `/api/v1/auth/register` and `/api/v1/auth/login`; the returned Bearer JWT is for public app APIs only.
- App user favorites and settings live under `/api/v1/users/me/...`.
- Admins can review app users and enable/disable accounts under `/admin/users`.
- Bare `/dashboard` and `/login` routes should stay absent; admin templates belong under `/admin`.

## Coding Conventions

- Keep components typed with TypeScript and follow existing double-quote import style.
- Prefer server components unless client behavior is necessary.
- Put global tokens and truly global styles in `app/globals.css`; keep page-specific styling near components with Tailwind classes.
- Keep font tokens in CSS variables; avoid `next/font/google` unless the deployment environment can reliably fetch Google Fonts during build.
- Avoid broad dependency additions for small UI tasks; use the platform and existing stack first.
- Use `pnpm dlx shadcn@latest ...` for shadcn CLI tasks.
- Verify current Supabase, NextAuth, and Aliyun OSS APIs before implementing auth-sensitive or storage-sensitive behavior.
- For database objects created by this app, use the `wg_` prefix, e.g. `wg_gallery_photos`.
- Do not read or print secrets from `.env.local`; report only whether required variables are present.
- This project is not targeting Vercel. Prefer server cron, process manager jobs, or external scheduler calls over `vercel.json` cron config.

## Design Conventions

- Replace starter content with domain-specific product UI when asked to build the app experience.
- Keep cards at `8px` radius or less unless a future design system says otherwise.
- Do not nest cards inside cards.
- Avoid one-note palettes and generic purple/blue gradient-heavy layouts.
- Make text fit inside controls and panels at mobile and desktop widths.

## Architecture Summary

- Public API: available to external users; use JWT login/authorization and document routes in `swagger.yaml`.
- Admin: account/password login; use NextAuth sessions to persist login state and gate admin features.
- Public website: open internet access; optimize for SEO, metadata, crawlability, and performance.
- Supabase stores application data with `wg_` table prefixes; Aliyun OSS stores image files while Supabase stores image metadata.
- Gallery photo ingestion writes to `wg_gallery_photos` and tracks progress in `wg_gallery_sync_state`.
- Picked photo metadata lives on `wg_gallery_photos` via `is_picked`, `picked_at`, `picked_by`, and `oss_*` fields.
- Collections live in `wg_photo_collections` and `wg_photo_collection_items`.
- App users/favorites/settings live in `wg_app_users`, `wg_user_favorites`, and `wg_user_settings`; identity fields include email now and schema placeholders for phone/WeChat later.