Cron job

Quark ERP သည် cron ပုံစံနှစ်မျိုး ထောက်ပံ့ပါသည် — process-local @CronJob (in-process timer) နှင့် distributed CronJobService (BullMQ + Redis + Postgres)။ Shared / multi-instance အတွက် BullMQ၊ single-process tick အတွက် @CronJob ကို အသုံးပြုရပါသည်။

အမျိုးအစားနှစ်ခု

အလုပ် မည်သို့ run ရမည်နှင့် ကိုက်သော ပုံစံကို ရွေးချယ်ရပါသည်။

Process cron (@CronJob) — @Service resolve ဖြစ်သောအခါ စတင်သော in-process schedule; Node cron package (ဤ process တွင်သာ)
BullMQ cron (CronJobService) — Redis queue + Postgres (cron_jobs) metadata; retry၊ repeat limit၊ multi-instance ဘေးကင်းပါသည်

မည်သည့်အချိန်တွင် မည်သည်ကို သုံးမည်

BullMQ CronJobService — domain sweep၊ reminder၊ reconcile၊ restart ခံနိုင်ပြီး instance အများနှင့် မှန်ကန်ရမည့် အလုပ်
Process @CronJob — single process ပေါ်ရှိ ပေါ့ပါး housekeeping သို့မဟုတ် Redis မလိုသော in-memory tick
အလုပ်အသစ်အတွက် @quan-erp-plugins/cron-schedular-backend မသုံးရပါ — တူညီသော API များသည် core တွင် CronJobService အဖြစ် ရှိပါသည်

1. Process cron (@CronJob)

DI-resolved @Service ပေါ်ရှိ method ကို decorate လုပ်ရပါသည်။ Class resolve ဖြစ်သောအခါ core က expression ဖြင့် process-local CronJob စတင်ပါသည်။ DB row / Redis / retry မရှိပါ — service load လုပ်သော process တိုင်း သီးခြား tick လုပ်ပါသည်။

expression (လိုအပ်) — cron pattern၊ ဥပမာ 0 * * * *
name (optional) — log အတွက် label
Class သည် @Service() ဖြစ်ရပါမည် (သို့မဟုတ် DI-resolved) နှင့် module providers တွင် မှတ်ပုံတင်ရပါမည်

TSX@CronJob

import { CronJob, Module, Service } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Service()
export class LocalHousekeepingService {
  @CronJob({ expression: "0 * * * *", name: "HourlyLocalCleanup" })
  async cleanup() {
    // runs on this Node process only
  }
}

@Module({
  name: metadata.name,
  providers: [LocalHousekeepingService],
  controllers: [],
  entities: [],
})
export class MyPluginModule {}

2. BullMQ cron (CronJobService)

Job များကို Redis ပေါ်ရှိ BullMQ မှ enqueue လုပ်ပါသည်။ Schedule metadata ကို Postgres (cron_jobs) တွင် သိမ်းပါသည်။ Boot တွင် active schedule များကို Redis သို့ ပြန် load လုပ်ပါသည်။ Callback များသည် in-memory သာဖြစ်သဖြင့် boot တိုင်း listener ပြန်တွဲရပါမည်။

CronJobService ကို inject လုပ်ပါ

Builtin core service ကို ContainerRegistryManager.BUILTIN_PLUGIN ဖြင့် inject လုပ်ရပါသည်။

TSXinject

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  Service,
} from "@quan-erp/shared-backend-core";

@Service()
export class MaturedSweepService {
  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  private cronJobService: CronJobService;
}

BullMQ job မှတ်ပုံတင်ခြင်း

Unique (pluginName, jobName) pair ဖြင့် register ခေါ်ရပါသည်။ pluginName အဖြစ် metadata.name ကို အသုံးပြုရပါသည်။ register က DB row ကို upsert လုပ်ပြီး Redis scheduler ကို (ပြန်)ဖန်တီးပါသည်။

TSXregister

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Service()
export class MaturedSweepService {
  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  private cronJobService: CronJobService;

  async registerJob() {
    await this.cronJobService.register({
      cronExpression: "0 2 * * *",
      pluginName: metadata.name,
      jobName: "matured-daily-sweep",
      status: "active",
      startDate: new Date(),
      data: { reason: "daily-sweep" },
      retry: { attempt: 3, delay: 5_000, type: "exponential" },
      callback: async (job) => {
        await this.runSweep(job.data);
      },
    });
  }

  private async runSweep(data: unknown) { /* … */ }
}

Restart ပြီးနောက် listener များ ပြန်တွဲပါ

Boot တွင် schedule များကို Postgres မှ Redis သို့ ပြန် load လုပ်ပါသည်။ Callback များကို မသိမ်းပါ — @OnAllModuleLoaded တွင် အမြဲ ပြန်မှတ်ပုံတင်ရပါသည် (သို့မဟုတ် register ဖြင့် callback ပြန်ပေးရပါသည်)။

TSXlistener

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  OnAllModuleLoaded,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Service()
export class MaturedSweepService {
  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  private cronJobService: CronJobService;

  @OnAllModuleLoaded()
  async onAllModuleLoaded() {
    this.cronJobService.addEventListener(
      metadata.name,
      "matured-daily-sweep",
      async (job) => { await this.runSweep(job.data); },
    );
  }

  private async runSweep(data: unknown) { /* … */ }
}

Stop / remove (BullMQ)

stop(pluginName, jobName) — scheduler ကို ခဏရပ်ပြီး inactive အဖြစ် မှတ်ပါသည်
remove(pluginName, jobName) — Redis scheduler၊ DB row နှင့် listener များကို ဖျက်ပါသည်
stopAllByPluginName / removeAllByPluginName — uninstall အတွက် bulk helper များ

Query helpers

TSXquery

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

@Service()
export class MaturedSweepService {
  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  private cronJobService: CronJobService;

  async listJobs() {
    const job = await this.cronJobService.getByPluginNameWithJobName(
      metadata.name,
      "matured-daily-sweep",
    );

    const jobs = await this.cronJobService.getByPluginName({
      pluginName: metadata.name,
      skip: 0,
      limit: 50,
      status: "active",
    });

    return { job, jobs };
  }
}

CreateCronJobDTO

cronExpression (လိုအပ်) — ဥပမာ 0 2 * * *
pluginName / jobName (လိုအပ်) — key သည် `${pluginName}/${jobName}`
status — active | inactive
data — BullMQ job.data ပေါ်ရှိ payload
startDate — အစောဆုံး စတင်ချိန် (initial delay)
repeat.limit — အများဆုံး အကြိမ်ရေ
retry.attempt / delay / type (fixed | exponential)
callback — register အချိန်တွင် optional in-memory listener

အကြံပြု BullMQ pattern

01
Inject
ContainerRegistryManager.BUILTIN_PLUGIN ဖြင့် CronJobService။
02
Boot တွင် မှတ်ပုံတင်ခြင်း
@OnAllModuleLoaded တွင် register({ pluginName: metadata.name, jobName, cronExpression, … })။
03
Boot တိုင်း listener တွဲပါ
register ပေါ်တွင် callback နှင့်/သို့မဟုတ် addEventListener — schedule သည် restart ကို ခံနိုင်သော်လည်း handler မခံနိုင်ပါ။
04
Cleanup
Uninstall / disable တွင် orphan Redis scheduler မကျန်အောင် stop သို့မဟုတ် remove လုပ်ရပါသည်။

TSXend-to-end

import {
  ContainerRegistryManager,
  CronJobService,
  Inject,
  OnAllModuleLoaded,
  Service,
} from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };

const JOB_NAME = "inventory-nightly-reconcile";

@Service()
export class InventoryReconcileCronService {
  @Inject(CronJobService, ContainerRegistryManager.BUILTIN_PLUGIN)
  private cronJobService: CronJobService;

  @OnAllModuleLoaded()
  async onAllModuleLoaded() {
    await this.cronJobService.register({
      cronExpression: "0 3 * * *",
      pluginName: metadata.name,
      jobName: JOB_NAME,
      startDate: new Date(),
      callback: async () => { await this.reconcile(); },
    });
  }

  private async reconcile() { /* domain work */ }
}