# Repository Guidelines

## Project Overview
AutoShopee Kit is a browser extension for e-commerce automation across Shopee, TikTok Shop, Lazada, and Tiki.

- Current app version: `3.4.3`
- Browser targets: Chrome `88+`, Firefox `78+`
- Manifest model: Chrome MV3, Firefox MV2-compatible build output
- Main frontend stack: Vue `2.7` with Options API, Vue Router `3`, Vuex `3`, Pinia `2`
- Core extension communication: `webext-bridge`
- Persistence and sync: PouchDB + CouchDB sync, `localStorage`, session storage
- Real-time features: Socket.io

Prefer the live codebase over prose docs if they conflict. `CLAUDE.md` and files under `docs/dev/` (kỹ thuật) plus `docs/business/` (nghiệp vụ, gói, phân quyền) are useful context, but implementation details in `src/`, `vue.config.js`, and `package.json` are the source of truth.

## Project Structure
The extension has four primary runtime entry points:

- `src/popup/main.js`: popup application entry
- `src/options/main.js`: options/settings application entry
- `src/background/index.js`: background entry
- `src/content/`: injected content scripts

Shared application code lives under `src/app/`. Important directories currently include:

- `api/`: platform API clients and AutoShopee internal APIs
- `adapter/`: data transformers per platform
- `bridge/`: `webext-bridge` message handlers
- `browser/`: browser helpers
- `components/`: Vue components
- `composables/`: existing helper logic used by the app
- `config/`, `constant/`, `data/`, `lib/`: shared config/constants/utilities/static data
- `mixin/`: Vue mixins
- `models/`: PouchDB models and loaders
- `pinia/`: supplementary Pinia stores
- `plugins/`: i18n, storage, settings, and other Vue plugins
- `router/`: route definitions
- `service/`: business logic
- `socket/`: real-time communication
- `store/`: primary Vuex store
- `styles/`: shared styling
- `types/`: JSDoc type definitions
- `validator/`: Joi validation schemas
- `views/`: routed pages/views

Content scripts are organized by browser target and platform. Follow the current structure in code, especially:

- `src/content/all/`
- `src/content/file/`
- `src/content/shopee/`
- `src/content/tiktok/`
- `src/content/lazada/`
- `src/content/tiki/`
- `src/content/service/`

Do not treat `dist/` or `artifacts/` as editable source. They are generated output.

## Build, Debug, and Release Commands
Use the existing npm scripts instead of ad hoc build steps:

- `npm run dev`: development build in watch mode
- `npm run dev:tool`: open Vue DevTools
- `npm run build:prod`: production build
- `npm run build:chrome`: Chrome bundle
- `npm run build:firefox`: Firefox bundle
- `npm run build:analyze`: Chrome build with bundle analyzer
- `npm run build:report`: Chrome build plus exported report
- `npm run zip:chrome`: build and zip Chrome package
- `npm run zip:firefox`: build and zip Firefox package
- `npm run zip:root`: Firefox root-mode package
- `npm run zip:s3`: upload packaged build to S3
- `npm run lint`: ESLint
- `npm run lint:fix`: ESLint autofix
- `npm run pretty`: Prettier write
- `npm run format`: Prettier + ESLint fix

## Coding Conventions
Follow `CLAUDE.md` conventions even where lint rules are permissive.

- Use Vue 2 Options API for new work.
- Do not convert files to Composition API or TypeScript.
- This repo already contains some legacy `@vue/composition-api` and VueUse usage. Keep changes minimal in those files, but do not expand that pattern unless the touched file already depends on it and changing direction would be riskier.
- Use JSDoc types only. Put reusable type definitions in `src/app/types/` instead of inline pseudo-types.
- Prefer path aliases over deep relative imports:
  - `@` -> `src/app/`
  - `@content` -> `src/content/`
  - `@background` -> `src/background/`
  - `@type` -> `src/app/types/`
- Formatting expectations:
  - 2-space indentation
  - single quotes
  - no semicolons
  - keep `.vue` files within the existing Prettier style
- Naming expectations:
  - PascalCase for Vue components, models, and type definition files
  - camelCase for services, utilities, store modules, and content-script files
- Use braces for every `if` block.
- Keep multi-part conditions readable, typically one condition per line.
- Avoid ternary-heavy branching; prefer explicit `if/else` when logic is non-trivial.
- Avoid explanatory inline comments unless they capture a non-obvious constraint.
- Do not split files during refactors unless explicitly asked. Extend existing files and modules when practical.
- Reuse the current UI stack: View Design (`view-design`), Tailwind CSS, and SASS. Do not introduce another UI framework for local changes.

## Architecture Notes
Key runtime relationships to keep in mind:

- Popup and Options are separate Vue apps.
- Background coordinates long-lived extension behavior and browser events.
- Content scripts run on marketplace pages and bridge data/actions back to Background.
- `webext-bridge` is the standard message channel between extension contexts.
- Vuex in `src/app/store/` remains the primary shared state layer.
- Pinia in `src/app/pinia/` is supplementary and already used for newer slices.
- PouchDB models in `src/app/models/` back local storage and sync behavior.
- Socket.io is used for real-time updates.

When a change affects state, messaging, or persistence, inspect both the UI-facing module and the background/content path that feeds it.

## Browser Extension-Specific Rules
When adding or changing extension entry behavior, verify the full registration path.

For a new content script:

1. Add the source file under the correct `src/content/...` location.
2. Register the entry in `vue.config.js` under `pluginOptions.browserExtension.componentOptions.contentScripts.entries`.
3. Update `src/manifest.json` with the right `matches` and built JS asset path.

Browser-specific behavior matters:

- Chrome build uses MV3 service worker background behavior.
- Firefox build is transformed in `vue.config.js` to MV2-style `background.scripts`.
- Firefox build also injects a Gecko add-on ID.
- `BROWSER`, `ROOT_MODE`, `ANALYZE`, and `NODE_ENV` drive build-time behavior.

If you change extension versioning, note that `vue.config.js` writes `package.json` field `verNumber` into the manifest version. Keep version fields aligned intentionally.

## Testing and Validation
There is no single `npm test` command in this repo. Minimum expectations:

- Run `npm run lint` for source changes.
- Use scripts in `test/` when they directly cover the area you changed.
- For popup, options, background, or content-script changes, build the affected browser bundle and test the flow manually from `dist/`.
- For marketplace-facing changes, verify on the relevant seller/client page rather than relying on static inspection alone.
- When touching browser-specific behavior, explicitly think through both Chrome and Firefox paths.

## Documentation Pointers
Useful repo docs:

- `CLAUDE.md`: AI-facing coding conventions
- `docs/dev/README.md`: nested index under `docs/dev/`
- `docs/dev/overview/architecture.md`: extension architecture and data flow
- `docs/dev/overview/project-structure.md`: folder map and key files
- `docs/dev/workflow/development.md`: build, packaging, env vars, workflow
- `docs/dev/overview/tech-stack.md`: framework and library inventory
- `docs/dev/api/integrations.md`: API and integration context
- `docs/business/skills.md`: feature catalog by plan
- `docs/business/permissions.md`: plan-based access and route matrix
- `docs/plan/improvements.md`: backlog and known improvement areas

If docs disagree with current code, update the code-facing guidance conservatively and follow the implementation that actually builds.
