Spaces:
Sleeping
Sleeping
Commit Β·
dc5b19b
1
Parent(s): ed049b3
docs: simplify Swagger documentation across all routers
Browse files- Simplify attendance router (check-in, check-out, summary)
- Simplify tasks router (get tasks, update status)
- Simplify expenses router (submit expense)
- Remove verbose sections and keep only essential information
- Improve documentation readability and conciseness
- app/tracker/attendance/router.py +3 -28
- app/tracker/expenses/router.py +5 -35
- app/tracker/tasks/router.py +7 -43
app/tracker/attendance/router.py
CHANGED
|
@@ -37,20 +37,10 @@ router = APIRouter(prefix="/attendance", tags=["Attendance"])
|
|
| 37 |
description="""
|
| 38 |
Mark the start of an employee's working day.
|
| 39 |
|
| 40 |
-
**Rules:**
|
| 41 |
- Can check-in only once per day
|
| 42 |
- Location coordinates are mandatory
|
| 43 |
-
- GPS tracking must be enabled for the employee
|
| 44 |
- Optional location_id if inside a geofence
|
| 45 |
-
-
|
| 46 |
-
|
| 47 |
-
**Edge Cases:**
|
| 48 |
-
- Duplicate check-in β 400 error
|
| 49 |
-
- GPS disabled β 400 error (checked from MongoDB: scm_employees.location_settings.location_tracking_consent)
|
| 50 |
-
|
| 51 |
-
**Data Storage:**
|
| 52 |
-
- Stores server timestamp, coordinates, and geofence match (if any) in PostgreSQL
|
| 53 |
-
- Table: trans.scm_attendance
|
| 54 |
"""
|
| 55 |
)
|
| 56 |
async def check_in(
|
|
@@ -153,21 +143,10 @@ async def check_in(
|
|
| 153 |
Mark the end of an employee's working day and calculate total working time.
|
| 154 |
|
| 155 |
**Rules:**
|
| 156 |
-
-
|
| 157 |
- Location coordinates are mandatory
|
| 158 |
- Auto-calculates total working hours in minutes
|
| 159 |
- GPS tracking must be enabled for the employee
|
| 160 |
-
- Timestamp and work_date are automatically set by the server
|
| 161 |
-
|
| 162 |
-
**Edge Cases:**
|
| 163 |
-
- No check-in found β 400 error
|
| 164 |
-
- Already checked out β 400 error
|
| 165 |
-
- GPS disabled β 400 error
|
| 166 |
-
- Check-out time before check-in time β 400 error (prevented by server time)
|
| 167 |
-
|
| 168 |
-
**Data Storage:**
|
| 169 |
-
- Updates the attendance record with check-out timestamp, coordinates, and total working minutes
|
| 170 |
-
- Table: trans.scm_attendance
|
| 171 |
"""
|
| 172 |
)
|
| 173 |
async def check_out(
|
|
@@ -278,12 +257,8 @@ async def check_out(
|
|
| 278 |
- date: Date in YYYY-MM-DD format (defaults to today if not provided)
|
| 279 |
|
| 280 |
**Authentication:**
|
| 281 |
-
- Requires valid JWT token
|
| 282 |
- Returns attendance for the authenticated employee only
|
| 283 |
-
|
| 284 |
-
**Behavior:**
|
| 285 |
-
- Returns empty attendance (not checked in) if no record found for the date
|
| 286 |
-
- Does not return 404 error for missing records
|
| 287 |
"""
|
| 288 |
)
|
| 289 |
async def get_daily_attendance(
|
|
|
|
| 37 |
description="""
|
| 38 |
Mark the start of an employee's working day.
|
| 39 |
|
|
|
|
| 40 |
- Can check-in only once per day
|
| 41 |
- Location coordinates are mandatory
|
|
|
|
| 42 |
- Optional location_id if inside a geofence
|
| 43 |
+
- GPS tracking must be enabled for the employee
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 44 |
"""
|
| 45 |
)
|
| 46 |
async def check_in(
|
|
|
|
| 143 |
Mark the end of an employee's working day and calculate total working time.
|
| 144 |
|
| 145 |
**Rules:**
|
| 146 |
+
- Must have checked in earlier on the same day
|
| 147 |
- Location coordinates are mandatory
|
| 148 |
- Auto-calculates total working hours in minutes
|
| 149 |
- GPS tracking must be enabled for the employee
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 150 |
"""
|
| 151 |
)
|
| 152 |
async def check_out(
|
|
|
|
| 257 |
- date: Date in YYYY-MM-DD format (defaults to today if not provided)
|
| 258 |
|
| 259 |
**Authentication:**
|
|
|
|
| 260 |
- Returns attendance for the authenticated employee only
|
| 261 |
+
- Returns empty attendance if no record found for the date
|
|
|
|
|
|
|
|
|
|
| 262 |
"""
|
| 263 |
)
|
| 264 |
async def get_daily_attendance(
|
app/tracker/expenses/router.py
CHANGED
|
@@ -43,41 +43,11 @@ router = APIRouter(prefix="/expenses", tags=["Expenses"])
|
|
| 43 |
description="""
|
| 44 |
Submit a new expense for reimbursement.
|
| 45 |
|
| 46 |
-
|
| 47 |
-
-
|
| 48 |
-
-
|
| 49 |
-
-
|
| 50 |
-
-
|
| 51 |
-
|
| 52 |
-
**Business Rules:**
|
| 53 |
-
- β
Receipt photo is mandatory for all reimbursable expenses
|
| 54 |
-
- β
Default status is 'pending' (requires admin approval)
|
| 55 |
-
- β
Amount must be positive
|
| 56 |
-
- β
Currency must be valid ISO 4217 code (3 letters)
|
| 57 |
-
- β
Timestamp must be within 30 days
|
| 58 |
-
|
| 59 |
-
**Security:**
|
| 60 |
-
- JWT authentication required
|
| 61 |
-
- Merchant ID validated from token
|
| 62 |
-
- User ID validated from token
|
| 63 |
-
- All expenses are merchant-scoped
|
| 64 |
-
|
| 65 |
-
**Validation:**
|
| 66 |
-
- Amount: Must be positive, max 1,000,000
|
| 67 |
-
- Currency: 3-letter ISO code (USD, THB, etc.)
|
| 68 |
-
- Timestamp: Within 30 days past, max 5 min future
|
| 69 |
-
- Receipt: Mandatory, must be valid URL
|
| 70 |
-
- Note: Optional, max 500 characters
|
| 71 |
-
|
| 72 |
-
**Response:**
|
| 73 |
-
- Returns unique expense ID (UUID)
|
| 74 |
-
- Status is always 'pending' on creation
|
| 75 |
-
- Admin approval required for reimbursement
|
| 76 |
-
|
| 77 |
-
**Error Handling:**
|
| 78 |
-
- 400 Bad Request: If validation fails
|
| 79 |
-
- 401 Unauthorized: If JWT invalid
|
| 80 |
-
- 500 Internal Error: If database operation fails
|
| 81 |
"""
|
| 82 |
)
|
| 83 |
async def submit_expense(
|
|
|
|
| 43 |
description="""
|
| 44 |
Submit a new expense for reimbursement.
|
| 45 |
|
| 46 |
+
- Types: Fuel, Food, Lodging, Miscellaneous
|
| 47 |
+
- Receipt photo is mandatory
|
| 48 |
+
- Amount must be positive, currency in ISO 4217 format
|
| 49 |
+
- Timestamp must be within 30 days
|
| 50 |
+
- Default status: pending (requires admin approval)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 51 |
"""
|
| 52 |
)
|
| 53 |
async def submit_expense(
|
app/tracker/tasks/router.py
CHANGED
|
@@ -32,22 +32,9 @@ router = APIRouter(prefix="/tasks", tags=["Tasks"])
|
|
| 32 |
description="""
|
| 33 |
Fetch all tasks assigned to the authenticated employee for today.
|
| 34 |
|
| 35 |
-
|
| 36 |
-
-
|
| 37 |
-
-
|
| 38 |
-
|
| 39 |
-
**Task Status:**
|
| 40 |
-
- not_started: Task has not been started yet
|
| 41 |
-
- in_progress: Task is currently being worked on
|
| 42 |
-
- completed: Task has been completed
|
| 43 |
-
|
| 44 |
-
**Authentication:**
|
| 45 |
-
- Requires valid JWT token
|
| 46 |
-
- Returns tasks for the authenticated employee only
|
| 47 |
-
|
| 48 |
-
**Data Source:**
|
| 49 |
-
- Table: scm_tasks
|
| 50 |
-
- Filters by: assigned_to (employee_id) and scheduled_at (today's date)
|
| 51 |
"""
|
| 52 |
)
|
| 53 |
async def get_today_tasks(
|
|
@@ -126,33 +113,10 @@ async def get_today_tasks(
|
|
| 126 |
description="""
|
| 127 |
Update the status of a task with location and timestamp tracking.
|
| 128 |
|
| 129 |
-
|
| 130 |
-
-
|
| 131 |
-
-
|
| 132 |
-
-
|
| 133 |
-
|
| 134 |
-
**Rules:**
|
| 135 |
-
- Location (latitude/longitude) is mandatory for every update
|
| 136 |
-
- Timestamp is mandatory and must be in Unix milliseconds
|
| 137 |
-
- Status transitions are validated (e.g., can't go from completed to not_started directly)
|
| 138 |
-
- Only the assigned employee can update the task
|
| 139 |
-
- Merchant ID must match the task's merchant
|
| 140 |
-
|
| 141 |
-
**Status Transitions:**
|
| 142 |
-
- not_started β in_progress (captures started_at timestamp)
|
| 143 |
-
- not_started β completed (direct completion allowed)
|
| 144 |
-
- in_progress β completed (captures completed_at timestamp)
|
| 145 |
-
- in_progress β not_started (revert allowed)
|
| 146 |
-
- completed β in_progress (reopening allowed)
|
| 147 |
-
|
| 148 |
-
**Timestamps Captured:**
|
| 149 |
-
- started_at: Set when status changes to in_progress
|
| 150 |
-
- completed_at: Set when status changes to completed
|
| 151 |
-
- updated_at: Set on every update
|
| 152 |
-
|
| 153 |
-
**Authentication:**
|
| 154 |
-
- Requires valid JWT token
|
| 155 |
-
- Task must be assigned to the authenticated employee
|
| 156 |
"""
|
| 157 |
)
|
| 158 |
async def update_task_status(
|
|
|
|
| 32 |
description="""
|
| 33 |
Fetch all tasks assigned to the authenticated employee for today.
|
| 34 |
|
| 35 |
+
- Returns tasks ordered by scheduled time
|
| 36 |
+
- Includes task status, location, and scheduled time
|
| 37 |
+
- Status: not_started, in_progress, completed
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 38 |
"""
|
| 39 |
)
|
| 40 |
async def get_today_tasks(
|
|
|
|
| 113 |
description="""
|
| 114 |
Update the status of a task with location and timestamp tracking.
|
| 115 |
|
| 116 |
+
- Status: not_started, in_progress, completed
|
| 117 |
+
- Location and timestamp are mandatory
|
| 118 |
+
- Only assigned employee can update
|
| 119 |
+
- Captures started_at and completed_at timestamps
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 120 |
"""
|
| 121 |
)
|
| 122 |
async def update_task_status(
|