kami_frontend/CLAUDE.md

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

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

# Git hooks
pnpm prepare            # Install Husky git 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
• camelOilAccountClient - CamelOilAccountApi for camel oil account management
• camelOilOrderClient - CamelOilOrderApi for camel oil order management

API base URL is configured via environment variables:

• Development: http://127.0.0.1:12401 (configured in .env.development)
• Production: Uses VITE_API_BASE_URL from .env.production (currently empty)

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
• Features: Square brackets in array names, single request parameter, string enums enabled

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) with modern flat config
• Stylelint: CSS/Less linting (**/*.{html,vue,css,less})
• Prettier: Code formatting (src/**/*.{js,ts,json,tsx,css,scss,vue,html,md})

ESLint Configuration:

• Uses modern flat config in eslint.config.js
• TypeScript support with inline type imports
• Vue 3 Composition API support
• Prettier integration for consistent formatting
• Allows explicit any types and non-null assertions

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