119 lines
5.1 KiB
Markdown
119 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
订单自动兑换系统 (Order Auto-Redemption System). 接收电商平台的 webhook 订单，通过 Playwright 浏览器自动化完成腾讯/QQ 等平台的兑换码兑换，生成用户领取链接。
|
|
|
|
## Architecture
|
|
|
|
**Monorepo**: `apps/backend` + `apps/frontend` + `deploy/`
|
|
|
|
### Backend (`apps/backend/`)
|
|
- **Stack**: Node.js (ESM), Express 5, PostgreSQL (pg), Playwright 1.42.1, Python OCR worker (ddddocr)
|
|
- **Entry**: `src/index.js` — Express app bootstrap with health checks and graceful shutdown
|
|
- **Layering**: `routes/` → `services/` → `repositories/` → `db/client.js` (pg Pool singleton)
|
|
- **Config**: `config/default.cjs` as base, `.env` overrides parsed in `src/config/runtime.js`. No dotenv library — custom env file parser.
|
|
- **DB migrations**: `src/db/migrations/` — SQL files run automatically on startup via `src/db/migrate.js` (tracks applied migrations in `schema_migrations` table)
|
|
- **Types**: Gradual TypeScript migration in progress. `tsconfig.json` with `allowJs: true, checkJs: false, strict: false` — JSDoc type annotations on selected files, types defined in `src/types/`
|
|
- **Test runner**: Node.js built-in `node --test`
|
|
|
|
**Key service domains**:
|
|
- `services/session/` — Playwright browser session management (login, redeem, screenshots), the core automation engine
|
|
- `services/claim/` — Claim token generation and user-facing claim page API
|
|
- `services/admin/` — Admin panel CRUD (split into read/write helpers, auth, dashboard, etc.)
|
|
- `services/order/` — Webhook processing, order/inventory management, Agiso platform integration
|
|
- `services/platforms/` — Third-party platform adapters (currently Agiso for 闲鱼/Xianyu)
|
|
- `subservices/ocr-worker/` — Python (uv) microservice for CAPTCHA OCR, invoked via subprocess
|
|
|
|
**Runtime data** (`data/` dir, mounted in Docker dev): logs, browser session artifacts, screenshots, `order-fulfillment-bindings.json`
|
|
|
|
### Frontend (`apps/frontend/`)
|
|
- **Stack**: Vue 3, Vite 8, Element Plus, vue-router (hash mode), TypeScript
|
|
- **Routes**: `/tx/browser` (browser session control), `/claim/:token` (user claim page), `/admin/*` (admin panel with role-based guards)
|
|
- **Auto-imports**: `unplugin-auto-import` + `unplugin-vue-components` for Element Plus
|
|
|
|
### Deployment (`deploy/`)
|
|
- Docker Compose: `docker-compose.yml` (production), `docker-compose.dev.yml` (hot-reload dev)
|
|
- Caddy reverse proxy: `/api/v1/*` → backend, `/*` → frontend
|
|
- Production Dockerfiles use Chinese mirrors (Tencent Cloud) for apt/npm/pip
|
|
|
|
## Common Commands
|
|
|
|
### Local Development (without Docker)
|
|
```bash
|
|
# Backend
|
|
cp .env.mac-docker.example .env
|
|
cd apps/backend
|
|
npm install
|
|
npm run dev # node --watch restart on src/ changes
|
|
|
|
# Frontend
|
|
cd apps/frontend
|
|
npm install
|
|
npm run dev # Vite dev server
|
|
|
|
# OCR worker (Python)
|
|
cd apps/backend/subservices/ocr-worker
|
|
uv sync
|
|
```
|
|
|
|
### Docker Development (recommended)
|
|
```bash
|
|
cp .env.mac-docker.example .env
|
|
docker compose -f docker-compose.dev.yml up -d --build
|
|
# Access: http://localhost, noVNC: http://localhost:6080/vnc.html
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# Run all backend tests
|
|
cd apps/backend && npm test
|
|
|
|
# Run a single test file
|
|
cd apps/backend && node --test src/services/session/session-redeem.test.js
|
|
|
|
# Run tests matching a pattern
|
|
cd apps/backend && node --test --test-name-pattern="redeem"
|
|
```
|
|
|
|
### Type Checking
|
|
```bash
|
|
cd apps/backend && npm run typecheck # tsc --noEmit (selected files)
|
|
cd apps/frontend && npm run typecheck # vue-tsc --noEmit
|
|
```
|
|
|
|
### Database
|
|
```bash
|
|
cd apps/backend && npm run db:migrate # Run migrations manually
|
|
cd apps/backend && npm run seed:dev-data # Seed dev data
|
|
cd apps/backend && npm run cleanup:dev-data # Clean dev data
|
|
```
|
|
|
|
### Browser (Playwright)
|
|
```bash
|
|
cd apps/backend && npm run browser:install # macOS
|
|
cd apps/backend && npm run browser:install:linux # Linux (with deps)
|
|
```
|
|
|
|
## API Routes
|
|
|
|
All backend routes are prefixed with `/api/v1/`:
|
|
- `/api/v1/tencent/browser/*` — Browser session CRUD and control
|
|
- `/api/v1/webhooks/agiso/*` — Agiso platform webhook receiver
|
|
- `/api/v1/claim/*` — Claim token validation and redemption
|
|
- `/api/v1/admin/*` — Admin panel API (auth, orders, tasks, inventory, etc.)
|
|
|
|
Health checks (no prefix): `/health`, `/health/live`, `/health/ready`
|
|
|
|
## Important Conventions
|
|
|
|
- Backend uses ESM throughout (`"type": "module"`) — always use `.js` extensions in imports
|
|
- Express route handlers use `buildSuccessPayload` / `sendRouteError` from `src/utils/http.js` for consistent response format
|
|
- Database queries go through `src/db/client.js` (`query()` / `withTransaction()`) — no raw pool usage in services
|
|
- Runtime config is accessed via `runtimeConfig` from `src/config/runtime.js` — never read `.env` directly outside that module
|
|
- Admin routes are split into separate files under `src/routes/admin/` with shared middleware in `shared.js`
|
|
- Frontend uses hash-based routing (`createWebHashHistory`) — claim links include `/#/claim/:token`
|
|
- Playwright version is pinned at `1.42.1` — do not upgrade without testing browser automation flows
|