Add USER_GUIDE.md
This commit is contained in:
parent
32666386fb
commit
f3a3250cb1
212
USER_GUIDE.md
Normal file
212
USER_GUIDE.md
Normal file
@ -0,0 +1,212 @@
|
||||
# PeopleDesk User Guide
|
||||
|
||||
Friendly guide for **new users**, **testers**, and **developers**.
|
||||
|
||||
PeopleDesk is an Employee Management System for attendance, leave, payroll, performance, and reporting — with role-based access for Admin, HR, and Employee.
|
||||
|
||||
---
|
||||
|
||||
## 1. Quick start (everyone)
|
||||
|
||||
1. Open the app: `http://localhost:5173`
|
||||
2. Sign in with a demo account (below)
|
||||
3. Use the left menu (it changes by role)
|
||||
4. Open **User Guide** inside the app anytime for help
|
||||
|
||||
### Demo accounts
|
||||
|
||||
| Role | Email | Password | What you can do |
|
||||
|------|-------|----------|-----------------|
|
||||
| Admin | `admin@ems.com` | `Admin@123` | Everything, including departments |
|
||||
| HR | `hr@ems.com` | `Hr@12345` | Employees, leave approvals, payroll, reviews |
|
||||
| Employee | `john@ems.com` | `Employee@123` | Own attendance, leave, payslips, profile |
|
||||
|
||||
---
|
||||
|
||||
## 2. Main flow (simple)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Login[Login] --> Dashboard[Dashboard]
|
||||
Dashboard --> Attendance[Attendance]
|
||||
Attendance --> Leaves[Leave_Requests]
|
||||
Leaves --> Payroll[Payroll]
|
||||
Payroll --> Reports[Reports_and_Notifications]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Who should use which path?
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start[Open_PeopleDesk] --> Role{Select_role_by_login}
|
||||
Role -->|Admin| AdminPath[Manage_Depts_Employees_Approvals_Payroll]
|
||||
Role -->|HR| HrPath[Manage_Employees_Approvals_Payroll_Reviews]
|
||||
Role -->|Employee| EmpPath[CheckIn_ApplyLeave_ViewPayslip_Profile]
|
||||
```
|
||||
|
||||
### Plain-language permissions
|
||||
|
||||
| Feature | Admin | HR | Employee |
|
||||
|---------|-------|----|----------|
|
||||
| Dashboard | Yes | Yes | Yes |
|
||||
| Manage employees | Yes | Yes | Own profile only |
|
||||
| Manage departments | Yes | View | No |
|
||||
| Check in / out | Yes | Yes | Yes |
|
||||
| Apply leave | Yes | Yes | Yes |
|
||||
| Approve / reject leave | Yes | Yes | No |
|
||||
| Generate payroll | Yes | Yes | View/download own |
|
||||
| Performance reviews | Create | Create | View own |
|
||||
|
||||
---
|
||||
|
||||
## 4. New employee guide
|
||||
|
||||
1. Login with your email/password
|
||||
2. Go to **Attendance** → **Check in**
|
||||
3. At end of day → **Check out**
|
||||
4. Need time off → **Leaves** → choose type + dates → Apply
|
||||
5. Watch status: Pending → Approved / Rejected
|
||||
6. Open **Payroll** to download salary PDF when ready
|
||||
7. Update phone in **Profile**
|
||||
|
||||
### Attendance diagram
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Check_In_once_per_day] --> B[Work]
|
||||
B --> C[Check_Out]
|
||||
C --> D[Hours_calculated]
|
||||
D --> E{Hours_over_8}
|
||||
E -->|Yes| F[Overtime_added]
|
||||
E -->|No| G[Normal_hours_only]
|
||||
```
|
||||
|
||||
**Important:** Only one check-in per employee per day. A second check-in shows an expected error.
|
||||
|
||||
---
|
||||
|
||||
## 5. Leave flow (HR + Employee)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Emp[Employee_applies_leave] --> Pending[Status_Pending]
|
||||
Pending --> Review{HR_or_Admin_decision}
|
||||
Review -->|Approve| Approved[Status_Approved]
|
||||
Approved --> BalanceDown[Leave_balance_decreases]
|
||||
BalanceDown --> NotifyA[Employee_notification]
|
||||
Review -->|Reject| Rejected[Status_Rejected]
|
||||
Rejected --> NotifyR[Employee_notification]
|
||||
Pending --> Cancel[Employee_can_cancel]
|
||||
```
|
||||
|
||||
Leave types: Casual, Sick, Paid, Unpaid.
|
||||
|
||||
---
|
||||
|
||||
## 6. Payroll flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Hr[HR_or_Admin_opens_Payroll] --> Fill[Select_employee_month_year]
|
||||
Fill --> Calc[System_calculates_net_salary]
|
||||
Calc --> Save[Payroll_saved]
|
||||
Save --> Pdf[Download_PDF_payslip]
|
||||
Save --> Note[Employee_gets_notification]
|
||||
```
|
||||
|
||||
Formula:
|
||||
|
||||
`Net = Basic + Allowances + Bonuses - Deductions - Tax`
|
||||
|
||||
**Currency:** All money values (salary, budget, payroll, payslips) use **Indian Rupees (INR)** with Indian grouping — e.g. `₹75,000.00` in the UI and `Rs. 75,000.00` on PDF payslips.
|
||||
|
||||
---
|
||||
|
||||
## 7. Tester checklist
|
||||
|
||||
- [ ] Login works for Admin, HR, Employee
|
||||
- [ ] Employee cannot manage all employees/departments
|
||||
- [ ] Duplicate attendance check-in is blocked
|
||||
- [ ] Leave approve reduces balance; reject does not
|
||||
- [ ] Payroll PDF downloads
|
||||
- [ ] Notifications appear after leave review and payroll generate
|
||||
- [ ] Mobile/responsive layout remains usable under 768px
|
||||
|
||||
---
|
||||
|
||||
## 8. Developer guide
|
||||
|
||||
### Run locally
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd people-desk-be
|
||||
npm install
|
||||
npm run seed
|
||||
npm run dev
|
||||
|
||||
# Frontend (new terminal)
|
||||
cd people-desk-fe
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
- UI: `http://localhost:5173`
|
||||
- API: `http://localhost:5000`
|
||||
- Root `.env` needs `MONGODB_URI`, `JWT_SECRET`, `PORT`, `CLIENT_URL`
|
||||
|
||||
### Access My Database (MongoDB Atlas)
|
||||
|
||||
PeopleDesk stores data in **MongoDB Atlas** (cloud). Local connection string lives in root `.env` as `MONGODB_URI` (also mirrored in `atlas-credentials.env` — keep both private).
|
||||
|
||||
1. Open [MongoDB Atlas](https://cloud.mongodb.com/) and sign in
|
||||
2. Choose your project → click the cluster (e.g. `Cluster0`)
|
||||
3. Click **Browse Collections** to open **Collections** (this is “My Database” in Atlas)
|
||||
4. Select database **`ems`** — you will see collections such as `users`, `employees`, `departments`, `attendances`, `leaverequests`, `payrolls`, `notifications`, etc.
|
||||
5. Optional — connect from a GUI:
|
||||
- In Atlas: **Connect** → **Drivers** or **MongoDB Compass**
|
||||
- Copy the URI (same style as `MONGODB_URI` in `.env`)
|
||||
- Open [MongoDB Compass](https://www.mongodb.com/products/compass) → paste URI → Connect → open database **`ems`**
|
||||
|
||||
**Tip:** After `npm run seed` in `people-desk-be`, demo users and sample employees appear under `ems`. If the app cannot connect, check Atlas **Network Access** (your IP allowlist) and that `MONGODB_URI` is correct.
|
||||
|
||||
### Architecture
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
FE[people-desk-fe_React] -->|JWT_Bearer_API| BE[people-desk-be_Express]
|
||||
BE --> MW[Auth_and_RBAC_middleware]
|
||||
MW --> CTRL[Controllers]
|
||||
CTRL --> DB[(MongoDB_Atlas)]
|
||||
```
|
||||
|
||||
### Useful API routes
|
||||
|
||||
- `POST /api/auth/login`
|
||||
- `GET /api/auth/me`
|
||||
- `CRUD /api/employees`
|
||||
- `CRUD /api/departments`
|
||||
- `POST /api/attendance/check-in` · `POST /api/attendance/check-out`
|
||||
- `POST /api/leaves` · `PUT /api/leaves/:id/review`
|
||||
- `POST /api/payroll/generate` · `GET /api/payroll/:id/payslip`
|
||||
- `GET /api/dashboard/stats`
|
||||
- `GET /api/notifications`
|
||||
|
||||
Use header: `Authorization: Bearer <token>`
|
||||
|
||||
---
|
||||
|
||||
## 9. Friendly tips
|
||||
|
||||
- Menus hide features your role cannot use
|
||||
- If a button fails, read the red message — it usually explains the rule (example: already checked in)
|
||||
- For demos, start as Employee for self-service, then switch to HR/Admin for approvals
|
||||
- Keep `.env` and `atlas-credentials.env` private — never commit secrets
|
||||
|
||||
---
|
||||
|
||||
## 10. Need more help?
|
||||
|
||||
Inside the app, open **User Guide** from the left menu for the same content in a visual layout.
|
||||
Loading…
Reference in New Issue
Block a user