PHARMACY-MANAGEMENT-WEB APP

Web App quản lý nhà thuốc dành cho dược sĩ, nhân viên bán hàng và quản lý

Đồ án thực tế công nghệ phần mềm

PharmaCare là Web App quản lý nhà thuốc, hỗ trợ các nghiệp vụ thường gặp như đăng nhập theo vai trò, quản lý thuốc, khách hàng, nhân viên, tài khoản, nhà cung cấp, phiếu nhập, hóa đơn, báo cáo doanh thu và trợ lý hướng dẫn sử dụng. Dự án sử dụng React cho frontend, ASP.NET Core Web API cho backend, Microsoft SQL Server cho database và Docker Compose để chạy toàn bộ hệ thống nhanh trên máy local.

Giới thiệu dự án

Mục đích của dự án

Xây dựng hệ thống quản lý nhà thuốc trực quan, dễ thao tác và phù hợp cho học phần đồ án thực tế công nghệ phần mềm.
Chuẩn hóa các quy trình cơ bản: quản lý kho thuốc, bán hàng, nhập hàng, khách hàng, nhân viên và báo cáo.
Tách frontend, backend và database rõ ràng để dễ bảo trì, kiểm thử, bàn giao và chạy bằng Docker.

Vấn đề dự án giải quyết

Giảm thao tác quản lý thủ công bằng sổ sách hoặc bảng tính rời rạc.
Hạn chế sai sót khi bán thuốc vượt tồn kho hoặc nhập dữ liệu thiếu.
Giúp nhân viên bán hàng tạo hóa đơn nhanh, nhân viên kho theo dõi phiếu nhập, quản lý xem báo cáo tổng quan.
Cho phép nhóm tải source code từ GitHub và chạy lại môi trường giống nhau bằng Docker Compose.

Đối tượng người dùng chính

Dược sĩ/Nhân viên bán hàng: tra cứu thuốc, tạo hóa đơn, nhập thông tin khách hàng.
Nhân viên quản lý sản phẩm/kho: quản lý thuốc, nhà cung cấp, phiếu nhập và tồn kho.
Quản lý/Admin: quản lý tài khoản, nhân viên, báo cáo, dashboard và dữ liệu tổng quan.

Tính năng chính

Đăng nhập, đăng xuất và điều hướng theo vai trò.
Quản lý tài khoản người dùng, trạng thái hoạt động và phân quyền.
Quản lý nhân viên, khách hàng, nhà cung cấp.
Quản lý thuốc, hình ảnh thuốc, tồn kho, đơn giá và nhóm thuốc.
Tìm kiếm, lọc dữ liệu và xem danh sách theo bảng.
Thêm, sửa, xóa dữ liệu ở các màn hình nghiệp vụ.
Tạo hóa đơn bán thuốc, kiểm tra giỏ hàng và in/lưu hóa đơn.
Tạo phiếu nhập, cộng tồn kho sau nhập hàng.
Trừ tồn kho sau bán hàng và kiểm tra không bán vượt tồn.
Báo cáo, thống kê và xuất dữ liệu.
Chatbot hướng dẫn sử dụng hệ thống dựa trên tài liệu nội bộ.
Hỗ trợ chạy public miễn phí bằng Cloudflare Quick Tunnel, không cần domain.

Tải xuống & Cài đặt nhanh

Cách 1: Tải ZIP từ GitHub

Mở repository GitHub của dự án.
Bấm Code.
Chọn Download ZIP.
Giải nén file ZIP.
Mở Terminal/PowerShell tại thư mục có file docker-compose.yml.

Cách 2: Clone bằng Git

git clone https://github.com/khainhq/PHARMACY-MANAGEMENT-webapp.git
cd PHARMACY-MANAGEMENT-webapp

Chạy nhanh bằng Docker Compose

docker compose up -d --build

Sau khi chạy xong:

Frontend: http://localhost:3000
Backend API: http://127.0.0.1:8000
Swagger: http://127.0.0.1:8000/swagger
SQL Server: localhost,1433

Chạy public miễn phí bằng Cloudflare Tunnel

Dùng khi muốn gửi link demo cho bạn bè hoặc giảng viên mà chưa có domain.

docker compose --profile tunnel up -d --build

Xem link public:

docker compose logs -f cloudflare-tunnel

Tìm dòng dạng:

https://ten-ngau-nhien.trycloudflare.com

Gửi link đó cho người khác để mở web. Frontend sẽ tự gọi backend qua cùng domain bằng các đường dẫn /api/... và /chatbot/..., nên người khác không cần mở port 8000 riêng.

Dừng tunnel:

docker compose stop cloudflare-tunnel

Lưu ý: Cloudflare Quick Tunnel miễn phí chỉ phù hợp demo/test. Link có thể đổi mỗi lần chạy lại và chỉ hoạt động khi laptop của người chạy Docker còn bật, còn mạng và container tunnel còn chạy.

Công nghệ sử dụng (Tech Stack)

Thành phần	Công nghệ / Thư viện	Vai trò
Frontend	React, React Router, Axios, Styled Components, MUI, Chart.js, Recharts	Xây dựng giao diện, điều hướng, biểu mẫu, dashboard, bảng dữ liệu và biểu đồ
Backend	C#, ASP.NET Core Web API, Entity Framework Core, BCrypt.Net	Cung cấp REST API, xử lý nghiệp vụ, xác thực, hash mật khẩu, cập nhật tồn kho
Database	Microsoft SQL Server	Lưu trữ tài khoản, thuốc, khách hàng, nhân viên, nhà cung cấp, hóa đơn, phiếu nhập
Runtime	Docker, Docker Compose, Nginx	Đóng gói và chạy frontend, backend, SQL Server bằng một lệnh
Public demo	Cloudflare Quick Tunnel	Tạo link public miễn phí để demo khi chưa có domain
Documentation	Swagger/OpenAPI, Markdown, PDF	Tài liệu API, hướng dẫn cài đặt và sử dụng
Testing	Jest, React Testing Library, dotnet build	Kiểm thử frontend và kiểm tra build backend

Kiến trúc hệ thống (Architecture)

flowchart LR
    User["Người dùng"] --> Browser["Trình duyệt"]
    Browser --> React["React Frontend / Nginx"]
    React --> API["ASP.NET Core Web API"]
    API --> SQL["Microsoft SQL Server"]
    React --> Assets["Logo, ảnh demo, ảnh thuốc"]
    Tunnel["Cloudflare Quick Tunnel"] --> React

Luồng chính:

Người dùng đăng nhập từ frontend.
Frontend gửi request đến backend qua /api/....
Backend xác thực tài khoản, verify mật khẩu bằng BCrypt và trả token.
Frontend dùng token để gọi các API nghiệp vụ.
Backend đọc/ghi dữ liệu trong SQL Server thông qua Entity Framework Core.
Khi chạy Cloudflare Tunnel, người ngoài truy cập link trycloudflare.com, request vào frontend/nginx rồi được proxy tới backend.

Cấu trúc dự án

PHARMACY-MANAGEMENT-webapp/
├── backend/                 # ASP.NET Core Web API
│   ├── Controllers/         # Nhóm endpoint API theo nghiệp vụ
│   ├── Data/                # DbContext và khởi tạo database
│   ├── Dtos/                # Request/response DTO dùng cho API
│   ├── Extensions/          # Extension methods cho endpoint/middleware
│   ├── Middleware/          # Middleware xác thực token
│   ├── Models/              # Entity model ánh xạ database
│   ├── Security/            # Token store và session đăng nhập
│   ├── Helpers/             # Vị trí mở rộng helper nghiệp vụ
│   ├── Interfaces/          # Vị trí mở rộng interface service/repository
│   ├── Mappers/             # Vị trí mở rộng mapper entity/DTO
│   ├── Repository/          # Vị trí mở rộng repository pattern
│   ├── Migrations/          # EF Core migrations
│   ├── SeedData/            # Dữ liệu mẫu dùng khi seed database
│   ├── Docs/                # Tài liệu nội bộ cho chatbot
│   ├── DataSeeder.cs        # Tạo dữ liệu demo và tài khoản demo
│   ├── Program.cs           # Cấu hình app, DI, Swagger, middleware
│   └── Dockerfile
├── frontend/                # React frontend
│   ├── public/images/       # Logo, hero images, ảnh thuốc, assets
│   ├── src/                 # Components, pages, services, tests
│   ├── nginx.conf           # Serve React và proxy /api, /chatbot tới backend
│   └── Dockerfile
├── database/                # Script SQL và dữ liệu mẫu bàn giao
├── docs/                    # API docs, PDF hướng dẫn, Cloudflare Tunnel guide
├── screenshots/             # Ảnh demo giao diện
├── Diagram/                 # Sơ đồ thiết kế hệ thống
├── Web Application Testing/ # Tài liệu kiểm thử web app
├── docker-compose.yml       # Chạy frontend + backend + SQL Server + tunnel tùy chọn
└── PharmacyManagement.sln   # Solution .NET

Hướng dẫn cài đặt

Yêu cầu

Docker Desktop.
Git hoặc khả năng tải ZIP từ GitHub.
Cổng 3000, 8000, 1433 chưa bị ứng dụng khác chiếm dụng.
Internet nếu muốn Docker tải image hoặc chạy Cloudflare Tunnel.

Các bước chạy local

docker compose up -d --build
docker compose ps

Nếu backend chưa sẵn sàng ngay lần đầu, chờ SQL Server khởi động xong rồi chạy:

docker compose restart backend

Dừng hệ thống:

docker compose down

Reset database demo:

docker compose down -v
docker compose up -d --build

docker compose down -v sẽ xóa volume SQL Server, chỉ dùng khi muốn tạo lại database demo từ đầu.

Một số hình ảnh Demo

Trang chủ và trợ lý nhà thuốc

_{Trang chủ PharmaCare}

_{Trợ lý nhà thuốc}

Đăng nhập theo vai trò

_{Đăng nhập Admin}

_{Đăng nhập nhân viên}

Dashboard và tài khoản

_{Dashboard quản trị}

_{Danh sách tài khoản}

Nhân viên và khách hàng

_{Quản lý nhân viên}

_{Quản lý khách hàng}

Thuốc, nhà cung cấp và phiếu nhập

_{Quản lý thuốc}

_{Quản lý nhà cung cấp}

_{Tạo phiếu nhập}

_{Danh sách phiếu nhập}

Hóa đơn và báo cáo

_{Tạo hóa đơn}

_{Danh sách hóa đơn}

_{Phiếu xem trước hóa đơn}

_{Báo cáo thống kê}

Vai trò người dùng

Vai trò	Tài khoản demo	Chức năng chính
Admin	`admin / admin123`	Dashboard, quản lý tài khoản, nhân viên, thuốc, khách hàng, nhà cung cấp, hóa đơn, phiếu nhập, báo cáo
Sales	`sales / sales123`	Bán thuốc, tạo hóa đơn, quản lý khách hàng, tra cứu thuốc
Product_manager	`product / product123`	Quản lý thuốc, nhà cung cấp, phiếu nhập, tồn kho

Database

Database sử dụng: Microsoft SQL Server.
Backend tự chạy migrations khi container khởi động.
Dữ liệu demo được seed trong backend/DataSeeder.cs.
Dữ liệu thuốc mẫu nằm trong backend/SeedData/medicine-products.json.
Thư mục database/ chứa script SQL và dữ liệu mẫu để tham khảo/bàn giao.

API Documentation

Tài liệu API nằm trong thư mục docs/:

Khi backend đang chạy, mở Swagger tại:

http://127.0.0.1:8000/swagger

Swagger đã được cấu hình tiêu đề, mô tả API, thông tin liên hệ và cơ chế nhập token theo header:

Authorization: Token <token>

Biến môi trường

Biến môi trường	Giá trị trong Docker	Mục đích
`ASPNETCORE_URLS`	`http://+:8000`	Cho backend lắng nghe ở port 8000
`ConnectionStrings__DefaultConnection`	Kết nối tới service `sqlserver`	Backend kết nối SQL Server trong Docker
`ACCEPT_EULA`	`Y`	Chấp nhận điều khoản SQL Server container
`MSSQL_SA_PASSWORD`	Mật khẩu demo trong Docker Compose	Mật khẩu tài khoản `sa` của SQL Server container

Không push API key thật hoặc secret cá nhân lên repository.

Tài khoản demo

Admin:                  admin / admin123
Nhân viên bán hàng:     sales / sales123
Quản lý sản phẩm:       product / product123

Hướng dẫn sử dụng

Admin

Vào /admin-login.
Đăng nhập bằng admin / admin123.
Kiểm tra dashboard.
Quản lý tài khoản, nhân viên, thuốc, khách hàng, nhà cung cấp, hóa đơn, phiếu nhập và báo cáo.

Nhân viên bán hàng

Vào /login.
Đăng nhập bằng sales / sales123.
Tạo hóa đơn bán thuốc.
Thêm thuốc vào giỏ hàng, nhập thông tin khách hàng và lưu hóa đơn.

Nhân viên quản lý sản phẩm

Vào /login.
Đăng nhập bằng product / product123.
Quản lý danh sách thuốc, nhà cung cấp và phiếu nhập.
Theo dõi tồn kho sau nhập hàng.

Kiểm thử

Backend

dotnet build backend\PharmacyManagement.Api.csproj

Frontend

cd frontend
npm install
npm test -- --watchAll=false

Docker

docker compose up -d --build
docker compose ps

Cloudflare Tunnel

docker compose --profile tunnel up -d --build
docker compose logs -f cloudflare-tunnel

Bảo mật

Mật khẩu tài khoản được hash bằng BCrypt.
Không lưu plaintext password trong database.
Các API quan trọng yêu cầu token đăng nhập.
Frontend không chứa mật khẩu thật hoặc API key thật.
Khi triển khai thật cần đổi mật khẩu SQL Server, dùng secret riêng, bật HTTPS ổn định và giới hạn CORS theo domain thật.
Cloudflare Quick Tunnel chỉ dùng cho demo/test, không thay thế cấu hình production lâu dài.

Triển khai

Local bằng Docker

docker compose up -d --build

Public demo miễn phí không cần domain

docker compose --profile tunnel up -d --build

Build frontend riêng

cd frontend
npm install
npm run build

Build backend riêng

dotnet build backend\PharmacyManagement.Api.csproj

Lỗi thường gặp

Lỗi	Cách xử lý
`localhost:3000` không mở được	Kiểm tra frontend container bằng `docker compose ps`, sau đó chạy lại `docker compose up -d --build`
Backend bật lên rồi tắt	Xem log bằng `docker compose logs backend`
SQL Server chưa sẵn sàng	Chờ thêm vài phút ở lần chạy đầu, sau đó restart backend
Đăng nhập admin không được	Vào đúng `/admin-login`; có thể chạy `docker compose restart backend` để backend đảm bảo lại tài khoản demo
Dữ liệu demo bị sai hoặc muốn làm mới	Chạy `docker compose down -v` rồi `docker compose up -d --build`
Link Cloudflare không vào được	Kiểm tra `docker compose ps`, xem lại `docker compose logs -f cloudflare-tunnel`, hoặc chạy lại profile tunnel để lấy link mới
Người khác vào link Cloudflare nhưng không có dữ liệu	Đảm bảo frontend đã dùng bản mới, đã rebuild bằng `docker compose --profile tunnel up -d --build`
Port bị chiếm	Đóng ứng dụng đang dùng port `3000`, `8000`, `1433` hoặc đổi port trong `docker-compose.yml`

Kế hoạch phát triển

Bổ sung cảnh báo thuốc sắp hết hạn hoặc gần hết tồn kho.
Thêm lịch sử thao tác người dùng.
Nâng cấp phân quyền chi tiết theo từng API.
Thêm import/export dữ liệu nâng cao.
Thêm dashboard phân tích doanh thu theo ngày, tháng, nhóm thuốc.
Tối ưu giao diện mobile/tablet.
Cấu hình production với HTTPS, secret manager, backup database và tên miền riêng.

License

This project is for educational purposes.

Cảm ơn

Dự án sử dụng và tham khảo các tài liệu, thư viện, framework sau:

React
ASP.NET Core
Entity Framework Core
Microsoft SQL Server
Docker và Docker Compose
Nginx
Cloudflare Tunnel
Swagger/OpenAPI
BCrypt.Net
React Testing Library
MUI, Styled Components, Chart.js, Recharts

Name		Name	Last commit message	Last commit date
Diagram		Diagram
Web Application Testing		Web Application Testing
backend		backend
database		database
docs		docs
frontend		frontend
screenshots		screenshots
.gitignore		.gitignore
PharmacyManagement.sln		PharmacyManagement.sln
README.md		README.md
docker-compose.yml		docker-compose.yml
dotnet-tools.json		dotnet-tools.json

Latest commit

History

Folders and files

Repository files navigation