**eTaskPro — Phần mềm Quản lý Công việc & Nhân sự - Tiền lương (PHP thuần, 21 module, có trình cài đặt)**
## Mô tả chi tiết
### Vì sao có phần mềm này
Phần lớn phần mềm quản lý công việc dừng ở chỗ giao việc và theo dõi tiến độ. Đến
cuối tháng, kế toán vẫn phải mở một file Excel khác để tính lương, và số liệu chấm
công lại phải nhập lại từ đầu.
eTaskPro nối liền hai phần đó: **chấm công, nghỉ phép và giờ làm thêm chảy thẳng vào
bảng lương**. Kế toán bấm một nút là ra bảng lương của cả tháng, kèm số ngày công,
giờ OT đã duyệt và tiền phạt đi muộn — không phải gõ lại con số nào.
### 21 module, chia làm 4 nhóm
**TỔNG QUAN**
- **Thống kê** — 8 ô số liệu bấm được (tổng nhiệm vụ, đang làm, hoàn thành, quá hạn,
tỷ lệ đúng hạn, thời gian hoàn thành trung bình, dữ liệu cần dọn, dự án trễ hạn),
4 biểu đồ (7 ngày qua, phân bố trạng thái, xu hướng 30 ngày, theo phòng ban), bảng
xếp hạng năng suất và khối tổng quan nhân sự trong tháng.
**CÔNG VIỆC**
- **Nhiệm vụ** — lưới thẻ, lọc theo dự án / danh mục / người thực hiện / trạng thái /
độ ưu tiên / mốc thời gian, đổi trạng thái ngay trên thẻ, xuất CSV.
- **Tiến độ** — bảng Kanban 5 cột, kéo thả để đổi trạng thái.
- **Lịch** — nhiệm vụ xếp theo hạn hoàn thành trong tháng, lọc bằng chip màu theo dự án.
- **Timeline công việc** và **Biểu đồ Gantt** — nhìn tiến độ theo trục thời gian.
- **Ghi chú - Nhắc việc** — sổ tay cá nhân: giấy nhớ có thẻ và màu, cùng việc cần làm
**lặp định kỳ** (hằng ngày / tuần / tháng / năm), tự nhắc qua chuông thông báo.
**NHÂN SỰ**
- **Chấm công** — ghi giờ vào, giờ ra, tự quy đổi ngày công và phân biệt có mặt / đi muộn.
- **GPS Check-in** — nhân viên tự chấm công bằng vị trí điện thoại, có bán kính cho phép
và bản đồ chọn tọa độ văn phòng.
- **Nghỉ phép** — đơn nghỉ, duyệt / từ chối theo phòng ban, tự trừ quỹ phép năm.
- **Yêu cầu OT** — đăng ký và duyệt giờ làm thêm.
- **Lịch làm việc** — bức tranh chấm công cả tháng theo 5 màu trạng thái.
- **Cài đặt lương** — lương cơ bản, phụ cấp, BHXH, thuế cho từng người, **có lịch sử
theo mốc hiệu lực**.
- **Bảng lương** — tính, chốt và thanh toán theo tháng; có phiếu lương cho từng nhân viên.
**HỆ THỐNG**
- **Phòng ban**, **Nhân viên**, **Danh mục**, **Dự án** — dữ liệu nền.
- **Thông báo** — trung tâm thông báo, chuông hiển thị số chưa đọc.
- **Cài đặt** — giờ làm việc, nghỉ trưa, ngày công chuẩn, mức phạt, hệ số OT, tỉ lệ
BHXH, tọa độ văn phòng, ngày lễ.
- **Sao lưu - Phục hồi** — sao lưu toàn bộ cơ sở dữ liệu ra file `.sql` và phục hồi khi
cần, ngay trong giao diện, không cần phpMyAdmin.
### Bảng lương tính thế nào
Bốn công thức, mọi tham số đều sửa được trong màn hình Cài đặt, không cắm cứng trong code:
```
lương OT = lương cơ bản ÷ ngày công chuẩn ÷ 8 × giờ OT đã duyệt × hệ số OT
tiền phạt = số lần đi muộn × mức phạt đi muộn + số ngày vắng × mức phạt vắng mặt
khấu trừ = BHXH + thuế + tiền phạt
tổng lương = lương cơ bản × ngày công ÷ ngày công chuẩn + phụ cấp + lương OT − khấu trừ
```
Chỉ **giờ OT đã được duyệt** mới vào bảng lương. Đơn nghỉ phép sau khi duyệt sẽ tự sinh
dòng chấm công tương ứng, nên người nghỉ phép không bị tính là vắng và không bị phạt.
**Bảng lương là chứng từ, không phải khung nhìn.** Khi chốt kỳ, hệ thống chụp lại toàn
bộ tham số và số liệu đầu vào tại thời điểm đó. Tháng sau tăng lương cho ai thì bảng
lương tháng trước vẫn nguyên si.
Vòng đời rõ ba bước, không quay lui tùy tiện:
```
Kỳ lương: Nháp ──► Đã duyệt ──► Đã đóng
Dòng lương: Nháp ──► Đã duyệt ──► Đã thanh toán
```
Muốn sửa kỳ đã duyệt thì phải mở khóa, và việc mở khóa **bắt buộc ghi lý do** vào nhật
ký kiểm toán. Kỳ đã có dòng thanh toán thì không mở khóa được nữa.
---
### Phân quyền 4 cấp
| Vai trò | Phạm vi |
|---|---|
| **Owner** | Toàn quyền, kể cả cấu hình và bảng lương |
| **Quản trị** | Như Owner, trừ việc đổi vai trò Owner |
| **Trưởng phòng** | Toàn quyền trong phòng ban mình: giao việc, duyệt nghỉ phép và OT |
| **Nhân viên** | Việc của mình, tự tạo đơn nghỉ và OT, tự chấm công GPS |
Lương là dữ liệu nhạy cảm nhất nên **chỉ Owner và Quản trị xem được**; nhân viên chỉ
xem phiếu lương của chính mình. Ghi chú cá nhân thì riêng tư tuyệt đối — kể cả Owner
cũng không đọc được ghi chú của người khác.
Quyền được kiểm ở **bốn lớp**: ẩn menu, chặn ở đầu mỗi trang, kiểm theo từng bản ghi,
và ràng buộc trong cơ sở dữ liệu.
### Cài đặt trong 5 phút, không cần dòng lệnh
1. Giải nén, chép lên hosting.
2. Đặt quyền ghi cho `uploads/` và `storage/`.
3. Tạo một cơ sở dữ liệu MySQL trống trong bảng điều khiển hosting.
4. Mở trình duyệt vào `ten-mien-cua-ban/cai-dat.php` và làm theo 4 bước trên màn hình.
Trình cài đặt tự kiểm tra yêu cầu hệ thống, tự dựng cơ sở dữ liệu, và **tạo tài khoản
quản trị theo mật khẩu bạn đặt** — sản phẩm không có tài khoản mặc định nào.
Về sau nâng cấp cũng qua chính file đó: đăng nhập bằng tài khoản quản trị, hệ thống
liệt kê những bản cập nhật cơ sở dữ liệu chưa chạy và chỉ chạy đúng phần còn thiếu.
---
### Bảo mật
- Mật khẩu băm bằng **bcrypt**, không bao giờ hiển thị lại. Sai 5 lần thì khóa 15 phút.
- **Chống CSRF** trên mọi biểu mẫu và mọi điểm nhận AJAX.
- **Chống SQL Injection**: toàn bộ truy vấn dùng prepared statement, tắt giả lập prepare.
- Thư mục `config/`, `uploads/`, `storage/` chặn truy cập và chặn thực thi mã.
- **Nhật ký kiểm toán** ghi lại mọi thao tác động tới tiền và quyền: duyệt đơn, tạo và
duyệt bảng lương, mở khóa kỳ lương, thanh toán, đổi vai trò, đặt lại mật khẩu — kể cả
lượt **xem** bảng lương.
- Trình cài đặt có **ba lớp chặn** không cho chạy lại sau khi đã cài.
---
### Giao diện
- Chạy tốt trên máy tính, máy tính bảng và điện thoại.
- **Chế độ tối** đầy đủ, nhớ lựa chọn của từng người.
- Thu gọn thanh điều hướng để lấy chỗ cho bảng dữ liệu rộng.
- Toàn bộ tiếng Việt, định dạng ngày `dd/mm/yyyy` và tiền `1.234.567đ`.
---
### Mở rộng về sau rất nhẹ
Phần mềm dùng **sổ đăng ký module**. Thêm một chức năng mới = tạo một thư mục trong
`modules/` kèm file khai báo:
```php
return [
'ten' => 'Chức năng mới', 'icon' => 'fa-star',
'nhom' => 'cong-viec', 'quyen' => 'MEMBER',
];
```
Menu, phân quyền hiển thị và điều hướng tự có. **Không phải sửa thanh điều hướng hay
bất kỳ file nào khác.**
Mã nguồn chú thích **bằng tiếng Việt**, giải thích cả lý do chọn cách làm chứ không chỉ
mô tả code.
## Thông số kỹ thuật
| Hạng mục | Chi tiết |
|---|---|
| Ngôn ngữ | PHP 8.1 trở lên (thuần, không framework, không Composer) |
| Cơ sở dữ liệu | MySQL 8 / MariaDB 10.4 trở lên — 26 bảng, khóa ngoại đầy đủ |
| Giao diện | Bootstrap 5.3, Font Awesome 6.5, Chart.js 4.4, Leaflet 1.9 |
| Quy mô mã nguồn | 120 file PHP, khoảng 13.400 dòng |
| Số module | 21 |
| Kích thước gói | 253 KB (131 file) |
| Kiểm thử | 130 phép kiểm tự động, chạy bằng dòng lệnh |
| Ngôn ngữ hiển thị | Tiếng Việt |
| Extension cần có | pdo, pdo_mysql, mbstring, json, session |
## Có sẵn trong gói
- Toàn bộ mã nguồn, không mã hóa, không rút gọn.
- Trình cài đặt qua trình duyệt (`cai-dat.php`), kiêm công cụ nâng cấp.
- File hướng dẫn cài đặt `HUONG-DAN-CAI-DAT.txt`.
- **Dữ liệu mẫu** để xem thử ngay: 12 nhân sự, 8 dự án, 33 nhiệm vụ, 180 dòng chấm
công, đơn nghỉ phép và yêu cầu OT. Tích một ô lúc cài là có; xóa sạch bằng một file
SQL kèm theo.
- Tác vụ nền chạy hằng ngày: tự chốt vắng cuối ngày, nhắc việc đến hạn, nhắc đơn tồn.
## Phù hợp với ai
- Doanh nghiệp vừa và nhỏ 10–100 nhân sự cần quản lý công việc **và** chấm công, tính lương.
- Đơn vị đang dùng Excel cho chấm công và bảng lương, muốn chuyển sang phần mềm.
- Lập trình viên cần một bộ khung PHP thuần sạch sẽ để phát triển tiếp cho khách hàng.
## Chưa có trong bản này
- Chưa hỗ trợ **nhiều công ty trên một bản cài** (mỗi bản cài phục vụ một đơn vị).
- Thuế thu nhập cá nhân **nhập tay theo từng người**, chưa tính theo biểu lũy tiến.
- Chưa có ứng dụng di động riêng (giao diện web co giãn dùng tốt trên điện thoại).
- Chưa nối thông báo qua Zalo OA (cơ sở dữ liệu đã chừa sẵn chỗ).
XEM THÊM ==> Hướng dẫn cài đặt chi tiết
HƯỚNG DẪN CÀI ĐẶT
# eTaskPro — Hướng dẫn cài đặt
Tài liệu này dành cho người cài đặt phần mềm lên máy chủ. Không cần biết lập trình,
không cần dùng dòng lệnh.
**Thời gian cài: khoảng 5–10 phút.**
---
## Mục lục
1. [Yêu cầu hệ thống](#1-yêu-cầu-hệ-thống)
2. [Chuẩn bị](#2-chuẩn-bị)
3. [Chạy trình cài đặt](#3-chạy-trình-cài-đặt)
4. [Việc phải làm ngay sau khi cài](#4-việc-phải-làm-ngay-sau-khi-cài)
5. [Thiết lập ban đầu](#5-thiết-lập-ban-đầu)
6. [Đặt tác vụ chạy hằng ngày](#6-đặt-tác-vụ-chạy-hằng-ngày)
7. [Nâng cấp lên bản mới](#7-nâng-cấp-lên-bản-mới)
8. [Sao lưu và phục hồi](#8-sao-lưu-và-phục-hồi)
9. [Xử lý sự cố](#9-xử-lý-sự-cố)
---
## 1. Yêu cầu hệ thống
| Hạng mục | Yêu cầu |
|---|---|
| PHP | **8.1 trở lên** |
| Cơ sở dữ liệu | MySQL 8 hoặc MariaDB 10.4 trở lên |
| Extension PHP | `pdo`, `pdo_mysql`, `mbstring`, `json`, `session` |
| Dung lượng | Khoảng 5 MB cho mã nguồn, cộng thêm dung lượng dữ liệu |
| HTTPS | **Bắt buộc nếu muốn dùng GPS Check-in** — xem mục 9 |
**Không cần** Composer, Node.js, hay quyền chạy lệnh trên máy chủ. Chạy được trên
hosting chia sẻ thông thường.
**Cách kiểm tra:** không cần tự kiểm. Trình cài đặt sẽ kiểm hộ bạn ở bước 1 và chỉ
rõ mục nào chưa đạt, sửa ở đâu.
---
## 2. Chuẩn bị
### 2.1. Tải mã nguồn lên máy chủ
Giải nén file `.zip`, bạn sẽ thấy một thư mục tên `eTaskPro`. Chép **toàn bộ nội dung
bên trong** thư mục đó lên máy chủ.
- Muốn chạy ở địa chỉ `congty.com` → chép vào `public_html/`
- Muốn chạy ở `congty.com/quanly` → chép vào `public_html/quanly/`
> Dùng File Manager của hosting để tải thẳng file `.zip` lên rồi giải nén ngay trên
> máy chủ sẽ nhanh hơn nhiều so với tải từng file bằng FTP.
### 2.2. Đặt quyền ghi cho hai thư mục
Hai thư mục sau phải cho ghi, nếu không phần mềm sẽ không lưu được tệp và bản sao lưu:
```
uploads/ → quyền 755
storage/ → quyền 755
```
Trong File Manager: bấm chuột phải vào thư mục → **Change Permissions** → chọn 755.
Nếu 755 vẫn báo không ghi được thì thử 775.
Thư mục `config/` cũng nên cho ghi trong lúc cài (để trình cài đặt tự lưu cấu hình).
Không cho ghi cũng cài được, chỉ là phải tạo một file bằng tay — trình cài đặt sẽ
hiện sẵn nội dung để bạn chép.
### 2.3. Tạo cơ sở dữ liệu
Vào bảng điều khiển hosting, tìm mục **MySQL Databases** (cPanel) hoặc **Cơ sở dữ liệu**:
1. Tạo một cơ sở dữ liệu mới, ví dụ `congty_etaskpro`.
2. Tạo một người dùng CSDL và đặt mật khẩu.
3. **Gán người dùng đó vào cơ sở dữ liệu vừa tạo, chọn ALL PRIVILEGES.**
Ghi lại bốn thông tin sau, lát nữa cần dùng:
- Máy chủ CSDL — thường là `localhost`
- Tên cơ sở dữ liệu
- Tên đăng nhập CSDL
- Mật khẩu CSDL
> Bước 3 hay bị bỏ sót. Tạo xong người dùng mà quên gán quyền thì trình cài đặt sẽ
> báo "Access denied".
---
## 3. Chạy trình cài đặt
Mở trình duyệt vào địa chỉ:
```
http://ten-mien-cua-ban/cai-dat.php
```
Nếu đặt trong thư mục con thì là `http://ten-mien-cua-ban/quanly/cai-dat.php`.
### Bước 1 — Kiểm tra yêu cầu hệ thống
Màn hình liệt kê từng mục kèm dấu ✓ hoặc ✕. Mục nào chưa đạt sẽ có dòng hướng dẫn
sửa ngay bên dưới. Sửa xong bấm **Kiểm tra lại**.
Khi mọi mục bắt buộc đều ✓, nút **Tiếp tục** hiện ra.
### Bước 2 — Kết nối cơ sở dữ liệu
Nhập bốn thông tin đã ghi ở mục 2.3, bấm **Kiểm tra kết nối**.
- Kết nối được → sang bước 3.
- Cơ sở dữ liệu chưa tồn tại → trình cài đặt **thử tạo giúp**. Nếu tài khoản không có
quyền tạo, nó sẽ báo rõ và bạn quay lại mục 2.3 tạo bằng tay.
### Bước 3 — Tài khoản quản trị và thông tin đơn vị
Nhập họ tên, email, tên đăng nhập và mật khẩu cho **tài khoản quản trị cao nhất**.
> **Phần mềm không có tài khoản mặc định nào.** Mật khẩu bạn đặt ở đây chính là mật
> khẩu đăng nhập. Ghi lại cẩn thận.
>
> Mật khẩu tối thiểu 8 ký tự, phải có cả chữ và số.
Nhập thêm tên đơn vị (hiện ở góc trái thanh điều hướng) và chọn múi giờ.
**Ô "Nạp dữ liệu mẫu":** tích vào nếu muốn xem thử phần mềm với dữ liệu có sẵn
(12 nhân sự, 8 dự án, 33 nhiệm vụ, 180 dòng chấm công). **Dùng thật thì đừng tích.**
Lỡ tích rồi vẫn xóa được — xem mục 5.1.
### Bước 4 — Hoàn tất
Màn hình liệt kê những việc đã làm. Đọc kỹ dòng cuối và làm theo mục 4 ngay sau đây.
---
## 4. Việc phải làm ngay sau khi cài
### 4.1. Xóa file `cai-dat.php`
**Đây là việc quan trọng nhất.** Vào File Manager, xóa file `cai-dat.php` ở thư mục gốc.
Trình cài đặt đã tự khóa lại nên người lạ không cài đè lên được, nhưng xóa hẳn vẫn an
toàn hơn. Khi nào cần nâng cấp thì tải file đó lên lại.
### 4.2. Kiểm tra đăng nhập
Vào `http://ten-mien-cua-ban/` và đăng nhập bằng tài khoản vừa tạo.
### 4.3. Bật HTTPS nếu định dùng GPS Check-in
Trình duyệt **không cho lấy vị trí trên kết nối HTTP thường**. Không có HTTPS thì nút
GPS Check-in sẽ báo không lấy được vị trí. Hầu hết hosting có sẵn chứng chỉ miễn phí
Let's Encrypt, bật trong mục **SSL/TLS**.
---
## 5. Thiết lập ban đầu
Làm theo thứ tự này, vì phần sau cần dữ liệu của phần trước.
### 5.1. Xóa dữ liệu mẫu (nếu đã nạp)
Vào **phpMyAdmin** → chọn cơ sở dữ liệu → tab **Import** → chọn file
`sql/du-lieu-mau-xoa.sql` → bấm **Go**.
Lệnh này xóa sạch dữ liệu mẫu nhưng **giữ nguyên** tài khoản quản trị của bạn.
### 5.2. Cấu hình nhân sự
Vào **Cài đặt** (nhóm HỆ THỐNG) và khai:
| Mục | Ghi chú |
|---|---|
| Giờ vào / giờ ra | Quyết định ai bị tính đi muộn |
| Nghỉ trưa từ – đến | Bị trừ ra khi tính giờ làm |
| Giờ tối thiểu đủ công | Làm đủ bấy nhiêu giờ mới được tính 1 ngày công |
| Ngày công chuẩn | Mẫu số khi tính lương theo ngày công, thường là 22 |
| Phạt đi muộn / vắng mặt | Cộng vào khấu trừ khi tính lương |
| Hệ số OT | Thường 1,5 |
| Tỉ lệ BHXH | Phần người lao động đóng, thường 10,5% |
| Vị trí văn phòng | Bấm lên bản đồ để chọn. **Chưa đặt thì GPS Check-in bị khóa.** |
| Bán kính cho phép | Khoảng cách tối đa được chấm công, ví dụ 200m |
> Phần mềm **không cho lưu cấu hình tự mâu thuẫn**. Ví dụ đặt giờ làm 08:30–17:30,
> nghỉ trưa 1,5 giờ mà đòi đủ công 8 giờ thì không ai đạt nổi một ngày công — hệ thống
> sẽ báo lỗi và chỉ rõ phải sửa gì.
Khai luôn **ngày lễ trong năm** ở khối bên phải. Ngày lễ được trừ ra khi đếm ngày nghỉ phép.
### 5.3. Phòng ban → Nhân viên → Danh mục → Dự án
Theo đúng thứ tự này:
1. **Phòng ban** — tạo các phòng, chọn trưởng phòng sau khi đã có nhân viên.
2. **Nhân viên** — mỗi người một tài khoản. Chọn vai trò:
- *Owner* — chủ doanh nghiệp, toàn quyền
- *Quản trị* — nhân sự, kế toán
- *Trưởng phòng* — duyệt đơn nghỉ phép và OT trong phòng mình
- *Nhân viên* — làm việc được giao
3. **Danh mục** — phân loại công việc theo lĩnh vực.
4. **Dự án** — nhóm nhiệm vụ, chọn người phụ trách và thành viên.
### 5.4. Cài đặt lương
Vào **Cài đặt lương**, khai cho từng người: lương cơ bản, phụ cấp, BHXH, thuế.
Nút phần trăm bên cạnh ô BHXH tự tính theo tỉ lệ đã khai ở mục 5.2.
> Người chưa có cài đặt lương sẽ **không xuất hiện** trong bảng lương. Phần mềm báo rõ
> tên những người này thay vì lặng lẽ tính ra 0đ.
---
## 6. Đặt tác vụ chạy hằng ngày
Tác vụ nền làm bốn việc mỗi ngày: chốt vắng cho người không chấm công, nhắc nhiệm vụ
đến hạn, nhắc đơn tồn quá 2 ngày, và dọn dữ liệu cũ.
**Không bắt buộc**, nhưng thiếu nó thì không ai được nhắc việc và người quên chấm công
sẽ không bị ghi vắng.
### Trên hosting cPanel
Vào **Cron Jobs**, thêm một dòng chạy lúc **20:00 hằng ngày**:
```
0 20 * * * /usr/local/bin/php /home/TAI_KHOAN/public_html/cron/chay-hang-ngay.php
```
Thay `TAI_KHOAN` bằng tên tài khoản hosting của bạn. Đường dẫn PHP có thể khác —
xem gợi ý ngay trong màn hình Cron Jobs.
### Trên máy chủ Windows
Mở **Task Scheduler** → Create Basic Task → chạy hằng ngày lúc 20:00 → chương trình:
```
C:\xampp\php\php.exe
```
Tham số:
```
C:\xampp\htdocs\eTaskPro\cron\chay-hang-ngay.php
```
### Chạy thử trước
Thêm `--thu` vào cuối lệnh để chạy thử: nó in ra sẽ làm gì mà **không ghi gì** vào
cơ sở dữ liệu.
---
## 7. Nâng cấp lên bản mới
1. **Sao lưu trước.** Vào **Sao lưu - Phục hồi** → tab Sao lưu → **Sao lưu ngay** →
bấm **Tải về** để giữ một bản trên máy tính.
2. Chép mã nguồn bản mới đè lên bản cũ. **Giữ nguyên** file `config/config.local.php`
và thư mục `uploads/`.
3. Tải file `cai-dat.php` lên lại (nếu đã xóa theo mục 4.1).
4. Mở `ten-mien-cua-ban/cai-dat.php`. Nó nhận ra hệ thống đã cài và hỏi đăng nhập.
5. Đăng nhập bằng tài khoản quản trị. Màn hình liệt kê những bản cập nhật cơ sở dữ
liệu chưa chạy. Bấm chạy.
6. Xóa lại `cai-dat.php`.
Trình cài đặt chỉ chạy đúng phần còn thiếu, **không đụng vào dữ liệu đang có**.
---
## 8. Sao lưu và phục hồi
### Sao lưu
Vào **Sao lưu - Phục hồi** → tab **Sao lưu** → **Sao lưu ngay**. File nằm trên máy chủ
và tải về được bằng nút **Tải về**.
Nên sao lưu trước mỗi lần nâng cấp và trước mỗi lần nhập liệu số lượng lớn. Hệ thống
tự nhắc nếu quá 7 ngày chưa sao lưu.
> **Bản sao lưu chỉ gồm cơ sở dữ liệu**, không có tệp đính kèm trong `uploads/`.
> Sao lưu đầy đủ thì chép thêm thư mục đó.
>
> Nên tải ít nhất một bản về máy tính: hỏng ổ đĩa máy chủ thì bản sao lưu nằm trên đó
> cũng mất theo.
### Phục hồi
Tab **Phục hồi** → chọn bản sao lưu → gõ `PHUC HOI` để xác nhận.
Hệ thống **tự sao lưu bản hiện tại trước khi ghi đè**, nên bấm nhầm vẫn còn đường về.
> Sau khi phục hồi bạn sẽ bị đăng xuất, vì bảng tài khoản cũng bị thay. Đăng nhập lại
> bằng mật khẩu **tại thời điểm sao lưu đó**, không phải mật khẩu hiện tại.
---
## 9. Xử lý sự cố
### Mở `cai-dat.php` ra trang trắng
Thường do PHP dưới 8.1. Vào bảng điều khiển hosting, mục **PHP Selector** hoặc
**PHP Version**, chọn 8.1 trở lên.
### "Access denied for user..."
Sai tên đăng nhập hoặc mật khẩu CSDL, hoặc **quên gán người dùng vào cơ sở dữ liệu**.
Quay lại mục 2.3 bước 3.
### "Cơ sở dữ liệu chưa tồn tại và tài khoản này không có quyền tạo"
Hosting chia sẻ không cho tạo CSDL từ mã nguồn. Tạo bằng tay trong bảng điều khiển
theo mục 2.3, rồi quay lại trình cài đặt.
### "Không ghi được config/config.local.php"
Thư mục `config/` không cho ghi. Hai cách:
- Đặt quyền 755 cho `config/` rồi cài lại, **hoặc**
- Chép nội dung mà trình cài đặt hiện ra, tạo file `config/config.local.php` bằng File
Manager và dán vào.
### Vào `cai-dat.php` thì bị đòi đăng nhập
Hệ thống đã được cài rồi. Đây là chế độ nâng cấp — xem mục 7.
Muốn cài lại từ đầu: xóa hai file `config/da-cai-dat.lock` và `config/config.local.php`
rồi mở lại. Thao tác này **không** xóa dữ liệu trong cơ sở dữ liệu.
### Quên mật khẩu quản trị
Cần đặt lại trực tiếp trong cơ sở dữ liệu:
1. Vào **phpMyAdmin** → chọn CSDL → tab **SQL**.
2. Chạy lệnh sau, thay `TEN_DANG_NHAP` bằng tài khoản của bạn:
```sql
UPDATE users
SET password_hash = '$2y$10$erqJFi1QLGYvc2lIu1ZU7.zDdRhid2rstQSeXwFFBd1W2rqAJHnPu'
WHERE username = 'TEN_DANG_NHAP';
```
3. Mật khẩu mới là `DoiNgay@2026`. **Đăng nhập rồi đổi ngay** ở menu tài khoản →
Đổi mật khẩu. Mã băm trên nằm công khai trong tài liệu này nên ai đọc được cũng
biết — để nguyên là mở cửa cho người lạ.
### Tiếng Việt hiển thị thành ký tự lạ
Xảy ra khi nạp file `.sql` bằng công cụ không đặt bảng mã. Nếu nạp bằng phpMyAdmin,
chọn **utf-8** ở ô *Character set of the file*. Nếu dùng dòng lệnh, thêm
`--default-character-set=utf8mb4`.
Cài qua `cai-dat.php` thì không gặp lỗi này.
### GPS Check-in không lấy được vị trí
Ba nguyên nhân, theo thứ tự hay gặp:
1. **Trang chạy HTTP, không phải HTTPS.** Trình duyệt chỉ cho lấy vị trí trên kết nối
an toàn. Bật SSL theo mục 4.3.
2. **Chưa đặt tọa độ văn phòng** trong Cài đặt → nút bị khóa có chủ ý.
3. **Người dùng đã từ chối quyền vị trí.** Bấm vào biểu tượng ổ khóa trên thanh địa
chỉ để cấp lại.
### Không tải được file sao lưu lên vì quá lớn
Giới hạn `upload_max_filesize` của hosting. Nạp thẳng file `.sql` bằng phpMyAdmin
(tab Import) thay vì qua giao diện phần mềm.
### Lỗi 500 sau khi nâng cấp
Thường do thiếu file khi chép đè. Chép lại toàn bộ mã nguồn, nhớ giữ
`config/config.local.php`.
Muốn xem lỗi thật: mở `config/config.local.php`, đổi `'debug' => false` thành
`'debug' => true`, tải lại trang để đọc thông báo lỗi. **Xong nhớ đổi lại `false`** —
để `true` trên máy chủ thật sẽ lộ đường dẫn và tên bảng.
---
## Cấu trúc thư mục
```
eTaskPro/
├── cai-dat.php Trình cài đặt và nâng cấp — XÓA sau khi cài xong
├── index.php Cửa vào ứng dụng
├── login.php Trang đăng nhập
├── config/ Cấu hình kết nối — KHÔNG chép đè khi nâng cấp
├── includes/ Thư viện dùng chung
├── modules/ 21 module chức năng
├── assets/ CSS và JavaScript
├── sql/ Lược đồ cơ sở dữ liệu và các bản cập nhật
├── cron/ Tác vụ chạy hằng ngày
├── uploads/ Tệp người dùng tải lên — KHÔNG chép đè khi nâng cấp
└── storage/ Bản sao lưu và tệp xuất tạm
```
Nguồn: Topcode.vn
