# CLAUDE.md

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

## Project Overview

AutoShopee Kit is a browser extension for e-commerce automation on Shopee, Lazada, TikTok, and Tiki.

- Current version: `3.4.3`
- Browser support: Chrome 88+, Firefox 78+
- Manifest: V3 (Chrome), V2 (Firefox)
- Frontend architecture: Vue 2 Options API only (do NOT use Composition API)

## Commands

```bash
npm run dev              # Development with HMR (Vite dev server, auto-opens Chrome)
npm run dev:firefox      # Development for Firefox
npm run dev:tool         # Development with Vue DevTools
npm run build:chrome     # Build for Chrome (MV3)
npm run build:firefox    # Build for Firefox (MV2)
npm run build:prod       # Production build (Chrome)
npm run zip:chrome       # Build + zip Chrome extension
npm run zip:firefox      # Build + zip Firefox extension
npm run zip:s3           # Upload zip to S3
npm run lint             # ESLint check
npm run lint:fix         # ESLint autofix
npm run format           # Prettier + ESLint fix combined
npm run pretty           # Prettier only
```

## Architecture

### Entry Points (WXT file-based)
- **Popup**: `entrypoints/popup/main.js` — extension popup UI
- **Options**: `entrypoints/options/main.js` — full options/settings page
- **Background**: `entrypoints/background.js` — wraps `src/background/index.js`
- **Content Scripts**: `entrypoints/*.content.js` — wrappers that import logic from `src/content/`

### Path Aliases
- `@` → `src/app/`
- `@content` → `src/content/`
- `@background` → `src/background/`
- `@type` → `src/app/types/`

### Source Structure (`src/app/`)
- `api/` — HTTP clients per platform (Shopee, Lazada, TikTok, AutoShopee internal API). Uses Axios.
- `bridge/` — webext-bridge wrappers for messaging between background, content scripts, and popup/options
- `store/` — Vuex store (primary state management)
- `pinia/` — Pinia stores (supplementary, for shop/seller/usage/settings)
- `components/` — Vue components organized by platform (Shopee/, Lazada/, Tiktok/) and function (Layout/, Plugin/, Widget/)
- `views/` — Vue pages/views organized by platform
- `router/` — Vue Router configuration
- `plugins/` — Vue plugins: i18n, logger, KV storage, settings
- `models/` — Data models for products, orders, shops
- `service/` — Business logic services
- `adapter/` — Platform adapters (Shopee, TikTok)
- `types/` — JSDoc type definitions (all types go here, not inline)
- `validator/` — Joi validation schemas
- `socket/` — Socket.io real-time communication
- `lib/` — Utility functions
- `mixin/` — Vue mixins
- `constant/` — Constants and enums
- `data/` — Static data and templates

### Extension Communication
- **Background ↔ Content/Popup**: `webext-bridge` (`sendMessage`/`onMessage`)
- **Real-time sync**: Socket.io
- **Local DB**: PouchDB (syncs with CouchDB remote)
- **State persistence**: `vuex-persistedstate`, `pinia-plugin-persistedstate`

### Build System
- WXT 0.20.20 (Vite-based browser extension framework)
- `wxt.config.ts` defines manifest, aliases, and Vite plugins
- Content scripts are file-based entrypoints (`entrypoints/*.content.js`) — auto-detected by WXT
- HMR for popup/options pages, auto-reload for content scripts and background
- MV3 (Chrome) / MV2 (Firefox) handled automatically by WXT
- CI/CD via Drone (`.drone.yml`) — triggers on push to `dev` branch

## Code Conventions

- **Vue 2 Options API only** — no Composition API
- **JSDoc types only** — define all types in `src/app/types/`, use `@param {import('@/types/...')}` syntax. No inline type descriptions.
- **No inline comments** describing what code does
- **Braces required** for all `if` statements
- **No ternary operators** — use full `if/else` blocks
- **Each condition on its own line**
- **Do not split files** when refactoring — keep code in existing files
- **PascalCase** for component names, **camelCase** for props
- **UI framework**: View Design (iView for Vue 2)
- **CSS**: Tailwind CSS + SASS

## Documentation

Project docs are organized in `docs/`:

### Index
- `docs/README.md` — project intro, current version, feature overview, full doc index

### Development (`docs/dev`)
- `docs/dev/README.md` — index of nested dev docs
- `docs/dev/overview/architecture.md` — extension architecture, data flow, messaging, state, database
- `docs/dev/overview/tech-stack.md` — framework/library versions and build tooling
- `docs/dev/overview/project-structure.md` — folder map, aliases, naming conventions, key files
- `docs/dev/workflow/development.md` — setup, build/package commands, env vars, workflow
- `docs/dev/workflow/codebase-rules.md` — ESLint, Prettier, Vue, JSDoc, CSS, build rules and naming conventions
- `docs/dev/workflow/screens.md` — all routes/views mapped with permissions
- `docs/dev/app/plugins.md` — Vue plugins, directives, filters, global mixins
- `docs/dev/app/stores.md` — Vuex modules + Pinia stores (state, getters, actions, persistence)
- `docs/dev/app/services.md` — business logic services (print, flash sale, shop, product)
- `docs/dev/app/settings.md` — settings system architecture, all setting groups
- `docs/dev/app/adapters.md` — platform data transformers (Shopee, TikTok, Lazada)
- `docs/dev/extension/background.md` — service worker init, events, shop detection, periodic tasks
- `docs/dev/extension/content-scripts.md` — lifecycle, injection, DOM patterns, IPC communication
- `docs/dev/extension/bridge.md` — webext-bridge message handlers and event flow
- `docs/dev/reference/constants.md` — constants, enums, storage keys, usage limits
- `docs/dev/reference/utilities.md` — utility functions (PDF, crypto, date, Excel, match)

### Business (`docs/business`)
- `docs/business/skills.md` — feature catalog organized by platform, plan, and status
- `docs/business/permissions.md` — plan-based access control and route matrix

### Shopee Features
- `docs/shopee/clone-product.md` — clone product from other shops, AI rewrite, watermark, cross-platform
- `docs/shopee/flash-sale.md` — bulk flash sale creation, scheduler, campaign, analytics
- `docs/shopee/send-message.md` — bulk messaging to customers (marketing automation)
- `docs/shopee/reply-rating.md` — auto-reply to customer ratings/reviews
- `docs/shopee/rating-order.md` — auto-rate completed orders with 5 stars
- `docs/shopee/ads.md` — ads campaign management and keyword optimization
- `docs/shopee/keyword.md` — keyword collection management for ads
- `docs/shopee/spy.md` — market research: spy products, shops, categories
- `docs/shopee/printer.md` — PDF order printing, template config, overlay
- `docs/shopee/push-product.md` — auto push product (coming soon)

### TikTok & Lazada
- `docs/tiktok/features.md` — TikTok clone, spy, print, content scripts
- `docs/lazada/features.md` — Lazada clone, print, affiliate, content scripts

### API Reference (`docs/dev/api`)
- `docs/dev/api/integrations.md` — external/internal APIs, socket, sync (overview)
- `docs/dev/api/shopee.md` — Shopee Seller/Client/Affiliate API endpoints
- `docs/dev/api/autoshopee.md` — AutoShopee REST API, Socket.io events, PouchDB/CouchDB sync
- `docs/dev/api/third-party.md` — TikTok, Lazada, GPT, Worker, KV Store APIs

### Plan
- `docs/plan/improvements.md` — prioritized improvement backlog (critical/high/medium/nice-to-have)
