Quick Start

# 1. Clone repo (code is on main)
git clone https://github.com/AI20K-Build-Cohort-2/C2-App-071.git
cd C2-App-071

# 2. Setup environment
cp .env.example .env
# Điền ANTHROPIC_API_KEY, NVIDIA_API_KEY hoặc GEMINI_API_KEY vào .env

# 3. Seed tài khoản đăng nhập (dev) — users.json bị gitignore
cp users.example.json users.json
# users.example.json chỉ chứa bcrypt password_hash, không chứa plaintext password.
# Nếu đổi mật khẩu demo, sinh hash trước rồi thay vào users.json:
# python -c "import bcrypt; print(bcrypt.hashpw(b'opstream', bcrypt.gensalt()).decode())"

# 4. Cài dependencies
pip install -r requirements.txt

# 5. Chạy server — FastAPI phục vụ cả hai màn hình
uvicorn src.main:app --reload --port 8000

Mở http://localhost:8000 — vì các màn hình giờ yêu cầu đăng nhập, bạn sẽ được chuyển tới /login. Đăng nhập bằng tài khoản demo (hiện ngay trên màn hình, bấm để điền): an / binh / gm, mật khẩu opstream. Sau khi đăng nhập, tự chuyển tới Lịch phòng. Dùng menu trên cùng để chuyển giữa Lịch phòng (/dashboard) và Tóm tắt ca (/summary); khách sạn đang chọn được giữ nguyên khi chuyển màn hình.

Phân quyền (FR-10): lễ tân chỉ thấy khách sạn của mình; GM thấy tất cả. Yếu tố ca trực đã được gỡ bỏ hoàn toàn (2026-06-23) khỏi việc và phân quyền — phân quyền chỉ theo khách sạn, và việc tồn tự động chuyển sang ngày sau (bàn giao theo ngày, một danh sách mọi việc chưa xong). Tài khoản đọc từ users.json (Phase 1); bảng users đã có trong database (Phase 2) làm gương FK/định danh, nhưng auth vẫn đọc users.json.

Windows (no make): the Makefile targets are convenience wrappers — run the commands directly if make isn't installed:

Make target	Direct command
make run	uvicorn src.main:app --reload --port 8000
make test	pytest tests/ -v
make lint	ruff check src/ tests/
make format	ruff format src/ tests/

Project Structure

├── src/
│   ├── agents/
│   │   ├── graph.py              # LangGraph: fetch → clean → summarize
│   │   ├── state.py              # AgentState schema
│   │   ├── prompts.py            # SYSTEM_PROMPT + boilerplate/service keywords
│   │   ├── nodes/
│   │   │   ├── fetch_node.py     # Async PMS fetch + check-out balances + room statuses + anomalies
│   │   │   ├── clean_node.py     # Strip OTA boilerplate, lead with unresolved tasks, inject filtered tables + anomalies, build LLM prompt
│   │   │   └── summarize_node.py # Dispatch to Claude / Nvidia / Gemini
│   │   └── tools/
│   │       └── reviews_tool.py   # OTA review stub (FR-01, pending)
│   ├── auth/                     # Auth foundation (Phase 1)
│   │   ├── users.py              # Seeded user store (JSON→memory, bcrypt)
│   │   ├── session.py            # Signed cookie session (itsdangerous)
│   │   └── dependencies.py       # get_current_user, require_role, can_access_hotel (FR-10)
│   ├── api/
│   │   ├── auth.py               # POST /auth/login, /auth/logout, GET /auth/me
│   │   ├── summary.py            # POST /api/v1/summary
│   │   ├── tasks.py              # Task lifecycle API (Phase 3): CRUD + transition/undo/reopen/audit
│   │   ├── assistant.py          # POST /api/v1/assistant/message (conversational ops assistant)
│   │   └── dashboard.py          # Dashboard JSON feeds: rooms/events/unpaid/reservation
│   ├── web/
│   │   └── dashboard.py          # Dashboard screens (gated): GET /login, /dashboard, /summary, /tasks, /dashboard/view
│   ├── dashboard/                # Static screen assets
│   │   ├── login.html            # Login screen (demo accounts, click-to-fill)
│   │   ├── index.html            # Scheduler overview screen
│   │   ├── summary.html          # Shift-summary screen (form → /api/v1/summary)
│   │   ├── tasks.html            # Task board (Phase 3): create, advance lifecycle, undo, audit
│   │   ├── view.html             # Read-only reservation detail screen
│   │   └── static/               # Vendored DayPilot JS + theme CSS + assistant.{js,css} (chat widget)
│   ├── models/
│   │   ├── schemas.py            # Pydantic contracts: Summary, Login/UserOut, Task/Audit/Verify
│   │   └── orm.py                # SQLAlchemy ORM (Phase 2): User, Task, append-only AuditLog
│   ├── services/
│   │   ├── pms.py                # Async PMS API client (httpx + asyncio.gather)
│   │   ├── dashboard_pms.py      # PMS client + transforms for the dashboard
│   │   ├── tasks.py              # Task lifecycle service (Phase 3): FR-05/08/09/10 rules
│   │   ├── verifier.py           # Verify-vs-PMS + note extraction (Phase 4): deterministic-wins
│   │   ├── assistant.py          # Conversational ops assistant: live context + propose-only actions
│   │   ├── result_cache.py       # In-memory LLM result cache (skip re-runs when PMS state unchanged)
│   │   └── llm.py                # Multi-provider LLM dispatcher
│   ├── db.py                     # Lazy engine + session factory (reads database_url)
│   ├── config.py                 # Pydantic Settings (all env vars)
│   └── main.py                   # FastAPI app entry point
├── alembic/                      # DB migrations (Phase 2); env reads settings.database_url
│   └── versions/                 # 0001_create_users_tasks_audit
├── alembic.ini
├── tests/
│   ├── test_agents/
│   │   ├── test_nodes.py         # Unit tests for each LangGraph node
│   │   └── test_routing.py       # Conditional edge routing tests
│   ├── test_auth/
│   │   └── test_auth.py          # Login/logout/me, session signing, FR-10 hotel scope
│   ├── test_db/
│   │   └── test_orm.py           # Schema + append-only audit guard (in-memory SQLite)
│   ├── test_services/
│   │   ├── test_tasks.py         # Lifecycle/RBAC/undo/reopen rules (Phase 3)
│   │   ├── test_verifier.py      # Deterministic-wins, no_evidence routing, defensive extract (Phase 4)
│   │   ├── test_assistant.py     # Ops assistant: context shape, JSON parse, action safety rails, briefing cache
│   │   └── test_result_cache.py  # Content-addressed cache: hit/miss on fingerprint match
│   └── test_api/
│       ├── test_summary.py       # Integration tests for /api/v1/summary
│       ├── test_assistant.py     # /assistant/message: auth gate, RBAC, response contract
│       └── test_tasks.py         # Task API: create→list, skip-to-Done rejected, audit
├── users.example.json            # Template for dev login accounts (copy → users.json)
├── docs/
│   └── architecture_diagram.md   # Mermaid diagrams
├── ARCHITECTURE.md               # Full architecture document
├── Dockerfile
├── docker-compose.yml
└── .github/workflows/            # CI/CD (lint + test)

API Endpoints

Dashboard

Screens (web layer — user-facing, no /api prefix). All dashboard screens require a session — unauthenticated requests redirect to /login?next=…:

A floating ops-assistant chat widget (src/dashboard/static/assistant.{js,css}) is embedded on the dashboard, summary, and task screens. Opening it greets the shift with a prioritized "what to do now" briefing built from live PMS + task state, answers follow-up questions, and turns "I just did X" into confirm-to-create/advance task buttons that run through the audited /tasks routes — so the AI proposes but the human (and the existing FR-05/FR-08/FR-09/FR-10 guards) still commit.

Both the summary and the assistant briefing are backed by an in-memory result cache (src/services/result_cache.py): the LLM input is a deterministic fingerprint of the PMS data + tasks, so an unchanged state reuses the last result and skips the LLM call (a subtle "data unchanged" hint shows); creating/advancing a task changes the fingerprint and re-runs automatically.

Data feeds (API layer — JSON consumed by the screens):

Environment Variables

# At least one LLM key is required
ANTHROPIC_API_KEY=sk-ant-...
NVIDIA_API_KEY=...
GEMINI_API_KEY=...

# PMS API (default already set)
PMS_BASE_URL=https://dongxuanboutiquehotel.com/api/

# Auth / session (defaults work for dev; set a real secret in production)
SESSION_SECRET=change-me-in-production
# SESSION_COOKIE=opstream_session
# SESSION_MAX_AGE=43200          # seconds (12h)
# USERS_FILE=users.json          # dev login accounts (gitignored)

# Database (Phase 2). Default is SQLite for the POC; gitignored data/app.db.
DATABASE_URL=sqlite:///./data/app.db

Database (Phase 2): persistence is back as schema only — SQLAlchemy ORM (src/models/orm.py) + Alembic. Create the local POC DB with:

DATABASE_URL='sqlite:///./data/app.db' alembic upgrade head

Tables: users, tasks (FR-05 lifecycle), audit_log (append-only, FR-08). The data/app.db file is gitignored.

Tests

pytest tests/ --cov=src --cov-report=term-missing
# 98 tests passing

Deliverables Checklist

• Source Code (GitHub — branch main)
• README.md
• Architecture Diagram (docs/architecture_diagram.md, ARCHITECTURE.md)
• AI Logs (auto-collected via hooks)
• Live URL / Deploy
• [ x] Video Demo
• [x ] Pitch Deck (presentation/)
• Development Journal (JOURNAL.md)
• Worklog (WORKLOG.md)
• Evaluation Evidence (eval/) — 7 agent eval cases, output thực tế (python -m eval.run_eval)

Team

License

MIT