kami_frontend/CLAUDE.md

<!-- OPENSPEC:START -->

# 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.

<!-- OPENSPEC:END -->

# 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                # Start Vite dev server with development config

# Build for production
pnpm build              # TypeScript compilation + Vite build with production config

# Type checking
pnpm type:check         # TypeScript + Vue type checking without emitting files

# Linting and formatting
pnpm lint               # Run all linting (ESLint + Stylelint + Prettier)
pnpm lint:fix           # Auto-fix all linting issues
pnpm eslint             # ESLint only (targets src,mock,config directories)
pnpm eslint:fix         # Fix ESLint issues only
pnpm prettier           # Check Prettier formatting
pnpm prettier:fix       # Fix Prettier formatting
pnpm stylelint          # Stylelint only (processes **/*.{html,vue,css,less})
pnpm stylelint:fix      # Fix Stylelint issues

# API generation
pnpm generate:api       # Generate TypeScript API client from OpenAPI spec at http://127.0.0.1:12401/api.json

# Cache and dependencies
pnpm clean:cache        # Clear .eslintcache 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
- `jdCookieClient` - JDCookieManagementApi for JD cookie management
- `jdHistoryClient` - JDHistoryApi for JD order history
- `jdOrderClient` - JDOrderManagementApi for JD order management

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

Uses OpenAPI Generator CLI to create TypeScript clients from `http://127.0.0.1:12401/api.json`. Generated client structure:

- Separate models and APIs packages with tag-based grouping
- TypeScript/axios generation with square brackets in array names
- Single request parameter and string enums enabled

### Component Registration

Global components are auto-registered via `src/components/index.ts`

### Path Aliases

Configured in `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: `http://127.0.0.1:12401` (configured in `.env.development`)
- Production: Uses `VITE_API_BASE_URL` from `.env.production` (currently empty)

### Code Quality

**Linting Tools**:

- ESLint: JavaScript/TypeScript linting (`src,mock,config` directories)
- Stylelint: CSS/Less linting (`**/*.{html,vue,css,less}`)
- Prettier: Code formatting (`src/**/*.{js,ts,json,tsx,css,scss,vue,html,md}`)

**Git Integration**:

- Husky for Git hooks
- Lint-staged for pre-commit checks with file-specific rules
- Commitlint for conventional commits
- All linting runs automatically on pre-commit

**Engine Requirements**:

- Node.js: `^18.0.0 || >=20.0.0`
- pnpm: `>=8.11.0` (package manager set to `pnpm@10.11.0`)

## Development Patterns

### API Calls

Use generated API clients from `src/api/generated/` or manual definitions from `src/api/*.ts`. All API calls go through axios interceptors for authentication handling.

### Component Structure

Follow Vue 3 Composition API patterns with `<script setup>` syntax. Use Arco Design components for UI consistency.

### State Management

- Pinia stores for shared application state (modules: app, user, tab-bar)
- TanStack Query for server state management and caching

### Build Configuration

Multi-environment Vite setup:

- `config/vite.config.base.mts` - Shared base configuration
- `config/vite.config.dev.mts` - Development server configuration
- `config/vite.config.prod.mts` - Production build configuration

Build pipeline: TypeScript compilation (`vue-tsc --noEmit`) → Vite bundling