419 lines
17 KiB
Markdown
419 lines
17 KiB
Markdown
# 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.
|