opencloud/AGENTS.md

AGENTS.md

Commands

• npm run dev — Vite dev server with HMR
• npm run lint / npm run lint:fix — ESLint checks / automatic fixes for JS, TS, and Vue; warnings fail the check
• npm run format:check / npm run format — Prettier check / formatting for source, config, and docs
• npm run check — lint, formatting, style contracts, typecheck, and communication tests
• npm run check:styles — validates shared style contracts and blocks deprecated palettes/classes
• npm run build — vue-tsc -b && vite build (typecheck must pass or build aborts)
• npm run typecheck — standalone Vue / TypeScript typecheck
• npm run preview — previews the production build on strict port 5173
• ESLint uses eslint.config.js; Prettier uses .prettierrc.json. Keep formatting rules in Prettier. Communication tests use Node’s built-in runner (npm test, Node 22.18+); check:styles checks the visual system.

Architecture

• Vue 3 + Vite + Tailwind CSS + Vue Router + Pinia + Hono + Better Auth + AMap (高德地图) + Naive UI
• Path alias @/ → src/ (configured in both vite.config.ts and tsconfig.app.json)
• HTTP transport at src/lib/api.ts; business calls in features/{clouds,profile,admin}/api.ts; API base URL comes from VITE_API_URL
• AMap loaded lazily via src/shared/map/amap.ts with type declarations in src/shared/map/types/amap.d.ts
• UI language is Chinese (zh-CN)
• All persistence, storage, authorization, and admin operations go through the Hono backend

Directory Map

Path	Purpose
src/features/	Business modules; each owns its route views, components, stores, and composables as needed
src/features/auth/	Auth views, auth store, and Better Auth client
src/features/clouds/	Shared cloud detail/edit/like components, cloud-type and likes stores, cloud-type constants
src/features/upload/	UploadView, QuickUploadModal, and useUpload
src/features/profile/	Profile views, profile store, and ContributionHeatmap
src/features/encyclopedia/	Encyclopedia views and encyclopedia store
src/features/{map,gallery,community,admin,system}/views/	Remaining route views grouped by feature
src/shared/map/	Reusable location picker and mini map, AMap loader, and AMap declarations
src/lib/	Shared infrastructure: API client and adapters, SEO meta builder, Naive UI theme
src/components/layout/	AppHeader (top nav bar with auth state)
src/style.css	Global stylesheet assembly point; imports Tailwind, tokens, base rules, and shared components
src/styles/	Visual system source: semantic tokens, global square-corner baseline, shared oc-* component contracts
src/lib/theme.ts	Naive UI theme overrides aligned with the semantic tokens
src/router/	Route registration, lazy view imports, guards, and per-route SEO
src/types/	Frontend models (models.ts, view-models.ts), generated HTTP DTOs (api-contract.ts), and router meta (router.d.ts)
docs/project-structure.md	File ownership, dependency conventions, and examples for placing new code
docs/style-system.md	Concise implementation and naming guide for the visual system
scripts/check-style-system.mjs	Automated guard against deprecated palettes and malformed shared classes

• When adding or moving source files, follow docs/project-structure.md: colocate business code under its owning feature; keep reusable location primitives in shared/map and application layout in components/layout.
• Import concrete files directly; route views remain lazy imports in src/router/index.ts.

Routes

Path	View	Auth Required
/	MapView	No
/login, /register, /forgot-password, /auth/confirm, /auth/reset-password	Auth views	No
/upload	UploadView	Yes
/encyclopedia	EncyclopediaView	Yes
/encyclopedia/:id	CloudTypeView	Yes
/gallery	GalleryView	No
/community	CommunityView	No
/profile	ProfileView (own)	Yes
/profile/settings	ProfileSettingsView	Yes
/profile/:id	ProfileView (public)	No
/admin	AdminView	Yes (admin)
/403	ForbiddenView	No
/401	AuthRequiredView	No
/:pathMatch(.*)*	NotFoundView	No

• Route guards in router/index.ts: requiresAuth redirects to /401 with the intended URL in the redirect query; requiresAdmin redirects to /403
• SEO meta tags applied per-route via lib/seo.ts in router.afterEach

Auth Flow

• main.ts calls authStore.initialize() before mounting: Better Auth checks the session cookie and then loads /profiles/me.
• The backend manages HttpOnly session cookies; browser requests use credentials: 'include'.
• features/auth/authClient.ts owns Better Auth SDK configuration and error adaptation. No custom access-token refresh or automatic mutation retry.
• Required business requests receiving 401 dispatch opencloud:auth-expired, which clears Pinia auth state. Public requests use { auth: false } to suppress that event.
• Email confirmation and password reset consume the backend’s opaque token query parameter. Passwords require at least 8 characters.

Stores

• auth — User session, profile, login/register/logout, username/password update, password reset. initialize() must be called before app mounts.
• clouds — Simple cache of cloud types returned by GET /cloud-types. Fetched once and shared across views.
• encyclopedia — Cloud-type catalog cache for encyclopedia pages; numeric rarity comes from the backend.
• profile — User profile pages. Fetches profile + cloud list per-user. Supports update/delete/visibility-toggle with optimistic cache patching; backend deletion also removes stored files.

Backend and API Conventions

• Current backend: sibling ../hono-api (Hono + Better Auth + PostgreSQL + object storage), default http://localhost:3000.
• When changing requests, DTOs, pagination, or authentication, read docs/api-architecture.md; the backend API.md lists endpoints and migration details.
• Views/stores call their feature API module; only feature API modules call lib/api.ts. Better Auth SDK calls stay in the auth module.
• Backend src/schemas/ generates contracts/api.ts; run frontend npm run api:sync to update src/types/api-contract.ts. For coordinated changes, run backend contract:check and frontend api:check; do not hand-edit generated DTOs.
• Use query objects, plain JSON bodies, and typed upload input. The API module handles URL encoding and FormData construction.
• Business JSON uses snake_case and ISO UTC date strings. Pagination returns items/page/page_size/has_more; use the explicit flag for navigation.
• Business errors use {message, issues?}; Better Auth keeps its SDK protocol. ApiError preserves HTTP status and error details.
• Batch mutations accept at most 100 UUID strings; feature API modules split larger selections. Completed batches remain applied after later failures.
• Backend permissions enforce ownership, verified sessions, roles, and disabled accounts; route guards provide navigation UX only.

Gallery Pagination

• Page-based navigation, 50 items/page, with a 250ms search debounce.
• Backend resolves cloud-type names and @username searches. Next-page availability comes from has_more.

Map Timeline

• Realtime mode: slider selects a minute of today, shows clouds captured within 2 hours before that time. Marker opacity decays with age.
• Archive mode: browse clouds by day or month. Toggling timeline controls closed auto-returns to realtime.
• Slider resets to current time each time the controls panel is opened.

Upload Flow

• useUpload handles selection, previews, EXIF dates, validation, sequential uploads and progress. The cloud API module encodes multipart data; the backend creates previews, stores variants and inserts records. Coordinates are blurred by the current frontend forms.
• Batch items upload sequentially. If a later item fails, earlier successful uploads remain saved; there is no transactional rollback or resumable upload in the frontend.
• UploadView is the full-page batch uploader. QuickUploadModal is a single-image shortcut from the map page.

Build & Deploy

• Vercel with vercel.json: SPA rewrites, security headers (X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy). No CSP or HSTS configured.
• Vite dev and preview servers both use strict port 5173, matching the backend’s CORS_ORIGIN development setting.
• SEO plugin in vite.config.ts: generates robots.txt and sitemap.xml at build time. Auth-only routes, including /encyclopedia, are excluded from the sitemap and disallowed in robots.txt.

Environment Variables

Required for map features:

• VITE_AMAP_KEY

Optional:

• VITE_API_URL — Hono root URL (defaults to http://localhost:3000, without /api/v1)
• VITE_SITE_URL — canonical frontend URL used by route SEO and generated sitemap; set it explicitly in deployed environments

Backend-only variables such as database credentials, Better Auth secrets, email-provider settings, cookie policy, CORS origins, and object-storage settings belong in ../hono-api/.env, never in the Vite environment.

Visual System

• The design language is a clean sky atlas: airy sky-blue surfaces, fresh eucalyptus green, square editorial panels, pixel-cloud identity, and hard offset shadows.
• Read .agents/skills/opencloud-style/SKILL.md before material visual changes. Treat src/styles/tokens.css, src/styles/base.css, src/styles/components.css, and src/lib/theme.ts as the implementation sources of truth.
• Shared/stable decisions belong in layers:
  • tokens and palette remapping → src/styles/tokens.css
  • global baseline and square-corner policy → src/styles/base.css
  • cross-page semantic classes → src/styles/components.css
  • feature-specific map/slider/media details → the component's scoped style
  • one-off layout and responsive composition → Tailwind in the template
• The global interface is square by default. Ordinary cards, inputs, dropdowns, buttons, modals, and map controls use 0px radius. Circular marker dots, media overlay controls, AMap-generated bubbles/cards, and the media-focused image-detail shell are explicit exceptions.
• Use hard zero-blur offset shadows (--oc-shadow-xs through --oc-shadow-xl) for ordinary UI depth. Interactive controls may lift by translate(-1px, -1px) on hover.
• Brand/interaction green is fresh eucalyptus: main #34745d, dark #274c40, light surface #f2faf6.
• Success green is a distinct leaf green: main #4d7f3b, dark #35522c, light surface #f4faef.
• Existing teal-* and emerald-* Tailwind class names are compatibility aliases remapped in tokens.css; do not assume Tailwind's default values.
• Do not introduce Tailwind green-*/lime-*, vivid default teal, purple, indigo, or generic gray palettes. Use slate, sky, remapped teal/emerald, amber, and rose according to semantic purpose.
• The header brand mark is the pixel cloud/sun SVG inside a square 40px sky-100 surface with a sky-200 border and neutral 4px hard shadow. Do not replace it with emoji or give it a green background.
• Map floating buttons use oc-map-button: square 40px × 40px, white background, slate border, 0px radius, and a hard shadow even when disabled.
• For material visual changes, inspect representative desktop and real 375px mobile screenshots and verify there is no horizontal overflow.

Naive UI

• Used for modals, buttons, inputs, tags, progress bars, alerts, dropdowns, empty states, skeletons, and message toasts.
• No SSR — pure client-side rendering.
• Custom CSS overrides via scoped <style> blocks for slider styling, transitions, and component tweaks.
• Global overrides are defined in src/lib/theme.ts and mounted by App.vue; keep brand/success colors aligned with src/styles/tokens.css.
• Do not rely on default Naive UI primary/secondary colors for page CTAs or panel actions. Use the shared classes in src/styles/components.css.
• Auth buttons use oc-primary-button with semantic variants:
  • oc-primary-button--teal — login / account-access actions
  • oc-primary-button--sky — register / create / forward actions
• Panel and utility buttons use oc-panel-button with semantic variants:
  • oc-panel-button--neutral — white card-style utility actions
  • oc-panel-button--sky — primary panel actions
  • oc-panel-button--teal — active toggles / confirm actions
  • oc-panel-button--danger — destructive actions
  • oc-panel-button--amber — admin/state-toggle actions where warning emphasis fits better than danger
• Card-like containers should prefer shared shadow classes instead of ad-hoc shadows:
  • oc-panel-card
  • oc-panel-card-soft
  • oc-empty-card
• When styling NButton, prefer type="default" plus the shared class when a custom panel button variant is intended. Otherwise Naive UI theme variables may override white backgrounds or semantic colors.
• Primary and panel actions use dark text on light semantic surfaces; do not assume primary buttons should use white text.

Visual Notes

• The site icon and header brand mark are a matching pixel-style cloud motif on a light sky-blue square; avoid emoji or unrelated icon styles for primary brand surfaces.
• Header action buttons use slight hover lift (translate(-1px, -1px)) with hard-offset shadow growth; new header-like actions should follow that interaction pattern.
• Heatmap view toggles in ContributionHeatmap intentionally use separate buttons with gap spacing instead of NButtonGroup, because grouped buttons visually collide once hard shadows and hover transforms are applied.
• Reuse existing oc-* classes before duplicating Tailwind bundles. New shared modifiers must always appear with their base class.
• Validate style work with npm run check:styles, git diff --check, and npm run build.

MVP Constraints

• No realtime updates — refresh-based loading
• No OAuth — email/password only, email confirmation required
• No AI cloud identification — manual type selection
• AMap only (China-focused), no Mapbox fallback yet