# Robot App Web (RBS)

Giao diện web quản lý robot: mission, map, dashboard, user, Modbus/REST tích hợp.

Tài liệu UI/UX và trạng thái tính năng: `[docs/Reference_guide.md](docs/Reference_guide.md)`.

**Backend:** C++ executable `robot_app` (`src/app/robot_app.cpp`, class `RobotApp`).  
**Frontend:** static `www/` (vanilla JS).

Chức năng chính:

- Đăng ký danh sách cảm biến LiDAR (tên, ip, port)
- Đăng ký IMU (tên, frame_id, topic, nguồn) và pose trên robot
- Kéo thả icon LiDAR/IMU trên canvas để set vị trí (robot frame)
- Nhiều layout — mỗi layout lưu profile trong SQLite (`layout_profiles`); catalog trong document `state`
- Mission editor, map editor, dashboard, transitions, paths, path guides, I/O modules



## Dữ liệu


| Thành phần        | Vị trí                                                                          |
| ----------------- | ------------------------------------------------------------------------------- |
| Database chính    | `data/RBS.db` (SQLite, WAL) — auth, users, missions, queue, maps, dashboards, … |
| Media map         | `data/maps/{map_id}/`                                                           |
| Media sound       | `data/sounds/{sound_id}/`                                                       |
| Recordings (stub) | `data/recordings/`                                                              |
| Layout catalog    | document `state` trong DB + `data/state.json` (legacy)                          |


Lần khởi động đầu, server **import** các file JSON cũ (nếu có) vào SQLite: `auth.json`, `missions.json`, `mission_queue.json`, `robot_runtime.json`.

**Site import/export** (Setup → Maps): bundle JSON gồm `maps`, `io_modules`, `transitions`, `paths` — `POST /api/sites/{site_id}/import`.

## Build

```bash
# Ubuntu/Debian: sudo apt install libsqlite3-dev cmake build-essential
cmake -S . -B build
cmake --build build -j
```

Binary: `build/robot_app`

## Run

Chạy mặc định port 8080, phục vụ static từ `www/`, database tại `data/RBS.db`:

```bash
./build/robot_app
```

Hoặc chỉ định đủ tham số:

```bash
./build/robot_app <port> <www_dir> <db_path>
# ví dụ:
./build/robot_app 8080 ./www ./data/RBS.db
```

Mở trình duyệt: `http://localhost:8080/`

Tắt auth cho dev/test:

```bash
LM_AUTH_DISABLED=1 ./build/robot_app
```



## Docker (giới hạn 2 CPU, 4 GB RAM)

Mô phỏng cấu hình controller tối thiểu (Dual-Core, 4 GB) trên máy dev:


| Mục             | Giá trị             |
| --------------- | ------------------- |
| Compose service | `robot-app`         |
| Image           | `robot-app:RBS`     |
| Container       | `robot-app-limited` |
| Port            | `8080`              |


```bash
./scripts/lm.sh docker up
# hoặc:
sudo docker compose up --build -d
```

Sau khi đổi tên service/container, nếu port 8080 bị chiếm bởi container cũ:

```bash
sudo docker compose down --remove-orphans
sudo docker compose up --build -d
```

Kiểm tra / dừng:

```bash
./scripts/lm.sh docker stats
./scripts/lm.sh docker down
```

Dữ liệu lưu trên host qua volume `./data:/app/data`.

```bash
./scripts/lm.sh docker shell   # shell trong container
./scripts/lm.sh docker htop
```



## Biến môi trường


| Biến               | Mặc định                | Mô tả                             |
| ------------------ | ----------------------- | --------------------------------- |
| `LM_AUTH_DISABLED` | —                       | `1` = tắt xác thực API (dev/test) |
| `LM_URL`           | `http://127.0.0.1:8080` | URL khi test container            |
| `LM_CONTAINER`     | `robot-app-limited`     | Tên container Docker              |
| `LM_TEST_PORT`     | `18080`                 | Port server tạm khi `test run`    |




## API (tóm tắt)



### Maps, sounds, dashboards


| Method         | Endpoint                | Mô tả                          |
| -------------- | ----------------------- | ------------------------------ |
| GET/POST       | `/api/maps`             | Danh sách / tạo map            |
| GET/PUT/DELETE | `/api/maps/{id}`        | CRUD map                       |
| GET/POST       | `/api/maps/{id}/image`  | Ảnh map (`data/maps/{id}/`)    |
| GET/POST       | `/api/sounds`           | Danh sách / tạo sound          |
| GET/PUT/DELETE | `/api/sounds/{id}`      | CRUD sound                     |
| GET/POST       | `/api/sounds/{id}/file` | Upload/tải file âm thanh       |
| POST           | `/api/sounds/{id}/play` | Phát trên robot (volume 0–100) |
| GET/PUT        | `/api/dashboards`       | Dashboard server-side          |




### Missions & queue


| Method  | Endpoint                      | Mô tả                    |
| ------- | ----------------------------- | ------------------------ |
| GET/PUT | `/api/missions`               | Danh sách / lưu missions |
| GET     | `/api/mission_queue`          | Queue + runner status    |
| POST    | `/api/mission_queue`          | Enqueue mission          |
| DELETE  | `/api/mission_queue`          | Xóa toàn bộ queue        |
| DELETE  | `/api/mission_queue/{id}`     | Xóa một entry            |
| PUT     | `/api/mission_queue/reorder`  | Sắp xếp lại queue        |
| POST    | `/api/mission_queue/pause`    | Tạm dừng runner          |
| POST    | `/api/mission_queue/continue` | Tiếp tục runner          |
| POST    | `/api/mission_queue/cancel`   | Hủy mission đang chạy    |


REST tương thích: `GET/POST/DELETE /api/v2.0.0/mission_queue`

### Transitions, paths, I/O


| Method              | Endpoint                        | Mô tả                                  |
| ------------------- | ------------------------------- | -------------------------------------- |
| GET/POST            | `/api/transitions`              | CRUD transition (`?site_id=`)          |
| GET/DELETE          | `/api/paths`, `/api/paths/{id}` | Path cache (auto-create; xóa thủ công) |
| GET/POST/PUT/DELETE | `/api/path_guides`              | Path guides                            |
| GET/POST/PUT/DELETE | `/api/io_modules`               | I/O modules (Bluetooth / WISE)         |
| POST                | `/api/io_modules/test`          | Kiểm tra kết nối TCP                   |


**Transitions:** Setup → Transitions — cấu hình chuyển map (from/to map, start/goal position, mission liên kết). Khi mission chạy `move_to_position` hoặc `adjust_localization` tới position trên map khác `active_map_id`, runner tự chèn: đi tới start position → chạy transition mission → chuyển map → đi tới goal position → tiếp tục bước gốc.

### Robot & tích hợp


| Method          | Endpoint                               | Mô tả                                       |
| --------------- | -------------------------------------- | ------------------------------------------- |
| GET             | `/api/robot/status`                    | Trạng thái robot (pin, pose, mission strip) |
| POST            | `/api/robot/start`, `/api/robot/pause` | Start / pause                               |
| POST            | `/api/robot/errors/reset`              | Xóa lỗi                                     |
| POST            | `/api/robot/active_map`                | Đặt map đang hoạt động                      |
| GET/POST/DELETE | `/api/triggers`                        | Modbus mission triggers (coil 1001–2000)    |
| GET/POST/DELETE | `/api/fleet/schedules`                 | Lịch fleet (stub scheduler)                 |
| GET             | `/api/recordings`                      | Stub — trả về `[]`                          |


Modbus TCP server: port **5502** (mission triggers + action coils 1–6).

### Đăng nhập

Trang web **bắt buộc đăng nhập** (password hoặc PIN 4 số). Tài khoản mặc định:


| User        | Password    | Nhóm                                  |
| ----------- | ----------- | ------------------------------------- |
| Admin       | admin       | Administrators (full quyền)           |
| User        | user        | Users (dashboard write, còn lại read) |
| Distributor | distributor | Distributors (full quyền)             |


PIN chỉ dùng với nhóm **Users** sau khi admin gán (`PUT /api/users/:id`).

Chi tiết auth & permissions: `docs/Reference_guide.md` [§2](docs/Reference_guide.md#2-đăng-nhập-và-phân-quyền).

## Test tự động

Chạy toàn bộ: unit C++ (GTest), API smoke (`curl`), pytest integration.

```bash
chmod +x scripts/lm.sh scripts/test/*.sh
./scripts/lm.sh test run
```

Chỉ unit test C++:

```bash
cmake -S . -B build -DBUILD_TESTING=ON
cmake --build build -j
./build/robot_app_tests
# hoặc: ctest --test-dir build --output-on-failure
```

Chỉ API smoke (server đang chạy, fixture `tests/fixtures/data/`):

```bash
./build/robot_app 18080 www tests/fixtures/data/state.json &
./scripts/lm.sh test smoke http://127.0.0.1:18080
```

Fixture mission id mặc định: `testmission00001` (`tests/fixtures/data/missions.json`).

Benchmark trong container (cần `docker compose up -d`):

```bash
./scripts/lm.sh docker bench
# hoặc: ./scripts/lm.sh bench http
```

CI: GitHub Actions workflow `.github/workflows/test.yml`.