mirror of
https://github.com/dreamhunter2333/cloudflare_temp_email.git
synced 2026-05-06 20:32:55 +08:00
13c3879033
docs: update CLAUDE.md with auth corrections, e2e testing, and architecture Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
104 lines
5.0 KiB
Markdown
104 lines
5.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Structure
|
|
|
|
- **Backend**: `worker/` — Cloudflare Workers API using Hono framework. Entry: `worker/src/worker.ts`, APIs under `worker/src/*_api/`.
|
|
- **Frontend**: `frontend/` — Vue 3 + Naive UI app deployed to Cloudflare Pages. Routes in `frontend/src/router/`.
|
|
- **Pages middleware**: `pages/functions/_middleware.js` — Routes API calls to Worker backend.
|
|
- **Mail parser**: `mail-parser-wasm/` — Rust WASM email parser.
|
|
- **SMTP/IMAP proxy**: `smtp_proxy_server/` — Python proxy server.
|
|
- **DB schema/migrations**: `db/` — SQLite via Cloudflare D1, dated migration patches.
|
|
- **Docs**: `vitepress-docs/` — VitePress documentation site (zh + en).
|
|
- **E2E tests**: `e2e/` — Playwright tests in Docker Compose (API, browser, SMTP proxy).
|
|
- **Changelogs**: `CHANGELOG.md` (中文) + `CHANGELOG_EN.md` (English).
|
|
|
|
## Build & Dev Commands
|
|
|
|
Run inside each subfolder with `pnpm`:
|
|
|
|
| Folder | Dev | Build | Lint | Deploy |
|
|
|--------|-----|-------|------|--------|
|
|
| `worker/` | `pnpm dev` | `pnpm build` | `pnpm lint` | `pnpm deploy` |
|
|
| `frontend/` | `pnpm dev` | `pnpm build` | — | `pnpm deploy` |
|
|
| `vitepress-docs/` | `pnpm dev` | `pnpm build` | — | — |
|
|
| `mail-parser-wasm/` | — | `wasm-pack build --release` | — | — |
|
|
|
|
SMTP proxy: `pip install -r smtp_proxy_server/requirements.txt` then `python smtp_proxy_server/main.py`.
|
|
|
|
## E2E Tests
|
|
|
|
Tests run in Docker Compose with Playwright. From `e2e/`:
|
|
|
|
```bash
|
|
npm test # Build, run all tests, exit
|
|
npm run test:down # Clean up containers
|
|
```
|
|
|
|
Test categories: `tests/api/` (API tests), `tests/browser/` (UI tests with Chromium), `tests/smtp-proxy/` (SMTP/IMAP proxy tests).
|
|
|
|
The Docker frontend serves over **HTTPS** (self-signed cert) with Vite proxy to worker — required for WebAuthn (`navigator.credentials`) and `crypto.subtle` which need a secure context. Browser tests use `ignoreHTTPSErrors: true`.
|
|
|
|
Key patterns for browser tests:
|
|
- Frontend hashes passwords with SHA-256 (`crypto.subtle`) before sending — API test registration must use pre-hashed passwords if UI login is needed.
|
|
- VueUse `useStorage('key', '')` with string default uses **raw string** serialization — set localStorage with raw value, not `JSON.stringify()`.
|
|
- WebAuthn browser tests use CDP virtual authenticator (`WebAuthn.enable` + `WebAuthn.addVirtualAuthenticator`).
|
|
|
|
## Architecture
|
|
|
|
### Worker Auth Flow (`worker/src/worker.ts`)
|
|
|
|
Three auth layers applied via Hono middleware, each using different headers:
|
|
|
|
| Path prefix | Header | Purpose |
|
|
|-------------|--------|---------|
|
|
| `/api/*` | `Authorization: Bearer <jwt>` | Address (mailbox) credential |
|
|
| `/user_api/*` | `x-user-token` | User account JWT |
|
|
| `/admin/*` | `x-admin-auth` | Admin password |
|
|
| (any) | `x-user-access-token` | User role-based access token |
|
|
| (any) | `x-custom-auth` | Optional global access password |
|
|
| (any) | `x-lang` | Language preference (`en`/`zh`) |
|
|
|
|
Public endpoints (no auth): `/open_api/*`, `/user_api/login`, `/user_api/register`, `/user_api/passkey/authenticate_*`, `/user_api/oauth2/*`.
|
|
|
|
### Worker Email Flow (`worker/src/email/`)
|
|
|
|
Cloudflare Email Worker entry: `email()` in `worker/src/email/index.ts`. Processing pipeline:
|
|
1. Parse raw email → check junk → check address exists
|
|
2. Auto-reply if configured → forward if configured → webhook if enabled
|
|
3. Store in D1 database
|
|
|
|
### Frontend State (`frontend/src/store/index.js`, `frontend/src/api/index.js`)
|
|
|
|
Global state via VueUse `useStorage` for persistence. The `api` module wraps axios with auto-attached auth headers and fingerprinting. API base URL comes from `VITE_API_BASE` env var (empty = same origin).
|
|
|
|
## Coding Style
|
|
|
|
- `worker/` uses TypeScript + ESLint; `frontend/` uses Vue SFCs.
|
|
- Keep existing naming patterns: `*_api/` folders, `utils/`, `models/`.
|
|
- ESM imports only (`type: module`).
|
|
|
|
## Commits & PRs
|
|
|
|
- Use Conventional Commits: `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `perf:`.
|
|
- PRs should explain scope; add screenshots for UI changes.
|
|
- Use squash merge for PRs.
|
|
|
|
## Post-Task Checklist (IMPORTANT)
|
|
|
|
After completing any feature, bug fix, or improvement, **always check**:
|
|
|
|
1. **CHANGELOG.md** (中文) and **CHANGELOG_EN.md** (English) — both must be updated under the current `(main)` version section with the change entry. Follow the existing format: `- feat/fix/docs: |模块| 描述`.
|
|
2. **Documentation** — if the change involves new environment variables, new API endpoints, or configuration changes, update the corresponding docs in `vitepress-docs/docs/zh/` and `vitepress-docs/docs/en/`. Key files:
|
|
- `guide/worker-vars.md` — Worker environment variables
|
|
- `guide/ui/` — Frontend deployment docs
|
|
- `guide/feature/` — Feature-specific docs
|
|
- `api/` — API reference docs
|
|
3. **Both languages** — docs and changelogs exist in Chinese and English; always update both.
|
|
|
|
## Config
|
|
|
|
- Worker settings in `worker/wrangler.toml` (see `wrangler.toml.template` for bindings).
|
|
- Frontend uses `VITE_*` env vars. Don't commit secrets.
|