98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is a Chinese-language enterprise SaaS device management platform (地空业务支撑平台——生产管理子系统) built with Next.js App Router. It manages the full lifecycle of geophysical instruments (device registration, BOM configuration, license/authorization management, repair orders, firmware, and scrap records).
|
|
|
|
## Tech Stack
|
|
|
|
- **Frontend**: Next.js 16, React 19, TypeScript 6, Tailwind CSS 4
|
|
- **Database**: SQLite via `better-sqlite3` (file-based, located at `data/app.db`)
|
|
- **Icons**: lucide-react
|
|
- **Forms**: react-hook-form + zod
|
|
- **Secondary backend**: FastAPI in `python_backend/` for device activation and encrypted license generation
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start Next.js dev server (http://localhost:3000)
|
|
npm run dev
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Start production server
|
|
npm run start
|
|
|
|
# Run linting
|
|
npm run lint
|
|
```
|
|
|
|
### Python Backend
|
|
|
|
The FastAPI service in `python_backend/` handles device check-in, encrypted license generation, and activation reporting independently from the Next.js app.
|
|
|
|
```bash
|
|
cd python_backend
|
|
pip install -r requirements.txt
|
|
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Database Layer (`src/lib/db.ts`)
|
|
|
|
- Uses `better-sqlite3` with WAL mode and foreign keys enabled.
|
|
- `getDb()` returns a singleton `Database` instance. The DB file is created at `data/app.db` relative to `process.cwd()`.
|
|
- `initTables()` defines the full schema on first run (tables: `devices`, `device_models`, `materials`, `bom_templates`, `config_files`, `licenses`, `repair_orders`, `scrap_records`, `firmware`, `applications`, `app_platform_versions`, etc.).
|
|
- `migrateDatabase()` handles incremental schema changes (e.g., adding `config_id`, `license_file`, `device_sn` to the `licenses` table, creating `license_download_logs` and `license_templates`).
|
|
- `generateLicenseFile()` builds a SHA256-signed JSON license payload.
|
|
|
|
### Data Fetching
|
|
|
|
- **Frontend**: Uses a lightweight custom hook `useApi(url, defaultValue)` defined in `src/lib/hooks.ts` (standard `fetch` + `useState`/`useEffect`). No React Query usage in practice despite being in `package.json`.
|
|
- **Backend API**: Implemented as Next.js Route Handlers under `src/app/api/`. Each endpoint typically calls `seedIfEmpty()` (currently a no-op that just ensures the DB is open) and then uses `getDb()` to run SQL queries.
|
|
- API routes generally support `GET` (list), `POST` (create), `PUT` (update), and `DELETE`.
|
|
|
|
### Page Structure (App Router)
|
|
|
|
- `src/app/layout.tsx` provides the root layout with a sidebar navigation and header.
|
|
- `src/app/components/sidebar.tsx` defines the navigation groups: 设备 (Devices), 物料 (Materials), 软件 (Software), 维修 (Repair).
|
|
- Major routes:
|
|
- `/` — Dashboard with statistics overview
|
|
- `/devices` — Device list with batch filtering and pagination
|
|
- `/devices/[sn]` — Device detail / BOM view
|
|
- `/registration` — Register new device
|
|
- `/models` — Device model management
|
|
- `/models/bom` — BOM template management
|
|
- `/materials/*` — Material (board/component) inventory and categories
|
|
- `/app-versions` — Mobile app release management
|
|
- `/repair` — Repair work orders
|
|
- `/scrap` — Scrap/disposal records
|
|
- `/licenses` — License/authorization configuration and JSON file generation
|
|
- `/config-files` — Device technical parameter configs
|
|
- `/firmware` — Firmware version management
|
|
|
|
### Styling
|
|
|
|
- Tailwind CSS v4 is imported in `src/styles/index.css` (`@import 'tailwindcss'`).
|
|
- Additional custom styles in `src/styles/theme.css` and `src/styles/fonts.css`.
|
|
- Many components also use inline `style` props for specific colors (primary brand color is `#4a7c59`).
|
|
|
|
### Path Aliases
|
|
|
|
- `@/*` maps to `./src/*` in `tsconfig.json`.
|
|
|
|
## Key Development Notes
|
|
|
|
- **No test suite is configured.** There are no test runners or test files in the repo.
|
|
- **No pre-commit hooks or CI configuration** were found.
|
|
- **Database schema changes**: When modifying the schema, update `initTables()` for new tables and `migrateDatabase()` for alterations to existing tables, since the app uses a single SQLite file that persists across restarts.
|
|
- **License file generation**: The `licenses` API automatically generates a signed JSON license on `POST`/`PUT` by calling `generateLicenseFile()` from `src/lib/db.ts`.
|
|
- **Python backend is separate**: The Next.js app does not depend on the FastAPI backend for normal operation. The Python service is specifically for field-device activation flows and encrypted license distribution to mobile apps.
|