# 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.