docs: 部署交接文档、lake_example 自动植入与 CLAUDE 快速部署指南

新增 seed_lake_example.sh 并在 init_after_clone 中调用；更新 README/CLAUDE/DEPLOY 使接手人 clone 后即可走通送标样例流程。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-16 17:36:37 +08:00
parent 5f9addb9bf
commit 2d450715ff
7 changed files with 236 additions and 50 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,6 +2,33 @@

 This file provides guidance to Claude Code when working with code in this repository.

+## Quick Deploy (Handover to Another Machine)
+
+```bash
+git clone https://git.sanyele.com/ChengFang.LU/HSAP.git
+cd HSAP
+bash scripts/init_after_clone.sh   # .env, feishu.env, build web, seed lake_example
+bash scripts/dev_up.sh             # or: make up
+```
+
+| Script | Purpose |
+|--------|---------|
+| `init_after_clone.sh` | First-time setup; calls `seed_lake_example.sh` |
+| `seed_lake_example.sh` | Copy `lake/lake_example/` → data lake inbox (idempotent) |
+| `dev_up.sh` | `docker compose up -d --build` (platform + CVAT + DB) |
+| `build_web.sh` | `platform/web` → `platform/ui-hsap/dist` |
+| `reset_labeling.sh` | Clear labeling DB; re-scan inbox |
+
+**Handover UI flow:** http://127.0.0.1:8787 → dev login (`AS_DEV_AUTH=true`) → 批次台账 → 扫描数据湖 → 登记 → 送标工作台 → 开标 → 我的标注.
+
+**Sample batches:** `lake/lake_example/datasets/manifest.yaml` (e.g. `adas/det_7cls/20260616_adas2d_pilot`).
+
+**Git push:** `https://git.sanyele.com/ChengFang.LU/HSAP.git` — use Gitea **Access Token** as HTTPS password if SSH fails.
+
+**Deploy docs:** `README.md`, `docs/DEPLOY.md`.
+
+---
+
 ## Project Overview

 **HSAP** (Huaxu Sentinel Active Safety Platform / 华胥 Sentinel 主动安全平台) is a truck active safety algorithm iteration platform covering DMS (Driver Monitoring), Lane detection, and ADAS perception tasks.
@@ -17,14 +44,14 @@ HSAP/
 ├── platform/          # Orchestration layer (API, auth, audit, jobs, web UI)
 ├── algorithms/        # Algorithm code layer (YOLO, UFLD adapters + registries)
 ├── datasets/          # Data layer (packs, inbox, sources, labeling configs)
-├── scripts/           # Operational scripts (init, smoke tests, sync, worker)
-├── docs/              # Documentation (20+ md files covering all aspects)
-├── lake/              # Data lake staging area
-├── reports/           # Reports, CSVs, figures
-├── manifests/         # Runtime configs (feishu.env, DB, job logs, catalog cache)
+├── lake/lake_example/ # Sample inbox batches (seeded by init_after_clone)
+├── vendor/cvat/patches/  # CVAT no_auth + iframe patches
+├── scripts/           # init_after_clone, dev_up, seed_lake_example, build_web
+├── manifests/         # Runtime configs (feishu.env — not in git)
+├── docs/              # DEPLOY.md, HANDOVER.md, ...
 ├── as.py              # CLI entry point for workflow commands
 ├── workflow.registry.yaml  # Central registry: projects, packs, automation rules
-├── docker-compose.yml      # PostgreSQL + Redis + platform + worker + optional minio
+├── docker-compose.yml      # platform + worker + CVAT + postgres + redis (single file)
 ├── Dockerfile              # Python 3.11-slim, FastAPI on port 8787
 └── Makefile                # up/down/dev/logs/build/ps/health shortcuts
 ```
@@ -99,36 +126,41 @@ Central configuration for:
 - **Platform settings**: batch metadata schema, drop zones for inbox/sources, training tracks, agent graphs
 - **Automation rules**: eval-before-promote requirement, minimum delta thresholds, baseline metrics

-## Docker Services
+## Docker Services (single `docker-compose.yml`)

 | Service | Port | Description |
 |---------|------|-------------|
 | platform | 8787 | FastAPI + static web UI |
-| postgres | 5432 (host mapped to 5433) | PostgreSQL 16 |
-| redis | 6379 (host mapped to 6380) | Redis 7 |
-| worker | - | Async job executor (same image, different command) |
-| minio | 9000/9001 | Optional S3-compatible staging (profile: minio) |
+| worker | — | Async job executor |
+| postgres | 5433 (host) | PostgreSQL 16 |
+| redis | 6380 (host) | Redis 7 |
+| cvat_traefik | 8080 | CVAT gateway (UI + API) |
+| cvat_server, cvat_ui, cvat_db, workers | internal | CVAT labeling engine |
+| minio | 9000/9001 | Optional (profile: minio) |

 ## Build & Run Commands

 ```bash
-# Quick start (Docker)
-bash scripts/init_after_clone.sh   # Generate .env / feishu.env
+# Deploy (recommended)
+bash scripts/init_after_clone.sh
 bash scripts/dev_up.sh             # Or: make up

+# Re-copy sample inbox batches
+bash scripts/seed_lake_example.sh
+
 # Local dev (no Docker for platform)
 pip install -r requirements.txt
 bash scripts/run_local.sh

-# Infrastructure only (Docker) + local platform
-docker compose up -d postgres redis
+# Infrastructure only + local platform
+docker compose up -d postgres redis cvat_traefik cvat_server
 bash scripts/run_local.sh

+# Frontend rebuild
+bash scripts/build_web.sh && docker compose restart platform
+
 # Utilities
-make logs      # platform + worker logs
-make down      # stop all
-make dev       # with Vite hot reload on :5173
-make health    # check API health
+make logs / make down / make health
 ```

 ## Key Environment Variables
@@ -141,7 +173,10 @@ make health    # check API health
 | `AS_JOB_EXECUTOR` | `thread` | `thread` or `worker` |
 | `AS_DEV_AUTH` | `false` | Bypass Feishu auth in dev |
 | `AS_JWT_SECRET` | - | JWT signing secret |
-| `AS_WORKSPACE_ROOT` | - | External workspace path for large files |
+| `AS_WORKSPACE_ROOT` | optional | External workspace (DMS/Lane large files) |
+| `AS_DATA_LAKE_HOST` | `../data` | Data lake root; `送标/adas/inbox` |
+| `AS_FRONTEND_URL` | `http://127.0.0.1:8787` | Browser URL (change for LAN deploy) |
+| `CVAT_PUBLIC_URL` | `http://127.0.0.1:8080` | CVAT iframe URL |
 | `AS_FLEET_MAP_ENABLED` | `1` | Enable fleet map APIs |
 | `AS_FLEET_MOCK_SEED` | `1` | Seed demo vehicles on first start |

@@ -150,12 +185,14 @@ make health    # check API health
 1. **Never commit**: `.env`, `feishu.env`, `node_modules`, `*.pt` (model weights), images/videos
 2. **Python path**: Platform code runs with `PYTHONPATH=platform` from repo root
 3. **Package name**: The Python package is `as_platform` (historical name preserved)
-4. **Web UI**: React/Vite frontend sources are external (in workspace), built via `scripts/build_hsap_ls_ui.sh`
-5. **Large files**: Images, videos, model weights live in external workspace, mounted at `/data/workspace` in Docker
+4. **Web UI**: `platform/web/` built via `scripts/build_web.sh` → `platform/ui-hsap/dist/`
+5. **Large files**: Training weights / bulk images in `AS_WORKSPACE_ROOT` or data lake; sample batches in `lake/lake_example/`
+6. **Git**: Remote `git.sanyele.com`; HTTPS + Access Token if SSH unavailable. Company Gerrit (`10.0.0.2:29418`) is unrelated to HSAP.

 ## Documentation Index

 Key docs in `docs/`:
+- `DEPLOY.md` — **New machine deploy + lake_example handover**
 - `DEVELOPMENT_GUIDE.md` — Architecture, conventions, design decisions
 - `DEVELOPMENT_ROADMAP.md` — Q2 2026 roadmap with phased milestones
 - `DATA_LAKE_CHECKLIST.md` — Data lake operations checklist