API Flow

Authentication Flow

Client                  Server
  │                       │
  │  POST /api/employee/login  │
  │  {username, password}      │
  │ ─────────────────────►    │
  │                       │  Validate credentials
  │                       │  Regenerate session
  │                       │  Set session cookie
  │ ◄───────────────────── │
  │  {status, data}        │
  │                       │
  │  GET /api/employee/profile  │
  │  (with session cookie) │
  │ ─────────────────────►    │
  │                       │  auth:employee middleware
  │                       │  Verify session
  │ ◄───────────────────── │
  │  {status, data}        │

Session-based Authentication

Hệ thống sử dụng session-based auth (không phải token-based).

Bước 1: Login

Gửi request đăng nhập:

curl -X POST http://localhost:8000/api/employee/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"username": "admin", "password": "password"}'

Server trả về session cookie (laravel_session) trong response header Set-Cookie.

Bước 2: Dùng session cookie cho các request tiếp theo

curl -X GET http://localhost:8000/api/employee/profile \
  -H "Accept: application/json" \
  -H "Cookie: laravel_session=your-session-id"

Bước 3: Logout

curl -X GET http://localhost:8000/api/employee/logout \
  -H "Accept: application/json" \
  -H "Cookie: laravel_session=your-session-id"

API Request Flow (có phân quyền)

Request
  │
  ▼
┌─────────────────────────────┐
│ 1. web middleware            │
│    - CSRF protection         │
│    - Session start           │
│    - Encrypt cookies         │
└─────────────────────────────┘
  │
  ▼
┌─────────────────────────────┐
│ 2. auth:employee middleware  │
│    - Kiểm tra đăng nhập      │
│    - 401 nếu chưa login      │
└─────────────────────────────┘
  │
  ▼
┌─────────────────────────────┐
│ 3. permission middleware     │
│    - Kiểm tra quyền          │
│      (vd: permission:dept.view)  │
│    - 403 nếu không có quyền  │
└─────────────────────────────┘
  │
  ▼
┌─────────────────────────────┐
│ 4. Controller               │
│    - Validation              │
│    - Company scope check     │
│    - Business logic          │
│    - Response                │
└─────────────────────────────┘

Standard Response Format

Success Response

{
  "status": "success",
  "message": "Operation successful",
  "data": { ... }
}

Error Response

{
  "status": "error",
  "message": "Error description",
  "errors": null
}

Validation Error

{
  "status": "error",
  "message": "The given data was invalid.",
  "errors": {
    "field_name": ["Error message 1", "Error message 2"]
  }
}

HTTP Status Codes

Permission & Company Scope

Luồng kiểm tra quyền

1. Route middleware kiểm tra "permission:department.view"
   → Employee có permission này trong Spatie không?
   
2. Controller kiểm tra company scope
   → Department này có thuộc company của employee không?

Ví dụ trong DepartmentController@getDepartment:

// 1. Spatie middleware (route) đã kiểm tra permission
// 2. Controller kiểm tra company scope:
if ($user->getCompanyAttribute()->id != $department->company_id) {
    return $this->error('You do not have permission to access this page.', 403);
}

Example: Complete API Call Flow

1. Đăng ký employee mới

curl -X POST http://localhost:8000/api/employee/register \
  -H "Accept: application/json" \
  -F "username=employee1" \
  -F "password=password123" \
  -F "password_confirmation=password123" \
  -F "status=active" \
  -F "full_name=Nguyen Van A" \
  -F "employee_code=EMP001" \
  -F "department_id=1"

2. Đăng nhập

curl -X POST http://localhost:8000/api/employee/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"username": "employee1", "password": "password123"}' \
  -c cookies.txt

3. Gọi API có authentication

curl -X GET http://localhost:8000/api/department/all \
  -H "Accept: application/json" \
  -b cookies.txt

4. Tạo department mới

curl -X POST http://localhost:8000/api/department/create \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -b cookies.txt \
  -d '{"title": "Phòng Kỹ thuật", "status": "active"}'

5. Đăng xuất

curl -X GET http://localhost:8000/api/employee/logout \
  -H "Accept: application/json" \
  -b cookies.txt

Sơ đồ database relationships

Company (company)
  ├── CompanyDetail (company_detail)          1-1
  ├── CompanyBranch (company_branch)          nhiều
  └── Department (departments)                nhiều
        └── EmployeeInfo (employees_info)     nhiều
              └── EmployeeAccount (employees_account)  1-1
                    ├── Role (roles)          nhiều-nhiều (qua model_has_roles)
                    └── Permission (permissions)  nhiều-nhiều (qua model_has_permissions)
                          └── PermissionGroup (permission_groups)  nhiều-1