CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Commands

# Development
pnpm dev:h5                        # Start dev server for H5 (browser)
pnpm dev:mp-weixin                 # Start dev server for WeChat Mini Program
pnpm dev:app                       # Start dev server for native app

# Build
pnpm build:h5:production           # Build H5 for production
pnpm build:h5:custom               # Build H5 to dist/smqjhh5
pnpm build:mp-weixin               # Build for WeChat Mini Program

# Code quality
pnpm type-check                    # Run TypeScript type checking (vue-tsc --noEmit)
pnpm lint                          # Run ESLint
pnpm lint:fix                      # Run ESLint with auto-fix

# API generation (auto-generates src/api/apiDefinitions.ts and src/api/globals.d.ts from OpenAPI spec)
pnpm alova-gen                     # Run alova gen -f

# Git
pnpm commit                        # Run commitizen (git-cz) for conventional commits

Architecture Overview

This is a uni-app 3.0 cross-platform project (Vue 3.4 + TypeScript) targeting WeChat Mini Program, H5, and native app. The project is "city-gather" (智慧社区/城市生活综合服务平台) — a multi-module city services platform.

Build & Toolchain

Vite with @dcloudio/vite-plugin-uni for cross-platform builds
pnpm 9.9.0 with Node >= 22
UnoCSS for utility-first styling (configured via unocss.config.ts)
Sass 1.78.0 as CSS preprocessor
uni-mini-router for routing (auto-generates routes from pages.json)
@uni-ku/pages-json for type-safe pages.json generation from the file system
unplugin-auto-import with auto-imports from: vue, @vueuse/core, pinia, uni-app, uni-mini-router, wot-design-uni, alova/client, plus all src/composables, src/store, src/utils, src/api, src/subPack-xsb/store-xsb

API Layer (`src/api/`)

Powered by Alova 3.3.4 with @alova/adapter-uniapp
src/api/core/instance.ts creates the Alova instance with:
- Auto auth injection (Bearer token or fallback Basic auth)
- GET request cache busting via _t timestamp
- 60s timeout, no response caching
src/api/core/handlers.ts handles responses: 401/403 triggers auto-logout; status >= 400 shows toast
src/api/core/middleware.ts provides delay-loading and global-loading middleware
src/api/apiDefinitions.ts is auto-generated by alova-gen from the backend OpenAPI spec — never edit manually
src/api/createApis.ts creates a global Apis proxy object, auto-imported so Apis.xxx.yyy() works in any file
API types are in src/api/globals.d.ts (also auto-generated)

Routing (`src/router/`)

uni-mini-router generates routes from pages.json via virtual:pages-json
Route guard in src/router/index.ts checks islogin from pages.json metadata
Pages without islogin: true are in the white-list; all other pages require authentication (redirects to smqjh-login)
Special handling for encoded QR-code scan parameters (q param)

State Management (`src/store/`)

Pinia with custom persist plugin (src/store/persist.ts) using uni.getStorageSync/uni.setStorageSync
Key stores: user (auth, profiles, addresses, unified payment/order actions), system (device info, navigation state), theme (follow-system dark/light mode), cart
Stores in src/store/ are auto-imported via unplugin-auto-import, so useUserStore(), useSysStore() etc. are available globally without imports

Page Structure

Main package (5 pages in src/pages/): index (home), classfiy, cart, my, login
10 sub-packages (lazy-loaded): subPack-xsb (supermarket), subPack-smqjh (citizen marketplace), subPack-film, subPack-charge (EV charging), subPack-attractions, subPack-refueling, subPack-djk (health), subPack-videoRights, subPack-common (shared pages like address, after-sales, user-center, payment results)
Each sub-package is defined in vite.config.ts under pagesJson.subPackageDirs

Cross-Platform Conditional Compilation

Uses uni-app preprocessor directives extensively:

// #ifdef H5         — H5 only
// #ifdef MP-WEIXIN   — WeChat Mini Program only
// #ifndef MP-WEIXIN  — Not WeChat Mini Program

Layout System

@uni-helper/vite-plugin-uni-layouts provides file-based layouts
src/layouts/default.vue is the default layout with addGlobalClass, virtualHost, styleIsolation: shared
src/layouts/tabbar.vue for pages with the bottom tab bar

UI Framework

Wot Design Uni (wot-design-uni) for components (auto-resolved via WotResolver)
Custom components in src/components/ are auto-registered via @uni-helper/vite-plugin-uni-components
Global composables for toast, message, loading (wrappers around uni/wot APIs)

Config (`src/config/`)

src/config/index.ts dynamically selects BASE_URL based on:
- H5: uses import.meta.env.MODE (development → local/test server, production → production API)
- WeChat Mini Program: uses uni.getAccountInfoSync().miniProgram.envVersion (develop/trial/release)
Static assets served from Alibaba Cloud OSS (StaticUrl)

Commit Convention

Conventional Commits enforced via commitlint + commitizen
Pre-commit hook: lint-staged runs ESLint --fix on all files
Version releases: pnpm release-patch, pnpm release-minor, pnpm release-major (standard-version)

CLAUDE.md 5.7 KB Historie Surový