create-entity-app-server 0.0.3

package/src/app/plugins/vessel_kr/service.ts

@@ -0,0 +1,264 @@
+import { XMLParser } from "fast-xml-parser";
+import { logger, entityServer } from "@gateway/api";
+import type {
+    VesselKrConfig,
+    VesselKrApiItem,
+    VesselKrDetail,
+    VesselKrRecord,
+} from "./types/index.ts";
+
+const BASE_URL = "https://apis.data.go.kr/1192000/VsslEtrynd5";
+const XML_PARSER = new XMLParser({
+    ignoreAttributes: false,
+    isArray: (name) => name === "detail",
+});
+
+// ─────────────────────────── 날짜 헬퍼 ────────────────────────────
+
+function yyyymmdd(d: Date): string {
+    return d.toISOString().slice(0, 10).replace(/-/g, "");
+}
+
+function addDays(d: Date, n: number): Date {
+    const r = new Date(d);
+    r.setDate(r.getDate() + n);
+    return r;
+}
+
+/** 어제 기준으로 syncDays만큼의 날짜 목록 (오래된 순) */
+export function buildSyncDates(syncDays: number): string[] {
+    const yesterday = addDays(new Date(), -1);
+    const dates: string[] = [];
+    for (let i = syncDays - 1; i >= 0; i--) {
+        dates.push(yyyymmdd(addDays(yesterday, -i)));
+    }
+    return dates;
+}
+
+// ─────────────────────────── API 호출 ─────────────────────────────
+
+interface FetchOptions {
+    apiKey: string;
+    prtAgCd: string;
+    date: string; // YYYYMMDD
+    pageNo?: number;
+    numOfRows?: number;
+}
+
+interface ApiPage {
+    items: VesselKrApiItem[];
+    totalCount: number;
+    pageNo: number;
+    numOfRows: number;
+}
+
+async function fetchPage(opts: FetchOptions): Promise<ApiPage> {
+    const { apiKey, prtAgCd, date, pageNo = 1, numOfRows = 100 } = opts;
+
+    const qs = new URLSearchParams({
+        serviceKey: apiKey,
+        pageNo: String(pageNo),
+        numOfRows: String(numOfRows),
+        type: "xml",
+        prtAgCd,
+        inqireDe: date,
+    });
+    const url = `${BASE_URL}/getVsslEtrynd?${qs}`;
+
+    const res = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+    if (!res.ok) {
+        throw new Error(`vessel_kr API HTTP ${res.status} — ${url}`);
+    }
+
+    const xml = await res.text();
+    const parsed = XML_PARSER.parse(xml);
+    const body = parsed?.response?.body;
+
+    if (!body) {
+        const errCode = parsed?.response?.header?.resultCode;
+        const errMsg = parsed?.response?.header?.resultMsg;
+        throw new Error(`vessel_kr API error ${errCode}: ${errMsg}`);
+    }
+
+    const rawItems = body.items?.item ?? [];
+    const items: VesselKrApiItem[] = Array.isArray(rawItems)
+        ? rawItems
+        : [rawItems];
+
+    return {
+        items,
+        totalCount: Number(body.totalCount ?? 0),
+        pageNo: Number(body.pageNo ?? 1),
+        numOfRows: Number(body.numOfRows ?? numOfRows),
+    };
+}
+
+/** prtAgCd × date 조합으로 전체 페이지 순회 */
+async function fetchAll(
+    apiKey: string,
+    prtAgCd: string,
+    date: string,
+): Promise<VesselKrApiItem[]> {
+    const first = await fetchPage({
+        apiKey,
+        prtAgCd,
+        date,
+        pageNo: 1,
+        numOfRows: 100,
+    });
+    const all: VesselKrApiItem[] = [...first.items];
+
+    const total = first.totalCount;
+    const pages = Math.ceil(total / first.numOfRows);
+
+    for (let p = 2; p <= pages; p++) {
+        const page = await fetchPage({
+            apiKey,
+            prtAgCd,
+            date,
+            pageNo: p,
+            numOfRows: 100,
+        });
+        all.push(...page.items);
+    }
+
+    return all;
+}
+
+// ─────────────────────────── 변환 ─────────────────────────────────
+
+function toDetails(raw: VesselKrApiItem): VesselKrDetail[] {
+    const d = raw.details?.detail;
+    if (!d) return [{} as VesselKrDetail];
+    return Array.isArray(d) ? d : [d];
+}
+
+function toRecords(
+    item: VesselKrApiItem,
+    syncedDate: string,
+): VesselKrRecord[] {
+    return toDetails(item).map((detail) => ({
+        prt_ag_cd: item.prtAgCd ?? "",
+        prt_ag_nm: item.prtAgNm ?? "",
+        clsgn: item.clsgn ?? "",
+        vssl_nm: item.vsslNm ?? "",
+        vssl_nlty_cd: item.vsslNltyCd ?? "",
+        vssl_nlty_nm: item.vsslNltyNm ?? "",
+        vssl_knd_cd: item.vsslKndCd ?? "",
+        vssl_knd_nm: item.vsslKndNm ?? "",
+        etrypt_purps_cd: item.etryptPurpsCd ?? "",
+        etrypt_purps_nm: item.etryptPurpsNm ?? "",
+        etryn_nm: detail.etryndNm ?? "",
+        reqst_se_nm: detail.reqstSeNm ?? "",
+        etrypt_dt: detail.etryptDt ?? "",
+        tkoff_dt: detail.tkoffDt ?? "",
+        ibobprt_nm: detail.ibobprtNm ?? "",
+        laidup_fclty_nm: detail.laidupFcltyNm ?? "",
+        tug_yn: detail.tugYn ?? "",
+        piltg_yn: detail.piltgYn ?? "",
+        grtg: detail.grtg ?? "",
+        intrl_grtg: detail.intrlGrtg ?? "",
+        crew_co: detail.crewCo ?? "",
+        koran_crew_co: detail.koranCrewCo ?? "",
+        frgnr_crew_co: detail.frgnrCrewCo ?? "",
+        mr_num: detail.mrNum ?? "",
+        satmnt_entrps_nm: detail.satmntEntrpsNm ?? "",
+        frst_dpmprt_prt_nm: item.frstDpmprtPrtNm ?? "",
+        prvs_dpmprt_prt_nm: item.prvsDpmprtPrtNm ?? "",
+        nxlnpt_prt_nm: item.nxlnptPrtNm ?? "",
+        dstn_prt_nm: item.dstnPrtNm ?? "",
+        ldadng_ton: detail.ldadngTon ?? "",
+        landng_frght_ton: detail.landngFrghtTon ?? "",
+        ld_frght_ton: detail.ldFrghtTon ?? "",
+        synced_date: syncedDate,
+    }));
+}
+
+// ─────────────────────────── 동기화 ───────────────────────────────
+
+export class VesselKrService {
+    constructor(private readonly config: VesselKrConfig) {}
+
+    /**
+     * 지정 날짜의 모든 항만청 데이터를 가져와 엔티티에 upsert.
+     * synced_date 기준으로 기존 레코드를 먼저 삭제(find → delete)하는 방식으로 중복 방지.
+     */
+    async syncDate(date: string): Promise<{ saved: number; errors: number }> {
+        const { apiKey, prtAgCodes, entity } = this.config;
+        let saved = 0;
+        let errors = 0;
+
+        for (const prtAgCd of prtAgCodes) {
+            try {
+                const items = await fetchAll(apiKey, prtAgCd, date);
+                const records = items.flatMap((item) => toRecords(item, date));
+
+                // 이미 저장된 같은 날짜+항만청 레코드 삭제
+                await this.deleteExisting(entity, date, prtAgCd);
+
+                // 배치 저장 (100건 단위)
+                for (let i = 0; i < records.length; i += 100) {
+                    const batch = records.slice(i, i + 100);
+                    await Promise.all(
+                        batch.map((r) => entityServer.submit(entity, r)),
+                    );
+                    saved += batch.length;
+                }
+
+                logger.info(
+                    { date, prtAgCd, count: records.length },
+                    "vessel_kr: synced",
+                );
+            } catch (err) {
+                errors++;
+                logger.error({ err, date, prtAgCd }, "vessel_kr: sync failed");
+            }
+        }
+
+        return { saved, errors };
+    }
+
+    private async deleteExisting(
+        entity: string,
+        date: string,
+        prtAgCd: string,
+    ): Promise<void> {
+        try {
+            // find로 해당 날짜+항만청 레코드 조회 후 삭제
+            const result = await entityServer.find<{ seq: number }[]>(
+                "vessel_kr_entry",
+                {
+                    where: { synced_date: date, prt_ag_cd: prtAgCd },
+                    limit: 1000,
+                },
+            );
+            const rows: { seq: number }[] = Array.isArray(result)
+                ? result
+                : (result?.data ?? []);
+            await Promise.all(
+                rows.map((r) => entityServer.delete(entity, r.seq)),
+            );
+        } catch {
+            // 없으면 무시
+        }
+    }
+
+    /** config.syncDays 기간만큼 동기화 */
+    async syncAll(): Promise<{
+        dates: string[];
+        saved: number;
+        errors: number;
+    }> {
+        const dates = buildSyncDates(this.config.syncDays);
+        let totalSaved = 0;
+        let totalErrors = 0;
+
+        for (const date of dates) {
+            const { saved, errors } = await this.syncDate(date);
+            totalSaved += saved;
+            totalErrors += errors;
+        }
+
+        return { dates, saved: totalSaved, errors: totalErrors };
+    }
+}

package/src/app/plugins/vessel_kr/types/index.ts

@@ -0,0 +1,100 @@
+export interface VesselKrConfig {
+    enabled: boolean;
+    /** 엔티티명 */
+    entity: string;
+    /** 해양수산부 선박운항정보 API 인증키 */
+    apiKey: string;
+    /** 조회 항만청 코드 목록 */
+    prtAgCodes: string[];
+    /** 동기화할 과거 일수 (기본 1 = 전날만) */
+    syncDays: number;
+    deploy: boolean;
+    minify: boolean;
+}
+
+export interface VesselKrApiItem {
+    prtAgCd: string;
+    prtAgNm: string;
+    etryptYear: string;
+    etryptCo: string;
+    clsgn: string;
+    vsslNm: string;
+    vsslNltyCd: string;
+    vsslNltyNm: string;
+    vsslKndCd: string;
+    vsslKndNm: string;
+    etryptPurpsCd: string;
+    etryptPurpsNm: string;
+    frstDpmprtNatPrtCd: string;
+    frstDpmprtPrtNm: string;
+    prvsDpmprtNatPrtCd: string;
+    prvsDpmprtPrtNm: string;
+    nxlnptNatPrtCd: string;
+    nxlnptPrtNm: string;
+    dstnNatPrtCd: string;
+    dstnPrtNm: string;
+    details?: { detail: VesselKrDetail | VesselKrDetail[] };
+}
+
+export interface VesselKrDetail {
+    reqstSeNm: string;
+    etryndNm: string;
+    etryptDt: string;
+    tkoffDt: string;
+    ibobprtNm: string;
+    laidupFcltyCd: string;
+    laidupFcltySubCd: string;
+    laidupFcltyNm: string;
+    tugYn: string;
+    piltgYn: string;
+    ldadngFrghtClCd: string;
+    ldadngTon: string;
+    trnpdtTon: string;
+    landngFrghtTon: string;
+    ldFrghtTon: string;
+    grtg: string;
+    intrlGrtg: string;
+    satmntEntrpsNm: string;
+    crewCo: string;
+    koranCrewCo: string;
+    frgnrCrewCo: string;
+    mrNum: string;
+    tkoffPrrrnDt: string;
+    dstnEtryptDt: string;
+}
+
+export interface VesselKrRecord extends Record<string, unknown> {
+    prt_ag_cd: string;
+    prt_ag_nm: string;
+    clsgn: string;
+    vssl_nm: string;
+    vssl_nlty_cd: string;
+    vssl_nlty_nm: string;
+    vssl_knd_cd: string;
+    vssl_knd_nm: string;
+    etrypt_purps_cd: string;
+    etrypt_purps_nm: string;
+    etryn_nm: string;
+    reqst_se_nm: string;
+    etrypt_dt: string;
+    tkoff_dt: string;
+    ibobprt_nm: string;
+    laidup_fclty_nm: string;
+    tug_yn: string;
+    piltg_yn: string;
+    grtg: string;
+    intrl_grtg: string;
+    crew_co: string;
+    koran_crew_co: string;
+    frgnr_crew_co: string;
+    mr_num: string;
+    satmnt_entrps_nm: string;
+    frst_dpmprt_prt_nm: string;
+    prvs_dpmprt_prt_nm: string;
+    nxlnpt_prt_nm: string;
+    dstn_prt_nm: string;
+    ldadng_ton: string;
+    landng_frght_ton: string;
+    ld_frght_ton: string;
+    synced_date: string;
+}

package/src/app/routes/README.md

@@ -0,0 +1,71 @@
+# app/routes/
+
+사용자 비즈니스 라우트 모음. 서버 시작 시 폴더명 알파벳 순으로 자동 로드됩니다.
+
+## 구조
+
+```
+{domain}/
+├── config.json   — 라우트 활성화 여부 (enabled: true/false)
+├── routes.ts     — URL ↔ 핸들러 매핑 테이블
+├── handlers.ts   — 요청/응답 처리 (FastifyRequest/Reply)
+├── service.ts    — 비즈니스 로직 (entityServer 호출, DB 쿼리 등)
+├── schema.ts     — zod 스키마 (요청/응답 런타임 검증)
+├── entities/     — 엔티티 스키마 JSON (entity-server 자동 등록)
+│   └── {table}.json
+└── types/        — TypeScript 타입 정의
+    ├── index.ts       — re-export 배럴
+    ├── {model}.ts     — 엔티티/모델별 타입
+    ├── params.ts      — 요청 파라미터 타입
+    ├── query.ts       — 쿼리스트링 타입
+    └── defaults.ts    — 타입별 기본값 객체
+```
+
+## 핵심 규칙
+
+- `config.json`의 `enabled: false` 이면 라우트가 로드되지 않습니다 (로그 없음).
+- `config.json`이 없으면 항상 로드됩니다.
+- 등록 경로: `src/app/routes/{domain}/` → `/v1/api/{domain}/*`
+- `routes.ts`에는 URL 매핑만, 비즈니스 로직은 `handlers.ts` / `service.ts`에 작성합니다.
+- `entities/` 폴더에 JSON 스키마를 두면 서버 시작 시 entity-server에 자동 등록됩니다 (`ensurePluginEntities`).
+- **`routes/`에 등록된 경로는 Go 서버 패스스루보다 항상 먼저 처리됩니다.** (`plugins/`도 동일)
+
+> 앱 서버 로딩 순서: `plugins/*/routes.ts` → `routes/*/routes.ts` → 패스스루
+> Go 서버가 제공하는 경로와 동일한 경로를 정의하면 앱 서버가 우선 처리합니다.
+
+## routes.ts 패턴
+
+```ts
+import type { FastifyInstance } from "fastify";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger, ensurePluginEntities } from "@gateway/api";
+import * as h from "./handlers.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default async function domainRoutes(app: FastifyInstance) {
+    await ensurePluginEntities(__dirname).catch((err) =>
+        logger.warn({ err }, "domain: ensureEntities failed"),
+    );
+
+    app.get("/", h.list);
+    app.post("/", h.create);
+    app.get("/:id", h.getById);
+}
+```
+
+> `entities/` 폴더가 없으면 `ensurePluginEntities`는 아무 동작도 하지 않으므로 미리 선언해 두는 것을 권장합니다.
+
+## 라우트 목록
+
+| 도메인     | 경로                   | 설명                     | 문서                                          |
+| ---------- | ---------------------- | ------------------------ | --------------------------------------------- |
+| health     | `/v1/api/health/*`     | 서비스 상태 확인         | [docs](../../../docs/routes/how-to-create.md) |
+| example-db | `/v1/api/example-db/*` | Kysely DB 직접 쿼리 예제 | —                                             |
+| example-es | `/v1/api/example-es/*` | Entity Server API 예제   | —                                             |
+
+## 상세 문서
+
+- [라우트 추가 가이드](../../../docs/routes/how-to-create.md)
+- [플러그인 라우트 레퍼런스](../../../docs/routes/README.md)

package/src/app/routes/account/change-password/config.json

@@ -0,0 +1,5 @@
+{
+    "enabled": true,
+    "deploy": true,
+    "minify": false
+}

package/src/app/routes/account/change-password/entities/password_history.json

@@ -0,0 +1,18 @@
+{
+    "name": "password_history",
+    "description": "비밀번호 변경 이력 (재사용 금지 정책용). change-password 라우트에서 관리합니다.",
+    "hard_delete": true,
+    "fields": {
+        "account_seq": {
+            "index": true,
+            "comment": "계정 seq",
+            "required": true
+        },
+        "passwd_hash": {
+            "comment": "변경 시점의 비밀번호 해시 (salt 포함)"
+        },
+        "changed_time": {
+            "comment": "비밀번호 변경 시각"
+        }
+    }
+}

package/src/app/routes/account/change-password/handlers.ts

@@ -0,0 +1,204 @@
+/**
+ * 비밀번호 변경(Change Password) 핸들러
+ *
+ * 흐름:
+ *   1) JWT에서 account_seq 추출
+ *   2) account 조회 + 현재 비밀번호 검증
+ *   3) 새 비밀번호 정책 검증 (password-policy.ts)
+ *   4) 비밀번호 이력 재사용 검사 (password_history 엔티티)
+ *   5) account.passwd 갱신 + passwd_changed_time / force_password_change 리셋
+ *   6) password_history 저장
+ *
+ * 기존 entity-server 비밀번호 변경 구현을 대체한다.
+ */
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+import { ok, fail, entityServer, logger } from "@gateway/api";
+import {
+    hashPassword,
+    verifyPassword,
+} from "../../password-reset/password-utils.ts";
+import { validatePassword } from "@gateway/api";
+import { getAccountSeqFromJwt } from "../../email-verify/handlers/utils.ts";
+
+/* ──────────── 상수 ──────────── */
+
+const MAX_PASSWD_LEN = 128;
+
+/* ──────────── 타입 ──────────── */
+
+interface ChangePasswordBody {
+    current_password?: string;
+    new_password?: string;
+}
+
+interface AccountRow {
+    seq: number;
+    passwd?: string;
+    has_password?: boolean;
+}
+
+interface PasswordHistoryRow {
+    seq: number;
+    passwd_hash?: string;
+}
+
+/* ──────────── 핸들러 ──────────── */
+
+export async function handleChangePassword(
+    req: FastifyRequest<{ Body: ChangePasswordBody }>,
+    reply: FastifyReply,
+): Promise<void> {
+    // 1. JWT에서 account_seq 추출
+    const accountSeq = getAccountSeqFromJwt(req);
+    if (!accountSeq) {
+        reply.code(401).send(fail("인증이 필요합니다."));
+        return;
+    }
+
+    const body = req.body ?? {};
+    const currentPassword = (body.current_password ?? "").trim();
+    const newPassword = (body.new_password ?? "").trim();
+
+    if (!currentPassword || !newPassword) {
+        reply
+            .code(400)
+            .send(fail("current_password and new_password are required"));
+        return;
+    }
+    if (newPassword.length > MAX_PASSWD_LEN) {
+        reply.code(400).send(fail("Password is too long"));
+        return;
+    }
+    if (currentPassword === newPassword) {
+        reply
+            .code(400)
+            .send(fail("New password must be different from current password"));
+        return;
+    }
+
+    // 2. account 조회
+    let account: AccountRow;
+    try {
+        const res = await entityServer.get<AccountRow>("account", accountSeq);
+        if (!res?.data) {
+            reply.code(404).send(fail("Account not found"));
+            return;
+        }
+        account = res.data;
+    } catch {
+        reply.code(404).send(fail("Account not found"));
+        return;
+    }
+
+    // 비밀번호가 설정되지 않은 계정 (소셜 전용)
+    if (!account.has_password || !account.passwd) {
+        reply
+            .code(400)
+            .send(
+                fail("This account has no password set (social-only account)"),
+            );
+        return;
+    }
+
+    // 3. 현재 비밀번호 검증
+    if (!verifyPassword(currentPassword, account.passwd)) {
+        reply.code(401).send(fail("Current password is incorrect"));
+        return;
+    }
+
+    // 4. 비밀번호 정책 검증 (복잡도)
+    const policyError = validatePassword(newPassword);
+    if (policyError) {
+        reply.code(400).send(fail(policyError));
+        return;
+    }
+
+    // 5. 이전 비밀번호 재사용 검사
+    const reused = await checkPasswordHistory(accountSeq, newPassword);
+    if (reused) {
+        reply.code(400).send(fail("Cannot reuse a recent password"));
+        return;
+    }
+
+    // 6. 비밀번호 해싱 및 account 업데이트
+    const newHash = hashPassword(newPassword);
+    const now = new Date()
+        .toISOString()
+        .replace("T", " ")
+        .replace(/\.\d+Z$/, "");
+
+    try {
+        await entityServer.submit("account", {
+            seq: accountSeq,
+            passwd: newHash,
+            passwd_changed_time: now,
+            force_password_change: false,
+            passwd_expiry_warned_days: 0,
+        });
+    } catch (err) {
+        logger.error(
+            { err, accountSeq },
+            "handleChangePassword: failed to update account",
+        );
+        reply.code(500).send(fail("Failed to update password"));
+        return;
+    }
+
+    // 7. 이력 저장 (실패해도 변경 자체는 성공)
+    await savePasswordHistory(accountSeq, newHash).catch((err) =>
+        logger.warn(
+            { err, accountSeq },
+            "handleChangePassword: failed to save password history",
+        ),
+    );
+
+    logger.info({ accountSeq }, "Password changed");
+    reply.send(ok({ message: "Password changed successfully" }));
+}
+
+/* ──────────── 이력 헬퍼 ──────────── */
+
+/**
+ * password_history 엔티티에서 최근 이력을 조회해 새 비밀번호 재사용 여부를 반환한다.
+ */
+async function checkPasswordHistory(
+    accountSeq: number,
+    newPassword: string,
+): Promise<boolean> {
+    try {
+        const res = await entityServer.list<PasswordHistoryRow>(
+            "password_history",
+            {
+                conditions: { account_seq: accountSeq },
+                limit: 10,
+                page: 1,
+            },
+        );
+        const items: PasswordHistoryRow[] = res?.data?.items ?? [];
+        for (const item of items) {
+            if (
+                item.passwd_hash &&
+                verifyPassword(newPassword, item.passwd_hash)
+            ) {
+                return true;
+            }
+        }
+    } catch {
+        // password_history 엔티티가 없거나 조회 실패 시 검사 건너뜀
+    }
+    return false;
+}
+
+/**
+ * 변경된 비밀번호 해시를 password_history 엔티티에 저장한다.
+ */
+async function savePasswordHistory(
+    accountSeq: number,
+    passwdHash: string,
+): Promise<void> {
+    await entityServer.submit("password_history", {
+        account_seq: accountSeq,
+        passwd_hash: passwdHash,
+    });
+}

package/src/app/routes/account/change-password/routes.ts

@@ -0,0 +1,28 @@
+/**
+ * 비밀번호 변경(Change Password) 라우트 서브 플러그인
+ *
+ * `routes/account/routes.ts`에서 prefix `/change-password`로 등록된다.
+ * 최종 엔드포인트: POST /api/v1/account/change-password
+ *
+ * JWT 인증이 필요한 보호 라우트.
+ */
+
+import type { FastifyInstance } from "fastify";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger } from "@gateway/api";
+import { ensurePluginEntities } from "@gateway/api";
+import { handleChangePassword } from "./handlers.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default async function changePasswordPlugin(
+    app: FastifyInstance,
+): Promise<void> {
+    await ensurePluginEntities(__dirname).catch((err) =>
+        logger.warn({ err }, "change-password: ensureEntities failed"),
+    );
+
+    // POST /api/v1/account/change-password  (JWT 필요)
+    app.post("/", handleChangePassword);
+}

package/src/app/routes/account/config.json

@@ -0,0 +1,5 @@
+{
+    "enabled": true,
+    "deploy": true,
+    "minify": false
+}