init: technical-visualization-haness 하네스 설계

This commit is contained in:
DongHyeonka
2026-07-24 14:02:50 +09:00
parent 09d7c594da
commit f43e909162
117 changed files with 10150 additions and 1 deletions
+28
View File
@@ -0,0 +1,28 @@
# 승인된 결제는 주문 상태 갱신 후 이벤트로 확산된다
## Alternative text
클라이언트 결제 요청이 인증 게이트웨이와 체크아웃 API를 거쳐 PostgreSQL, 결제 제공자, 이벤트 버스로 흐르는 데이터 흐름도.
## Long description
왼쪽에서 오른쪽으로 읽는다. 클라이언트가 HTTPS 결제 요청을 인증 게이트웨이에 보내고, 검증된 요청이 체크아웃 API로 전달된다. 체크아웃 API는 PostgreSQL에 PENDING 주문을 기록하고 결제 제공자 API에 승인을 요청한다. 승인 응답을 받으면 같은 주문을 PAID로 갱신하고 payment.approved 이벤트를 이벤트 버스에 발행한다.
## Elements and evidence
- **클라이언트** (actor): 로그인 세션과 장바구니 식별자를 가지고 결제를 요청한다. Evidence: L7L7, L11L11.
- **인증 게이트웨이** (security): 세션을 검증하고 유효한 요청만 체크아웃 API로 전달한다. Evidence: L7L7, L11L11.
- **체크아웃 API** (service): 주문 상태를 저장하고 결제 승인 및 이벤트 발행을 조정한다. Evidence: L7L7, L11L13.
- **PostgreSQL 주문 저장소** (database): 주문을 PENDING으로 기록하고 승인 후 PAID로 갱신한다. Evidence: L13L13.
- **결제 제공자 API** (service): 체크아웃 API의 결제 승인 요청을 처리하고 승인 응답을 반환한다. Evidence: L13L13.
- **이벤트 버스** (queue): 승인된 결제를 payment.approved 이벤트로 수신한다. Evidence: L13L13.
## Relationships
- **결제 제공자 API → 체크아웃 API:** 승인 응답. Evidence: L13L13.
- **체크아웃 API → 결제 제공자 API:** 승인 요청. Evidence: L13L13.
- **클라이언트 → 인증 게이트웨이:** HTTPS 결제 요청. Evidence: L11L11.
- **체크아웃 API → PostgreSQL 주문 저장소:** PENDING 주문 기록. Evidence: L13L13.
- **체크아웃 API → PostgreSQL 주문 저장소:** PAID 상태 갱신. Evidence: L13L13.
- **체크아웃 API → 이벤트 버스:** payment.approved 발행. Evidence: L13L13.
- **인증 게이트웨이 → 체크아웃 API:** 검증된 요청 전달. Evidence: L11L11.
+28
View File
@@ -0,0 +1,28 @@
# 승인된 결제는 주문 상태 갱신 후 이벤트로 확산된다
# Question: 결제 요청은 어디를 거쳐 저장되고 승인 후 어떤 이벤트를 발행하는가?
direction: right
n0: "클라이언트" {
shape: person
}
n1: "인증 게이트웨이" {
shape: rectangle
}
n2: "체크아웃 API" {
shape: rectangle
}
n3: "PostgreSQL 주문 저장소" {
shape: sql_table
}
n4: "결제 제공자 API" {
shape: rectangle
}
n5: "이벤트 버스" {
shape: queue
}
n0 -> n1: "HTTPS 결제 요청"
n1 -> n2: "검증된 요청 전달"
n2 -> n3: "PENDING 주문 기록"
n2 -> n4: "승인 요청"
n4 -> n2: "승인 응답"
n2 -> n3: "PAID 상태 갱신"
n2 -> n5: "payment.approved 발행" { style.stroke-dash: 4 }
+18
View File
@@ -0,0 +1,18 @@
digraph techviz {
graph [rankdir=LR, splines=ortho, nodesep=0.55, ranksep=0.85, label="승인된 결제는 주문 상태 갱신 후 이벤트로 확산된다", labelloc=t, fontsize=20];
node [fontname=Helvetica, fontsize=11, margin="0.18,0.12", style="rounded,filled", fillcolor=white, color="#2d4357", penwidth=1.5];
edge [fontname=Helvetica, fontsize=10, color="#364b5f", penwidth=1.4, arrowsize=0.75];
n0 [label="클라이언트", shape=box, style="rounded,dashed,filled"];
n1 [label="인증 게이트웨이", shape=box, style="rounded,filled"];
n2 [label="체크아웃 API", shape=box, style="rounded,filled"];
n3 [label="PostgreSQL 주문 저장소", shape=cylinder, style="rounded,filled"];
n4 [label="결제 제공자 API", shape=box, style="rounded,filled"];
n5 [label="이벤트 버스", shape=oval, style="rounded,filled"];
n0 -> n1 [label="HTTPS 결제 요청", style=solid];
n1 -> n2 [label="검증된 요청 전달", style=solid];
n2 -> n3 [label="PENDING 주문 기록", style=solid];
n2 -> n4 [label="승인 요청", style=solid];
n4 -> n2 [label="승인 응답", style=solid];
n2 -> n3 [label="PAID 상태 갱신", style=solid];
n2 -> n5 [label="payment.approved 발행", style=dashed];
}
+64
View File
@@ -0,0 +1,64 @@
<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="app.diagrams.net" modified="2026-07-23T00:00:00.000Z" agent="techviz-harness" version="24.7.17" type="device">
<diagram id="payment-request" name="승인된 결제는 주문 상태 갱신 후 이벤트로 확산된다">
<mxGraphModel dx="1214" dy="587" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1214" pageHeight="1169" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="n_client" value="클라이언트" tooltip="로그인 세션과 장바구니 식별자를 가지고 결제를 요청한다. | Evidence: L7-L7, L11-L11" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;dashed=1;fillColor=#f5f7fa;" vertex="1" parent="1">
<mxGeometry x="70.0" y="281.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="n_auth-gateway" value="인증 게이트웨이" tooltip="세션을 검증하고 유효한 요청만 체크아웃 API로 전달한다. | Evidence: L7-L7, L11-L11" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
<mxGeometry x="380.0" y="281.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="n_checkout-api" value="체크아웃 API" tooltip="주문 상태를 저장하고 결제 승인 및 이벤트 발행을 조정한다. | Evidence: L7-L7, L11-L13" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
<mxGeometry x="690.0" y="281.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="n_event-bus" value="이벤트 버스" tooltip="승인된 결제를 payment.approved 이벤트로 수신한다. | Evidence: L13-L13" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;rounded=1;arcSize=50;fillColor=#f6f1fb;" vertex="1" parent="1">
<mxGeometry x="1002.2" y="145.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="n_orders-db" value="PostgreSQL 주문 저장소" tooltip="주문을 PENDING으로 기록하고 승인 후 PAID로 갱신한다. | Evidence: L13-L13" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;shape=cylinder3;boundedLbl=1;backgroundOutline=1;fillColor=#eef6fb;" vertex="1" parent="1">
<mxGeometry x="1000.0" y="281.0" width="154.4" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="n_payment-provider" value="결제 제공자 API" tooltip="체크아웃 API의 결제 승인 요청을 처리하고 승인 응답을 반환한다. | Evidence: L13-L13" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
<mxGeometry x="1002.2" y="417.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="e_authorization-approved" value="승인 응답" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_payment-provider" target="n_checkout-api">
<mxGeometry relative="1" as="geometry">
<mxPoint x="853.1" y="499.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_authorization-request" value="승인 요청" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_checkout-api" target="n_payment-provider">
<mxGeometry relative="1" as="geometry">
<mxPoint x="907.1" y="385.4" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_client-request" value="HTTPS 결제 요청" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_client" target="n_auth-gateway">
<mxGeometry relative="1" as="geometry">
<mxPoint x="300.0" y="285.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_create-pending" value="PENDING 주문 기록" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_checkout-api" target="n_orders-db">
<mxGeometry relative="1" as="geometry">
<mxPoint x="944.0" y="303.5" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_mark-paid" value="PAID 상태 갱신" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_checkout-api" target="n_orders-db">
<mxGeometry relative="1" as="geometry">
<mxPoint x="924.5" y="341.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_publish-approved" value="payment.approved 발행" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;dashed=1;" edge="1" parent="1" source="n_checkout-api" target="n_event-bus">
<mxGeometry relative="1" as="geometry">
<mxPoint x="945.1" y="235.1" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_validated-request" value="검증된 요청 전달" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_auth-gateway" target="n_checkout-api">
<mxGeometry relative="1" as="geometry">
<mxPoint x="610.0" y="285.0" as="offset"/>
</mxGeometry>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,27 @@
{
"harness_version": "0.1.0",
"spec_id": "payment-request",
"spec_version": "1.0",
"spec_sha256": "788512f48619a6873ba7e07979a224a2975e9ce2c69bdc9d019185d7df660357",
"source_context": {
"document": "examples/docs/payment-flow.md",
"document_sha256": "d1449d2ad322f11e735bf5c98ee33311d03ff893ef91eb97b5422f6cc04b0e7c",
"anchor": {
"kind": "marker",
"value": "payment-request",
"line": 15
}
},
"outputs": [
"payment-request.svg",
"payment-request.mmd",
"payment-request.d2",
"payment-request.dot",
"payment-request.drawio",
"payment-request.excalidraw",
"payment-request.alt.md"
],
"lint_issue_count": 0,
"assumption_count": 0,
"assumptions_allowed": false
}
+18
View File
@@ -0,0 +1,18 @@
%% 승인된 결제는 주문 상태 갱신 후 이벤트로 확산된다
%% question: 결제 요청은 어디를 거쳐 저장되고 승인 후 어떤 이벤트를 발행하는가?
flowchart LR
n0(["클라이언트"])
n1["인증 게이트웨이"]
n2["체크아웃 API"]
n3[("PostgreSQL 주문 저장소")]
n4["결제 제공자 API"]
n5(["이벤트 버스"])
n0 -->|"HTTPS 결제 요청"| n1
n1 -->|"검증된 요청 전달"| n2
n2 -->|"PENDING 주문 기록"| n3
n2 -->|"승인 요청"| n4
n4 -->|"승인 응답"| n2
n2 -->|"PAID 상태 갱신"| n3
n2 -.->|"payment.approved 발행"| n5
classDef external stroke-dasharray: 6 4
class n0 external
Binary file not shown.

After

Width:  |  Height:  |  Size: 73 KiB

+96
View File
@@ -0,0 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="1214" height="587" viewBox="0 0 1214 587" role="img" aria-labelledby="diagram-title diagram-description">
<title id="diagram-title">승인된 결제는 주문 상태 갱신 후 이벤트로 확산된다</title>
<desc id="diagram-description">왼쪽에서 오른쪽으로 읽는다. 클라이언트가 HTTPS 결제 요청을 인증 게이트웨이에 보내고, 검증된 요청이 체크아웃 API로 전달된다. 체크아웃 API는 PostgreSQL에 PENDING 주문을 기록하고 결제 제공자 API에 승인을 요청한다. 승인 응답을 받으면 같은 주문을 PAID로 갱신하고 payment.approved 이벤트를 이벤트 버스에 발행한다.</desc>
<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.0&quot;,&quot;id&quot;:&quot;payment-request&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;examples/docs/payment-flow.md&quot;,&quot;document_sha256&quot;:&quot;d1449d2ad322f11e735bf5c98ee33311d03ff893ef91eb97b5422f6cc04b0e7c&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;marker&quot;,&quot;value&quot;:&quot;payment-request&quot;,&quot;line&quot;:15}},&quot;evidence_policy&quot;:&quot;Each factual element cites source lines or is marked assumption.&quot;}</metadata>
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
<path d="M 0 0 L 10 5 L 0 10 z" />
</marker>
<filter id="soft-shadow" x="-20%" y="-20%" width="140%" height="140%">
<feDropShadow dx="0" dy="2" stdDeviation="2" flood-opacity="0.16" />
</filter>
<style>
:root { color-scheme: light; }
text { font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #17202a; }
.canvas { fill: #ffffff; }
.diagram-title { font-size: 24px; font-weight: 700; }
.diagram-question { font-size: 14px; fill: #4d5966; }
.group-box { fill: #f7f9fb; stroke: #66788a; stroke-width: 1.5; stroke-dasharray: 7 5; }
.group-label-bg { fill: #ffffff; }
.group-label { font-size: 13px; font-weight: 650; fill: #334455; }
.edge { fill: none; stroke: #364b5f; stroke-width: 2; stroke-linejoin: round; marker-end: url(#arrow); }
.edge.async, .edge.event, .edge.publish { stroke-dasharray: 7 5; }
.edge.assumption { stroke-dasharray: 3 5; }
.edge-label-bg { fill: #ffffff; stroke: #d5dce3; stroke-width: 1; rx: 5; }
.edge-label { font-size: 12px; font-weight: 560; text-anchor: middle; }
.node-shape { fill: #ffffff; stroke: #2d4357; stroke-width: 2; }
.kind-external, .kind-actor, .kind-user { fill: #f5f7fa; stroke-dasharray: 6 4; }
.kind-database, .kind-datastore, .kind-storage { fill: #eef6fb; }
.kind-queue, .kind-event, .kind-topic { fill: #f6f1fb; }
.kind-decision, .kind-gateway { fill: #fff7e8; }
.kind-security, .kind-auth { fill: #fdf0f0; }
.node-shape.assumption { stroke-dasharray: 4 4; }
.storage-bottom { fill: none; stroke: #2d4357; stroke-width: 2; }
.node-label { font-size: 14px; font-weight: 650; text-anchor: middle; }
.node-kind { font-size: 10px; letter-spacing: 0.07em; text-transform: uppercase; text-anchor: middle; fill: #5d6975; }
.assumption-badge { font-size: 9px; font-weight: 700; fill: #7a4300; }
.footer { font-size: 10px; fill: #697783; }
</style>
</defs>
<rect class="canvas" width="1214" height="587" />
<text class="diagram-title" x="50" y="42">승인된 결제는 주문 상태 갱신 후 이벤트로 확산된다</text>
<text class="diagram-question" x="50" y="67">결제 요청은 어디를 거쳐 저장되고 승인 후 어떤 이벤트를 발행하는가?</text>
<polyline class="edge response" points="1077.2,481.0 1077.2,527.0 765.0,527.0 765.0,345.0" data-evidence="13-13" />
<rect class="edge-label-bg" x="827.1" y="485.0" width="52.0" height="22" />
<text class="edge-label" x="853.1" y="500.0">승인 응답</text>
<polyline class="edge request" points="840.0,332.8 931.1,332.8 931.1,458.0 1002.2,458.0" data-evidence="13-13" />
<rect class="edge-label-bg" x="881.1" y="371.4" width="52.0" height="22" />
<text class="edge-label" x="907.1" y="386.4">승인 요청</text>
<polyline class="edge request" points="220.0,313.0 300.0,313.0 300.0,313.0 380.0,313.0" data-evidence="11-11" />
<rect class="edge-label-bg" x="253.6" y="271.0" width="92.8" height="22" />
<text class="edge-label" x="300.0" y="286.0">HTTPS 결제 요청</text>
<polyline class="edge data" points="840.0,303.1 920.0,303.1 920.0,304.0 1000.0,304.0" data-evidence="13-13" />
<rect class="edge-label-bg" x="890.8" y="289.5" width="106.4" height="22" />
<text class="edge-label" x="944.0" y="304.5">PENDING 주문 기록</text>
<polyline class="edge data" points="840.0,313.0 930.0,313.0 930.0,322.0 1000.0,322.0" data-evidence="13-13" />
<rect class="edge-label-bg" x="881.5" y="327.0" width="86.0" height="22" />
<text class="edge-label" x="924.5" y="342.0">PAID 상태 갱신</text>
<polyline class="edge publish" points="840.0,293.2 921.1,293.2 921.1,177.0 1002.2,177.0" data-evidence="13-13" />
<rect class="edge-label-bg" x="871.5" y="221.1" width="147.2" height="22" />
<text class="edge-label" x="945.1" y="236.1">payment.approved 발행</text>
<polyline class="edge request" points="530.0,313.0 610.0,313.0 610.0,313.0 690.0,313.0" data-evidence="11-11" />
<rect class="edge-label-bg" x="570.4" y="271.0" width="79.2" height="22" />
<text class="edge-label" x="610.0" y="286.0">검증된 요청 전달</text>
<g id="node-client">
<rect class="node-shape kind-actor" data-evidence="7-7,11-11" x="70.0" y="281.0" width="150.0" height="64.0" rx="10" />
<text class="node-kind" x="145.0" y="298.0">actor</text>
<text class="node-label" x="145.0" y="320.0">클라이언트</text>
</g>
<g id="node-auth-gateway">
<rect class="node-shape kind-security" data-evidence="7-7,11-11" x="380.0" y="281.0" width="150.0" height="64.0" rx="10" />
<text class="node-kind" x="455.0" y="298.0">security</text>
<text class="node-label" x="455.0" y="320.0">인증 게이트웨이</text>
</g>
<g id="node-checkout-api">
<rect class="node-shape kind-service" data-evidence="7-7,11-13" x="690.0" y="281.0" width="150.0" height="64.0" rx="10" />
<text class="node-kind" x="765.0" y="298.0">service</text>
<text class="node-label" x="765.0" y="320.0">체크아웃 API</text>
</g>
<g id="node-event-bus">
<rect class="node-shape kind-queue" data-evidence="13-13" x="1002.2" y="145.0" width="150.0" height="64.0" rx="26" />
<text class="node-kind" x="1077.2" y="162.0">queue</text>
<text class="node-label" x="1077.2" y="184.0">이벤트 버스</text>
</g>
<g id="node-orders-db">
<rect class="node-shape kind-database" data-evidence="13-13" x="1000.0" y="291.7" width="154.4" height="42.7" /><ellipse class="node-shape kind-database" cx="1077.2" cy="291.7" rx="77.2" ry="10.7" /><path class="storage-bottom" d="M 1000.0 334.3 A 77.2 10.7 0 0 0 1154.4 334.3" />
<text class="node-kind" x="1077.2" y="298.0">database</text>
<text class="node-label" x="1077.2" y="320.0">PostgreSQL 주문 저장소</text>
</g>
<g id="node-payment-provider">
<rect class="node-shape kind-service" data-evidence="13-13" x="1002.2" y="417.0" width="150.0" height="64.0" rx="10" />
<text class="node-kind" x="1077.2" y="434.0">service</text>
<text class="node-label" x="1077.2" y="456.0">결제 제공자 API</text>
</g>
<text class="footer" x="50" y="565.0">Generated from grounded VizSpec · editable sources are versioned separately</text>
</svg>

After

Width:  |  Height:  |  Size: 7.4 KiB