Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/InnoDev69/StockManager/llms.txt

Use this file to discover all available pages before exploring further.

StockManager maintains a persistent audit trail of every significant action performed through the API. Each record captures who performed the action, what entity was affected, the before and after state of that entity, the client IP address, and whether the action succeeded or failed. The audit system is fully automatic — routes opt in by applying the @audit_action decorator, and the log is never written directly by business logic.

​
The @audit_action Decorator

The audit_action decorator from tools/audit_decorator.py wraps a Flask route handler and logs the action both before and after the function executes. For update and delete operations it fetches the entity’s current state before the handler runs, then compares snapshots to produce a human-readable change description. 
from tools.audit_decorator import audit_action

@audit_action(entity_type, action_name=None, id_param=None)
def my_route_handler(...):
    ...
Parameters:
ParameterTypeDescription
entity_typestringThe kind of entity being acted on ("user", "product", "sale", "application")
action_namestringThe action label stored in the log. Defaults to the HTTP method name if omitted.
id_paramstringName of the URL keyword argument that holds the entity’s ID (e.g., "user_id"). Used to retrieve before/after snapshots.

​
Real Usage Examples

# Logs a create action; builds description from request JSON
@audit_action("user", "create")
def create_user():
    ...

# Fetches old/new snapshots for update diff
@audit_action("user", "update", "target_user_id")
def update_user(target_user_id):
    ...

# Records pre-delete snapshot before the handler runs
@audit_action("user", "delete", "target_user_id")
def delete_user(target_user_id):
    ...

# Application workflow actions
@audit_action("application", "approve", "user_id")
def approve_application(user_id):
    ...
If an exception is raised inside the handler the decorator still writes an error-status audit entry before re-raising, so failures are captured too.

​
Logged Entities and Actions

ActionTrigger
createNew product added via POST /api/products
updateProduct fields changed via PUT /api/products/<id>
deleteProduct removed via DELETE /api/products/<id>
activateSoft-deleted product re-enabled
ActionTrigger
createNew sale recorded via POST /api/sales
updateSale record modified via PUT /api/sales/<id>
ActionTrigger
createAdmin creates an account via POST /api/users
updateAccount fields changed via PUT /api/users/<id>
deleteAccount disabled (soft delete) via DELETE /api/users/<id>
loginUser authenticates via POST /api/login
registerUser self-registers via POST /api/register
reset_passwordPassword-reset code requested
change_passwordPassword changed after code verification
ActionTrigger
approveAdmin approves a pending registration
rejectAdmin rejects a pending registration

​
Audit Endpoints

​
User History

GET /api/user/<user_id>
Returns the audit history for a specific user. A regular authenticated user can only query their own history. A root user can query any user ID. Query parameters:
ParameterTypeDefaultDescription
actionstring—Filter by action name (e.g., login, update)
fromstring—ISO 8601 start date/time (inclusive)
tostring—ISO 8601 end date/time (inclusive)
limitinteger50Maximum records to return
offsetinteger0Pagination offset
Response: 
{
  "total": 12,
  "records": [
    {
      "id": 88,
      "user_id": 3,
      "username": "alice",
      "action": "update",
      "entity_type": "product",
      "entity_id": 14,
      "description": "Cambios: Precio: '$10.00' → '$12.50'",
      "timestamp": "2024-11-15T09:41:02",
      "status": "success"
    }
  ]
}

​
Full Audit Log

GET /api/all
This endpoint is restricted to root only. Any other authenticated role receives 403 Forbidden.
Returns the complete audit log across all users and entities. Accepts the same query parameters as the user-history endpoint (action, from, to, limit, offset).

​
Entity Change Trail

GET /api/entity/<entity_type>/<entity_id>
Returns the chronological change trail for one specific entity. Includes the full old_value and new_value snapshots for each event, making it easy to reconstruct the state of an entity at any point in time. Requires admin or root role. Response: 
{
  "entity_type": "product",
  "entity_id": 14,
  "changes": [
    {
      "user_id": 3,
      "username": "alice",
      "action": "update",
      "old_value": { "id": 14, "name": "Notebook", "price": 10.0, "quantity": 50 },
      "new_value": { "id": 14, "name": "Notebook", "price": 12.5, "quantity": 50 },
      "timestamp": "2024-11-15T09:41:02",
      "description": "Cambios: Precio: '$10.00' → '$12.50'"
    }
  ]
}

​
Example: Querying Product Changes

The following example retrieves all audit events for product ID 14 and filters for update actions only: 
curl -s "http://localhost:5000/api/entity/product/14?action=update&limit=20" \
  -H "Cookie: session=<your-session-cookie>"
To query the full log within a date window (root only): 
curl -s "http://localhost:5000/api/all?from=2024-11-01&to=2024-11-30&limit=100" \
  -H "Cookie: session=<your-session-cookie>"

​
Audit Record Fields

Every record in the audit_log table and every API response includes these fields:
FieldDescription
idAuto-incremented log entry ID
user_idID of the user who performed the action (actor_id)
usernameUsername of the actor (joined from users)
actionAction label: create, update, delete, login, etc.
entity_typeType of entity affected: user, product, sale, application
entity_idPrimary key of the affected entity (nullable for session actions)
descriptionHuman-readable summary of what changed
timestampISO 8601 datetime of the action
statussuccess or error
The old_value and new_value JSON snapshots are stored in the database but only returned by the entity trail endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us