Ubuntu
107 lines
5.1 KiB
Markdown
107 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
|
||
|
||
Urine test strip recognition system (尿检识别系统) — a full-stack web app that analyzes photos of medical urine reagent strips. Two analysis modes:
|
||
|
||
- **Image mode**: Upload a strip photo → OpenCV computer vision pipeline locates reagent pads and extracts color values in RGB/HSV/LAB.
|
||
- **JSON data mode**: Upload pre-extracted color data → OpenCV Random Trees ML models infer semi-quantitative results (negative, +, ++, etc.) per analyte.
|
||
|
||
The system was ported from a C++ HarmonyOS app (`/home/ubuntu/nanocode/UrineCheck/`).
|
||
|
||
## Commands
|
||
|
||
```bash
|
||
# Backend (Python/FastAPI)
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
uvicorn app:app --host 0.0.0.0 --port 8904
|
||
# OR: python app.py
|
||
|
||
# Frontend (React/Vite)
|
||
cd frontend
|
||
npm install
|
||
npm run dev # dev server on :8905, proxies /api → :8904
|
||
npm run build # production build to dist/
|
||
```
|
||
|
||
There are **no application-level tests** (no pytest, no Jest/Vitest).
|
||
|
||
## Architecture
|
||
|
||
```
|
||
Browser → :8905 (Vite/React) ──/api──proxy──→ :8904 (FastAPI/Uvicorn)
|
||
│
|
||
SSO Center (:9000) ←── JWT cookie verification
|
||
```
|
||
|
||
### Backend (`backend/`)
|
||
|
||
- **`app.py`** — FastAPI entry point. Creates SQLite tables on startup, registers `auth` and `urinecheck` routers, CORS configured for localhost + `129.211.173.87`.
|
||
- **`routers/auth.py`** — Dual-mode auth: local username/password (JWT bearer token, 30-day expiry, stored in localStorage) and SSO cookie validation (decodes JWT from `access_token` cookie using a shared secret). Default admin `admin`/`admin123` created on first startup.
|
||
- **`routers/urinecheck.py`** — Two endpoints: `POST /api/urinecheck/analyze` (multipart image upload → CV recognition) and `POST /api/urinecheck/analyze-json` (JSON body → ML inference).
|
||
- **`database.py`** / **`models.py`** — SQLAlchemy + SQLite. Single `admins` table (id, username, password_hash, created_at). Database file: `backend/urinecheck.db`.
|
||
- **`schemas.py`** — Pydantic request/response models for both endpoints.
|
||
- **`sso_client.py`** — Reads `access_token` cookie, decodes JWT locally with a shared secret key. Validates against external SSO at `http://129.211.173.87:9000`.
|
||
|
||
### Two recognition pipelines
|
||
|
||
#### Image-based CV pipeline (`urine_recognizer.py`, ~1180 lines — the largest file)
|
||
|
||
`UrineStripRecognizer` class implements a 7-step algorithm:
|
||
1. Preprocess (BGR/HSV/Gray conversion, Gaussian blur)
|
||
2. Detect locator blocks (HSV color segmentation, contour finding with Canny fallback)
|
||
3. Filter candidates (area, aspect ratio, rectangularity, Y-clustering, pair validation by color + RGB distance + area ratio)
|
||
4. Blur assessment (Laplacian variance → 3 sharpness levels)
|
||
5. Spec matching (distance ratio + area ratio → matches one of 6 PaperConfigs)
|
||
6. Calculate color block centers (edge-to-edge interpolation)
|
||
7. Read colors (white balance, circular ROI sampling → RGB/HSV/LAB output)
|
||
|
||
`PaperConfig` holds the geometric layout for 6 strip specifications (8/11/14 pads × S-type 10mm / L-type 15mm locators). `ColorReader` handles white balancing and color-space extraction.
|
||
|
||
#### JSON-based ML pipeline (`json_recognizer.py`, ~430 lines)
|
||
|
||
`UrineJsonRecognizer` class:
|
||
- Loads OpenCV RTrees models from `/usr/local/Models/*.data`
|
||
- Processes multi-frame data and takes majority vote across frames
|
||
- Applies analyte-specific result index corrections (14 correction functions per strip color type)
|
||
- Enforces PRO/MAU and SG/pH cross-correlation rules
|
||
|
||
### ML model configuration (`ml_config.py`)
|
||
|
||
`MLConfigLoader` singleton parses `/usr/local/Models/ml.json` which defines model files, positions, algorithms, and result index maps for 21 paper types × 15 positions.
|
||
|
||
### Frontend (`frontend/src/`)
|
||
|
||
- **React 18 + React Router 6 + Vite 5 + Tailwind CSS 3**
|
||
- `App.jsx` — Route definitions with `PrivateRoute` auth wrapper.
|
||
- `pages/Login.jsx` — Local auth form + SSO redirect support.
|
||
- `pages/UrineCheck.jsx` — Image upload + results display.
|
||
- `pages/JsonDataCheck.jsx` — JSON/paste upload + ML results table.
|
||
- `api/config.js` — Axios instance configured with `baseURL` from `import.meta.env.VITE_API_BASE_URL` (falls back to current origin).
|
||
|
||
## Ports
|
||
|
||
| Service | Port |
|
||
|---------|------|
|
||
| Frontend (Vite dev) | 8905 |
|
||
| Backend (Uvicorn) | 8904 |
|
||
| SSO Center | 9000 |
|
||
|
||
Frontend dev server proxies `/api/*` to `http://localhost:8904`.
|
||
|
||
## Deployment
|
||
|
||
systemd units in `deploy/`:
|
||
- `urinecheck-backend.service` — runs uvicorn as user `ubuntu` from `backend/`
|
||
- `urinecheck-frontend.service` — runs `npm run dev` as user `ubuntu` from `frontend/`
|
||
|
||
The ML model files (`/usr/local/Models/ml.json` and `/usr/local/Models/*.data`) must be present on the server — they are not in this repository.
|
||
|
||
## Key dependencies
|
||
|
||
Backend: `fastapi`, `uvicorn`, `sqlalchemy` (SQLite), `python-jose` (JWT), `passlib[bcrypt]`, `opencv-python-headless`, `numpy`
|
||
Frontend: `react` 18, `react-router-dom` 6, `axios`, `vite` 5, `tailwindcss` 3, `preline` (UI component library)
|