order_site/CLAUDE.md

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)

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

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

# 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

cd apps/backend && npm run typecheck    # tsc --noEmit (selected files)
cd apps/frontend && npm run typecheck   # vue-tsc --noEmit

Database

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)

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