# OpenSpec Instructions These instructions are for AI assistants working in this project. Always open `@/openspec/AGENTS.md` when the request: - Mentions planning or proposals (words like proposal, spec, change, plan) - Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work - Sounds ambiguous and you need the authoritative spec before coding Use `@/openspec/AGENTS.md` to learn: - How to create and apply change proposals - Spec format and conventions - Project structure and guidelines Keep this managed block so 'openspec update' can refresh the instructions. # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a Vue 3 frontend application built with Arco Design Pro, TypeScript, and Vite. The project is a management system for various card/account services including Apple Card, JD accounts, Walmart accounts, and T-Mall game accounts. ## Development Commands ```bash # Development server pnpm dev # Build for production pnpm build # Runs type check then builds # Type checking pnpm type:check # TypeScript and Vue type checking # Linting and formatting pnpm lint # Run all linting checks (ESLint + Stylelint + Prettier) pnpm lint:fix # Fix all linting issues automatically pnpm eslint # ESLint only pnpm eslint:fix # Fix ESLint issues pnpm prettier # Check Prettier formatting pnpm prettier:fix # Fix Prettier formatting pnpm stylelint # Stylelint only pnpm stylelint:fix # Fix Stylelint issues # API generation pnpm generate:api # Generate TypeScript API client from OpenAPI spec # Cache and dependencies pnpm clean:cache # Clear ESLint cache and reinstall dependencies pnpm lint-staged # Run lint-staged (used by pre-commit hooks) ``` ## Architecture ### Core Stack - **Framework**: Vue 3 with Composition API - **UI Library**: Arco Design Vue - **State Management**: Pinia - **Router**: Vue Router 4 - **Data Fetching**: TanStack Vue Query + Axios - **Build Tool**: Vite - **Language**: TypeScript - **Package Manager**: pnpm ### Directory Structure ``` src/ ├── api/ # API layer with manual and generated clients │ ├── generated/ # Auto-generated API clients from OpenAPI │ └── *.ts # Manual API definitions for different services ├── components/ # Reusable Vue components │ ├── navbar/ # Navigation bar components │ ├── tab-bar/ # Tab navigation │ ├── menu/ # Menu components │ └── ... ├── views/ # Page components organized by feature │ ├── dashboard/ # Dashboard pages │ ├── login/ # Authentication pages │ ├── merchant/ # Merchant management │ ├── card-*/ # Various card management (apple, jd, walmart, etc.) │ └── user-center/ # User management ├── store/ # Pinia stores │ └── modules/ # Separate store modules (app, user, tab-bar) ├── router/ # Vue Router configuration │ ├── routes/ # Route definitions │ └── guard/ # Route guards ├── utils/ # Utility functions ├── types/ # TypeScript type definitions ├── hooks/ # Vue 3 composables ├── plugins/ # Vue plugins (TanStack Query setup) └── layout/ # Layout components ``` ### API Architecture The project uses a dual API approach: 1. **Manual API definitions** in `src/api/*.ts` for specific services 2. **Generated API client** from OpenAPI spec in `src/api/generated/` API clients are configured in `src/api/index.ts`: - `apiClient` - DefaultApi for main backend operations - `apiCkClient` - CkApi for CK-related operations API base URL is configured via environment variables: - Development: `http://127.0.0.1:12401` - Production: Set in `.env.production` The API client generation uses: - Input: `http://127.0.0.1:12401/api.json` - Generator: `typescript-axios` - Output: Separate models and APIs packages with tag-based grouping ### State Management Uses Pinia with modular stores: - `useAppStore` - Application-wide settings - `useUserStore` - User authentication and profile - `useTabBarStore` - Tab navigation state ### Authentication - JWT token-based authentication stored in local storage - Automatic token refresh via response interceptors - Route guards protect authenticated pages - Token expiration handling with user prompts ### Key Features - Multi-service card/account management platform - Real-time dashboard with charts (ECharts integration) - Role-based access control - Responsive design with Arco Design components - CodeMirror integration for code editing - Milkdown integration for rich text editing ## Development Notes ### API Generation The project uses OpenAPI Generator to create TypeScript clients: ```bash pnpm generate:api ``` This generates clients from `http://127.0.0.1:12401/api.json` ### Component Registration Global components are auto-registered via `src/components/index.ts` ### Path Aliases Configured in Vite config (`config/vite.config.base.mts`): - `@/*` maps to `src/*` - `assets` maps to `src/assets` - `vue` maps to `vue/dist/vue.esm-bundler.js` (for template compilation) ### Environment Configuration Development settings in `.env.development`, production in `.env.production` ### Code Quality - ESLint for JavaScript/TypeScript linting (targets `src,mock,config` directories) - Stylelint for CSS/Less linting (processes `**/*.{html,vue,css,less}`) - Prettier for code formatting (processes `src/**/*.{js,ts,json,tsx,css,scss,vue,html,md}`) - Husky for Git hooks - Lint-staged for pre-commit checks (configured with file-specific linting rules) - Commitlint for conventional commits **Note**: All linting tools are configured to run automatically via lint-staged on pre-commit hooks. ## Common Patterns ### API Calls Use generated API clients or manual definitions from `src/api/`. All calls go through axios interceptors for auth handling. ### Component Structure Follow Vue 3 Composition API patterns with `