# RBS Web Interface — Tài liệu tham chiếu

> Ứng dụng `robot_app` — giao diện web quản lý robot, mission, map và tích hợp.

**Chú thích trạng thái:** ✅ đầy đủ · 🔶 một phần · ⏳ placeholder · ❌ chưa có

---

## 1. Giới thiệu

Tài liệu mô tả giao diện web RBS cho **administrator**, kỹ sư cấu hình và operator: đăng nhập, dashboard, mission, map, user, Modbus/REST tích hợp.

**Stack:** frontend `www/` (vanilla JS), backend C++ (`src/server/`, `src/mission/`, …), dữ liệu SQLite `data/RBS.db` + `data/auth.json`.

---

## 2. Đăng nhập và phân quyền

### 2.1 Luồng đăng nhập

```
Trình duyệt → / (trang Sign in)
  → POST /api/auth/login (password hoặc PIN)
  → Cookie lm_session + shell app (Dashboard / Setup / Monitoring / System / Help)
  → Menu user (góc phải): đổi mật khẩu, đăng xuất
```

- Toàn bộ API (trừ health/login/logout) yêu cầu session; UI bị chặn cho đến khi đăng nhập.
- `auth.js` gọi `GET /api/auth/me` khi mở trang; session hợp lệ thì vào app ngay.
- Các module JS (`app.js`, `missions.js`, `dashboard.js`, …) khởi động sau sự kiện `lm:auth-ready`.

### 2.2 Giao diện Sign in

| Thành phần | Mô tả |
|------------|--------|
| Tab **Tên đăng nhập và mật khẩu** | Form username + password |
| Tab **Mã PIN** | Keypad 4 chữ số; tự đăng nhập khi đủ 4 số |
| Sau login | Menu user topbar; ẩn/vô hiệu hóa theo quyền read-only |

File: `www/index.html`, `www/auth.js`, `www/style.css`.

### 2.3 Tài khoản mặc định

Tự tạo lần đầu trong `data/auth.json`:

| Username | Password | User group |
|----------|----------|------------|
| `Admin` | `admin` | Administrators |
| `User` | `user` | Users |
| `Distributor` | `distributor` | Distributors |

- Username **không phân biệt hoa thường**.
- **PIN:** không có mã mặc định; chỉ nhóm có `allow_pin: true`; admin gán qua API/UI.

### 2.4 User groups và permissions

Credentials gắn **user**; quyền gắn **group**. Mỗi user thuộc một nhóm.

**7 resource:** `dashboard`, `config`, `maps`, `missions`, `sounds`, `integrations`, `users` — giá trị `none` | `read` | `write`.

| Group | PIN | dashboard | config | maps | missions | sounds | integrations | users |
|-------|-----|-----------|--------|------|----------|--------|--------------|-------|
| Distributors | Không | write | write | write | write | write | write | write |
| Administrators | Không | write | write | write | write | write | write | write |
| Users | Sau khi gán | write | read | read | read | read | read | none |

Trang không có quyền write: **vẫn hiển thị**, nút tạo/sửa bị vô hiệu (`body.auth-readonly-*`).

**Quyền trang** (`www/auth.js`):

| Trang | Resource |
|-------|----------|
| `config` | Chỉ nhóm **Distributors** |
| `maps`, `transitions`, `paths`, `path-guides` | `maps` |
| `missions` | `missions` |
| `sounds` | `sounds` |
| `io-modules`, `integrations` | `integrations` |
| `users`, `user-groups` | `users` |
| `monitoring`, `help` | Mọi user đã đăng nhập |

### 2.5 Session và API auth

| Cơ chế | Chi tiết |
|--------|----------|
| Session | Server-side; mất khi restart process |
| Cookie | `lm_session=<token>; HttpOnly; SameSite=Lax` |
| Header | `Authorization: Bearer <token>` |
| Middleware | `AuthService::preRoute` trên `/api/*` |
| Public | `GET /api/health`, `POST /api/auth/login`, `POST /api/auth/logout`, `OPTIONS` |
| Dev | `LM_AUTH_DISABLED=1` tắt auth |

**API → module:**

| Module | Prefix |
|--------|--------|
| config | `/api/lidars`, `/api/imus`, `/api/layouts`, `/api/state`, … |
| maps | `/api/maps`, `/api/sites`, `/api/paths`, `/api/path_guides`, `/api/transitions` |
| missions | `/api/missions`, `/api/mission_queue` |
| sounds | `/api/sounds` |
| integrations | `/api/triggers`, `/api/schedules`, `/api/fleet`, `/api/modbus`, `/api/io_modules`, `/api/v2.0.0/` |
| users | `/api/users`, `/api/user_groups` |

**Endpoint auth chính:**

| Method | Endpoint | Mô tả |
|--------|----------|--------|
| POST | `/api/auth/login` | `{ username, password }` hoặc `{ pin }` |
| POST | `/api/auth/logout` | Xóa session |
| GET | `/api/auth/me` | User, group, permissions |
| PUT | `/api/auth/password` | Đổi mật khẩu |
| GET/POST/PUT/DELETE | `/api/users`, `/api/user_groups` | CRUD user và nhóm |

**Mã nguồn:** `src/auth/auth_service.cpp`, `www/auth.js`, `www/users.js`, `www/user-groups.js`.

**Chưa có:** auto sign-out theo nhóm, OAuth.

---

## 3. Điều hướng và topbar

### 3.1 Shell 3 cột

Rail trái → flyout submenu → content (`www/nav.js`).

| Module | Flyout (section → page) | File JS | Trạng thái |
|--------|-------------------------|---------|------------|
| **Dashboards** | Danh sách động → `dashboard` | `dashboard.js` | ✅ |
| **Setup** | missions, maps, sounds, transitions, users, user-groups, io-modules, paths, path-guides | `*.js` | 🔶 |
| **Robot+** | robot → `config`, simulation → `simulation` | `app.js` (config), — | 🔶 |
| **Monitoring** | analytics (mặc định), system log, error logs, hardware, safety, mission log → `monitoring` | — | ✅ |
| **System** | integrations → `integrations` | `integrations.js` | 🔶 |
| **Help** | help-api → `help` | — | ⏳ |

### 3.2 Topbar (`www/topbar.js`)

| Thành phần | API |
|------------|-----|
| Start / Pause robot | `POST /api/robot/start`, `POST /api/robot/pause` |
| Strip mission, queue hint | `GET /api/robot/status` (~1.5s) |
| Panel lỗi + RESET | `POST /api/robot/errors/reset` |
| Pin, locale vi/en | từ `/api/robot/status` |
| Joystick overlay | `POST /api/robot/joystick`, `POST /api/robot/cmd_vel` |
| Menu user | `GET /api/auth/me` |

Ẩn topbar nếu user không có quyền trang `missions`.

---

## 4. Mục lục tính năng

### 4.1 Dashboards — ✅ / 🔶

- **Quản lý:** list, filter, phân trang, tạo, xóa, designer (kéo thả grid, resize), **Permissions** theo user group, chế độ edit/operate.
- API: `GET/PUT /api/dashboards`.

**Widget:**

| Widget | Trạng thái | Ghi chú |
|--------|------------|---------|
| `mission_button` | ✅ | Queue mission cố định |
| `mission_group` | ✅ | Nút theo nhóm mission |
| `mission_queue` | ✅ | Xem + xóa queue |
| `pause_continue` | ✅ | Pause/continue (+ hủy mission) |
| `mission_action_log` | 🔶 | Log mission đang chạy (~10 dòng) |
| `map_locked` | 🔶 | Robot-centered, không pan/zoom |
| `map` | 🔶 | Pose marker |
| `io_connect` | ✅ | Connect/disconnect I/O |
| `io_status` | ✅ | LED cổng digital |
| `io_configuration` | ✅ | Bật/tắt output |
| `logout_button` | ✅ | |
| `robot_summary` | ⏳ | Chỉ tên robot |
| PLC tab | ⏳ | «Coming soon» |
| Hook / Joystick / Distributor widget | ❌ | Joystick chỉ trên topbar |

File: `www/dashboard.js`.

### 4.2 Setup — Missions — 🔶

| UI | API |
|----|-----|
| Danh sách, tạo, sửa, xóa, Save, Save as | `GET/PUT /api/missions` |
| Editor kéo-thả, If/While/Loop, embed mission con | |
| Queue từ list (dialog biến) | `POST /api/mission_queue` |
| Panel queue: sắp xếp, xóa, clear, pause/continue/cancel | `/api/mission_queue/*` |

**Action types (22):**

| Nhóm | Types |
|------|-------|
| Move | `move_to_position`, `move_to_marker`, `adjust_localization`, `switch_map`, `wait`, `set_speed` |
| Logic | `if`, `while`, `loop`, `break`, `continue`, `pause` |
| I/O | `set_digital_output`, `wait_digital_input`, `connect_bluetooth`, `disconnect_bluetooth`, `set_plc_register` |
| Cart | `pick_cart`, `drop_cart` |
| Misc | `user_log`, `play_sound` |

**Ba cách chạy mission:**

| Cách | Mô tả |
|------|--------|
| Dashboard | Widget mission button |
| Setup → Missions | Icon queue → thêm vào queue |
| Tích hợp ngoài | Modbus trigger, `POST /api/v2.0.0/mission_queue` |

Queue chạy tuần tự; biến mission (`*_var`) hỏi operator khi enqueue.

File: `www/missions.js`, `src/mission/mission_queue.cpp`.

**Chưa có:** Prompt User, Try/Catch, Email, shelf actions, điều kiện If đầy đủ.

### 4.3 Setup — Maps — 🔶

| UI | API |
|----|-----|
| List theo site, tạo, xóa, import site bundle | `/api/maps`, `/api/sites`, `…/import` |
| Editor: pan/zoom, wall/floor/position, zones | `PUT /api/maps` |
| Upload ảnh, YAML, occupancy, undo | `/api/maps/…/image`, `…/yaml` |
| Path preview (từ Paths → View) | overlay trên map editor |
| Cảnh báo preferred zone khi có path cache | confirm trước save |

**Zone types:** wall, floor, position, forbidden, preferred, unpreferred, speed, sound, directional, planner, I/O.

**Chưa có:** markers, evacuation/limit-robots zones; mapping live đầy đủ.

File: `www/maps.js`, `www/map-editor.js`.

### 4.4 Setup — Sounds — ✅

List, upload, nghe, play trên robot, CRUD (không xóa system sound). API: `/api/sounds`. File: `www/sounds.js`.

### 4.5 Setup — Transitions — ✅

List, filter, pager, CRUD dialog (site, from/to map, start/goal position, mission). API: `/api/transitions`. File: `www/transitions.js`.

### 4.6 Setup — Users — ✅

List, filter, CRUD, PIN 4 số. API: `/api/users`. File: `www/users.js`.

### 4.7 Setup — User groups — ✅

List, CRUD, ma trận quyền 7 resource, `allow_pin`. API: `/api/user_groups`. File: `www/user-groups.js`.

### 4.8 Setup — I/O modules — 🔶

List, filter, CRUD; loại Bluetooth / WISE; test TCP từ dialog. API: `/api/io_modules`, `…/test`. Connect runtime qua dashboard widgets.

File: `www/io-modules.js`.

### 4.9 Setup — Paths — 🔶

**Không có Create** — path cache tự tạo khi robot chạy giữa hai position.

| UI | API |
|----|-----|
| List, filter, pager | `GET /api/paths` |
| View trên map | `MapsApp.openEditorWithPath` |
| Delete | `DELETE /api/paths/:id` |

Backend: `PathStore`, `PathPlanner`, `PathService`; invalidate khi đổi position; export/import trong site bundle.

File: `www/paths.js`.

### 4.10 Setup — Path guides — ✅

List, wizard tạo, sửa starts/vias/goals, xóa. API: `/api/path_guides`. File: `www/path-guides.js`.

### 4.11 Setup — Build robot — 🔶

Chỉ **Distributor**. Layout đa cấu hình, LiDAR/IMU CRUD, canvas robot diff.

API: `/api/layouts`, `/api/lidars`, `/api/imus`, `/api/state`. File: `www/app.js` (`pageConfig`).

### 4.12 Chưa triển khai (Setup)

| Mục | Trạng thái |
|-----|------------|
| Shelf types | ❌ |

---

## 5. Monitoring — ✅

Flyout 6 mục (giống MiR): **Analytics**, **System log**, **Error logs**, **Hardware health**, **Safety system**, **Mission log**.  
Frontend: `www/monitoring.js` (poll ~2.5s), layout `www/index.html`, style `www/style.css`, i18n `www/i18n.js`.  
Backend: `src/monitoring/monitoring_service.*`, routes `src/server/api_monitoring_routes.cpp`, mission persist trong `src/storage/mission_run_store.*`.

### 5.1 Analytics — ✅
- **UI**: chọn `Start date` / `End date`; preset (current week/7d/30d/365d); `Grouping` day/month; chart mode **Bar graph** / **Accumulated**.
- **API**: `GET /api/monitoring/analytics?start=YYYY-MM-DD&end=YYYY-MM-DD&grouping=day|month`
- **Data**: document SQLite `monitoring_analytics` (tích lũy khi robot di chuyển; tick từ `RobotRuntime`).

### 5.2 System log — ✅
- **UI**: bảng `State` (dot màu), `Module`, `Message`, `Time`; filter + pager; refresh.
- **API**: `GET /api/monitoring/system_log`
- **Data**: document SQLite `monitoring_system_log` (sự kiện hệ thống + một phần sự kiện error).

### 5.3 Error logs — ✅
- **UI**: bảng `Description`, `Module`, `Time`; nút **Generate log** (user log); **Delete all**; xóa từng dòng; **Download** từng log.
- **API**:
  - `GET /api/monitoring/error_logs`
  - `POST /api/monitoring/error_logs/generate`
  - `DELETE /api/monitoring/error_logs`
  - `DELETE /api/monitoring/error_logs/<id>`
  - `GET /api/monitoring/error_logs/<id>/download`
- **Data**: document SQLite `monitoring_error_logs` (+ action snapshot ring `monitoring_action_ring`).

### 5.4 Hardware health — ✅
- **UI**: accordion nhóm (Computer, Motors, Power system, Safety system, Sensors, Modbus) → expand xem component.
- **API**: `GET /api/monitoring/hardware_health`
- **Data**: ghép từ `robot_status` + `StateRepository` (Build robot: LiDAR/IMU).

### 5.5 Safety system — ✅
- **UI**: live cards (E-stop, Front scanner, Rear scanner) với trạng thái Free/Blocked, Released/Activated.
- **API**: `GET /api/monitoring/safety`
- **Data**: từ `robot_status.safety` (hiện default/placeholder nếu chưa có phần cứng thật).

### 5.6 Mission log — ✅ (MiR-like, có lịch sử bền vững)
- **UI**: bảng Mission/State/Message/Start time/Ran for/Started by; filter + pager; **View action log** (icon mắt); Phase 3/4: **Delete history**, xóa từng run, **Download run bundle**.
- **API**:
  - Queue hiện tại: `GET /api/mission_queue`
  - Lịch sử persist:
    - `GET /api/monitoring/mission_runs?limit=N`
    - `GET /api/monitoring/mission_runs/<id>/actions`
    - `DELETE /api/monitoring/mission_runs` (clear history)
    - `DELETE /api/monitoring/mission_runs/<id>`
    - `GET /api/monitoring/mission_runs/<id>/download` (Phase 4 bundle JSON: run + actions + robot snapshot)
- **Data**:
  - Queue: document SQLite `mission_queue` (mất khi clear queue)
  - History: tables `mission_runs`, `mission_run_actions` (không mất khi clear queue)
  - **Retention** (Phase 4): giữ tối đa ~2000 runs gần nhất (DB bounded history).

**Chưa có (so với MiR)**: error log file mã hóa gửi Support; retention cấu hình qua UI; safety/hardware đọc từ phần cứng thật (thay vì stub/snapshot).

---

## 6. System — Integrations — 🔶

File: `www/integrations.js`.

| UI | API |
|----|-----|
| Modbus mission triggers (tạo, xóa, fire coil) | `/api/triggers`, `/api/modbus/coils` |
| REST v2 — ví dụ enqueue | `POST /api/v2.0.0/mission_queue` |
| Fleet schedules (tạo, xóa, run now) | `/api/fleet/schedules` |

**Modbus (tương thích tích hợp):**

- Mission triggers: coil 1001–2000 → enqueue mission.
- Action commands: coil 1–6 (continue, pause, cancel mission, clear queue, clear error).
- Server Modbus TCP `:5502`.

**Chưa có:** Settings, Backups, PLC registers UI, Processes, Software versions; sửa trigger/schedule (chỉ add/delete).

### 6.1 System — Settings — ✅

Trang Settings theo style MiR (card/section + Apply). Frontend: `www/settings.js`.

**Nhóm Logging & retention:**
- `retention_mission_runs`: số mission runs lịch sử tối đa (bounded history; ảnh hưởng Mission log Phase 3/4).
- `retention_system_log`: số dòng system log tối đa.
- `retention_error_logs`: số dòng error log tối đa.
- `log_level`: `error|warn|info|debug` (hiện mới dùng làm setting; chưa ảnh hưởng sâu tới backend logging).

**API:**
- `GET /api/settings`
- `PUT /api/settings`

**Data:** document SQLite `settings`. Retention được áp dụng khi ghi log/runs mới (trim tự động).

---

## 7. Help — ⏳

Trang `pageHelp`: text trỏ tới System → Integrations và tài liệu API.

**Chưa có:** API browser nhúng, service book.

---

## 8. REST API robot

Base tương thích: `http://<host>/api/v2.0.0/`

| Endpoint | Mô tả |
|----------|--------|
| `GET /status` | Trạng thái robot |
| `GET /missions` | Danh sách mission |
| `GET /mission_queue` | Queue hiện tại |
| `POST /mission_queue` | Enqueue (`mission_id`) |
| `DELETE /mission_queue` | Xóa queue |

Xác thực: session cookie hoặc Bearer (ưu tiên session web); tích hợp ngoài có thể dùng Basic tùy cấu hình.

**Robot runtime:** `GET /api/robot/status`, start/pause, joystick, active map, sound play.

---

## 9. Tóm tắt triển khai

```
✅ Hoàn thiện tốt:  Sign in, Users, User groups, Sounds, Transitions, Path guides, Monitoring
🔶 Đang dùng được:  Dashboard, Missions, Maps, I/O, Paths, Integrations, Topbar, Build robot
⏳ Placeholder:     Help, Robot summary widget, PLC tab
❌ Chưa bắt đầu:    Shelf types, Analytics/Error logs/Hardware/Safety, System Settings/Backups
```

**File frontend chính:** `index.html`, `nav.js`, `topbar.js`, `auth.js`, `app.js`, `dashboard.js`, `missions.js`, `maps.js`, `map-editor.js`, `sounds.js`, `transitions.js`, `users.js`, `user-groups.js`, `io-modules.js`, `paths.js`, `path-guides.js`, `integrations.js`, `monitoring.js`, `style.css`, `i18n.js`.

---

## 10. Vận hành và kiểm thử

```bash
./scripts/lm.sh test run   # smoke + pytest
docker compose up --build -d   # sau sửa www/
```

- Dữ liệu: `data/RBS.db`, `data/auth.json`, `data/state.json`.
- Hard refresh (`Ctrl+Shift+R`) nếu cache JS/CSS.