AIRegulation/AIRegulation-DocAnalysis
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix SSE route dependency and align architecture docs

Browse Source
This commit is contained in:
ash66
2026-05-18 16:32:42 +08:00
parent 86b9ac806a
commit 3f69cad404
149 changed files with 4786 additions and 5957 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
AGENTS.md
View File

@@ -2,38 +2,47 @@
## Scope
- This repo uses `backend/app/` for the backend and `frontend/` for the Vite React app.
- Backend code lives under `backend/app/`; frontend is the Vite app in `frontend/`.
## Real Entrypoints
## Entrypoints
- Current backend app entrypoint is `backend/app/main.py`, exporting `app` from `app.api.main`.
- Current backend dev start command is `python -m uvicorn app.main:app --reload` with `PYTHONPATH=backend`.
- `dev.sh start api --foreground` is the repo script flow that encodes the expected backend startup behavior.
- Frontend dev server is `frontend` Vite on port `5173`, proxying `/api` to `http://localhost:8000`.
- Backend entrypoint is `backend/app/main.py`, which re-exports `app` from `app.api.main`.
- FastAPI mounts the real API under `/api/v1`; health endpoints are `GET /health` and `GET /`.
- Frontend API calls use relative `/api` URLs from `frontend/src/api/index.ts`.
- Current Vite dev proxy in `frontend/vite.config.ts` forwards `/api` to `http://6.86.80.8:8000`, not the local backend.
## Commands
## Preferred Commands
- Backend install: `pip install -r backend/requirements.txt`
- Backend run from repo root: `PYTHONPATH=backend uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload`
- Frontend install: `cd frontend && npm install`
- Frontend dev: `cd frontend && npm run dev`
- Frontend build: `cd frontend && npm run build`
- Frontend lint: `cd frontend && npm run lint`
- Prefer the repo scripts over ad hoc startup commands: `./dev.sh ...` on Unix, `dev.bat ...` on Windows.
- First-time local setup: `./dev.sh setup` or `dev.bat setup`.
- Backend foreground dev server: `./dev.sh start api --foreground` or `dev.bat start api --foreground`.
- Equivalent direct backend run from repo root: `PYTHONPATH=backend uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload`.
- Python tooling must use the repo-root `.venv` environment; do not use the global `python`.
- Prefer `uv`-managed execution from the repo root, for example `uv run --python .venv\\Scripts\\python.exe python ...` or other `uv run ...` forms that resolve within the project environment.
- Frontend dev: `npm --prefix frontend run dev`.
- Frontend verification: `npm --prefix frontend run lint` and `npm --prefix frontend run build`.
- Use `npm`, not `pnpm`; the checked-in scripts run `npm install` even though `frontend/pnpm-lock.yaml` also exists.
## Infra And Env
## Env And Infra
- Backend settings load from root `.env`, not `backend/.env`, because `backend/app/config/settings.py` uses `env_file = ".env"`.
- Docker infra is defined in `docker/docker-compose.yml`; it starts Milvus, MinIO, Redis, and PostgreSQL.
- Default local service ports: Milvus `19530`, MinIO `9000/9001`, Redis `6379`, PostgreSQL `5432`, backend `8000`, frontend `5173`.
- LLM base URLs in `.env.example` point at a shared remote gateway (`http://6.86.80.4:30080/v1`); do not assume offline/local-only LLM execution.
- Backend settings must resolve env files from the repo root only. The supported files are root `.env` and optional root `.env.development`; files under `backend/` must not be treated as authoritative env sources.
- The dev scripts read `API_HOST`, `API_PORT`, `FRONTEND_PORT`, and `FRONTEND_MODE` from root `.env` first, then root `.env.development` as an override; all other backend config comes from the repo-root env files via Pydantic settings.
- Docker infra is `docker/docker-compose.yml`; it brings up `milvus`, `minio`, `redis`, and `postgres`.
- Default ports from config/scripts: backend `8000`, frontend `5173`, Milvus `19530`, MinIO `9000/9001`, Redis `6379`, PostgreSQL `5432`.
- `.env.example` points embedding/LLM base URLs at a shared remote gateway `http://6.86.80.4:30080/v1`; do not assume model inference is local.
## Verification
- Root pytest config in `pyproject.toml` points at root `tests/`, and those tests import from `backend/app` via `PYTHONPATH` setup.
- For frontend-only changes, run `npm run lint` and `npm run build` in `frontend`.
- For backend changes, prefer focused import/startup verification against `backend/app`, and run root `tests/` when the environment supports it.
- Root `pyproject.toml` is the active Python manifest and pytest config; `testpaths = ["tests"]`.
- Tests under `tests/` insert `backend/` into `sys.path` themselves, so targeted runs can be launched from the repo root.
- `tests/test_milvus.py` and `tests/verify_mvp.py` require Milvus and model/runtime dependencies; they are not cheap smoke tests.
- `tests/verify_mvp.py` also expects the `BGEM3Embedder` stack to be available and explicitly mentions `FlagEmbedding`.
- For backend-only changes, prefer focused import/startup checks unless you know the external services and model dependencies are available.
## Gotchas
## Backend Commenting Standard
- Backend settings load from root `.env`, not `backend/.env`, because `backend/app/config/settings.py` uses `env_file = ".env"`.
- The root `pyproject.toml` is the active Python package manifest for the repo.
- All comments and docstrings in `backend/**/*.py` must be written in English.
- Every Python file under `backend` must include a module-level explanation and at least one meaningful `#` code comment.
- Every function and method must include a docstring.
- Files without functions, including `__init__.py`, schemas, enums, dataclasses, and export-only modules, must still include a module docstring, class docstrings when applicable, and at least one meaningful `#` code comment.
- Comments must explain intent, assumptions, invariants, or non-obvious logic; do not add empty, placeholder, or restatement-only comments.