docs: Symphony 테스트 워크플로 정리 (#240)

* docs: Symphony 테스트 워크플로 정리

* docs: 아키텍처 문서 및 시퀀스 다이어그램 보완

Author: Ji-minhyeok

.github/PULL_REQUEST_TEMPLATE.md

@@ -20,6 +20,6 @@
 - [x] Label을 지정했나요?
 
 ## 🔗 관련 이슈
-
+- 
 
 ## 💬 기타 참고 사항

README.md

@@ -179,6 +179,77 @@ Redis는 목적에 따라 Core Redis와 MQ Redis로 분리해 사용합니다.
 | `redis-core` | 6379 | 재고, 중복 신청, 대기열, 분산 락 |
 | `redis-mq` | 6380 | Redis Stream, 신청 처리 상태 |
 
+## 시퀀스 다이어그램
+
+### 선착순 신청 흐름
+
+```mermaid
+---
+config:
+  theme: redux-color
+  themeCSS: |
+    text.actor {
+      font-size: 17px !important;
+    }
+    .messageText {
+      font-size: 19px !important;
+    }
+    .note {
+      fill: #f1f5f9 !important;
+      stroke: #cbd5e1 !important;
+    }
+    .noteText {
+      font-size: 17px !important;
+    }
+    .labelText {
+      font-size: 17px !important;
+    }
+    .loopText {
+      font-size: 17px !important;
+    }
+---
+sequenceDiagram
+    autonumber
+    actor User
+    participant API as API Server
+    participant Core as Redis Core<br/>(Sorted Set)
+    participant Consumer as Consumer Server
+    participant Stream as Redis Stream
+    participant DB as PostgreSQL / PostGIS
+
+    activate API
+    User->>API: POST /lesson/apply
+    API->>Core: 재고 선점 / 중복 확인 / 대기열 등록
+    Note over API,Core: requestId는 Sorted Set Waiting Room에서 대기
+    API-->>User: requestId 반환
+    deactivate API
+
+    activate Consumer
+    rect rgb(255, 242, 242)
+    Note over Core,Stream: Admission 단계
+    Consumer->>Core: 대기열 requestId dequeue
+    Consumer->>Core: 상태변경: PROCESSING
+    Consumer->>Stream: XADD 신청 메시지
+    end
+    Note over Consumer,Stream: 신청 메시지는 Redis Stream에 적재
+    rect rgb(239, 246, 255)
+    Note over Core,DB: Consumer 처리 단계
+    Stream-->>Consumer: XREADGROUP
+    Consumer->>DB: DB 반영
+    Consumer->>Core: 상태변경: SUCCESS / FAIL
+    end
+    deactivate Consumer
+
+    loop requestId polling
+        activate API
+        User->>API: GET /lesson/apply/{requestId}
+        API->>Core: 상태 조회
+        Core-->>API: WAITING / PROCESSING / SUCCESS / FAIL
+        API-->>User: 현재 상태 응답
+        deactivate API
+    end
+```
+
 ## 배포 자동화
 
 배포는 GitHub Actions, S3, CodeDeploy를 사용합니다. 

WORKFLOW.md

@@ -0,0 +1,102 @@
+---
+tracker:
+  kind: linear
+  api_key: $LINEAR_API_KEY
+  project_slug: "ai-test-workflow-94d799fcd978"
+  required_labels:
+    - ai-test-workflow
+  active_states:
+    - Backlog
+    - Todo
+    - Research
+    - Planning
+    - Approved
+    - In Progress
+    - In Review
+    - Rework
+  terminal_states:
+    - Done
+    - Closed
+    - Cancelled
+    - Canceled
+    - Duplicate
+polling:
+  interval_ms: 5000
+workspace:
+  root: ~/code/symphony-workspaces/trainus
+hooks:
+  after_create: |
+    git clone --branch develop https://github.com/prgrms-web-devcourse-final-project/WEB5_7_3star_BE.git .
+agent:
+  max_concurrent_agents: 1
+  max_turns: 8
+codex:
+  command: codex --model gpt-5.4-mini --config model_reasoning_effort="high" --config shell_environment_policy.inherit=all app-server
+  approval_policy: never
+  thread_sandbox: workspace-write
+  turn_sandbox_policy:
+    type: workspaceWrite
+    networkAccess: true
+---
+
+너는 Linear 이슈 `{{ issue.identifier }}`를 작업하고 있다.
+
+이 파일은 실행 설정과 공통 지시만 담는다. 세부 역할, 승인 기준, 테스트 경계는 이슈 본문과 `docs/ai-test-workflow/rules/*.md`에서 정한다.
+
+산출물 경로:
+- Researcher: `docs/ai-test-workflow/reports/research-report.md`
+- Planner: `docs/ai-test-workflow/reports/test-plan.md`
+- Reviewer: `docs/ai-test-workflow/reports/review-report.md`
+- 공통 로그: `docs/ai-test-workflow/logs/prompt-and-tool-log.md`
+
+이슈 정보:
+- 식별자: {{ issue.identifier }}
+- 제목: {{ issue.title }}
+- 현재 상태: {{ issue.state }}
+- 라벨: {{ issue.labels }}
+- URL: {{ issue.url }}
+
+설명:
+{% if issue.description %}
+{{ issue.description }}
+{% else %}
+설명이 없습니다.
+{% endif %}
+
+참조 문서:
+- `docs/ai-test-workflow/rules/agent-roles.md`가 있으면 읽는다.
+- `docs/ai-test-workflow/rules/human-approval-policy.md`가 있으면 읽는다.
+- `docs/ai-test-workflow/rules/test-boundary.md`가 있으면 읽는다.
+- 근거가 부족할 때는 임의로 만들지 말고, 부족한 근거를 기록한 뒤 가능한 범위의 분석만 계속한다.
+
+출력 규칙:
+- 이슈 결과, 리포트 파일, 로그 항목, Linear 코멘트, 최종 응답은 모두 한국어로 작성한다.
+- 코드 식별자, 파일 경로, 클래스명, 메서드명, 명령어, 예외명은 원문 그대로 유지한다.
+
+작업 원칙:
+1. Linear 이슈를 작업의 단일 기준으로 삼는다.
+2. 이슈 본문에 적힌 역할과 범위를 따른다.
+3. 이슈 범위를 벗어나지 않는다.
+4. 이슈에 사람 승인이 필요하면, 요청된 리포트 또는 계획만 만든 뒤 멈춘다.
+5. Implementer 역할이 명시되고 승인이 완료되지 않으면 운영 코드를 수정하지 않는다.
+6. 이슈가 워크플로 증거를 요구하면 `docs/ai-test-workflow/logs/prompt-and-tool-log.md`에 프롬프트/도구 사용 내역을 기록한다.
+7. 최종 응답에는 완료한 작업, 수정한 파일, 실행한 검증, 남은 블로커를 요약한다.
+8. 리포트를 작성할 때는 `목적, 확인한 근거, 발견 사항, 한계/블로커, 다음 단계`처럼 간결한 한국어 섹션을 우선 사용한다.
+
+상태 전이:
+- `Backlog`: 아직 착수하지 않은 이슈다.
+- `Todo`: 작업 대기 상태다.
+- `Research`: 저장소 근거를 조사하는 단계다.
+- `Planning`: 계획을 정리했고 사람 승인을 기다리는 단계다. 이 상태에서는 구현을 시작하지 않는다.
+- `Approved`: 사람이 승인했고 구현을 시작할 수 있는 단계다. 이 상태에서만 Implementer가 동작한다.
+- `In Progress`: 승인된 범위 안에서 구현 중인 단계다.
+- `In Review`: 구현이 끝났고 결과를 검토하는 단계다. 이 상태에서는 Reviewer만 검토를 수행한다.
+- `Rework`: 검토 결과 수정이 필요한 단계다. 이 상태에서는 같은 범위만 다시 수정한다.
+- `Done`: 최종 수용이 끝난 상태다.
+
+워크플로 메모:
+- PR, 커밋, 리포트, 로그 같은 산출물은 상태가 아니라 작업 결과로 다룬다.
+- Linear 상태는 작업의 진행 단계만 표현하고, 세부 산출물은 리포트/로그 문서로 남긴다.
+- PR 본문이 필요하면 `.github/PULL_REQUEST_TEMPLATE.md`의 항목 순서와 제목을 그대로 따라 작성한다.
+- PR 본문은 자유 서술로 대체하지 말고, 작업 개요 / 작업 내용 / PR 유형 / Check List / 관련 이슈 / 기타 참고 사항 항목을 빠짐없이 채운다.
+- PR의 `관련 이슈`에는 GitHub 이슈 목록을 확인한 뒤 실제 이슈 번호를 `#123` 형식으로 적는다.

docs/architecture/trainus-architecture-async-processing.png

@@ -13,6 +13,19 @@
     "ranksep": "1.3",
 }
 
+node_attr = {
+    "fontsize": "19",
+    "margin": "0.20",
+}
+
+edge_attr = {
+    "fontsize": "20",
+}
+
+cluster_attr = {
+    "fontsize": "22",
+}
+
 
 with Diagram(
     "TrainUs Architecture - Async Processing",
@@ -21,29 +34,31 @@
     outformat="png",
     direction="LR",
     graph_attr=graph_attr,
+    node_attr=node_attr,
+    edge_attr=edge_attr,
 ):
     client = ALB("Client / ALB")
 
-    with Cluster("API Server"):
+    with Cluster("API Server", graph_attr=cluster_attr):
         api = EC2("API Server\n(api profile)")
 
-    with Cluster("Redis Core"):
+    with Cluster("Redis Core", graph_attr=cluster_attr):
         core = Redis("Redis Core\nstock / duplicate")
 
-    with Cluster("Consumer Server - Admission"):
+    with Cluster("Consumer Server - Admission", graph_attr=cluster_attr):
         admission = EC2("Consumer Server\n(admission dequeue)")
         stream = Redis("Redis Stream\nlesson:apply:stream")
 
-    with Cluster("Consumer Server"):
+    with Cluster("Consumer Server", graph_attr=cluster_attr):
         consumer = EC2("Consumer Server\n(batch insert)")
 
-    with Cluster("Database"):
+    with Cluster("Database", graph_attr=cluster_attr):
         db = PostgreSQL("PostgreSQL / PostGIS")
 
-    client >> Edge(label="apply request") >> api
-    api >> Edge(label="duplicate / stock check") >> core
-    core >> Edge(label="dequeue requestIds") >> admission
-    admission >> Edge(label="SET PROCESSING + XADD") >> stream
-    stream >> Edge(label="XREADGROUP batch") >> consumer
-    consumer >> Edge(label="batch insert") >> db
-    consumer >> Edge(label="XACK / XDEL", dir="back") >> stream
+    client >> Edge(label="apply request", fontsize="20") >> api
+    api >> Edge(label="duplicate / stock check", fontsize="20") >> core
+    core >> Edge(label="dequeue requestIds", fontsize="20") >> admission
+    admission >> Edge(label="SET PROCESSING + XADD", fontsize="20") >> stream
+    stream >> Edge(label="XREADGROUP batch", fontsize="20") >> consumer
+    consumer >> Edge(label="batch insert", fontsize="20") >> db
+    consumer >> Edge(label="XACK / XDEL", dir="back", fontsize="20") >> stream

docs/architecture/trainus-architecture-async-processing.py

@@ -22,27 +22,27 @@
 }
 
 node_attr = {
-    "fontsize": "18",
-    "margin": "0.14",
+    "fontsize": "19",
+    "margin": "0.20",
 }
 
 edge_attr = {
-    "fontsize": "15",
+    "fontsize": "20",
 }
 
 cluster_attr = {
     "margin": "20",
-    "fontsize": "18",
+    "fontsize": "22",
 }
 
 instance_cluster_attr = {
     "margin": "8",
-    "fontsize": "15",
+    "fontsize": "22",
 }
 
 asg_cluster_attr = {
     "margin": "15",
-    "fontsize": "18",
+    "fontsize": "24",
 }
 
 with Diagram(
@@ -79,7 +79,7 @@
                 width="1.42",
                 height="0.28",
                 fixedsize="true",
-                fontsize="15",
+                fontsize="19",
             )
             api_app_n = Node(
                 "Spring Boot",
@@ -88,7 +88,7 @@
                 width="1.42",
                 height="0.28",
                 fixedsize="true",
-                fontsize="15",
+                fontsize="19",
             )
             api_ec2_n - api_app_n
 
@@ -113,7 +113,7 @@
                 width="1.42",
                 height="0.28",
                 fixedsize="true",
-                fontsize="15",
+                fontsize="19",
             )
             consumer_app_n = Node(
                 "Spring Boot",
@@ -122,7 +122,7 @@
                 width="1.42",
                 height="0.28",
                 fixedsize="true",
-                fontsize="15",
+                fontsize="19",
             )
             consumer_ec2_n - consumer_app_n
 
@@ -135,15 +135,15 @@
     alb >> Edge(minlen="2") >> api_ec2_1
     alb >> Edge(minlen="2") >> api_ec2_n
 
-    api_app_1 >> Edge(label="apply request") >> redis_core
-    api_app_1 >> Edge(label="poll status") >> redis_mq
-    api_app_1 >> Edge(label="read/write", color="darkgreen") >> postgres
+    api_app_1 >> Edge(label="apply request", fontsize="20") >> redis_core
+    api_app_1 >> Edge(label="poll status", fontsize="20") >> redis_mq
+    api_app_1 >> Edge(label="read/write", color="darkgreen", fontsize="20") >> postgres
 
-    redis_core >> Edge(label="admit") >> consumer_app_1
-    consumer_app_1 >> Edge(label="XREAD / ACK") >> redis_mq
-    consumer_app_1 >> Edge(label="batch insert") >> postgres
+    redis_core >> Edge(label="admit", fontsize="20") >> consumer_app_1
+    consumer_app_1 >> Edge(label="XREAD / ACK", fontsize="20") >> redis_mq
+    consumer_app_1 >> Edge(label="batch insert", fontsize="20") >> postgres
 
-    prometheus << Edge(label="metrics", style="dashed") << [api_app_1, consumer_app_1]
+    prometheus << Edge(label="metrics", style="dashed", fontsize="20") << [api_app_1, consumer_app_1]
 
-    codedeploy >> Edge(label="deploy api", color="blue", style="dashed", constraint="false") >> api_ec2_1
-    codedeploy >> Edge(label="deploy consumer", color="blue", style="dashed", constraint="false") >> consumer_ec2_1
+    codedeploy >> Edge(label="deploy api", color="blue", style="dashed", constraint="false", fontsize="20") >> api_ec2_1
+    codedeploy >> Edge(label="deploy consumer", color="blue", style="dashed", constraint="false", fontsize="20") >> consumer_ec2_1