create-entity-app-server 0.0.3

package/src/app/routes/vessel-tracking/entities/tracked_vessel.json

@@ -0,0 +1,261 @@
+{
+    "name": "tracked_vessel",
+    "description": "선박 트래킹 및 거리 계산에 사용하는 선박 제원/연료 소비 정보",
+    "license_scope": false,
+    "history": false,
+    "hard_delete": true,
+    "fields": {
+        "account_seq": {
+            "index": true,
+            "comment": "소유 account seq",
+            "nullable": true
+        },
+        "name": {
+            "index": true,
+            "comment": "선박명",
+            "type": "varchar(255)",
+            "required": true
+        },
+        "vessel_type": {
+            "index": true,
+            "comment": "선박 종류",
+            "type": "varchar(30)",
+            "nullable": true
+        },
+        "length_m": {
+            "comment": "전장(m)",
+            "type": "double",
+            "nullable": true
+        },
+        "beam_m": {
+            "comment": "폭(m)",
+            "type": "double",
+            "nullable": true
+        },
+        "draft_m": {
+            "comment": "흘수(m)",
+            "type": "double",
+            "nullable": true
+        },
+        "dwt": {
+            "comment": "재화중량톤수",
+            "type": "bigint",
+            "nullable": true
+        },
+        "gt": {
+            "comment": "총톤수",
+            "type": "bigint",
+            "nullable": true
+        },
+        "nt": {
+            "comment": "순톤수",
+            "type": "bigint",
+            "nullable": true
+        },
+        "hire_per_day": {
+            "comment": "일일 용선료(USD/day)",
+            "type": "decimal(12,2)",
+            "nullable": true
+        },
+        "ballast_speed": {
+            "comment": "밸러스트 Full 속도(kn)",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_speed": {
+            "comment": "만재 Full 속도(kn)",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_eco_speed": {
+            "comment": "밸러스트 Eco 속도(kn)",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_eco_speed": {
+            "comment": "만재 Eco 속도(kn)",
+            "type": "double",
+            "nullable": true
+        },
+        "hsfo_price": {
+            "comment": "HSFO 가격(USD/MT)",
+            "type": "decimal(10,4)",
+            "nullable": true
+        },
+        "vlsfo_price": {
+            "comment": "VLSFO 가격(USD/MT)",
+            "type": "decimal(10,4)",
+            "nullable": true
+        },
+        "mdo_price": {
+            "comment": "MDO 가격(USD/MT)",
+            "type": "decimal(10,4)",
+            "nullable": true
+        },
+        "mgo_price": {
+            "comment": "MGO 가격(USD/MT)",
+            "type": "decimal(10,4)",
+            "nullable": true
+        },
+        "ballast_vlsfo_tpd": {
+            "comment": "밸러스트 Full VLSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_hsfo_tpd": {
+            "comment": "밸러스트 Full HSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_mdo_tpd": {
+            "comment": "밸러스트 Full MDO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_mgo_tpd": {
+            "comment": "밸러스트 Full MGO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_eco_vlsfo_tpd": {
+            "comment": "밸러스트 Eco VLSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_eco_hsfo_tpd": {
+            "comment": "밸러스트 Eco HSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_eco_mdo_tpd": {
+            "comment": "밸러스트 Eco MDO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_eco_mgo_tpd": {
+            "comment": "밸러스트 Eco MGO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_seca_vlsfo_tpd": {
+            "comment": "밸러스트 Full SECA VLSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_seca_hsfo_tpd": {
+            "comment": "밸러스트 Full SECA HSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_seca_mdo_tpd": {
+            "comment": "밸러스트 Full SECA MDO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_seca_mgo_tpd": {
+            "comment": "밸러스트 Full SECA MGO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_eco_seca_vlsfo_tpd": {
+            "comment": "밸러스트 Eco SECA VLSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_eco_seca_hsfo_tpd": {
+            "comment": "밸러스트 Eco SECA HSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_eco_seca_mdo_tpd": {
+            "comment": "밸러스트 Eco SECA MDO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "ballast_eco_seca_mgo_tpd": {
+            "comment": "밸러스트 Eco SECA MGO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_vlsfo_tpd": {
+            "comment": "만재 Full VLSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_hsfo_tpd": {
+            "comment": "만재 Full HSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_mdo_tpd": {
+            "comment": "만재 Full MDO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_mgo_tpd": {
+            "comment": "만재 Full MGO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_eco_vlsfo_tpd": {
+            "comment": "만재 Eco VLSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_eco_hsfo_tpd": {
+            "comment": "만재 Eco HSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_eco_mdo_tpd": {
+            "comment": "만재 Eco MDO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_eco_mgo_tpd": {
+            "comment": "만재 Eco MGO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_seca_vlsfo_tpd": {
+            "comment": "만재 Full SECA VLSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_seca_hsfo_tpd": {
+            "comment": "만재 Full SECA HSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_seca_mdo_tpd": {
+            "comment": "만재 Full SECA MDO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_seca_mgo_tpd": {
+            "comment": "만재 Full SECA MGO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_eco_seca_vlsfo_tpd": {
+            "comment": "만재 Eco SECA VLSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_eco_seca_hsfo_tpd": {
+            "comment": "만재 Eco SECA HSFO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_eco_seca_mdo_tpd": {
+            "comment": "만재 Eco SECA MDO 소모량",
+            "type": "double",
+            "nullable": true
+        },
+        "laden_eco_seca_mgo_tpd": {
+            "comment": "만재 Eco SECA MGO 소모량",
+            "type": "double",
+            "nullable": true
+        }
+    }
+}

package/src/app/routes/vessel-tracking/handlers.ts

@@ -0,0 +1,134 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { BadRequestError, NotFoundError, entityServer, ok } from "@gateway/api";
+import type {
+    CreateVesselBody,
+    TrackedVesselRecord,
+    UserWithAccount,
+} from "./types/index.ts";
+
+const ENTITY = "tracked_vessel";
+const LIST_LIMIT = 500;
+type VesselListQueryItem = { seq: number };
+
+function toDto(row: TrackedVesselRecord) {
+    return {
+        id: row.seq,
+        name: row.name,
+        vessel_type: row.vessel_type ?? null,
+        length_m: row.length_m ?? null,
+        beam_m: row.beam_m ?? null,
+        draft_m: row.draft_m ?? null,
+        dwt: row.dwt ?? null,
+        gt: row.gt ?? null,
+        nt: row.nt ?? null,
+        hire_per_day: row.hire_per_day ?? null,
+        ballast_speed: row.ballast_speed ?? null,
+        laden_speed: row.laden_speed ?? null,
+        ballast_eco_speed: row.ballast_eco_speed ?? null,
+        laden_eco_speed: row.laden_eco_speed ?? null,
+        hsfo_price: row.hsfo_price ?? null,
+        vlsfo_price: row.vlsfo_price ?? null,
+        mdo_price: row.mdo_price ?? null,
+        mgo_price: row.mgo_price ?? null,
+        ballast_vlsfo_tpd: row.ballast_vlsfo_tpd ?? null,
+        ballast_hsfo_tpd: row.ballast_hsfo_tpd ?? null,
+        ballast_mdo_tpd: row.ballast_mdo_tpd ?? null,
+        ballast_mgo_tpd: row.ballast_mgo_tpd ?? null,
+        ballast_eco_vlsfo_tpd: row.ballast_eco_vlsfo_tpd ?? null,
+        ballast_eco_hsfo_tpd: row.ballast_eco_hsfo_tpd ?? null,
+        ballast_eco_mdo_tpd: row.ballast_eco_mdo_tpd ?? null,
+        ballast_eco_mgo_tpd: row.ballast_eco_mgo_tpd ?? null,
+        ballast_seca_vlsfo_tpd: row.ballast_seca_vlsfo_tpd ?? null,
+        ballast_seca_hsfo_tpd: row.ballast_seca_hsfo_tpd ?? null,
+        ballast_seca_mdo_tpd: row.ballast_seca_mdo_tpd ?? null,
+        ballast_seca_mgo_tpd: row.ballast_seca_mgo_tpd ?? null,
+        ballast_eco_seca_vlsfo_tpd: row.ballast_eco_seca_vlsfo_tpd ?? null,
+        ballast_eco_seca_hsfo_tpd: row.ballast_eco_seca_hsfo_tpd ?? null,
+        ballast_eco_seca_mdo_tpd: row.ballast_eco_seca_mdo_tpd ?? null,
+        ballast_eco_seca_mgo_tpd: row.ballast_eco_seca_mgo_tpd ?? null,
+        laden_vlsfo_tpd: row.laden_vlsfo_tpd ?? null,
+        laden_hsfo_tpd: row.laden_hsfo_tpd ?? null,
+        laden_mdo_tpd: row.laden_mdo_tpd ?? null,
+        laden_mgo_tpd: row.laden_mgo_tpd ?? null,
+        laden_eco_vlsfo_tpd: row.laden_eco_vlsfo_tpd ?? null,
+        laden_eco_hsfo_tpd: row.laden_eco_hsfo_tpd ?? null,
+        laden_eco_mdo_tpd: row.laden_eco_mdo_tpd ?? null,
+        laden_eco_mgo_tpd: row.laden_eco_mgo_tpd ?? null,
+        laden_seca_vlsfo_tpd: row.laden_seca_vlsfo_tpd ?? null,
+        laden_seca_hsfo_tpd: row.laden_seca_hsfo_tpd ?? null,
+        laden_seca_mdo_tpd: row.laden_seca_mdo_tpd ?? null,
+        laden_seca_mgo_tpd: row.laden_seca_mgo_tpd ?? null,
+        laden_eco_seca_vlsfo_tpd: row.laden_eco_seca_vlsfo_tpd ?? null,
+        laden_eco_seca_hsfo_tpd: row.laden_eco_seca_hsfo_tpd ?? null,
+        laden_eco_seca_mdo_tpd: row.laden_eco_seca_mdo_tpd ?? null,
+        laden_eco_seca_mgo_tpd: row.laden_eco_seca_mgo_tpd ?? null,
+    };
+}
+
+function sanitizeCreateBody(body: CreateVesselBody, accountSeq?: number) {
+    const name = (body.name ?? "").trim();
+    if (!name) throw new BadRequestError("name is required");
+
+    return {
+        ...body,
+        name,
+        account_seq: accountSeq ?? null,
+    };
+}
+
+export async function listVessels(_req: FastifyRequest, reply: FastifyReply) {
+    const resp = await entityServer.query<VesselListQueryItem>(ENTITY, {
+        sql: `SELECT data_seq AS seq FROM ${ENTITY} ORDER BY created_time DESC`,
+        limit: LIST_LIMIT,
+    });
+
+    const items = await Promise.all(
+        resp.data.items.map(async ({ seq }) => {
+            const row = await entityServer.get<TrackedVesselRecord>(
+                ENTITY,
+                seq,
+            );
+            return toDto(row.data);
+        }),
+    );
+
+    return reply.send(ok(items));
+}
+
+export async function createVessel(
+    req: FastifyRequest<{ Body: CreateVesselBody }>,
+    reply: FastifyReply,
+) {
+    const accountSeq = (req.user as UserWithAccount | undefined)?.account_seq;
+    const submitBody = sanitizeCreateBody(
+        req.body ?? ({} as CreateVesselBody),
+        accountSeq,
+    );
+    const created = await entityServer.submit(ENTITY, submitBody);
+    const row = await entityServer.get<TrackedVesselRecord>(
+        ENTITY,
+        created.seq!,
+    );
+
+    return reply.code(201).send(ok(toDto(row.data)));
+}
+
+export async function deleteVessel(
+    req: FastifyRequest<{ Params: { id: string } }>,
+    reply: FastifyReply,
+) {
+    const id = Number(req.params.id);
+    if (!Number.isInteger(id) || id <= 0) {
+        throw new BadRequestError("invalid vessel id");
+    }
+
+    const existing = await entityServer
+        .get<TrackedVesselRecord>(ENTITY, id)
+        .catch(() => null);
+    if (!existing?.data) {
+        throw new NotFoundError(`Vessel ${id} not found`);
+    }
+
+    await entityServer.delete(ENTITY, id);
+    return reply.send(ok({ deleted: true }));
+}

package/src/app/routes/vessel-tracking/routes.ts

@@ -0,0 +1,25 @@
+/**
+ * Vessel Tracking 라우트
+ *
+ * prefix: /api/v1/vessel-tracking
+ */
+
+import type { FastifyInstance } from "fastify";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensurePluginEntities, logger } from "@gateway/api";
+import * as h from "./handlers.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default async function vesselTrackingRoutes(
+    app: FastifyInstance,
+): Promise<void> {
+    await ensurePluginEntities(__dirname).catch((err) =>
+        logger.warn({ err }, "vessel-tracking: ensureEntities failed"),
+    );
+
+    app.get("/vessels", h.listVessels);
+    app.post("/vessels", h.createVessel);
+    app.delete("/vessels/:id", h.deleteVessel);
+}

package/src/app/routes/vessel-tracking/types/index.ts

@@ -0,0 +1,5 @@
+export type {
+    CreateVesselBody,
+    TrackedVesselRecord,
+    UserWithAccount,
+} from "./vessel.ts";

package/src/app/routes/vessel-tracking/types/vessel.ts

@@ -0,0 +1,59 @@
+export interface UserWithAccount {
+    account_seq?: number;
+}
+
+export interface TrackedVesselRecord {
+    seq: number;
+    account_seq?: number | null;
+    name: string;
+    vessel_type?: string | null;
+    length_m?: number | null;
+    beam_m?: number | null;
+    draft_m?: number | null;
+    dwt?: number | null;
+    gt?: number | null;
+    nt?: number | null;
+    hire_per_day?: number | null;
+    ballast_speed?: number | null;
+    laden_speed?: number | null;
+    ballast_eco_speed?: number | null;
+    laden_eco_speed?: number | null;
+    hsfo_price?: number | null;
+    vlsfo_price?: number | null;
+    mdo_price?: number | null;
+    mgo_price?: number | null;
+    ballast_vlsfo_tpd?: number | null;
+    ballast_hsfo_tpd?: number | null;
+    ballast_mdo_tpd?: number | null;
+    ballast_mgo_tpd?: number | null;
+    ballast_eco_vlsfo_tpd?: number | null;
+    ballast_eco_hsfo_tpd?: number | null;
+    ballast_eco_mdo_tpd?: number | null;
+    ballast_eco_mgo_tpd?: number | null;
+    ballast_seca_vlsfo_tpd?: number | null;
+    ballast_seca_hsfo_tpd?: number | null;
+    ballast_seca_mdo_tpd?: number | null;
+    ballast_seca_mgo_tpd?: number | null;
+    ballast_eco_seca_vlsfo_tpd?: number | null;
+    ballast_eco_seca_hsfo_tpd?: number | null;
+    ballast_eco_seca_mdo_tpd?: number | null;
+    ballast_eco_seca_mgo_tpd?: number | null;
+    laden_vlsfo_tpd?: number | null;
+    laden_hsfo_tpd?: number | null;
+    laden_mdo_tpd?: number | null;
+    laden_mgo_tpd?: number | null;
+    laden_eco_vlsfo_tpd?: number | null;
+    laden_eco_hsfo_tpd?: number | null;
+    laden_eco_mdo_tpd?: number | null;
+    laden_eco_mgo_tpd?: number | null;
+    laden_seca_vlsfo_tpd?: number | null;
+    laden_seca_hsfo_tpd?: number | null;
+    laden_seca_mdo_tpd?: number | null;
+    laden_seca_mgo_tpd?: number | null;
+    laden_eco_seca_vlsfo_tpd?: number | null;
+    laden_eco_seca_hsfo_tpd?: number | null;
+    laden_eco_seca_mdo_tpd?: number | null;
+    laden_eco_seca_mgo_tpd?: number | null;
+}
+
+export type CreateVesselBody = Omit<TrackedVesselRecord, "seq" | "account_seq">;

package/src/app/schedules/README.md

@@ -0,0 +1,105 @@
+# app/schedules/
+
+백그라운드 크론 스케줄 모음. 서버 시작 시 폴더명 알파벳 순으로 자동 로드됩니다.
+
+## 구조
+
+```
+{name}/
+├── config.json          — 스케줄러 활성화 여부·cron 표현식 등
+├── config.example.json  — 설정 예시 (config.json 없을 때 복사해 사용)
+└── index.ts             — start() / stop() export 필수
+```
+
+복잡한 스케줄은 단일 `index.ts` 대신 분할할 수 있습니다.
+
+```
+{name}/
+├── config.json
+├── config.example.json
+├── index.ts     — 진입점·스케줄 등록
+├── service.ts   — 핵심 배치 로직
+└── types.ts     — 설정·Row 타입 정의
+```
+
+## 핵심 규칙
+
+- `index.ts`는 반드시 `start()` / `stop()` 함수를 named export해야 합니다.
+- `config.json`의 `enabled: false` 이면 `start()` 내부에서 early return합니다.
+- 분산 환경(멀티인스턴스)에서 중복 실행 방지가 필요하면 `acquireLock` / `releaseLock`을 사용합니다.
+- Fastify `onReady` 훅(start) / `onClose` 훅(stop) 이 자동으로 호출됩니다.
+
+## index.ts 최소 패턴
+
+```ts
+import { createCron, logger, type CronHandle } from "@gateway/api";
+
+let cronHandle: CronHandle | null = null;
+
+export function start(): void {
+    const cfg = loadConfig();
+    if (!cfg.enabled) return;
+
+    cronHandle = createCron({
+        expression: cfg.cron,
+        onTick: async () => {
+            // 배치 로직
+        },
+    });
+
+    logger.info({ cron: cfg.cron }, "{name} scheduler started");
+}
+
+export function stop(): void {
+    cronHandle?.stop();
+    cronHandle = null;
+}
+```
+
+## 스케줄 목록
+
+| 스케줄              | 기본 cron      | 설명                                     | 문서                                                      |
+| ------------------- | -------------- | ---------------------------------------- | --------------------------------------------------------- |
+| `dormancy`          | `0 2 * * *`    | 장기 미접속 계정 휴면 전환·경고          | [docs](../../../docs/schedules/dormancy-and-retention.md) |
+| `data-retention`    | `30 2 * * *`   | 개인정보 보유 기간 만료 데이터 삭제      | [docs](../../../docs/schedules/dormancy-and-retention.md) |
+| `ais_sync`          | `*/10 * * * *` | 전세계 AIS 선박 위치 수집 (aisstream.io) | —                                                         |
+| `kobc_freight_sync` | `0 6 * * *`    | KOBC 해운 운임지수 수집                  | —                                                         |
+| `vessel_kr_sync`    | `0 3 * * *`    | 해양수산부 선박 입항 정보 수집           | —                                                         |
+
+## cron 표현식
+
+```
+┌─────── 분 (0-59)
+│ ┌───── 시 (0-23)
+│ │ ┌─── 일 (1-31)
+│ │ │ ┌─ 월 (1-12)
+│ │ │ │ ┌ 요일 (0-7, 0·7=일요일)
+│ │ │ │ │
+0 2 * * *
+```
+
+### 자주 쓰는 패턴
+
+| 표현식           | 실행 시점                    |
+| ---------------- | ---------------------------- |
+| `0 2 * * *`      | 매일 02:00                   |
+| `0 3 * * *`      | 매일 03:00                   |
+| `0 */6 * * *`    | 6시간마다 (00:00, 06:00 ...) |
+| `*/30 * * * *`   | 30분마다                     |
+| `0 9 * * 1`      | 매주 월요일 09:00            |
+| `0 9 1 * *`      | 매월 1일 09:00               |
+| `0 9 1,15 * *`   | 매월 1일·15일 09:00          |
+| `0 9-18 * * 1-5` | 평일 09:00~18:00 매시 정각   |
+
+### 주의사항
+
+- 시간은 **서버 로컬 타임** 기준이다. 서버 타임존을 확인하고 cron을 설정한다.
+- 멀티인스턴스 환경에서는 `acquireLock`을 사용해 중복 실행을 방지한다.
+- cron 표현식은 서버 재시작 없이 `config.json`만 수정하면 변경된다.
+
+---
+
+## 상세 문서
+
+- [스케줄 추가 가이드](../../../docs/schedules/how-to-create.md)
+- [휴면·데이터 보존 스케줄](../../../docs/schedules/dormancy-and-retention.md)

package/src/app/schedules/ais_sync/config.json

@@ -0,0 +1,4 @@
+{
+    "enabled": true,
+    "cron": "*/10 * * * *"
+}

package/src/app/schedules/ais_sync/index.ts

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+    createCron,
+    acquireLock,
+    releaseLock,
+    logger,
+    type CronHandle,
+} from "@gateway/api";
+import { loadAisConfig } from "@app/plugins/ais/config.ts";
+import { AisService } from "@app/plugins/ais/service.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LOCK_KEY = "ais_sync";
+const LOCK_TTL = 300; // 5분 (수집 60초 + 여유)
+
+interface ScheduleConfig {
+    enabled?: boolean;
+    cron?: string;
+}
+
+function loadScheduleConfig(): ScheduleConfig {
+    const configPath = join(__dirname, "config.json");
+    if (!existsSync(configPath)) return {};
+    try {
+        return JSON.parse(readFileSync(configPath, "utf-8")) as ScheduleConfig;
+    } catch {
+        return {};
+    }
+}
+
+let cronHandle: CronHandle | null = null;
+
+export function start(): void {
+    const schedCfg = loadScheduleConfig();
+    if (schedCfg.enabled === false) return;
+
+    const pluginConfig = loadAisConfig();
+    if (!pluginConfig) return;
+
+    const cron = schedCfg.cron ?? "*/10 * * * *";
+    const service = new AisService(pluginConfig);
+
+    cronHandle = createCron({
+        expression: cron,
+        onTick: async () => {
+            const locked = await acquireLock(LOCK_KEY, LOCK_TTL);
+            if (!locked) {
+                logger.warn("ais sync: already running, skipping");
+                return;
+            }
+            try {
+                logger.info("ais sync: started");
+                const result = await service.syncSnapshot();
+                logger.info(result, "ais sync: completed");
+            } catch (err) {
+                logger.error({ err }, "ais sync: unexpected error");
+            } finally {
+                await releaseLock(LOCK_KEY, LOCK_TTL);
+            }
+        },
+    });
+}
+
+export function stop(): void {
+    cronHandle?.stop();
+    cronHandle = null;
+}

package/src/app/schedules/data-retention/config.json

@@ -0,0 +1,9 @@
+{
+    "_comment": "데이터 보존 정책 설정. enabled를 true로 설정하면 휴면 후 일정 기간 경과 시 개인정보 자동 파기/익명화 기능이 활성화됩니다.",
+    "enabled": false,
+    "retention_days": 1095,
+    "action": "anonymize",
+    "cron": "30 2 * * *",
+    "deploy": true,
+    "minify": false
+}