create-entity-app-server 0.0.3

package/docs/routes/tax-invoice-routes.md

@@ -0,0 +1,109 @@
+# Tax Invoice Routes
+
+기준 파일: `src/app/plugins/taxinvoice/routes.ts`
+
+이 문서는 실제 API 호출 중심(라우트표/사용 예제/응답 예제)을 다룹니다.  
+플러그인의 개요/설정/운영 가이드는 [Tax Invoice Guide](../../plugins/taxinvoice.md) 문서를 참고하세요.
+
+## 라우트 목록
+
+| Method | Path                                                             | 설명                              |
+| ------ | ---------------------------------------------------------------- | --------------------------------- |
+| POST   | [/api/v1/taxinvoice](#post-v1apitaxinvoice)                      | 세금계산서 등록/발행 요청(레거시) |
+| POST   | [/api/v1/taxinvoice/register](#post-v1apitaxinvoiceregister)     | 세금계산서 등록                   |
+| POST   | [/api/v1/taxinvoice/:seq/issue](#post-v1apitaxinvoiceseqissue)   | 등록 건 발행                      |
+| POST   | [/api/v1/taxinvoice/:seq/cancel](#post-v1apitaxinvoiceseqcancel) | 발행 취소                         |
+| GET    | [/api/v1/taxinvoice/:seq/state](#get-v1apitaxinvoiceseqstate)    | 발행 상태 조회                    |
+| GET    | [/api/v1/taxinvoice/:seq](#get-v1apitaxinvoiceseq)               | 상세 조회                         |
+
+## 라우트 상세
+
+### POST /api/v1/taxinvoice
+
+<a id="post-v1apitaxinvoice"></a>
+
+- 설명: 세금계산서 등록 및 발행 플로우를 단일 요청으로 처리한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/taxinvoice" \
+	-H "Content-Type: application/json" \
+	-d '{"supplier":{"corpNo":"1234567890"},"buyer":{"corpNo":"0987654321"}}'
+```
+
+### POST /api/v1/taxinvoice/register
+
+<a id="post-v1apitaxinvoiceregister"></a>
+
+- 설명: 발행 전 단계로 세금계산서 데이터를 등록한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/taxinvoice/register" \
+	-H "Content-Type: application/json" \
+	-d '{"writeDate":"2026-03-04","amount":110000}'
+```
+
+### POST /api/v1/taxinvoice/:seq/issue
+
+<a id="post-v1apitaxinvoiceseqissue"></a>
+
+- 설명: 등록된 문서(`seq`)를 실제 발행한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/taxinvoice/1001/issue"
+```
+
+### POST /api/v1/taxinvoice/:seq/cancel
+
+<a id="post-v1apitaxinvoiceseqcancel"></a>
+
+- 설명: 이미 발행된 세금계산서를 취소한다.
+- 사용 예제:
+
+```bash
+curl -X POST "http://localhost:3000/api/v1/taxinvoice/1001/cancel" \
+	-H "Content-Type: application/json" \
+	-d '{"reason":"오발행 정정"}'
+```
+
+### GET /api/v1/taxinvoice/:seq/state
+
+<a id="get-v1apitaxinvoiceseqstate"></a>
+
+- 설명: 발행 진행 상태(접수/성공/실패 등)를 조회한다.
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/taxinvoice/1001/state"
+```
+
+### GET /api/v1/taxinvoice/:seq
+
+<a id="get-v1apitaxinvoiceseq"></a>
+
+- 설명: 세금계산서 상세 데이터와 처리 결과를 조회한다.
+- 사용 예제:
+
+```bash
+curl "http://localhost:3000/api/v1/taxinvoice/1001"
+```
+
+## 관련 문서
+
+- [Account Routes](./account-routes.md)
+- [Alimtalk Routes](./alimtalk-routes.md)
+- [Email Verification](./email-verification.md)
+- [Friendtalk Routes](./friendtalk-routes.md)
+- [Holidays Routes](./holidays-routes.md)
+- [Identity Routes](./identity-routes.md)
+- [LLM Routes](./llm-routes.md)
+- [OCR Routes](./ocr-routes.md)
+- [Password Reset](./password-reset.md)
+- [PG Routes](./pg-routes.md)
+- [SMS Routes](./sms-routes.md)
+- [SMTP Routes](./smtp-routes.md)
+- [라우트 추가 가이드](./how-to-create.md)
+- [Push Routes](./push-routes.md)
+- [← 전체 목록](./README.md)

package/docs/schedules/dormancy-and-retention.md

@@ -0,0 +1,160 @@
+# 휴면 정책 스케줄러 (Dormancy)
+
+> **위치**: `app/schedules/dormancy/`  
+> **유형**: 크론 스케줄 (기본 매일 02:00)  
+> **분산 락**: `privacy_cron_lock` 엔티티 (job: `privacy:dormancy`)
+
+---
+
+## 개요
+
+장기 미접속 계정에 경고 이메일을 발송하고, 설정된 기간이 지나면 자동으로
+휴면 상태(`dormant`)로 전환하는 배치 스케줄러입니다.
+
+Go 엔티티서버의 `internal/privacy/service.go` (`dormancyLoop` /
+`runDormancyCycle`)에서 게이트웨이로 이관되었습니다.
+
+---
+
+## 동작 흐름
+
+```
+매일 02:00 (cron)
+  ├─ 분산 락 획득 (privacy:dormancy, slot = now/86400)
+  │
+  ├─ active 계정 페이징 조회 (500건씩)
+  │    ├─ admin 건너뛰기 (rbac_role == "admin")
+  │    ├─ resolveLastActivityTime: last_login_time → updated_time → created_time
+  │    │
+  │    ├─ [A] 마지막 활동 < cutoff (now - dormancy_days)
+  │    │    ├─ status = "dormant" 전환
+  │    │    └─ (send_completed_email = true 이면) 휴면 완료 안내 이메일 발송
+  │    │
+  │    └─ [B] 경고 이메일
+  │         ├─ warningDays [30, 7] 내림차순 대조
+  │         ├─ daysUntilDormancy ≤ warnDay AND lastWarned ≠ warnDay
+  │         ├─ dormancy_warned_days 업데이트 (중복 방지)
+  │         └─ 이메일 발송
+  │
+  └─ 분산 락 해제
+```
+
+---
+
+## 설정 (`config.json`)
+
+| 필드                       | 타입     | 기본값                         | 설명                                     |
+| -------------------------- | -------- | ------------------------------ | ---------------------------------------- |
+| `enabled`                  | boolean  | `false`                        | 스케줄러 활성화 여부                     |
+| `dormancy_days`            | number   | `365`                          | 휴면 전환 기준 일수 (마지막 활동 기준)   |
+| `warning_days`             | number[] | `[30, 7]`                      | 경고 발송 기준 일수 (휴면까지 남은 일수) |
+| `cron`                     | string   | `"0 2 * * *"`                  | 크론 표현식                              |
+| `email_subject`            | string   | `"계정 휴면 예정 안내"`        | 경고 이메일 제목 접두어                  |
+| `email_template`           | string   | `"account/dormancy_warning"`   | 경고 이메일 템플릿 경로                  |
+| `login_url`                | string   | `""`                           | 로그인 페이지 URL (템플릿 변수)          |
+| `send_completed_email`     | boolean  | `false`                        | 휴면 전환 완료 시 안내 이메일 발송 여부  |
+| `completed_email_subject`  | string   | `"계정이 휴면 처리되었습니다"` | 완료 이메일 제목                         |
+| `completed_email_template` | string   | `"account/dormancy_completed"` | 완료 이메일 템플릿 경로                  |
+
+---
+
+## 이메일 템플릿
+
+### 경고 이메일: `templates/email/account/dormancy_warning.html`
+
+| 변수           | 설명               |
+| -------------- | ------------------ |
+| `${email}`     | 사용자 이메일      |
+| `${days_left}` | 휴면까지 남은 일수 |
+| `${login_url}` | 로그인 페이지 URL  |
+
+### 완료 이메일: `templates/email/account/dormancy_completed.html`
+
+`send_completed_email = true` 일 때 계정이 실제로 휴면 전환된 직후 발송된다.
+
+| 변수           | 설명              |
+| -------------- | ----------------- |
+| `${email}`     | 사용자 이메일     |
+| `${login_url}` | 로그인 페이지 URL |
+
+---
+
+# 데이터 보유기간 스케줄러 (Data Retention)
+
+> **위치**: `app/schedules/data-retention/`  
+> **유형**: 크론 스케줄 (기본 매일 02:30)  
+> **분산 락**: `privacy_cron_lock` 엔티티 (job: `privacy:retention`)
+
+---
+
+## 개요
+
+휴면(`dormant`) 상태로 전환된 후 보유기간(`retention_days`)이 경과한 계정을
+자동으로 익명화 또는 삭제하는 배치 스케줄러입니다.
+
+---
+
+## 동작 흐름
+
+```
+매일 02:30 (cron)
+  ├─ 분산 락 획득 (privacy:retention)
+  │
+  ├─ dormant 계정 페이징 조회 (500건씩)
+  │    ├─ updated_time (= 휴면 전환 시점) + retention_days < 현재 시각
+  │    │
+  │    ├─ action == "delete"
+  │    │    └─ hard delete (account)
+  │    │
+  │    └─ action == "anonymize" (기본)
+  │         ├─ email → "withdrawn_{seq}@anonymized.local"
+  │         ├─ status → "inactive"
+  │         └─ passwd → ""
+  │
+  │    └─ 후처리 (공통)
+  │         ├─ account_oauth 레코드 삭제
+  │         ├─ user 엔티티 익명화 (name → "탈퇴회원_{user.seq}")
+  │         └─ password_history 삭제
+  │
+  └─ 분산 락 해제
+```
+
+---
+
+## 설정 (`config.json`)
+
+| 필드             | 타입    | 기본값         | 설명                                 |
+| ---------------- | ------- | -------------- | ------------------------------------ |
+| `enabled`        | boolean | `false`        | 스케줄러 활성화 여부                 |
+| `retention_days` | number  | `1095`         | 보유기간 (일, 기본 약 3년)           |
+| `action`         | string  | `"anonymize"`  | 처리 방식: `anonymize` 또는 `delete` |
+| `cron`           | string  | `"30 2 * * *"` | 크론 표현식                          |
+
+---
+
+## 관련 엔티티
+
+| 엔티티             | 용도                                   |
+| ------------------ | -------------------------------------- |
+| `account`          | 대상 계정 (status: dormant → inactive) |
+| `account_oauth`    | OAuth 연동 레코드 (삭제)               |
+| `user`             | 사용자 프로필 (익명화)                 |
+| `password_history` | 비밀번호 이력 (삭제)                   |
+
+---
+
+## Go 서버와의 차이점
+
+| 항목          | Go 서버                  | Gateway (TS)               |
+| ------------- | ------------------------ | -------------------------- |
+| 스케줄링      | ticker 기반              | croner 기반 고정 시각 cron |
+| 설정          | `privacy_policy.json`    | 스케줄 전용 `config.json`  |
+| login_url     | 미전달 (템플릿 기본값 #) | 설정 가능                  |
+| email_subject | 하드코딩                 | 설정 가능                  |
+| 에러 처리     | panic 시 락 미해제       | `try/finally` 락 해제 보장 |
+
+---
+
+## 관련 문서
+
+- [스케줄 추가 가이드](how-to-create.md)

package/docs/schedules/how-to-create.md

@@ -0,0 +1,255 @@
+# 스케줄 추가 가이드
+
+`dormancy`는 `app/schedules`에 새 스케줄을 추가할 때의 기준 샘플이다.
+
+기준 파일: `src/app/schedules/dormancy/index.ts`
+
+---
+
+## 1) 폴더 구조
+
+`{name}`은 새 스케줄 이름이다 (예: `subscription-reminder`, `stats-aggregator`).
+
+```text
+src/app/schedules/{name}/
+├── config.json          — 런타임 설정 (Git에서 제외, .gitignore 추가 권장)
+├── config.example.json  — 기본값 예시 (Git에 포함)
+└── index.ts             — 진입점, start() / stop() export 필수
+```
+
+복잡한 배치 로직은 파일을 분리할 수 있다.
+
+```text
+src/app/schedules/{name}/
+├── config.json
+├── config.example.json
+├── index.ts     — 스케줄 등록, start() / stop()
+├── service.ts   — 실제 배치 로직 (페이징 조회, 처리, 이메일 등)
+└── types.ts     — Config 인터페이스, Row 타입
+```
+
+---
+
+## 2) 파일 역할
+
+| 파일                  | 역할                                                         |
+| --------------------- | ------------------------------------------------------------ |
+| `config.json`         | `enabled`, `cron`, 기타 파라미터. 없으면 코드 내 기본값 사용 |
+| `config.example.json` | config.json의 샘플. 코드에서 읽지 않음, 문서용               |
+| `index.ts`            | `start()` / `stop()` 구현. 크론 등록, 락 획득, 배치 호출     |
+| `service.ts` (선택)   | 비즈니스 배치 로직 (entityServer 호출, DB 쿼리, 이메일 등)   |
+| `types.ts` (선택)     | Config 인터페이스, DB Row 타입                               |
+
+---
+
+## 3) `config.json` 규칙
+
+필드는 스케줄마다 자유롭게 정의한다. `enabled`와 `cron` 만 공통 관례이며
+나머지는 비즈니스 요구에 따라 추가한다.
+
+```json
+{
+    "enabled": false,
+    "cron": "0 3 * * *"
+}
+```
+
+`enabled: false` 이면 `start()` 내부에서 즉시 반환해 크론을 등록하지 않는다.  
+`config.json`이 없으면 코드 내 기본값으로 동작한다.
+
+---
+
+## 4) `index.ts` 최소 구현 (dormancy 패턴)
+
+```ts
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createCron, logger, type CronHandle } from "@gateway/api";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+interface MyConfig {
+    enabled: boolean;
+    cron: string;
+    // ...비즈니스 파라미터
+}
+
+function loadConfig(): MyConfig {
+    const configPath = resolve(__dirname, "config.json");
+    let raw: Record<string, unknown> = {};
+    if (existsSync(configPath)) {
+        raw = JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    return {
+        enabled: raw.enabled === true,
+        cron: String(raw.cron || "0 3 * * *"),
+    };
+}
+
+let cronHandle: CronHandle | null = null;
+
+export function start(): void {
+    const cfg = loadConfig();
+    if (!cfg.enabled) {
+        logger.info("{name} scheduler disabled");
+        return;
+    }
+
+    cronHandle = createCron({
+        expression: cfg.cron,
+        onTick: async () => {
+            try {
+                // 배치 로직
+            } catch (err) {
+                logger.error({ err }, "{name} batch failed");
+            }
+        },
+    });
+
+    logger.info(
+        { cron: cfg.cron, next: cronHandle.nextRun },
+        "{name} scheduler started",
+    );
+}
+
+export function stop(): void {
+    cronHandle?.stop();
+    cronHandle = null;
+}
+```
+
+---
+
+## 5) 분산 락 (멀티인스턴스 중복 방지)
+
+여러 인스턴스가 동시에 실행될 수 있는 환경이라면 `acquireLock` / `releaseLock`을
+사용한다. `privacy_cron_lock` 엔티티의 unique constraint를 이용한 슬롯 기반 락이다.
+
+```ts
+import {
+    acquireLock,
+    releaseLock,
+} from "../../../system/scheduler/distributed-lock.ts";
+
+const LOCK_TTL_SEC = 86_400; // 24시간 슬롯 (일 1회 배치)
+
+const execute = async () => {
+    const locked = await acquireLock("my-schedule:job-name", LOCK_TTL_SEC);
+    if (!locked) return; // 다른 인스턴스에서 이미 실행 중
+
+    try {
+        await runBatch(cfg);
+    } catch (err) {
+        logger.error({ err }, "Batch failed");
+    } finally {
+        await releaseLock("my-schedule:job-name", LOCK_TTL_SEC);
+    }
+};
+```
+
+> **락 키 규칙**: `{도메인}:{job-name}` 형태로 지정한다.  
+> 예: `"privacy:password_expiry"`, `"stats:daily"`, `"subscription:reminder"`
+
+단일 인스턴스 환경이거나 중복 실행이 무해한 배치는 락을 생략해도 된다.
+
+---
+
+## 6) 페이징 배치 패턴
+
+대량 데이터를 처리할 때는 페이징으로 처리한다. `entityServer.list()`의 기본 limit은 서버 설정에 따라 다르므로 명시적으로 지정한다.
+
+```ts
+import { entityServer } from "@gateway/api";
+
+async function processBatch(): Promise<number> {
+    let page = 1;
+    const limit = 500;
+    let processed = 0;
+
+    while (true) {
+        const result = await entityServer.list<MyRow>("my_entity", {
+            conditions: { status: "active" },
+            page,
+            limit,
+        });
+
+        const items = result?.data?.items;
+        if (!items || items.length === 0) break;
+
+        for (const item of items) {
+            // 항목별 처리
+            processed++;
+        }
+
+        const total = result?.data?.total ?? 0;
+        if (page * limit >= total) break;
+        page++;
+    }
+
+    return processed;
+}
+```
+
+---
+
+## 7) 이메일 발송
+
+이메일 템플릿을 사용하는 스케줄은 `sendEmail` 과 `setTemplateDir`을 함께 사용한다.
+
+```ts
+import { sendEmail, setTemplateDir } from "@gateway/api";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function ensureTemplateDir(): void {
+    const gatewayRoot = resolve(__dirname, "..", "..", "..", "..");
+    setTemplateDir(join(gatewayRoot, "templates", "email"));
+}
+
+// start() 내에서 호출
+ensureTemplateDir();
+
+// 발송
+await sendEmail({
+    to: [account.email],
+    subject: "제목",
+    templateName: "account/my_template", // templates/email/account/my_template.html
+    templateData: {
+        name: account.name,
+        action_url: "https://example.com/action",
+    },
+});
+```
+
+템플릿 파일 위치: `templates/email/{templateName}.html`
+
+---
+
+## 8) 등록 경로 규칙
+
+`src/app/schedules/{name}/index.ts`에 파일이 있으면 서버 시작 시 자동으로 로드된다.
+
+- `start()` / `stop()` 둘 다 없으면 경고 로그를 남기고 스킵된다.
+- 로드 순서: 알파벳(폴더명) 순.
+- `start()`는 `onReady` 시점에, `stop()`은 `onClose` 시점에 호출된다.
+
+---
+
+## 9) 문서 업데이트 규칙
+
+새 스케줄을 추가하면 다음을 업데이트한다.
+
+1. `docs/schedules/{name}.md` — 스케줄 동작·설정·이메일 템플릿 변수 설명
+2. `src/app/schedules/README.md` 스케줄 목록 테이블에 행 추가
+
+---
+
+## 기존 스케줄 참고
+
+| 스케줄           | 분산 락 | 페이징 | 이메일 | 설명                      |
+| ---------------- | ------- | ------ | ------ | ------------------------- |
+| `dormancy`       | ✓       | ✓      | ✓      | 휴면 전환·경고            |
+| `data-retention` | ✓       | ✓      | ✗      | 데이터 삭제 (이메일 없음) |