HiepLM/App

Fork 0

Files

HiepLM e0e864ea13

Test / test (push) Has been cancelled

Details

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

2026-06-24 17:09:58 +07:00

13 KiB

Raw Blame History

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.

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, build-robot → `config`	`*.js`	🔶
Monitoring	monitoring-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 — ⏳

Trang pageMonitoring: placeholder «System log — đang phát triển».

Chưa có: Analytics, Error logs, Hardware health, Safety system, Mission log browser.

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).

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
🔶 Đang dùng được:  Dashboard, Missions, Maps, I/O, Paths, Integrations, Topbar, Build robot
⏳ Placeholder:     Monitoring, 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, style.css, i18n.js.

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

./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.

13 KiB Raw Blame History Unescape Escape