Mplan/opencloud
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

重组前端功能目录并统一代码规范工具链 (#10)

Browse Source 
Reviewed-on: #10
This commit was merged in pull request #10.
This commit is contained in:
Mplan
2026-09-29 18:09:38 +08:00
parent 720ad29f06
commit 0af0256c97
101 changed files with 14644 additions and 10309 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+60 -50
View File
@@ -3,57 +3,68 @@
## 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, and typecheck
- `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)
- `npx vue-tsc -b` — standalone typecheck (no script in package.json)
- `npm run typecheck` — standalone Vue / TypeScript typecheck
- `npm run preview` — previews the production build on strict port `5173`
- No general linter, formatter, or test runner exists; `check:styles` is the project-specific visual-system check
- ESLint uses `eslint.config.js`; Prettier uses `.prettierrc.json`. Keep formatting rules in Prettier. No general test runner exists; `check:styles` remains the project-specific visual-system check.
## Architecture
- **Vue 3 + Vite + Tailwind CSS + Vue Router + Pinia + FastAPI + AMap (高德地图) + Naive UI**
- Path alias `@/` → `src/` (configured in both `vite.config.ts` and `tsconfig.app.json`)
- FastAPI client at `src/lib/api.ts`; API base URL comes from `VITE_API_URL`
- AMap loaded lazily via `src/lib/amap.ts` with type declarations in `src/types/amap.d.ts`
- 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 FastAPI backend
## Directory Map
| Path | Purpose |
| --- | --- |
| `src/lib/` | Singletons and utilities: FastAPI client, amap, canvas patch, cloudTypes constants, cloudBadges canvas renderer, SEO meta builder |
| `src/stores/` | Pinia stores: auth, clouds (cloud_types cache), encyclopedia (collection + unlock tracking), profile (user pages + cloud CRUD) |
| `src/composables/` | Vue composables: `useUpload` (batch multipart upload, EXIF extraction, badge result handling) |
| `src/components/cloud/` | Cloud-related modals and widgets: ImageDetailModal, CloudEditModal, MapPickerModal, QuickUploadModal, MiniLocationMap |
| `src/components/layout/` | AppHeader (top nav bar with auth state) |
| `src/components/profile/` | ContributionHeatmap |
| `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/views/` | Route-level page components (see Routes below) |
| `src/types/` | TypeScript types: domain models (`database.ts`), API DTOs (`api.ts`), AMap declarations (`amap.d.ts`), router meta (`router.d.ts`) |
| `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 |
| 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/` | Shared domain models (`database.ts`), API DTOs (`api.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 |
| 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`
@@ -117,7 +128,6 @@
- **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 default `CORS_ORIGINS` and `FRONTEND_URL`.
- **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`.
- **`lib/canvas.ts`**: patches `HTMLCanvasElement.getContext('2d')` to always pass `willReadFrequently: true` — needed for the badge card renderer in `lib/cloudBadges.ts`.
## Environment Variables
@@ -137,11 +147,11 @@ Backend-only variables such as database credentials, JWT secrets, SMTP settings,
- 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
- 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`.
@@ -160,18 +170,18 @@ Backend-only variables such as database credentials, JWT secrets, SMTP settings,
- 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
- `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
- `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`
- `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.