Digisales

Documented design

• A controller calls a use case, which injects a repository interface by a string token, and a TypeORM repository implements that interface on top of a shared base repository. Domain models, enums and the error catalogs live in the domain layer.
• Cross-cutting behaviour is applied per controller with decorators: authentication, a permission guard, a validation pipe, an interceptor that wraps results in a standard envelope with the duration, and an interceptor that writes an API log record to MongoDB.
• Authentication calls an external identity service to validate each token; the service issues no tokens itself. Permissions are codes of the form module and action, in 22 enum groups with 206 codes. A guard accepts a list as OR, and a nested list as AND.
• A request-scoped transaction interceptor, applied on 33 controllers, opens a transaction, hands its entity manager to the repositories through the request, and commits or rolls back at the end.
• Entities share a base with created, updated and deleted timestamps and actor columns, and delete is soft. A shared pagination helper defaults to 15 rows and caps at 100.

Documented design

• A job has an assignee, a creator, a type, dates, a status, a completion percentage, a result, document paths and a role for the assignee. Jobs can have sub-jobs, with a single parent each, and can link to customers or to a business opportunity's action plan.
• The statuses are CREATING, WAITING_STAFF_CONFIRM, WAITING_MANAGER_CONFIRM, REJECTED, IN_PROCESS, PENDING, EXPIRED, COMPLETED and CANCEL. There is no transition table: the rules are spread across the create, update, send and confirm paths.
• Sending moves a job out of CREATING and only the creator may send it. If the assignee is someone else and the role is not implementer, the job waits for the assignee's confirmation; an implementer goes straight to IN_PROCESS. If the sender is the assignee, a salesperson goes to IN_PROCESS and anyone else waits for the manager's confirmation.
• The confirmer is derived from the position hierarchy, the next position up. Confirming or rejecting is allowed only for that confirmer, takes a list of job ids, and leads to IN_PROCESS or REJECTED.
• Updates depend on the current status. Only the creator edits a CREATING job; a rejected job is edited by the line manager; moving from IN_PROCESS or PENDING allows IN_PROCESS, COMPLETED, PENDING or CANCEL; COMPLETED needs a completion date; COMPLETED, PENDING and CANCEL need a result; an EXPIRED job cannot be changed.
• Validation requires that the end date is after the start date, that referenced samples, types and customers exist, and that a sub-job is not its own parent or already under another parent. When a job is tied to an action plan, its dates are clamped into the plan's range.
• A history row records the actor and a task (create, edit, confirm, reject) with old and new snapshots, but only for edits made after the job has been sent. Discussion threads are stored in MongoDB and broadcast to a room for the job.

Documented design

• A job's settings define a repeat cycle (none, daily, weekly, monthly or yearly), an interval, weekdays for the weekly cycle, how many days ahead to create the next job, whether the previous one must be completed, and a reminder.
• A cron job runs at midnight in the local business timezone. It selects jobs that have not yet been repeated, are not cancelled, repeat on a cycle, whose next start date has arrived and, when required, are completed. It works in batches of 100.
• Each generated job copies the source with a new id, starts directly as IN_PROCESS (skipping the confirmation workflow), keeps a link to the original and gets a copy of the settings. It becomes the next template in a chain, and the source is flagged as repeated.
• The next date adds the interval for daily, monthly and yearly cycles, with the day clamped to the length of the target month, and takes the next listed weekday for weekly ones. The job's duration is preserved.
• After downtime, a chain catches up at one job per run, because the next start date is compared with the current time at each run.

Documented design

• Two cron jobs run every minute for jobs. The overdue check selects IN_PROCESS jobs whose end date plus a configured number of minutes has passed and which have not been warned yet. The setting is a single record with the minutes and the channels (email, in-app notification); with no value, a day is used.
• The due-soon check selects IN_PROCESS jobs whose end date minus the job's own reminder amount has passed, and notifies the assignee.
• Each run sends in batches with a pause of 60 seconds between batches, then sets a flag on the job so that it is warned once. Editing the end date resets the overdue flag.
• Overdue warnings go to the creator and the assignee (or the creator and the confirmer when they are the same person), by email, in-app or both, as configured. A warning does not change the job's status.

Documented design

• A feedback ticket has a code of the form prefix, year and a six-digit sequence, and moves through eleven statuses: CREATING, WAITING_ACCEPTANCE, REJECT, PENDING_INVESTIGATION, UNDER_INVESTIGATION, WAITING_APPROVAL, WAITING_FIX, WAITING_FIX_CHANGE, FIXED, COMPLETED and CLOSED.
• Sending moves a ticket to the next status in a fixed order; if the creator is also the sales manager, creation skips straight to investigation. Rejecting is allowed only from WAITING_ACCEPTANCE and closing only from COMPLETED, each by the step's handlers or a super-admin.
• In the investigation step a primary cause is required. If it is not yet determined, the status stays and a further handler is added, and a second submission with the cause still undetermined is refused.
• Handlers per step come from a configuration per business unit: explicit employees and positions, which are mapped to the ticket's own sales manager, assistant, supervisor and representative. From the later steps on, the handlers also depend on the primary cause. A step with no handler fails with a message naming the step.
• Each step has a service-level deadline in hours, plus thresholds for reaching-due and overdue warnings. After every status change the ticket's warning rows are recreated with a deadline, a reaching-due time and an overdue time, and two per-minute cron jobs notify the step's handlers once per row.
• A status history records the old and new status and the actor. Tickets also have discussion threads, an activity history and an Excel export.

Documented design

• Surveys, weekly order plans, price updates and plan documents share a ladder of six statuses with ranks from 0 to 5: draft, created or submitted, and four successive confirmation levels.
• A shared rule decides whether a status may change: with no role it is refused; a forward move needs a role whose rank is above the current status (or the lowest, sales representative role); a return must go to a lower rank and cannot be done by someone at the status's own rank.
• An output forecast, attached to a survey, has its own approval with a history table. Requesting approval is allowed only from draft or edit and only by the owner; approving is allowed only from the awaiting state and by someone else. Each step runs in a transaction and writes a history row.
• A business opportunity has seven statuses, and its status change records a history row (send, confirm, reject, request adjustment) and notifies the manager, the creator or the reviewers, with an email to reviewers when it becomes CREATED.

Documented design

• There are 17 multipart Excel import endpoints, for customers, surveys, plans, prices, output forecasts and job customers, and 27 template files for download. An import history record keeps the file name, status (waiting, in process, success or fail), type and errors.
• The price update import is synchronous. The workbook is read from memory, the required sheets and the header and data rows are validated, and any error returns an annotated workbook so the user can fix it. If it is clean, duplicates are checked, overwriting is allowed only for drafts, and the records and items are created inside the request's transaction.
• Notifications go through a separate notification service for the in-app list and count, over HTTP. Socket.io, with a Redis adapter, announces new notifications and carries discussion messages in rooms per business opportunity, job and feedback ticket.
• Email uses a pooled nodemailer transport and nine EJS templates (seven for feedback statuses, one for overdue jobs and one for opportunity reviews), sent directly or through a queue service.
• Calls to other services use axios with up to three retries, which by default cover network errors and server errors on idempotent methods.