docs: finalize submission materials
Document domain, launch/build commands, structure, env vars, cloud split, and the real CV prototype on drho1y-mvp_1 for the final submission. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
root
175
README.md
175
README.md
@@ -2,27 +2,55 @@
|
|||||||
|
|
||||||
Web digital twin of an Ozon Tech Track 3 conveyor sorting line: continuous product playback, camera/classification stage, B/C/D routing, and author-CAD diverter motion.
|
Web digital twin of an Ozon Tech Track 3 conveyor sorting line: continuous product playback, camera/classification stage, B/C/D routing, and author-CAD diverter motion.
|
||||||
|
|
||||||
## Current product
|
**Production domain:** https://arhipovdan.ru
|
||||||
|
|
||||||
This repository contains:
|
## Current solution
|
||||||
|
|
||||||
- web-based conveyor sorting simulation (`/`);
|
This repository (`main`) contains the final web simulation:
|
||||||
|
|
||||||
|
- continuous 3D conveyor digital twin (`/`);
|
||||||
- engineering documentation page (`/documentation`);
|
- engineering documentation page (`/documentation`);
|
||||||
- author CAD conveyor source (`3d_models/conveer.FCStd`);
|
- author CAD conveyor source (`3d_models/conveer.FCStd`);
|
||||||
- runtime conveyor GLB (`public/models/sorter/conveyor-clean.glb`);
|
- runtime conveyor GLB (`public/models/sorter/conveyor-clean.glb`);
|
||||||
- product STL assets (`public/models/*.stl`);
|
- product STL assets (`public/models/*.stl`);
|
||||||
- camera / classification stage;
|
- camera-triggered measurement / rule-based classification (digital sensor simulation);
|
||||||
- B / C / D route mapping with CAD left/right diverters;
|
- B / C / D route mapping with CAD left/right diverters (−45° / +45°);
|
||||||
- Rapier-backed product physics (contact routing **not** fully validated).
|
- Rapier physics: belt ≈ 1.0 m/s, fixed timestep 1/120 s, CCD on product profiles, discharge into receivers.
|
||||||
|
|
||||||
## Quick start
|
### Main functions
|
||||||
|
|
||||||
|
1. Continuous SKU playback on a three-module CAD conveyor (clean → camera → sorter).
|
||||||
|
2. Camera-volume triggered measurement and B/C/D classification.
|
||||||
|
3. Physical diverter routing and receiver settle detection.
|
||||||
|
4. Desktop WebGL twin + mobile-capable 3D policy.
|
||||||
|
5. Canonical engineering status on `/documentation`.
|
||||||
|
|
||||||
|
## Technology stack
|
||||||
|
|
||||||
|
| Layer | Packages |
|
||||||
|
|---|---|
|
||||||
|
| UI | React, react-router-dom |
|
||||||
|
| 3D | three, @react-three/fiber, @react-three/drei, @react-three/postprocessing |
|
||||||
|
| Physics | @react-three/rapier, @dimforge/rapier3d-compat |
|
||||||
|
| Build | Vite, TypeScript, @vitejs/plugin-react |
|
||||||
|
| Tests | Vitest, Playwright |
|
||||||
|
|
||||||
|
See `package.json` for exact versions. Do not treat transitive npm packages as first-class product dependencies.
|
||||||
|
|
||||||
|
## Dependencies / Node
|
||||||
|
|
||||||
|
- Node.js **20+**
|
||||||
|
- npm (lockfile: `package-lock.json`)
|
||||||
|
|
||||||
|
### Exact commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm ci
|
npm ci
|
||||||
npm run dev # http://127.0.0.1:3100
|
npm run dev # development: http://127.0.0.1:3100
|
||||||
npm test -- --run
|
npm test -- --run # unit tests
|
||||||
npm run build
|
npm run build # production build → dist/
|
||||||
npm run preview # http://127.0.0.1:3100
|
npm run preview # serve build: http://127.0.0.1:3100
|
||||||
|
npm run test:e2e # Playwright (needs preview or PLAYWRIGHT_BASE_URL)
|
||||||
```
|
```
|
||||||
|
|
||||||
## Active routes
|
## Active routes
|
||||||
@@ -35,20 +63,37 @@ npm run preview # http://127.0.0.1:3100
|
|||||||
|
|
||||||
Removed routes (`/details`, `/device-test`) are not part of the product.
|
Removed routes (`/details`, `/device-test`) are not part of the product.
|
||||||
|
|
||||||
## Runtime architecture
|
## Project structure
|
||||||
|
|
||||||
```
|
```
|
||||||
index.html
|
src/ React app, domain logic, 3D twin, pages
|
||||||
→ src/main.tsx
|
public/ Runtime static assets (models, draco)
|
||||||
→ src/App.tsx
|
models/ Product STL + sorter/conveyor-clean.glb
|
||||||
→ MainPage (/) | DocumentationPage (/documentation)
|
3d_models/ Author CAD (conveer.FCStd)
|
||||||
→ SorterDigitalTwinContinuous
|
docs/ Engineering notes (ENGINEERING.md)
|
||||||
→ ConveyorCadModel (conveyor-clean.glb)
|
e2e/ Playwright smoke / routes
|
||||||
→ product visuals / physics (STL + Rapier)
|
input_info/ Official Ozon input packs (PDFs/ZIPs)
|
||||||
→ classifier (domain)
|
official_sources/ Classifier bounds PDF cited by code
|
||||||
→ diverter product state machine (READY→ARMED→OPENING→HOLDING→CLOSING)
|
Dockerfile Multi-stage Vite build + nginx
|
||||||
|
docker-compose.server.yml
|
||||||
|
nginx.conf
|
||||||
|
.github/workflows/ci.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Environment variables
|
||||||
|
|
||||||
|
No runtime secrets are required for local demo or production static hosting.
|
||||||
|
|
||||||
|
Optional **build-time** identity (Docker / CI only; never commit real secrets):
|
||||||
|
|
||||||
|
| Variable | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `VITE_BUILD_COMMIT` | Short git commit in `/version.json` |
|
||||||
|
| `VITE_BUILD_BRANCH` | Branch name in `/version.json` |
|
||||||
|
| `VITE_BUILD_RELEASE` | Release label in `/version.json` |
|
||||||
|
|
||||||
|
Do not commit `.env` files. Local `npm run build` derives identity from git when available.
|
||||||
|
|
||||||
## Active assets
|
## Active assets
|
||||||
|
|
||||||
| Path | Role |
|
| Path | Role |
|
||||||
@@ -69,6 +114,24 @@ public/models/sorter/conveyor-clean.glb
|
|||||||
1dc7a8d7891bfe756e277ad5368df74cb73410156b2fe0f92845afb8a56f285a
|
1dc7a8d7891bfe756e277ad5368df74cb73410156b2fe0f92845afb8a56f285a
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Classifier vs real CV
|
||||||
|
|
||||||
|
**Web twin (`main`):** classification is a **digital sensor simulation**. When a product enters the camera scan volume, dimensions / roundness are measured in the twin and routed with the same B/C/D rules as Track 3 (`src/domain/classifier.ts`, `src/domain/cameraClassification.ts`). This is **not** a neural network and is **not** wired to a live RealSense camera in production.
|
||||||
|
|
||||||
|
**Real CV (parallel prototype, not merged into the web app):** preserved on branch **`drho1y-mvp_1`** under `vision_classifier/` (OpenCV + RealSense D415 depth → L×W×H + circle_ratio → B/C/D → MQTT). No PyTorch/YOLO weights are stored in git.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git fetch origin
|
||||||
|
git switch drho1y-mvp_1
|
||||||
|
cd vision_classifier
|
||||||
|
# see vision_classifier/README.md and START.md
|
||||||
|
./demo.sh # browser HUD demo
|
||||||
|
.venv/bin/python test_classify.py
|
||||||
|
./run.sh --preview # full pipeline on hardware (Orange PI + RealSense)
|
||||||
|
```
|
||||||
|
|
||||||
|
Integration status: **WORKING_PROTOTYPE on `drho1y-mvp_1`**, **not integrated** into https://arhipovdan.ru.
|
||||||
|
|
||||||
## Sorting logic
|
## Sorting logic
|
||||||
|
|
||||||
**CURRENT_IMPLEMENTATION_VERIFIED_IN_CODE** (`src/domain/classifier.ts`, `src/domain/pusherMotion.ts`, unit tests).
|
**CURRENT_IMPLEMENTATION_VERIFIED_IN_CODE** (`src/domain/classifier.ts`, `src/domain/pusherMotion.ts`, unit tests).
|
||||||
@@ -92,35 +155,79 @@ Classifier bounds (code + `official_sources/doc-1783095831.pdf` reference; PDF n
|
|||||||
- circular when **K > 0.8**
|
- circular when **K > 0.8**
|
||||||
- check order: dimensions → C, else circular → D, else B
|
- check order: dimensions → C, else circular → D, else B
|
||||||
|
|
||||||
Missing primary brief (do not cite as present): `input_info/extracted/Постановка_Задача_3_сжато_2.pdf`.
|
## Physical simulation
|
||||||
|
|
||||||
|
- Fixed timestep **1/120 s**, max **4** substeps, gravity **[0, −9.81, 0]**
|
||||||
|
- Belt target speed **1.0 m/s** (supported-body velocity coupling)
|
||||||
|
- CCD enabled on active product physics profiles
|
||||||
|
- Single dynamic product rigid body through spawn → junction → receiver settle
|
||||||
|
- LEFT/RIGHT CAD diverters: `kinematicPositionBased` colliders synced to CAD yaw
|
||||||
|
- Discharge edge ends belt support; gravity fall into receivers
|
||||||
|
- Receiver volumes are sensors for completion
|
||||||
|
|
||||||
|
Details: `docs/ENGINEERING.md`, `/documentation`.
|
||||||
|
|
||||||
## Validation
|
## Validation
|
||||||
|
|
||||||
- Unit tests: **221/221** (`npm test -- --run`)
|
```bash
|
||||||
- Production build: **PASS** (`npm run build`)
|
npm ci
|
||||||
|
npm test -- --run # currently 245 unit tests
|
||||||
|
npm run build
|
||||||
|
# focused E2E (with preview on :3101):
|
||||||
|
npx vite preview --host 127.0.0.1 --port 3101 &
|
||||||
|
PLAYWRIGHT_BASE_URL=http://127.0.0.1:3101 npm run test:e2e -- e2e/routes.spec.ts e2e/smoke.spec.ts
|
||||||
|
```
|
||||||
|
|
||||||
- Two-page routing: `/` + `/documentation`
|
- Two-page routing: `/` + `/documentation`
|
||||||
- CAD / GLB checksums: verified against values above
|
- CAD / GLB checksums: verified against values above
|
||||||
- Diverter frozen angles / duration: covered by unit tests
|
- Diverter frozen angles / duration: covered by unit tests
|
||||||
- Physical junction contact matrix: **45/45** — **ENGINEERING-DERIVED PHYSICAL VALIDATION** (not production-certified)
|
- Junction / discharge / camera classification: covered by domain tests (engineering-derived, not production-calibrated)
|
||||||
|
|
||||||
## Physics (junction contact)
|
## Production deploy (this host)
|
||||||
|
|
||||||
- Same dynamic product rigid body through spawn → junction → receiver settle
|
Nginx terminates TLS for `arhipovdan.ru` and proxies to Docker `owl-web-1` on `127.0.0.1:3100` (`docker-compose.server.yml` + `Dockerfile`).
|
||||||
- LEFT/RIGHT CAD diverters use `kinematicPositionBased` colliders synced to the accepted CAD yaw
|
|
||||||
- B: physical straight corridor; C/D: contact-only redirection; receiver sensors detect only
|
```bash
|
||||||
- Temporary scripted junction handoff removed from the active product path
|
cd /opt/arhipovdan/app # or your checkout
|
||||||
|
COMMIT=$(git rev-parse --short HEAD)
|
||||||
|
BRANCH=$(git rev-parse --abbrev-ref HEAD)
|
||||||
|
RELEASE=$(date -u +%Y%m%d-%H%M%S)
|
||||||
|
docker compose -p owl -f docker-compose.server.yml build \
|
||||||
|
--build-arg "BUILD_COMMIT=${COMMIT}" \
|
||||||
|
--build-arg "BUILD_BRANCH=${BRANCH}" \
|
||||||
|
--build-arg "BUILD_RELEASE=${RELEASE}"
|
||||||
|
docker compose -p owl -f docker-compose.server.yml up -d --force-recreate
|
||||||
|
curl -s https://arhipovdan.ru/version.json
|
||||||
|
```
|
||||||
|
|
||||||
|
## Repository vs cloud materials
|
||||||
|
|
||||||
|
| Material | In git | Cloud expected |
|
||||||
|
|---|---|---|
|
||||||
|
| Source, README, docs, configs, tests | yes | — |
|
||||||
|
| Runtime GLB/STL used by the deployed app | yes (required for deploy) | recommended mirror |
|
||||||
|
| Author CAD `conveer.FCStd` (~5 MB) | yes | recommended upload |
|
||||||
|
| Official PDFs/ZIPs under `input_info/`, `official_sources/` | yes | optional mirror |
|
||||||
|
| Presentation / video demonstration | **not in repo** | **required for platform field** |
|
||||||
|
| ML weights | none (CV is classical OpenCV depth) | N/A |
|
||||||
|
|
||||||
|
Confirmed public presentation / video / cloud-folder URLs are **not stored in this repository**. Add them in the platform submission field when available.
|
||||||
|
|
||||||
|
Презентация / видеодемонстрация: links must be supplied by the owner (not invented here).
|
||||||
|
|
||||||
## Current limitations
|
## Current limitations
|
||||||
|
|
||||||
- Product profiles are **engineering-derived**, not production-calibrated.
|
- Web classifier is a digital sensor simulation, not live RealSense inference.
|
||||||
|
- Product profiles are engineering-derived, not production-calibrated.
|
||||||
- Author CAD horn / complete transmission is absent or incomplete in the active GLB (`AUTHOR_CAD_INCOMPLETE`).
|
- Author CAD horn / complete transmission is absent or incomplete in the active GLB (`AUTHOR_CAD_INCOMPLETE`).
|
||||||
- Official compliance claims are limited by the **missing** extracted task PDF and by not re-parsing PDFs in every doc pass.
|
- Official compliance claims are limited by the missing extracted task PDF and by not re-parsing PDFs in every doc pass.
|
||||||
- Generated screenshots, videos, Gate stage folders, and tool `out/` trees are **not** canonical.
|
- Generated screenshots, videos, Gate stage folders, and tool `out/` trees are not canonical.
|
||||||
|
|
||||||
## Repository policy
|
## Repository policy
|
||||||
|
|
||||||
- Keep author CAD, active runtime assets, official sources, build configs, and tests that protect active behavior.
|
- Keep author CAD, active runtime assets, official sources, build configs, and tests that protect active behavior.
|
||||||
- Generated outputs and historical media are not product truth.
|
- Generated outputs and historical media are not product truth.
|
||||||
- Rollback point: git baseline `4413f01` on `dan_branch`.
|
- Real CV remains on `drho1y-mvp_1`; do not force-merge it into `main` without a validated web integration.
|
||||||
|
- Rollback point for the pre-cleanup web baseline: git `4413f01` on `dan_branch` history.
|
||||||
|
|
||||||
See also: `/documentation` in the running app, and `docs/ENGINEERING.md`.
|
See also: `/documentation` in the running app, and `docs/ENGINEERING.md`.
|
||||||
|
|||||||
Reference in New Issue
Block a user