ljwx-study/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

The FastAPI backend lives in backend/. main.py handles auth, paper, and question APIs, helper modules follow the pdf_* naming for OCR/extraction, utils/question_formatter.py normalizes payloads, and uploads/ stores transient PDF assets. Run migrate_db.py for schema updates and create_admin.py to seed accounts. The Vue 3 client is under frontend/: src/views provide page shells, src/components house dashboard widgets, src/services/api.js wraps Axios defaults, and src/stores implement Pinia stores like useAuthStore. Generated bundles stay in dist/; keep logs and .db files untracked.

Build, Test, and Development Commands

• python -m venv .venv && source .venv/bin/activate, then cd backend && pip install -r requirements.txt to prepare the API runtime.
• cd backend && uvicorn main:app --reload --host 0.0.0.0 --port 8888 runs the server; python migrate_db.py migrates tables and python create_admin.py --username admin --password **** seeds credentials.
• cd frontend && npm install, npm run dev for hot reload, and npm run build && npm run preview -- --port 3000 to verify the production bundle or drive start_*.sh.

Coding Style & Naming Conventions

Python files use 4-space indentation, snake_case names, and Pydantic response models. Lean on FastAPI's Depends, keep config constants in UPPER_SNAKE_CASE, and reuse QuestionFormatter when shaping responses. Vue/Pinia follows 2-space indentation, PascalCase SFC names (QuestionNavigation.vue), camelCase composables (useExamStore), and centralizes API mutations in src/services. Style Element Plus overrides within scoped <style> blocks to avoid collisions.

Testing Guidelines

Smoke scripts live beside the backend: python backend/test_split_api.py verifies PDF segmentation, python backend/test_frontend_fixes.py validates frontend-facing endpoints, and python backend/test_all_fixes.py performs an end-to-end flow. Each script expects a running API on http://localhost:8888 with .env variables loaded and lightweight sample PDFs in backend/uploads/. Remove temporary fixtures once results are captured.

Commit & Pull Request Guidelines

Git history uses conventional commits (feat:, fix:, chore:) with succinct bilingual subjects such as feat: Add Claude exam parser. Pull requests should summarize backend vs. frontend impact, list verification commands (npm run build, uvicorn smoke tests), and attach screenshots or JSON snippets for UI/API tweaks. Reference related issues and update README/AGENTS when workflows change.

Security & Configuration Tips

Store secrets in a root .env and define DATABASE_URL, SECRET_KEY, ALGORITHM, and ACCESS_TOKEN_EXPIRE_MINUTES before running the server. Never commit .env, SQLite databases, or log files—extend .gitignore when new sensitive artifacts appear. Use HTTPS when exposing FastAPI, rotate credentials generated by create_admin.py, and purge PDFs from backend/uploads/ after tests or demos.