Thêm hướng dẫn vào tài liệu

README.md

@@ -1,60 +1,174 @@
 # Robot App Web (RBS)
 
-Chức năng:
+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`
-- Database SQLite: `data/RBS.db` (WAL mode). Thư mục media: `data/maps/`, `data/sounds/`, `data/recordings/`
+- 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
-cd /home/robotics/RD/RBS
-# Ubuntu/Debian: sudo apt install libsqlite3-dev
+# 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/`, dữ liệu SQLite tại `data/RBS.db`:
+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:
+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/`
 
-### API Maps & Sounds (SQLite)
+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 | `/api/maps` | Danh sách map |
-| POST | `/api/maps` | Tạo map (JSON metadata) |
+| GET/POST | `/api/maps` | Danh sách / tạo map |
 | GET/PUT/DELETE | `/api/maps/{id}` | CRUD map |
-| GET/POST | `/api/maps/{id}/image` | Tải/xem ảnh map (file trong `data/maps/{id}/`) |
-| GET | `/api/sounds` | Danh sách sound |
-| POST | `/api/sounds` | Tạo sound |
+| 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` | Tải/upload file âm thanh |
-| POST | `/api/sounds/{id}/play` | Phát sound trên robot (volume 0–100) |
-| GET/POST | `/api/transitions` | Danh sách / tạo transition (`?site_id=`) |
-| GET/PUT/DELETE | `/api/transitions/{id}` | CRUD transition |
-| GET/PUT | `/api/dashboards` | Dashboard (server-side, thay localStorage) |
-| GET | `/api/recordings` | Stub — trả về `[]` (Phase sau) |
+| 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 |
 
-**Transitions (MiR §4.4):** Setup → Transitions — cấu hình chuyển map (from/to, start/goal position, mission có `switch_map`). 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: di chuyển tới start position → chạy transition mission → chuyển map → di chuyển tới goal position → tiếp tục bước gốc. Position trong mission editor lấy từ zones `type: position` trên từng map.
+### Missions & queue
 
-### Đăng nhập (Signing in — MiR §2.1)
+| 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 |
 
-Trang web **bắt buộc đăng nhập**. Hai tab: tên/mật khẩu hoặc **Mã PIN** (keypad 4 số). Tài khoản mặc định (trong `data/RBS.db`, seed lần đầu):
+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 |
 |------|----------|------|
@@ -62,60 +176,15 @@ Trang web **bắt buộc đăng nhập**. Hai tab: tên/mật khẩu hoặc **M
 | User | user | Users (dashboard write, còn lại read) |
 | Distributor | distributor | Distributors (full quyền) |
 
-PIN 4 chữ số chỉ dùng được với user thuộc nhóm **Users** sau khi admin gán PIN (`PUT /api/users/:id`).
+PIN chỉ dùng với nhóm **Users** sau khi admin gán (`PUT /api/users/:id`).
 
-Tắt auth cho dev/test: `LM_AUTH_DISABLED=1 ./build/robot_app …`
-Tài liệu đầy đủ: [`docs/Reference_guide.md` §2.1](docs/Reference_guide.md#21-signing-in).
-
-## Docker (giới hạn 2 CPU, 4 GB RAM)
-
-Mô phỏng cấu hình controller tối thiểu SICK (Dual-Core, 4 GB) trên máy dev:
-
-```bash
-cd /home/robotics/RD/RBS
-./scripts/lm.sh docker up
-# hoặc: sudo docker compose up --build -d
-```
-
-Kiểm tra giới hạn:
-
-```bash
-./scripts/lm.sh docker stats
-```
-
-Dừng:
-
-```bash
-./scripts/lm.sh docker down
-```
-
-Dữ liệu layout vẫn lưu tại `data/` trên host (volume mount).
-
-Kiểm tra tài nguyên trong container:
-
-```bash
-# Vào shell container
-./scripts/lm.sh docker shell
-
-# Trong container, thử:
-htop          # CPU/RAM (q để thoát)
-free -h       # RAM
-nproc         # số CPU nhìn thấy
-ps aux        # process
-cat /proc/meminfo | head
-```
-
-```bash
-./scripts/lm.sh docker htop
-./scripts/lm.sh docker stats
-```
+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
-cd /home/robotics/RD/RBS
 chmod +x scripts/lm.sh scripts/test/*.sh
 ./scripts/lm.sh test run
 ```
@@ -125,10 +194,11 @@ Chỉ unit test C++:
 ```bash
 cmake -S . -B build -DBUILD_TESTING=ON
 cmake --build build -j
-ctest --test-dir build --output-on-failure
+./build/robot_app_tests
+# hoặc: ctest --test-dir build --output-on-failure
 ```
 
-Chỉ API smoke (server đang chạy, dùng fixture `tests/fixtures/data/`):
+Chỉ API smoke (server đang chạy, fixture `tests/fixtures/data/`):
 
 ```bash
 ./build/robot_app 18080 www tests/fixtures/data/state.json &
@@ -137,12 +207,11 @@ Chỉ API smoke (server đang chạy, dùng fixture `tests/fixtures/data/`):
 
 Fixture mission id mặc định: `testmission00001` (`tests/fixtures/data/missions.json`).
 
-Benchmark hiệu năng trong container (cần `docker compose up -d`):
+Benchmark trong container (cần `docker compose up -d`):
 
 ```bash
 ./scripts/lm.sh docker bench
-# hoặc chỉ HTTP: ./scripts/lm.sh bench http
+# hoặc: ./scripts/lm.sh bench http
 ```
 
 CI: GitHub Actions workflow `.github/workflows/test.yml`.
-