wms-app/docs/reviewing/system-settings.md

System And Settings Features

Authentication

Routes:

• app/login/index.php
• app/login/register.php
• app/login/verify.php
• app/login/forgot_password.php
• app/login/onboarding.php
• app/login/api/engine/*

Authentication supports registration, login, OTP confirmation, password reset, onboarding, and app branch selection.

Backend support:

• PasswordManager
• PasswordResetManager
• Login APIs under app/login/api/engine

Session And Security

Core files:

• app/session.php
• app/assets/utils/db_auth.php
• app/assets/utils/db_helpers.php

Security behavior:

• Authenticated session required for normal API routes.
• POST routes validate CSRF token.
• OTP freshness is checked against the user's current password.
• Company access is validated through company_map_user.
• API payloads are accepted as JSON-wrapped POST or FormData.
• Role checks use require_role().

User Management

Routes:

• app/setting/users.php
• app/setting/api/engine/manage_users.php
• app/setting/api/engine/search_users.php
• app/setting/api/engine/retrieve_users.php

User management supports company users, invitation, role updates, and user removal.

Backend support:

• UserManager::getCompanyUsers()
• UserManager::searchUsers()
• UserManager::inviteUser()
• UserManager::updateRole()
• UserManager::removeUser()

Profile And Password

Routes:

• app/setting/profile.php
• app/setting/api/engine/manage_profile.php
• app/setting/api/engine/change_password.php
• app/setting/api/engine/request_reset_otp.php
• app/setting/api/engine/reset_password_otp.php

Users can maintain profile details and change/reset passwords.

Backend support:

• UserManager::getProfile()
• Password reset managers and setting APIs

Company Settings

Routes:

• app/setting/company.php
• app/setting/system_config.php
• app/setting/api/engine/company_setting.php
• app/setting/api/engine/manage_company.php
• app/setting/api/engine/retrieve_company.php

Company settings store transaction configuration, posting windows, system behavior toggles, branch/company details, and setup values.

System configuration includes:

• Advanced Location: simple location mode or three-level zone/aisle/rack mode.
• Location Labels: custom labels for warehouse location levels.
• Default Stock Status: draft or auto-approved stock entries.
• Auto-Complete on Shipped: whether shipped orders become completed automatically.
• Invoice and Credit Note Generation: automatic invoice on order confirmation and credit note on return confirmation.
• Setting Locks: selected settings become locked after dependent transactions exist.

Backend support:

• CompanySettingManager

SMTP Settings

Routes:

• app/setting/smtp.php
• app/setting/api/engine/manage_smtp.php
• app/setting/api/engine/retrieve_smtp.php
• app/setting/api/engine/test_smtp.php
• app/assets/utils/module/mailer.php

SMTP settings configure outbound email and include a test route.

Branch Switching

Routes:

• app/setting/api/engine/switch_branch.php
• app/include_topbar.php

Branch switching changes the active company/context for a logged-in user when they have access to more than one company.

Backend support:

• UserManager::getCompanyList()

Shared JavaScript Utilities

File:

• app/assets/js/custom.js

Shared frontend utilities include:

• ajax_request() with CSRF headers, loading overlay, queue lock, JSON payload preparation, and FormData handling.
• generate_pagination() for table paging.
• batch_process() for retryable sequential batch jobs.
• Operation lock helpers (acquire_op_lock / release_op_lock) for long-running cross-tab operations — wraps OperationLockManager (see below).
• Account autocomplete for posting-account selection.
• Number formatting that avoids scientific notation and suppresses tiny floating point noise.

Operation Locks

Routes:

• app/accounting/api/engine/acquire_op_lock.php
• app/accounting/api/engine/release_op_lock.php

Operation locks prevent two users (or two browser tabs) from running the same long-running operation simultaneously. A lock is a DB row in operation_locks with a company_id, operation_type, user_id, and expiry timestamp.

Behavior:

• acquire() inserts or refreshes a lock row. Returns { acquired: true } if successful or { acquired: false, held_by: '...' } if another user holds it.
• release() deletes the lock row for the calling user.
• Locks have a configurable TTL (default 120 minutes). Expired locks are treated as unowned — any user can acquire them even without an explicit release.

Currently used for:

• gl_post — Batch GL posting in accounting/gl_entries.php. Prevents two users from running overlapping batch jobs against the same company's GL.

Backend support:

• OperationLockManager::acquire(string $operation_type, int $ttl_minutes = 120)
• OperationLockManager::release(string $operation_type)

ETL Summary Maintenance

Routes:

• app/setting/gl_maintenance.php
• app/setting/stock_maintenance.php
• app/setting/api/engine/gl_maintenance.php
• app/setting/api/engine/stock_maintenance.php
• app/cron/etl_gl_maintenance.php
• app/cron/etl_stock_maintenance.php

Two pre-aggregated summary tables accelerate dashboard and report queries:

• etl_gl_summary — monthly GL totals per account, fed by every GL post/delete. Used by the accounting dashboard.
• etl_stock_summary — monthly stock in/out totals per warehouse/product, fed by WarehouseManager::adjustBalance(). Used by the WMS dashboard and stock overview.

Each summary table is maintained write-through on every transaction. The maintenance system provides a safety net for periods that drift out of sync due to crashes, rollbacks, or manual DB edits.

Gap detection compares MAX(source_updated_at) in the raw source table against the summary table's source_updated_at per period. A mismatch means the summary is stale and needs repair.

Automatic repair runs via the Node.js cron scheduler once per hour. Companies are spread across 24 hourly slots using company_id % 24 to distribute load. GL runs at :00 and stock runs at :30 past each hour.

Manual rebuild is available in the maintenance UI. The page shows the cron schedule slot, last run result, and a live count of current gaps. A full rebuild drops and regenerates all periods for the company.

Backend support:

• EtlManager — GL ETL (gap detection, period repair, full rebuild, status)
• EtlStockManager — Stock ETL (same interface, works across dynamic td_stock_<warehouse_id> tables)

Node.js Cron Scheduler

File:

• nodejs/scheduler.js

The scheduler runs inside the Node.js process alongside the Socket.IO server. It uses node-cron to call PHP cron endpoints over HTTP on a fixed schedule. The shared x-cron-secret header authenticates each call.

Current schedules:

Schedule	Endpoint	Purpose
0 * * * * (every hour, :00)	/cron/etl_gl_maintenance.php	GL summary gap repair for slot = current hour
30 * * * * (every hour, :30)	/cron/etl_stock_maintenance.php	Stock summary gap repair for slot = current hour

Each cron run processes only the companies whose company_id % 24 equals the current hour slot — no company is processed more than once per hour.

Database Schema Setup

Files:

• setup.php

The auth database includes a schema_migrations table, but this repository snapshot does not contain a migrations/ directory or migrate.php. Fresh installation schema creation is currently handled by the CLI-only setup.php script, with some runtime-created structures such as dynamic td_stock_<warehouse_id> tables.

File Uploads

File:

• app/assets/utils/classes/FileUploader.php

File upload support is used by product/contact/company/profile flows. It handles directory creation, uploaded file lists, cleanup of replaced files, and rollback on failure.