Michael-Antony commited on
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 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
- - Timestamp and work_date are automatically set by the server
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
- - Allowed only after successful check-in
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
- **Expense Types:**
47
- - Fuel: Gas, diesel, vehicle fuel
48
- - Food: Meals, snacks during work
49
- - Lodging: Hotel, accommodation
50
- - Miscellaneous: Other work-related expenses
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
- **Returns:**
36
- - List of tasks with title, description, status, location, and scheduled time
37
- - Tasks are ordered by scheduled time (earliest first)
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
- **Supported Status Values:**
130
- - not_started: Task has not been started yet
131
- - in_progress: Task is currently being worked on
132
- - completed: Task has been completed
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(