create-entity-server 0.0.9

package/template/samples/kotlin/EntityServerClient.kt

@@ -0,0 +1,194 @@
+/**
+ * Entity Server 클라이언트 (Kotlin / Android)
+ *
+ * 의존성 (build.gradle):
+ *   implementation("org.bouncycastle:bcprov-jdk18on:1.80")
+ *
+ * 환경 설정:
+ *   val client = EntityServerClient(
+ *       baseUrl    = "http://your-server:47200",
+ *       apiKey     = BuildConfig.ENTITY_API_KEY,
+ *       hmacSecret = BuildConfig.ENTITY_HMAC_SECRET,
+ *       magicLen   = 4   // 서버 packet_magic_len 과 동일
+ *   )
+ *
+ * 트랜잭션 사용 예:
+ *   es.transStart()
+ *   try {
+ *     val orderRef  = es.submit("order", JSONObject(mapOf("user_seq" to 1, "total" to 9900))) // seq: "\$tx.0"
+ *     es.submit("order_item", JSONObject(mapOf("order_seq" to orderRef.getString("seq"), "item_seq" to 5))) // "\$tx.0" 자동 치환
+ *     val result    = es.transCommit()
+ *     val orderSeq  = (result.getJSONArray("results")).getJSONObject(0).getLong("seq") // 실제 seq
+ *   } catch (e: Exception) {
+ *     es.transRollback()
+ *   }
+ */
+
+package com.example.entityserver
+
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import org.bouncycastle.crypto.engines.ChaCha7539Engine
+import org.bouncycastle.crypto.modes.ChaChaEngine
+import org.bouncycastle.crypto.params.KeyParameter
+import org.bouncycastle.crypto.params.ParametersWithIV
+import org.json.JSONArray
+import org.json.JSONObject
+import java.security.MessageDigest
+import java.util.UUID
+import javax.crypto.Mac
+import javax.crypto.spec.SecretKeySpec
+
+class EntityServerClient(
+    private val baseUrl: String = "http://localhost:47200",
+    private val apiKey: String = "",
+    private val hmacSecret: String = "",
+    private val magicLen: Int = 4,
+) {
+    private val http = OkHttpClient()
+    private var activeTxId: String? = null
+
+    // ─── CRUD ─────────────────────────────────────────────────────────
+
+    fun get(entity: String, seq: Long): JSONObject =
+        request("GET", "/v1/entity/$entity/$seq")
+
+    fun list(entity: String, page: Int = 1, limit: Int = 20): JSONObject =
+        request("GET", "/v1/entity/$entity/list?page=$page&limit=$limit")
+
+    fun count(entity: String): JSONObject =
+        request("GET", "/v1/entity/$entity/count")
+
+    fun query(entity: String, filter: JSONArray, page: Int = 1, limit: Int = 20): JSONObject =
+        request("POST", "/v1/entity/$entity/query?page=$page&limit=$limit", filter.toString())
+
+    /**
+     * 트랜잭션 시작 — 서버에 큐를 등록하고 txId 를 저장합니다.
+     * 이후 submit / delete 가 실제 실행되지 않고 서버 큐에 쌓입니다.
+     * transCommit() 시 한 번에 DB 트랜잭션으로 실행됩니다.
+     */
+    fun transStart(): String {
+        val res = request("POST", "/v1/transaction/start")
+        activeTxId = res.getString("transaction_id")
+        return activeTxId!!
+    }
+
+    /**
+     * 트랜잭션 전체 롤백
+     * transactionId 생략 시 transStart() 로 시작한 활성 트랜잭션을 롤백합니다.
+     */
+    fun transRollback(transactionId: String? = null): JSONObject {
+        val txId = transactionId ?: activeTxId
+            ?: error("No active transaction. Call transStart() first.")
+        activeTxId = null
+        return request("POST", "/v1/transaction/rollback/$txId")
+    }
+
+    /**
+     * 트랜잭션 커밋 — 큐에 쌓인 모든 작업을 단일 DB 트랜잭션으로 일괄 실행합니다.
+     * transactionId 생략 시 transStart() 로 시작한 활성 트랜잭션을 커밋합니다.
+     */
+    fun transCommit(transactionId: String? = null): JSONObject {
+        val txId = transactionId ?: activeTxId
+            ?: error("No active transaction. Call transStart() first.")
+        activeTxId = null
+        return request("POST", "/v1/transaction/commit/$txId")
+    }
+
+    /** 생성 또는 수정 (seq 포함시 수정, 없으면 생성) */
+    fun submit(entity: String, data: JSONObject, transactionId: String? = null): JSONObject {
+        val txId = transactionId ?: activeTxId
+        val extra = if (txId != null) mapOf("X-Transaction-ID" to txId) else emptyMap()
+        return request("POST", "/v1/entity/$entity/submit", data.toString(), extra)
+    }
+
+    /** 삭제 */
+    fun delete(entity: String, seq: Long, transactionId: String? = null, hard: Boolean = false): JSONObject {
+        val q = if (hard) "?hard=true" else ""
+        val txId = transactionId ?: activeTxId
+        val extra = if (txId != null) mapOf("X-Transaction-ID" to txId) else emptyMap()
+        return request("DELETE", "/v1/entity/$entity/delete/$seq$q", extraHeaders = extra)
+    }
+
+    fun history(entity: String, seq: Long, page: Int = 1, limit: Int = 50): JSONObject =
+        request("GET", "/v1/entity/$entity/history/$seq?page=$page&limit=$limit")
+
+    fun rollback(entity: String, historySeq: Long): JSONObject =
+        request("POST", "/v1/entity/$entity/rollback/$historySeq")
+
+    // ─── 내부 ─────────────────────────────────────────────────────────
+
+    private fun request(method: String, path: String, bodyStr: String = "", extraHeaders: Map<String, String> = emptyMap()): JSONObject {
+        val timestamp = (System.currentTimeMillis() / 1000).toString()
+        val nonce = UUID.randomUUID().toString()
+        val signature = sign(method, path, timestamp, nonce, bodyStr)
+
+        val requestBuilder = Request.Builder()
+            .url(baseUrl.trimEnd('/') + path)
+            .addHeader("Content-Type", "application/json")
+            .addHeader("X-API-Key", apiKey)
+            .addHeader("X-Timestamp", timestamp)
+            .addHeader("X-Nonce", nonce)
+            .addHeader("X-Signature", signature)
+            .apply { extraHeaders.forEach { (k, v) -> addHeader(k, v) } }
+
+        val body = if (bodyStr.isNotEmpty())
+            bodyStr.toRequestBody("application/json".toMediaType())
+        else null
+
+        val req = when (method.uppercase()) {
+            "GET"    -> requestBuilder.get().build()
+            "DELETE" -> requestBuilder.delete(body).build()
+            else     -> requestBuilder.method(method.uppercase(), body).build()
+        }
+
+        val res = http.newCall(req).execute()
+        val contentType = res.header("Content-Type") ?: ""
+        val rawBytes = res.body?.bytes() ?: byteArrayOf()
+
+        // 패킷 암호화 응답: application/octet-stream → 복호화
+        return if (contentType.contains("application/octet-stream")) {
+            JSONObject(decryptPacket(rawBytes))
+        } else {
+            JSONObject(String(rawBytes, Charsets.UTF_8))
+        }
+    }
+
+    /**
+     * XChaCha20-Poly1305 패킷 복호화
+     * 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
+     * 키: sha256(hmac_secret)
+     *
+     * Bouncy Castle XChaCha20-Poly1305 사용
+     */
+    private fun decryptPacket(data: ByteArray): String {
+        val key = sha256(hmacSecret.toByteArray(Charsets.UTF_8))
+
+        val nonce = data.copyOfRange(magicLen, magicLen + 24)
+        val ciphertext = data.copyOfRange(magicLen + 24, data.size)
+
+        // Bouncy Castle: XChaCha20-Poly1305 (AEAD)
+        val aead = org.bouncycastle.crypto.modes.ChaCha20Poly1305()
+        aead.init(false, org.bouncycastle.crypto.params.AEADParameters(
+            KeyParameter(key), 128, nonce
+        ))
+
+        val plaintext = ByteArray(aead.getOutputSize(ciphertext.size))
+        val len = aead.processBytes(ciphertext, 0, ciphertext.size, plaintext, 0)
+        aead.doFinal(plaintext, len)
+        return plaintext.toString(Charsets.UTF_8)
+    }
+
+    /** HMAC-SHA256 서명 */
+    private fun sign(method: String, path: String, timestamp: String, nonce: String, body: String): String {
+        val payload = listOf(method, path, timestamp, nonce, body).joinToString("|")
+        val mac = Mac.getInstance("HmacSHA256")
+        mac.init(SecretKeySpec(hmacSecret.toByteArray(Charsets.UTF_8), "HmacSHA256"))
+        return mac.doFinal(payload.toByteArray(Charsets.UTF_8)).joinToString("") { "%02x".format(it) }
+    }
+
+    private fun sha256(input: ByteArray): ByteArray =
+        MessageDigest.getInstance("SHA-256").digest(input)
+}

package/template/samples/node/package.json

@@ -0,0 +1,16 @@
+{
+    "name": "entity-server-client-sample",
+    "version": "1.0.0",
+    "type": "module",
+    "description": "Entity Server HMAC 클라이언트 샘플 (Node.js)",
+    "scripts": {
+        "example": "node src/example.js"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "dependencies": {
+        "@noble/ciphers": "^1.3.0",
+        "@noble/hashes": "^1.7.2"
+    }
+}

package/template/samples/node/src/EntityServerClient.js

@@ -0,0 +1,246 @@
+/**
+ * Entity Server 클라이언트 (Node.js)
+ *
+ * 의존성: Node.js 18+, @noble/ciphers, @noble/hashes
+ *   npm install @noble/ciphers @noble/hashes
+ *
+ * 환경변수:
+ *   ENTITY_SERVER_URL          http://localhost:47200
+ *   ENTITY_SERVER_API_KEY      your-api-key
+ *   ENTITY_SERVER_HMAC_SECRET  your-hmac-secret
+ *   ENTITY_SERVER_MAGIC_LEN    4  (서버 packet_magic_len 과 동일하게)
+ *
+ * 사용 예:
+ *   const es = new EntityServerClient();
+ *   const list = await es.list('account', { page: 1, limit: 20 });
+ *   const seq  = await es.submit('account', { name: '홍길동' });
+ *
+ * 트랜잭션 사용 예:
+ *   await es.transStart();
+ *   try {
+ *     const orderRef  = await es.submit('order', { ... });         // seq: "$tx.0"
+ *     await es.submit('order_item', { order_seq: orderRef.seq });  // "$tx.0" 자동 치환
+ *     const result = await es.transCommit();
+ *     const orderSeq = result.results[0].seq;  // 실제 seq
+ *   } catch (e) {
+ *     await es.transRollback();
+ *   }
+ */
+
+import { createHmac, randomUUID } from "crypto";
+import { xchacha20_poly1305 } from "@noble/ciphers/chacha";
+import { sha256 } from "@noble/hashes/sha2";
+
+export class EntityServerClient {
+    #baseUrl;
+    #apiKey;
+    #hmacSecret;
+    #magicLen;
+    #activeTxId = null;
+
+    constructor({
+        baseUrl = process.env.ENTITY_SERVER_URL ?? "http://localhost:47200",
+        apiKey = process.env.ENTITY_SERVER_API_KEY ?? "",
+        hmacSecret = process.env.ENTITY_SERVER_HMAC_SECRET ?? "",
+        magicLen = Number(process.env.ENTITY_SERVER_MAGIC_LEN ?? "4"),
+    } = {}) {
+        this.#baseUrl = baseUrl.replace(/\/$/, "");
+        this.#apiKey = apiKey;
+        this.#hmacSecret = hmacSecret;
+        this.#magicLen = magicLen > 0 ? magicLen : 4;
+    }
+
+    // ─── 트랜잭션 ─────────────────────────────────────────────────────────────
+
+    /**
+     * 트랜잭션 시작 — 서버에 트랜잭션 큐를 등록하고 transaction_id 를 반환합니다.
+     * 이후 submit / delete 가 서버 큐에 쌓이고 transCommit() 시 일괄 처리됩니다.
+     * @returns {Promise<string>} transaction_id
+     */
+    async transStart() {
+        const res = await this.#request("POST", "/v1/transaction/start");
+        this.#activeTxId = res.transaction_id;
+        return this.#activeTxId;
+    }
+
+    /**
+     * 트랜잭션 단위로 변경사항을 롤백합니다.
+     * @param {string} [transactionId]  생략 시 transStart() 로 시작한 활성 트랜잭션 사용
+     */
+    transRollback(transactionId) {
+        const txId = transactionId ?? this.#activeTxId;
+        if (!txId)
+            throw new Error("No active transaction. Call transStart() first.");
+        this.#activeTxId = null;
+        return this.#request("POST", `/v1/transaction/rollback/${txId}`);
+    }
+
+    /**
+     * 트랜잭션 커밋 — 서버 큐에 쌓인 작업들을 단일 DB 트랜잭션으로 일괄 처리합니다.
+     * @param {string} [transactionId]  생략 시 transStart() 로 시작한 활성 트랜잭션 사용
+     */
+    transCommit(transactionId) {
+        const txId = transactionId ?? this.#activeTxId;
+        if (!txId)
+            throw new Error("No active transaction. Call transStart() first.");
+        this.#activeTxId = null;
+        return this.#request("POST", `/v1/transaction/commit/${txId}`);
+    }
+
+    // ─── CRUD ────────────────────────────────────────────────────────────────
+
+    /** 단건 조회 */
+    get(entity, seq) {
+        return this.#request("GET", `/v1/entity/${entity}/${seq}`);
+    }
+
+    /** 목록 조회 */
+    list(entity, { page = 1, limit = 20, orderBy } = {}) {
+        const q = new URLSearchParams({
+            page,
+            limit,
+            ...(orderBy && { order_by: orderBy }),
+        });
+        return this.#request("GET", `/v1/entity/${entity}/list?${q}`);
+    }
+
+    /** 건수 조회 */
+    count(entity) {
+        return this.#request("GET", `/v1/entity/${entity}/count`);
+    }
+
+    /**
+     * 필터 검색
+     * @param {Array}  filter  예: [{ field: 'status', op: 'eq', value: 'active' }]
+     * @param {Object} params  예: { page: 1, limit: 20, orderBy: 'name' }
+     */
+    query(entity, filter = [], { page = 1, limit = 20, orderBy } = {}) {
+        const q = new URLSearchParams({
+            page,
+            limit,
+            ...(orderBy && { order_by: orderBy }),
+        });
+        return this.#request("POST", `/v1/entity/${entity}/query?${q}`, filter);
+    }
+
+    /**
+     * 생성 또는 수정
+     * body에 seq 포함 시 수정, 없으면 생성
+     * @param {string} entity
+     * @param {Object} data
+     * @param {Object} [opts]
+     * @param {string} [opts.transactionId]  transStart() 가 반환한 ID (생략 시 활성 트랜잭션 자동 사용)
+     */
+    submit(entity, data, { transactionId } = {}) {
+        const txId = transactionId ?? this.#activeTxId;
+        const extra = txId ? { "X-Transaction-ID": txId } : {};
+        return this.#request(
+            "POST",
+            `/v1/entity/${entity}/submit`,
+            data,
+            extra,
+        );
+    }
+
+    /**
+     * 삭제
+     * @param {string} entity
+     * @param {number} seq
+     * @param {Object} [opts]
+     * @param {string} [opts.transactionId]  transStart() 가 반환한 ID (생략 시 활성 트랜잭션 자동 사용)
+     * @param {boolean} [opts.hard]           하드 삭제 여부 (기본 false)
+     */
+    delete(entity, seq, { transactionId, hard = false } = {}) {
+        const q = hard ? "?hard=true" : "";
+        const txId = transactionId ?? this.#activeTxId;
+        const extra = txId ? { "X-Transaction-ID": txId } : {};
+        return this.#request(
+            "DELETE",
+            `/v1/entity/${entity}/delete/${seq}${q}`,
+            null,
+            extra,
+        );
+    }
+
+    /** 변경 이력 조회 */
+    history(entity, seq, { page = 1, limit = 50 } = {}) {
+        return this.#request(
+            "GET",
+            `/v1/entity/${entity}/history/${seq}?page=${page}&limit=${limit}`,
+        );
+    }
+
+    /** history seq 단위 롤백 (단건) */
+    rollback(entity, historySeq) {
+        return this.#request(
+            "POST",
+            `/v1/entity/${entity}/rollback/${historySeq}`,
+        );
+    }
+
+    // ─── 내부 ─────────────────────────────────────────────────────────────────
+
+    async #request(method, path, body, extraHeaders = {}) {
+        const bodyStr = body != null ? JSON.stringify(body) : "";
+        const timestamp = String(Math.floor(Date.now() / 1000));
+        const nonce = randomUUID();
+        const signature = this.#sign(method, path, timestamp, nonce, bodyStr);
+
+        const headers = {
+            "Content-Type": "application/json",
+            "X-API-Key": this.#apiKey,
+            "X-Timestamp": timestamp,
+            "X-Nonce": nonce,
+            "X-Signature": signature,
+            ...extraHeaders,
+        };
+
+        const res = await fetch(this.#baseUrl + path, {
+            method,
+            headers,
+            ...(bodyStr ? { body: bodyStr } : {}),
+        });
+
+        const contentType = res.headers.get("Content-Type") ?? "";
+
+        // 패킷 암호화 응답: application/octet-stream → 복호화
+        if (contentType.includes("application/octet-stream")) {
+            const buffer = await res.arrayBuffer();
+            return this.#decryptPacket(buffer);
+        }
+
+        const data = await res.json();
+
+        if (!data.ok) {
+            throw new Error(
+                `EntityServer error: ${data.message ?? "Unknown"} (HTTP ${res.status})`,
+            );
+        }
+        return data;
+    }
+
+    /**
+     * XChaCha20-Poly1305 패킷 복호화
+     * 포맷: [magic:magicLen][nonce:24][ciphertext+tag]
+     * 키: sha256(hmac_secret)
+     */
+    #decryptPacket(buffer) {
+        const key = sha256(new TextEncoder().encode(this.#hmacSecret));
+        const data = new Uint8Array(buffer);
+        const nonce = data.slice(this.#magicLen, this.#magicLen + 24);
+        const ciphertext = data.slice(this.#magicLen + 24);
+        const cipher = xchacha20_poly1305(key, nonce);
+        const plaintext = cipher.decrypt(ciphertext);
+        return JSON.parse(new TextDecoder().decode(plaintext));
+    }
+
+    /** HMAC-SHA256 서명 */
+    #sign(method, path, timestamp, nonce, body) {
+        const payload = [method, path, timestamp, nonce, body].join("|");
+        return createHmac("sha256", this.#hmacSecret)
+            .update(payload)
+            .digest("hex");
+    }
+}
+
+export default EntityServerClient;

package/template/samples/node/src/example.js

@@ -0,0 +1,39 @@
+import { EntityServerClient } from "./EntityServerClient.js";
+
+const es = new EntityServerClient({
+    baseUrl: process.env.ENTITY_SERVER_URL ?? "http://localhost:47200",
+    apiKey: process.env.ENTITY_SERVER_API_KEY ?? "mykey",
+    hmacSecret: process.env.ENTITY_SERVER_HMAC_SECRET ?? "mysecret",
+});
+
+// 목록 조회
+const list = await es.list("product", { page: 1, limit: 10 });
+console.log("List:", list.data?.length, "items");
+
+// 생성
+const created = await es.submit("product", {
+    name: "무선 키보드",
+    price: 89000,
+    category: "peripherals",
+});
+console.log("Created seq:", created.seq);
+
+// 수정 (seq 포함)
+await es.submit("product", { seq: created.seq, price: 79000 });
+console.log("Updated");
+
+// 필터 검색
+const results = await es.query(
+    "product",
+    [{ field: "category", op: "eq", value: "peripherals" }],
+    { page: 1, limit: 5 },
+);
+console.log("Query results:", results.data?.length);
+
+// 이력 조회
+const hist = await es.history("product", created.seq);
+console.log("History count:", hist.data?.length);
+
+// 삭제
+await es.delete("product", created.seq);
+console.log("Deleted");

package/template/samples/php/ci4/Controllers/ProductController.php

@@ -0,0 +1,141 @@
+<?php
+
+namespace App\Controllers;
+
+use App\Controllers\BaseController;
+use App\Libraries\EntityServer;
+
+/**
+ * EntityServer 라이브러리를 사용하는 CI4 컨트롤러 예시
+ */
+class ProductController extends BaseController
+{
+    private EntityServer $es;
+
+    public function __construct()
+    {
+        $this->es = new EntityServer();
+    }
+
+    /** GET /products */
+    public function index(): string
+    {
+        $page   = (int) ($this->request->getGet('page')  ?? 1);
+        $limit  = (int) ($this->request->getGet('limit') ?? 20);
+        $result = $this->es->list('product', ['page' => $page, 'limit' => $limit]);
+
+        return $this->response->setJSON($result)->getBody();
+    }
+
+    /** GET /products/(:num) */
+    public function show(int $seq): string
+    {
+        $result = $this->es->get('product', $seq);
+        return $this->response->setJSON($result)->getBody();
+    }
+
+    /** POST /products/search */
+    public function search(): string
+    {
+        $body   = $this->request->getJSON(true);
+        $filter = $body['filter'] ?? [];
+        $params = ['page' => $body['page'] ?? 1, 'limit' => $body['limit'] ?? 20];
+
+        // 필터 예: [['field' => 'category', 'op' => 'eq', 'value' => 'electronics']]
+        $result = $this->es->query('product', $filter, $params);
+        return $this->response->setJSON($result)->getBody();
+    }
+
+    /** POST /products */
+    public function create(): string
+    {
+        $data   = $this->request->getJSON(true);
+        // seq 없이 submit → 생성
+        $result = $this->es->submit('product', $data);
+        return $this->response->setStatusCode(201)->setJSON($result)->getBody();
+    }
+
+    /** PUT /products/(:num) */
+    public function update(int $seq): string
+    {
+        $data        = $this->request->getJSON(true);
+        $data['seq'] = $seq; // seq 포함 → 수정
+        $result      = $this->es->submit('product', $data);
+        return $this->response->setJSON($result)->getBody();
+    }
+
+    /** DELETE /products/(:num) */
+    public function delete(int $seq): string
+    {
+        $result = $this->es->delete('product', $seq);
+        return $this->response->setJSON($result)->getBody();
+    }
+
+    /** GET /products/(:num)/history */
+    public function history(int $seq): string
+    {
+        $result = $this->es->history('product', $seq);
+        return $this->response->setJSON($result)->getBody();
+    }
+
+    /**
+     * POST /products/order
+     *
+     * 트랜잭션 예시: 상품 재고 차감 + 주문 생성을 하나의 DB 트랜잭션으로 처리.
+     * submit 요청은 서버 큐에 쌓이고 transCommit() 시 단일 DB 트랜잭션으로 일괄 커밋됩니다.
+     * 실패 시 transRollback() 으로 큐를 버립니다.
+     *
+     * 요청 body 예:
+     *   { "product_seq": 5, "qty": 2, "buyer": "홍길동" }
+     */
+    public function order(): string
+    {
+        $body        = $this->request->getJSON(true);
+        $productSeq  = (int) ($body['product_seq'] ?? 0);
+        $qty         = (int) ($body['qty']         ?? 1);
+        $buyer       = $body['buyer'] ?? '';
+
+        if (!$productSeq) {
+            return $this->response->setStatusCode(400)
+                ->setJSON(['ok' => false, 'message' => 'product_seq required'])
+                ->getBody();
+        }
+
+        $this->es->transStart(); // 서버 큐 등록, 이후 submit / delete 시 큐에씀임
+
+        try {
+            // 1) 상품 조회 후 재고 차감
+            $product = $this->es->get('product', $productSeq);
+            $stock   = (int) ($product['data']['stock'] ?? 0);
+            if ($stock < $qty) {
+                throw new \RuntimeException('재고 부족');
+            }
+            $this->es->submit('product', [
+                'seq'   => $productSeq,
+                'stock' => $stock - $qty,
+            ]);
+
+            // 2) 주문 생성
+            $this->es->submit('order', [
+                'product_seq' => $productSeq,
+                'qty'         => $qty,
+                'buyer'       => $buyer,
+                'status'      => 'pending',
+            ]);
+
+            // 3) 단일 DB 트랜잭션으로 일괄 커밋
+            //    results[0] = product update, results[1] = order insert
+            $commitResult = $this->es->transCommit();
+            $orderSeq = $commitResult['results'][1]['seq'] ?? null;
+
+            return $this->response->setStatusCode(201)
+                ->setJSON(['ok' => true, 'order_seq' => $orderSeq])
+                ->getBody();
+        } catch (\Throwable $e) {
+            $this->es->transRollback(); // 큐 버림 (아직 커밋 안 된 경우) 또는 saga 롤백
+            return $this->response->setStatusCode(500)
+                ->setJSON(['ok' => false, 'message' => $e->getMessage()])
+                ->getBody();
+        }
+    }
+}