{"openapi":"3.0.3","info":{"title":"AA Portal Backend API","description":"RESTful API for the AA Portal Backend — IAM Integration & Masterdata Portal.\nPhase 1 covers IAM (authentication, users, permissions) and Data Store (custom tables, row CRUD, import/export).\n","version":"1.0.0","contact":{"name":"AA Portal Team"}},"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/vietnamsilicon/APIContract1/1.0.0"},{"url":"http://localhost:8080/api/v1","description":"Local development"},{"url":"https://portal-api.example.com/api/v1","description":"Production"}],"tags":[{"name":"Auth","description":"Authentication (OAuth 2.0 / OIDC via Casdoor)"},{"name":"Users","description":"User management (proxied from Casdoor)"},{"name":"Permissions","description":"Permission matrix management"},{"name":"DataStore","description":"Custom master data tables and row operations"},{"name":"Health","description":"Health check endpoints"}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health check","operationId":"healthCheck","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string","example":"1.0.0"}}}}}}}}},"/auth/login":{"get":{"tags":["Auth"],"summary":"Initiate Casdoor SSO login","description":"Generates a cryptographic `state` token (CSRF protection), stores it in Redis with a 5-minute TTL\nalongside the requested redirect_uri, then redirects the browser to Casdoor's authorization endpoint.\nThe backend is a confidential client — no PKCE is used; the code exchange relies on `client_secret`.\n","operationId":"authLogin","parameters":[{"name":"redirect_uri","in":"query","description":"URL to redirect after successful login (stored server-side with the state token)","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to Casdoor login page (state stored in Redis, not in a cookie)","headers":{"Location":{"description":"Casdoor authorize URL with client_id, response_type=code, redirect_uri, scope, and state","schema":{"type":"string"}}}}}}},"/auth/callback":{"get":{"tags":["Auth"],"summary":"OAuth callback from Casdoor","description":"Validates the `state` parameter against Redis (rejects with 400 if missing, expired, or mismatched),\ndeletes the state key (single-use), exchanges the authorization code for tokens server-to-server\nusing `client_secret`, parses the JWT, creates a Redis session, and redirects to the portal\nwith an opaque session cookie. The browser passively follows Casdoor's redirect to this endpoint.\n","operationId":"authCallback","parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to portal dashboard with session cookie set","headers":{"Set-Cookie":{"schema":{"type":"string"}},"Location":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/auth/logout":{"post":{"tags":["Auth"],"summary":"Logout","description":"Destroys the server-side session in Redis, clears the session cookie, and optionally\nrevokes the token at Casdoor server-to-server. Returns a JSON response (no redirect);\nthe SPA handles post-logout navigation.\n","operationId":"authLogout","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"Successfully logged out","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"logged out"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/auth/me":{"get":{"tags":["Auth"],"summary":"Get current user info","description":"Returns the authenticated user's identity from the active session.","operationId":"authMe","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"Current user info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUser"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/users":{"get":{"tags":["Users"],"summary":"List and search users","description":"Returns a paginated list of users. Requires `users:view` permission.","operationId":"listUsers","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"search","in":"query","description":"Search by name or email","schema":{"type":"string"}},{"name":"role","in":"query","description":"Filter by role","schema":{"type":"string","enum":["Operator","Manager","Administrator"]}},{"name":"status","in":"query","description":"Filter by status","schema":{"type":"string","enum":["active","inactive"]}},{"name":"sort_by","in":"query","description":"Sort field","schema":{"type":"string","enum":["name"],"default":"name"}},{"name":"sort_order","in":"query","description":"Sort direction","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}}],"responses":{"200":{"description":"Paginated user list","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UserListItem"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/users/{userId}":{"get":{"tags":["Users"],"summary":"Get user profile","description":"Returns full user profile including account info, access & permissions, and recent activity. Requires `users:view` permission.","operationId":"getUser","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/UserId"}],"responses":{"200":{"description":"User profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Users"],"summary":"Edit user profile","description":"Updates editable user fields (name, department, employee ID, phone, role). Email is read-only. Requires `users:edit` permission.","operationId":"editUser","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/UserId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditUserRequest"}}}},"responses":{"200":{"description":"Updated user profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Business rule violation (e.g. deactivating the last active administrator)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"LAST_ADMIN_PROTECTED","message":"Cannot deactivate the last active administrator"}}}}}}},"/users/{userId}/deactivate":{"post":{"tags":["Users"],"summary":"Deactivate user","description":"Sets user status to Inactive and invalidates all sessions. Requires `users:deactivate` permission.","operationId":"deactivateUser","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/UserId"}],"responses":{"200":{"description":"User deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserStatusResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"User is already inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"USER_ALREADY_INACTIVE","message":"User is already inactive"}}}},"422":{"description":"Business rule violation (e.g. deactivating the last active administrator)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"LAST_ADMIN_PROTECTED","message":"Cannot deactivate the last active administrator"}}}},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/users/{userId}/reactivate":{"post":{"tags":["Users"],"summary":"Reactivate user","description":"Sets user status to Active. Requires `users:deactivate` permission.","operationId":"reactivateUser","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/UserId"}],"responses":{"200":{"description":"User reactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserStatusResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"User is already active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"USER_ALREADY_ACTIVE","message":"User is already active"}}}},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/users/{userId}/activity":{"get":{"tags":["Users"],"summary":"Get user activity","description":"Returns paginated recent activity for a user. Requires `users:view` permission.","operationId":"getUserActivity","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/UserId"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"search","in":"query","description":"Search activity descriptions by keyword (e.g., \"Job_100234\", \"vendor_code\")","schema":{"type":"string"}},{"name":"event_type","in":"query","description":"Filter by activity category. Maps to the 'All Types' dropdown in the UI.","schema":{"type":"string","enum":["auth","authz","user_mgmt","permission","datastore"]}},{"name":"date_from","in":"query","description":"Start of date range filter (inclusive). ISO 8601 date. E.g., 'Last 7 days' = today minus 7.","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","description":"End of date range filter (inclusive). ISO 8601 date. Defaults to today.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Paginated activity list","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ActivityItem"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/permissions":{"get":{"tags":["Permissions"],"summary":"Get permission matrix","description":"Returns the full permission matrix organized by module and role. Requires `users:permissions` permission.","operationId":"getPermissionMatrix","security":[{"sessionCookie":[]}],"parameters":[{"name":"search","in":"query","description":"Filter permissions by keyword (matches module name or permission display name). Maps to 'Search permissions...' input.","schema":{"type":"string"}}],"responses":{"200":{"description":"Permission matrix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionMatrix"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"put":{"tags":["Permissions"],"summary":"Update permission matrix","description":"Applies a batch of permission changes (grant/revoke) atomically. Requires `users:manage_permissions` permission.","operationId":"updatePermissionMatrix","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionUpdateRequest"}}}},"responses":{"200":{"description":"Updated permission matrix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionMatrix"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/tables":{"get":{"tags":["DataStore"],"summary":"List data store tables","description":"Returns all custom tables with metadata. Requires `datastore:view` permission.","operationId":"listTables","security":[{"sessionCookie":[]}],"parameters":[{"name":"search","in":"query","description":"Search by table name or description","schema":{"type":"string"}}],"responses":{"200":{"description":"List of tables","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DataTableSummary"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["DataStore"],"summary":"Create custom table","description":"Creates a new master data table with column definitions. Requires `datastore:create` permission.","operationId":"createTable","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTableRequest"}}}},"responses":{"201":{"description":"Table created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataTableDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Table name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"CONFLICT","message":"A table with the name 'Vendor Agreements' already exists"}}}}}}},"/tables/{tableId}":{"get":{"tags":["DataStore"],"summary":"Get table detail","description":"Returns table metadata and column schema. Requires `datastore:view` permission.","operationId":"getTable","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/TableId"}],"responses":{"200":{"description":"Table detail with columns","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataTableDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/tables/{tableId}/rows":{"get":{"tags":["DataStore"],"summary":"List table rows","description":"Returns paginated rows with column schema bundled in the response, enabling single-call table rendering.\nThe `columns` array provides the column definitions needed to interpret `DataRow.data` keys and render\ntable headers, data types, and validation rules. Requires `datastore:view` permission.\n","operationId":"listRows","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/TableId"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"search","in":"query","description":"Full-text search across all text columns in the table. Maps to 'Search in table...' input.","schema":{"type":"string"}},{"name":"sort_by","in":"query","description":"Column name to sort by","schema":{"type":"string"}},{"name":"sort_order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}},{"name":"filter","in":"query","description":"JSON-encoded filter object: {\"column\": {\"op\": \"eq|neq|gt|gte|lt|lte|like|in\", \"value\": ...}}","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated rows","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"type":"object","properties":{"columns":{"type":"array","description":"Column definitions for this table. Included so the frontend can render\ntable headers, determine data types, and interpret DataRow.data keys\n— all in a single API call (no need to GET /tables/{tableId} separately).\n","items":{"$ref":"#/components/schemas/ColumnDefinition"}},"data":{"type":"array","items":{"$ref":"#/components/schemas/DataRow"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["DataStore"],"summary":"Create row","description":"Adds a new row to the table. Requires `datastore:edit` permission.","operationId":"createRow","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/TableId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRowRequest"}}}},"responses":{"201":{"description":"Row created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataRow"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/tables/{tableId}/rows/{rowId}":{"put":{"tags":["DataStore"],"summary":"Update row","description":"Updates an existing row. Requires `datastore:edit` permission.","operationId":"updateRow","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/TableId"},{"$ref":"#/components/parameters/RowId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRowRequest"}}}},"responses":{"200":{"description":"Row updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataRow"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["DataStore"],"summary":"Delete row","description":"Deletes a row. Requires `datastore:delete` permission.","operationId":"deleteRow","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/TableId"},{"$ref":"#/components/parameters/RowId"}],"responses":{"204":{"description":"Row deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/tables/{tableId}/rows/{rowId}/duplicate":{"post":{"tags":["DataStore"],"summary":"Duplicate row","description":"Creates a copy of an existing row with the same data values and a new ID. Requires `datastore:edit` permission.","operationId":"duplicateRow","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/TableId"},{"$ref":"#/components/parameters/RowId"}],"responses":{"201":{"description":"Duplicated row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataRow"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/tables/{tableId}/columns":{"post":{"tags":["DataStore"],"summary":"Add column to table","description":"Adds a new column to an existing table. Requires `datastore:edit` permission.","operationId":"addColumn","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/TableId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ColumnDefinition"}}}},"responses":{"201":{"description":"Column added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataTableDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/tables/{tableId}/import":{"post":{"tags":["DataStore"],"summary":"Import CSV","description":"Imports data from a CSV file into the table. Requires `datastore:import` permission.","operationId":"importCSV","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/TableId"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"CSV file (max 50MB, max 100k rows)"}}}}}},"responses":{"200":{"description":"Import report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportReport"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"File too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"PAYLOAD_TOO_LARGE","message":"File exceeds maximum allowed size of 50MB"}}}}}}},"/tables/{tableId}/export":{"get":{"tags":["DataStore"],"summary":"Export table data","description":"Exports table data as CSV or Excel. Requires `datastore:export` permission.","operationId":"exportTable","security":[{"sessionCookie":[]}],"parameters":[{"$ref":"#/components/parameters/TableId"},{"name":"format","in":"query","required":true,"schema":{"type":"string","enum":["csv","xlsx"]}},{"name":"filter","in":"query","description":"JSON-encoded filter (same as list rows)","schema":{"type":"string"}},{"name":"sort_by","in":"query","schema":{"type":"string"}},{"name":"sort_order","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"File download","content":{"text/csv":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"securitySchemes":{"sessionCookie":{"type":"apiKey","in":"cookie","name":"portal_session"}},"parameters":{"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"PageSize":{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"UserId":{"name":"userId","in":"path","required":true,"schema":{"type":"string"}},"TableId":{"name":"tableId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"RowId":{"name":"rowId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}},"responses":{"BadRequest":{"description":"Bad request — validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"VALIDATION_ERROR","message":"Field 'name' is required","details":[{"field":"name","message":"must not be empty"}]}}}},"Unauthorized":{"description":"Unauthorized — missing or invalid session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"UNAUTHORIZED","message":"Session expired or invalid. Please log in again."}}}},"Forbidden":{"description":"Forbidden — insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"FORBIDDEN","message":"You do not have the required permission: users:edit"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"NOT_FOUND","message":"Resource not found"}}}},"BadGateway":{"description":"Bad gateway — upstream service (Casdoor) unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"BAD_GATEWAY","message":"Unable to reach identity provider (Casdoor). Please try again later."}}}},"ServiceUnavailable":{"description":"Service unavailable — permission service unreachable (fail-closed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":"SERVICE_UNAVAILABLE","message":"Permission service is temporarily unavailable. Access denied by default (fail-closed)."}}}}},"schemas":{"ErrorResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Values per HTTP status:\n- 400: VALIDATION_ERROR\n- 401: UNAUTHORIZED\n- 403: FORBIDDEN\n- 404: NOT_FOUND\n- 409: CONFLICT\n- 413: PAYLOAD_TOO_LARGE\n- 502: BAD_GATEWAY\n- 503: SERVICE_UNAVAILABLE\n","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Human-readable error message","example":"Field 'name' is required"},"details":{"description":"Additional error details (field-level validation errors, etc.)","type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Field name that caused the error"},"message":{"type":"string","description":"Specific error for this field"}}}}}},"PaginatedResponse":{"type":"object","properties":{"page":{"type":"integer","example":1},"page_size":{"type":"integer","example":20},"total":{"type":"integer","format":"int64","example":150},"total_pages":{"type":"integer","example":8}}},"CurrentUser":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["Operator","Manager","Administrator"]},"avatar":{"type":"string"},"organization":{"type":"string"}}},"UserListItem":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["Operator","Manager","Administrator"]},"status":{"type":"string","enum":["active","inactive"]},"avatar":{"type":"string"},"last_active":{"type":"string","format":"date-time"}}},"UserProfile":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","inactive"],"description":"Current account status of the user."},"account_information":{"$ref":"#/components/schemas/AccountInformation"},"access_permissions":{"$ref":"#/components/schemas/AccessPermissions"},"recent_activities":{"type":"array","description":"Preview of the last 5 activity items. Use GET /users/{userId}/activity for full paginated history.","maxItems":5,"items":{"$ref":"#/components/schemas/ActivityItem"}}}},"AccountInformation":{"type":"object","description":"UI card: Account Information","properties":{"name":{"type":"string","description":"Full name (consistent with top-level UserProfile.name)"},"email":{"type":"string","description":"Read-only — synced from Casdoor"},"department":{"type":"string"},"employee_id":{"type":"string"},"phone":{"type":"string"}}},"AccessPermissions":{"type":"object","description":"UI card: Access & Permissions","properties":{"role":{"type":"string","enum":["Operator","Manager","Administrator"]},"granted_permissions":{"type":"integer","description":"Number of permissions granted to this user's role"},"total_permissions":{"type":"integer","description":"Total available permissions"},"organization":{"type":"string","description":"Casdoor organization / Azure AD Group name"},"last_login":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time","description":"Account creation date"}}},"EditUserRequest":{"type":"object","required":["name","role"],"properties":{"name":{"type":"string","maxLength":255,"description":"Full Name (required)"},"department":{"type":"string","maxLength":255,"description":"Department (dropdown)"},"employee_id":{"type":"string","maxLength":100,"description":"Employee ID"},"phone":{"type":"string","description":"Phone number"},"role":{"type":"string","enum":["Operator","Manager","Administrator"],"description":"Role (required, dropdown). Changing role updates the user's base permissions."},"status":{"type":"string","enum":["active","inactive"],"description":"Account status. Changing to 'inactive' invalidates all sessions (same as deactivate). Changing to 'active' reactivates the user."}}},"UserStatusResponse":{"type":"object","description":"Lightweight response returned by deactivate and reactivate endpoints.","required":["id","status"],"properties":{"id":{"type":"string","description":"Casdoor user identifier."},"status":{"type":"string","enum":["active","inactive"],"description":"The new account status after the operation."}}},"ActivityItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"actor_id":{"type":"string","description":"Casdoor user ID of the user who performed the action"},"actor_name":{"type":"string","description":"Display name of the actor at the time of the event"},"event_type":{"type":"string","description":"Category for icon rendering (e.g., auth, task, data_correction, permission, user_management)"},"action":{"type":"string","description":"Specific action performed (e.g., login, approve, update, create)"},"target_id":{"type":"string","description":"ID of the referenced entity (user, job, table, etc.)"},"target_type":{"type":"string","description":"Type of the referenced entity (e.g., user, job, task, permission, table)"},"target_name":{"type":"string","description":"Human-readable name of the referenced entity."},"description":{"type":"string","description":"Primary line / title (bold in UI). E.g., 'Approved task for Job_100234', 'Logged in via Azure AD'."},"detail":{"type":"string","description":"Secondary line / subtitle (muted in UI). E.g., 'FO-6100697843', 'Changed: vendor_code 61139 → 61140'. Null if no extra context."},"metadata":{"type":"string","description":"Structured supplementary context serialised as a string. Null if no extra context."},"timestamp":{"type":"string","format":"date-time"}}},"PermissionMatrix":{"type":"object","properties":{"modules":{"type":"array","items":{"$ref":"#/components/schemas/ModulePermissions"}},"roles":{"type":"array","items":{"$ref":"#/components/schemas/RoleInfo"}}}},"ModulePermissions":{"type":"object","properties":{"module":{"type":"string","description":"Module name — unique, use as React key for this list item","example":"Dashboard"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionEntry"}},"role_summaries":{"type":"array","description":"Per-role granted count for this module, ordered to match column layout.","items":{"$ref":"#/components/schemas/ModuleRoleSummary"}}}},"ModuleRoleSummary":{"type":"object","description":"Summary badge per role per module (e.g., '1/5', '3/5'). Use 'role' as React key (unique within parent module).","properties":{"role":{"type":"string","enum":["Operator","Manager","Administrator"],"description":"References RoleInfo.key — unique within parent, use as React key","example":"Operator"},"granted":{"type":"integer","description":"Number of permissions granted to this role in this module","example":1},"total":{"type":"integer","description":"Total permissions in this module","example":5},"label":{"type":"string","description":"Pre-formatted label for the UI badge","example":"1/5"}}},"PermissionEntry":{"type":"object","properties":{"key":{"type":"string","description":"Globally unique permission identifier (module:action format) — use as React key","example":"dashboard:view"},"display_name":{"type":"string","example":"View Dashboard"},"description":{"type":"string","description":"Tooltip text shown on ⓘ icon hover. Null if no tooltip needed.","example":"Allows viewing the main dashboard and summary widgets"},"role_grants":{"type":"array","description":"Checkbox state per role, ordered to match column layout.","items":{"$ref":"#/components/schemas/RoleGrant"}}}},"RoleGrant":{"type":"object","description":"Checkbox state for one role on one permission. Use 'role' as React key (unique within parent PermissionEntry).","properties":{"role":{"type":"string","enum":["Operator","Manager","Administrator"],"description":"References RoleInfo.key — unique within parent, use as React key","example":"Operator"},"granted":{"type":"boolean","description":"true = checked, false = unchecked","example":true}}},"RoleInfo":{"type":"object","description":"Role metadata for column headers. Use 'key' as React key.","properties":{"key":{"type":"string","description":"Machine identifier for the role (matches role enum values) — use as React key","example":"Operator"},"display_name":{"type":"string","description":"Human-readable label for column headers in the UI","example":"Operator"},"user_count":{"type":"integer","description":"Number of users assigned to this role (shown in column header)","example":3}}},"PermissionUpdateRequest":{"type":"object","required":["changes"],"properties":{"changes":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/PermissionChange"}}}},"PermissionChange":{"type":"object","required":["role","permission","action"],"properties":{"role":{"type":"string","enum":["Operator","Manager","Administrator"],"description":"References RoleInfo.key","example":"Operator"},"permission":{"type":"string","description":"Permission key in module:action format","example":"datastore:create"},"action":{"type":"string","enum":["grant","revoke"]}}},"DataTableSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","description":"Icon identifier for the table card (e.g., 'people', 'document', 'price-tag', 'grid'). Set by user on creation or auto-assigned.","example":"people"},"color":{"type":"string","description":"Hex color for the icon background on the table card (e.g., '#7C3AED' purple, '#10B981' green). Set by user on creation or auto-assigned.","example":"#7C3AED"},"row_count":{"type":"integer"},"column_count":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"DataTableDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"row_count":{"type":"integer"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/ColumnDefinition"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":"string"}}},"CreateTableRequest":{"type":"object","required":["name","columns"],"properties":{"name":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":1000},"icon":{"type":"string","description":"Icon identifier for the table card. Auto-assigned if not provided.","example":"people"},"color":{"type":"string","description":"Hex color for the icon background. Auto-assigned if not provided.","example":"#7C3AED"},"columns":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ColumnDefinition"}},"import_option":{"type":"string","enum":["empty","csv"],"default":"empty","description":"How to populate the table after creation:\n- `empty`: Start with an empty table (default)\n- `csv`: Import data from a CSV file immediately after creation.\n  When `csv` is selected, the client MUST follow up with a\n  POST /tables/{tableId}/import call to upload the file.\n  The response will include the tableId needed for the import call.\n"}}},"ColumnDefinition":{"type":"object","required":["name","data_type"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","maxLength":100},"data_type":{"type":"string","enum":["text","number","date","select","boolean","currency"]},"is_required":{"type":"boolean","default":false},"default_value":{},"select_options":{"type":"array","items":{"type":"string"},"description":"Required when data_type is 'select'"},"position":{"type":"integer"}}},"DataRow":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"values":{"type":"object","additionalProperties":true,"description":"Dynamic column values keyed by column name. E.g., {\"vendor_name\": \"Acme\", \"amount\": 1500}"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":"string"},"updated_by":{"type":"string"}}},"CreateRowRequest":{"type":"object","required":["values"],"properties":{"values":{"type":"object","additionalProperties":true,"description":"Column values keyed by column name"}}},"UpdateRowRequest":{"type":"object","required":["values"],"properties":{"values":{"type":"object","additionalProperties":true,"description":"Column values keyed by column name (partial update — only include fields to change)"}}},"ImportReport":{"type":"object","properties":{"rows_imported":{"type":"integer"},"rows_skipped":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer"},"column":{"type":"string"},"message":{"type":"string"}}}}}}}}}