Tìm dịch vụ, đặt lịch, theo dõi hồ sơ khám và vận hành bệnh viện trong một hệ thống; trợ lý AI hỗ trợ thông tin theo các ranh giới nguồn và quyền truy cập.
Ngôn ngữ: Tiếng Việt · English
Website · Tài liệu · Chạy local · Kiến trúc
Ảnh và GIF được ghi từ stack demo local với dữ liệu giả lập. Chúng cho thấy giao diện đã render, không xác nhận thao tác đặt lịch, thanh toán, điều trị hay trạng thái của website đang triển khai. Trợ lý AI hỗ trợ thông tin; quyết định y tế thuộc nhân viên chuyên môn. Nguồn gốc media.
- Tổng quan sản phẩm
- Trải nghiệm và GIF
- Kiến trúc hệ thống
- Luồng nghiệp vụ và dữ liệu
- Trợ lý AI và ranh giới an toàn
- Chạy dự án trên máy mới
- Công nghệ, mã nguồn và API
- Kiểm thử và tài liệu chuyên sâu
- Đóng góp và giấy phép
HealthCare tổ chức hành trình khám trong một mô hình bệnh viện có nhiều chi nhánh. Người dùng khám phá chuyên khoa, bác sĩ và gói khám; chọn khung giờ; theo dõi cuộc hẹn và thông tin sau khám. Bác sĩ làm việc trong cổng lâm sàng riêng. Quản trị viên quản lý danh mục, nội dung, tài khoản và các hàng đợi cần quyết định của người có quyền.
| Vai trò | Hành trình trong ứng dụng | Điểm đọc tiếp |
|---|---|---|
| Khách | Tìm cơ sở, chuyên khoa, bác sĩ, gói khám, bài viết và bắt đầu đặt lịch | Luồng booking |
| Bệnh nhân | Xem lịch hẹn, hồ sơ, đơn thuốc, kết quả, chăm sóc, thông báo và hội thoại AI | Cổng bệnh nhân |
| Bác sĩ | Xem lịch khám, ghi nhận lâm sàng, tư vấn, kế hoạch chăm sóc và bài viết | Cổng bác sĩ |
| Quản trị | Quản lý danh mục, lịch, người dùng, CMS, kiểm duyệt AI và đối soát | Cổng quản trị |
Chi nhánh trong sơ đồ dữ liệu là các đơn vị của cùng một mô hình bệnh viện; điều đó không tự chứng minh cô lập dữ liệu giữa nhiều bệnh viện độc lập. Quyền đọc hồ sơ được kiểm tra tại backend theo chủ sở hữu và liên kết chuyên môn. Phạm vi và thuật ngữ giải thích các vai trò.
Bốn tour dưới đây là video điều hướng trình duyệt thật, ghi trên localhost:3000 từ dữ liệu seed giả lập rồi chuyển sang GIF. Mỗi tour chỉ mở màn hình; không tạo lịch, gửi chat, sửa hồ sơ, xuất bản nội dung hoặc phê duyệt tiền. Media guide ghi tuyến, kích thước, giới hạn và cách tái tạo.
Trang chủ → Chuyên khoa → Bác sĩ → Gói khám → Đặt lịch.
| Trang chủ | Chuyên khoa |
|---|---|
 |
 |
| Bác sĩ | Trang đặt lịch |
 |
 |
Gói khám · Trang chủ ở viewport 390 px
Dashboard → Lịch hẹn → Lịch sử khám → Đơn thuốc → Trợ lý AI.
| Tổng quan | Lịch hẹn |
|---|---|
 |
 |
| Lịch sử khám | Trợ lý AI |
 |
 |
Không gian lâm sàng → Lịch khám → Tư vấn → Kế hoạch chăm sóc → Bài viết.
| Không gian lâm sàng | Lịch khám |
|---|---|
 |
 |
| Tư vấn | Kế hoạch chăm sóc |
 |
 |
Điều hành → Bác sĩ → Người dùng → CMS → Kiểm duyệt AI → Đối soát thanh toán.
| Tổng quan vận hành | Danh bạ bác sĩ |
|---|---|
 |
 |
| CMS | Đối soát thanh toán |
 |
 |
Ứng dụng web dùng Next.js cho giao diện và các route BFF cùng origin. Spring Boot là nơi xác thực, kiểm tra quyền, xử lý giao dịch và lưu nghiệp vụ; đây là một modular monolith. FastAPI phục vụ retrieval/generation AI phía sau Core. PostgreSQL giữ dữ liệu nghiệp vụ; Redis dùng cho rate limit và tín hiệu realtime. Các tích hợp tệp, scanner và mail phụ thuộc cấu hình tính năng.
flowchart TB
Browser["Khách / bệnh nhân / bác sĩ / admin"] --> UI["Next.js UI"]
UI --> BFF["Same-origin BFF"]
BFF -->|"Trusted HTTP + phiên người dùng"| Core["Spring Boot · modular monolith"]
Core -->|"Giao dịch và dữ liệu nghiệp vụ"| SQL[("PostgreSQL + Flyway")]
Core -->|"Rate limit / tín hiệu realtime"| Redis[("Redis")]
Core -->|"Service-authenticated HTTP"| AI["FastAPI · AI service"]
Core -. "Tính năng được bật" .-> Object["MinIO / S3 + scanner"]
Core -. "Theo cấu hình" .-> Mail["Mail / notification"]
AI --> Local["Local RAG"]
AI -. "Adapter được chọn" .-> Projection["Protected RAG projection"]
AI -. "Policy + environment" .-> Provider["Remote provider"]
Ranh giới quan trọng: browser không nhận service token; BFF không cấp quyền nghiệp vụ; Core vẫn kiểm tra vai trò và quyền sở hữu. Đường chấm thể hiện lựa chọn hoặc tính năng có điều kiện, không khẳng định mọi tích hợp đang chạy trên website. Sơ đồ phân tầng, Compose và hosted · Auth/BFF.
flowchart LR
User["Browser localhost:3000"] --> Web["Frontend + BFF"]
Web --> Api["Spring API"]
Api --> DB[("PostgreSQL")]
Api --> Cache[("Redis")]
Api --> AI["FastAPI trên network internal"]
Api -. "Feature flag" .-> Files["MinIO + scanner"]
Api -. "Local mail" .-> Inbox["Mailpit"]
Compose khai báo cổng AI loopback mặc định 127.0.0.1:8000 và AI gắn network internal; khai báo ingress này không tạo provider egress. Các cổng có thể đổi theo .env. Compose base · demo overlay · deployment chi tiết.
Người dùng chọn slot; backend kiểm tra lịch bác sĩ và giữ chỗ có hạn trong transaction. Mã OTP xác nhận trước khi cuộc hẹn chuyển sang CONFIRMED. Khóa slot và ràng buộc PostgreSQL xử lý các request cạnh tranh; UI vô hiệu hóa nút không đủ để ngăn trùng.
sequenceDiagram
actor Patient as Người đặt lịch
participant Web as Browser / BFF
participant Core as BookingService
participant DB as PostgreSQL
participant Mail as Email delivery
Patient->>Web: Chọn bác sĩ, ngày và slot
Web->>Core: POST /appointments/hold
Core->>DB: Transaction + slot lock + validation
alt Slot không hợp lệ hoặc đã bị chiếm
Core-->>Web: Từ chối / xung đột
else Hold hợp lệ
Core->>DB: PENDING_CONFIRMATION + hạn giữ
Core->>Mail: Gửi OTP (outbox khi bật)
Core-->>Web: Booking code và thời hạn
Patient->>Web: Nhập OTP
Web->>Core: POST /appointments/confirm
Core->>DB: Kiểm tra OTP, expiry và trạng thái
Core-->>Web: CONFIRMED khi hợp lệ
end
BookingService, slot locker và luồng nghiệp vụ đầy đủ là nguồn chính xác cho mọi nhánh và trạng thái.
Sơ đồ chỉ chọn các quan hệ giúp đọc hành trình bệnh nhân; schema đầy đủ thuộc Flyway migrations. Dấu quan hệ tùy chọn không cấp quyền truy cập.
erDiagram
users o|--o| patient_profiles : account_binding
users o|--o| doctors : account_binding
doctors ||--o{ doctor_branches : assigned
branches ||--o{ doctor_branches : hosts
doctors ||--o{ doctor_specialties : has
specialties ||--o{ doctor_specialties : includes
patient_profiles ||--o{ appointments : books
doctors ||--o{ appointments : attends
appointments o|--o| medical_records : encounter
medical_records o|--o{ prescriptions : treatment
appointments ||--o| bank_transfer_payments : payment
appointments ||--o{ patient_care_plans : follow_up
PostgreSQL sở hữu appointment, hồ sơ, thanh toán, conversation history và CMS snapshot. Redis không thay thế SQL; object storage chứa tệp nhưng linkage/quyền và trạng thái quét thuộc Core. ERD theo miền và migration.
| Tình huống | Điều kiện để chuyển trạng thái | Nguồn |
|---|---|---|
| Cuộc hẹn | Hold, OTP, hết hạn, check-in và hủy theo quy tắc slot/owner | Booking lifecycle |
| Thanh toán chuyển khoản | Mã giao dịch hoặc webhook vào hàng đợi; duyệt/từ chối theo policy và audit | Payment flow |
| Nội dung CMS | Draft tách public snapshot; publish tạo version rồi client reconcile | CMS realtime |
| Nguồn AI lâm sàng | Revision/hash, approval, revoke và expiry quyết định eligibility | AI governance |
Hỗ trợ công khai chỉ dùng thông tin bệnh viện phù hợp. Hội thoại bệnh nhân có chủ sở hữu, mode, consent, quota và lifecycle riêng. Một lượt tạo câu trả lời đi qua Core để kiểm tra nguồn trước khi dùng provider. Hướng dẫn khẩn cấp cố định được nhận diện sau kiểm tra owner và trước mode/current-consent gate; nhánh đó không gọi provider nhưng vẫn đi qua idempotency và commit control.
flowchart TB
Request["Patient request"] --> Owner["Conversation owner"]
Owner --> Emergency{"Khẩn cấp?"}
Emergency -->|"Có"| Fixed["Hướng dẫn cố định"]
Emergency -->|"Không"| Gate["Mode · consent · safety"]
Gate -->|"Được phép"| Sources["Retrieve + source eligibility"]
Gate -->|"Safety action"| Bounded["Câu trả lời có giới hạn"]
Sources -->|"Nguồn hợp lệ"| Answer["Generation + validation"]
Sources -->|"Thiếu nguồn"| Bounded
Fixed --> Commit["Idempotency + permit + commit"]
Bounded --> Commit
Answer --> Commit
Commit --> History[("Conversation history")]
SSE hoặc hiệu ứng đánh máy không tự chứng minh provider stream token thật. Nguồn công khai, RAG projection và dữ liệu y tế riêng có authority khác nhau. AI/RAG contract · Security · AI service.
Cần Git và Docker Engine với Compose v2. Chạy từng service ngoài Docker cần Node/npm theo frontend engines, Java 21 và Python 3.12. Bắt đầu từ thư mục gốc repo; điền mọi biến server-only bắt buộc trong .env trước khi khởi động.
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
# Điền cấu hình bắt buộc theo docs/getting-started.md.
docker compose -p healthcare-local-demo --env-file .env -f infrastructure/docker-compose.yml -f infrastructure/docker-compose.local-demo.yml config --quiet
docker compose -p healthcare-local-demo --env-file .env -f infrastructure/docker-compose.yml -f infrastructure/docker-compose.local-demo.yml up -d --build
docker compose -p healthcare-local-demo --env-file .env -f infrastructure/docker-compose.yml -f infrastructure/docker-compose.local-demo.yml psKhông chạy lệnh up khi ô bí mật bắt buộc còn trống hoặc khi tên project Compose trùng stack có dữ liệu cần giữ. Getting started mô tả preflight, biến môi trường, health check và cách tránh ghi đè stack hiện hữu.
| Điểm truy cập mặc định | Mục đích |
|---|---|
| localhost:3000 | Website và BFF |
| localhost:8080/actuator/health | Backend health |
| localhost:8025 | Mailpit local |
| localhost:9001 | MinIO console |
localhost:5434 |
PostgreSQL host port của demo |
Tài khoản seed local: patient@healthcare.com, doctor@healthcare.com, admin@healthcare.com. Mật khẩu và binding hồ sơ thuộc demo runbook; tài khoản seed không được suy ra là có trên website public.
| Thành phần | Công nghệ | Nguồn |
|---|---|---|
| Web và BFF | Next.js 16, React, TypeScript, Tailwind | Frontend package, route handlers |
| Core API | Spring Boot 3.5, Java 21, Security, JPA, Flyway | Backend POM, modules |
| AI service | FastAPI, Python 3.12, retrieval/provider adapters | Requirements, AI app |
| Data và local tools | PostgreSQL 16, Redis, MinIO, Mailpit, scanner/ClamAV | Compose |
| CI và infrastructure | GitHub Actions, Docker images, conditional hosted configuration | Workflows, operations |
| Thư mục | Trách nhiệm chính |
|---|---|
| apps/frontend | UI, browser API/BFF và rendered tests |
| apps/backend | Nghiệp vụ, quyền, migration và Java tests |
| apps/ai-service | Routing AI, retrieval, generation và Python tests |
| infrastructure | Compose, scanner và local services |
| supabase | Projection/RLS và reconciliation theo cấu hình |
| docs | Hướng dẫn và quyết định kỹ thuật |
Browser dùng đường /api/v1/* cùng origin; BFF chuyển request tin cậy đến Spring. Method, DTO và quyền cuối cùng thuộc controller/service, không thuộc bảng tóm tắt này.
| Nhóm API | Owner | Điều cần chú ý |
|---|---|---|
| Auth và browser session | AuthController | Cookie/CSRF khác JWT APIs |
| Danh mục và booking | Hospital controllers, AppointmentController | Public/role routes, hold, OTP, owner proof |
| Clinical và chăm sóc | Clinical controllers, Careplan controllers | Patient/doctor linkage |
| Payment và CMS | Payment controllers, CMS controllers | Audit, review và published snapshot |
| Public/patient AI | PublicAiChatController, AiConversationController | Hai bề mặt, nguồn và consent riêng |
API reference chỉ cách tìm method/path/DTO chính xác và phân biệt browser session, JWT, API public, API theo role và control plane nội bộ.
Chạy lệnh trong đúng thư mục của từng service và chuẩn bị môi trường theo Testing. Bảng này là chỉ dẫn tái tạo, không phải tuyên bố toàn bộ suite vừa pass.
| Thành phần | Lệnh chính | Điều kiện |
|---|---|---|
| Frontend | npm ci, npm run verify |
Chạy trong apps/frontend |
| Backend | .\mvnw.cmd -B verify |
Chạy trong apps/backend sau test preflight |
| AI | python -m pytest, python -m ruff check ., python -m mypy |
Chạy trong apps/ai-service với requirements đã cài |
| Muốn đọc | Bắt đầu tại |
|---|---|
| Cài đặt và demo | Getting started · local demo runbook |
| Kiến trúc và quyết định | System overview · ADR index |
| Nghiệp vụ và dữ liệu | Business workflows · Database/ERD |
| API, phiên và bảo mật | API reference · Security |
| AI, nguồn và consent | AI system · AI service |
| Kiểm thử và vận hành | Testing · Operations |
| Ảnh/GIF và provenance | Media guide · metadata |
Đọc hướng dẫn đóng góp trước khi sửa repo. Ghi rõ môi trường và gate thực sự đã chạy khi đề xuất thay đổi. Mã nguồn được phát hành theo MIT License.