From a144a091b9c69e5266c683858d5ee8383ea2f2b6 Mon Sep 17 00:00:00 2001
From: thug0bin <thug0bin@users.noreply.git.0bin.in>
Date: Thu, 5 Mar 2026 13:24:03 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20PAAI=20=EC=8B=9C=EC=8A=A4=ED=85=9C=20?=
 =?UTF-8?q?=EC=95=84=ED=82=A4=ED=85=8D=EC=B2=98=20=EB=AC=B8=EC=84=9C=20?=
 =?UTF-8?q?=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- PAAI 전체 흐름 다이어그램
- 구성 요소 (Trigger, WebSocket, API, 프린터)
- WebSocket 이벤트 목록
- 자동인쇄/중복방지/재시도 로직 설명
- 로그 파일 위치
---
 docs/ARCHITECTURE.md | 124 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index a305434..16d4202 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -420,6 +420,128 @@ OPENAI_MODEL=gpt-4o-mini
 
 ---
 
+---
+
+## 🤖 PAAI 시스템 (처방 AI 분석)
+
+### 개요
+
+**PAAI (Prescription AI Analysis)**는 처방 접수 시 자동으로 AI 분석을 수행하고, 
+분석 결과를 영수증 프린터로 출력하는 시스템입니다.
+
+### 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           PAAI 시스템 흐름                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  POS 접수   │────►│  PM_PRES_LOG    │────►│ Trigger Module  │
+│  (처방입력)  │     │  (MSSQL)        │     │ (폴링 감지)     │
+└─────────────┘     └─────────────────┘     └─────────────────┘
+                                                    │
+                    ┌───────────────────────────────┤
+                    │                               │
+                    ▼                               ▼
+           ┌─────────────────┐            ┌─────────────────┐
+           │  WebSocket 알림  │            │  PAAI 분석 요청  │
+           │  (ws://8765)    │            │  Flask API      │
+           └─────────────────┘            └─────────────────┘
+                    │                               │
+                    ▼                               ▼
+           ┌─────────────────┐            ┌─────────────────┐
+           │  프론트엔드     │            │  Claude API     │
+           │  pmr.html       │            │  (분석 수행)     │
+           └─────────────────┘            └─────────────────┘
+                    │                               │
+                    │◄──────────────────────────────┤
+                    │    analysis_completed 이벤트
+                    ▼
+           ┌─────────────────┐
+           │  자동 인쇄      │
+           │  ESC/POS 프린터 │
+           └─────────────────┘
+```
+
+### 구성 요소
+
+| 모듈 | 위치 | 역할 |
+|------|------|------|
+| **Trigger Module** | `prescription-trigger/prescription_trigger.py` | PM_PRES_LOG 폴링, 처방 감지, 분석 요청 |
+| **WebSocket Server** | Trigger 내장 (port 8765) | 프론트엔드에 실시간 이벤트 전송 |
+| **PAAI API** | `backend/pmr_api.py` | 분석 요청 처리, Claude API 호출, 결과 저장 |
+| **프론트엔드** | `backend/templates/pmr.html` | 조제관리 UI, 자동인쇄 토글 |
+| **프린터 모듈** | `backend/paai_printer.py` | ESC/POS 영수증 프린터 출력 |
+
+### WebSocket 이벤트
+
+| 이벤트 | 방향 | 설명 |
+|--------|------|------|
+| `prescription_detected` | Server → Client | 새 처방 감지됨 |
+| `analysis_started` | Server → Client | AI 분석 시작 |
+| `analysis_completed` | Server → Client | 분석 완료 (결과 포함) |
+| `analysis_failed` | Server → Client | 분석 실패 (에러 포함) |
+
+### 자동 인쇄 흐름
+
+```javascript
+// 1. WebSocket으로 analysis_completed 수신
+ws.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    if (data.event === 'analysis_completed') {
+        // 2. 자동인쇄 ON 상태면 인쇄
+        if (window.autoPrintEnabled) {
+            printPaaiResult(data.pre_serial, data.patient_name, data);
+        }
+    }
+};
+
+// 3. 인쇄 API 호출
+POST /pmr/api/paai/print
+{
+    "pre_serial": "20260305000099",
+    "patient_name": "홍길동",
+    "result": { "analysis": {...}, "kims_summary": {...} }
+}
+
+// 4. ESC/POS 프린터로 출력
+```
+
+### 중복 방지
+
+```javascript
+// window.printedSerials (Set) 으로 중복 인쇄 방지
+if (window.printedSerials.has(preSerial)) {
+    console.log('[AutoPrint] 이미 인쇄됨, 스킵:', preSerial);
+    return;
+}
+window.printedSerials.add(preSerial);  // 요청 전에 추가 (race condition 방지)
+```
+
+### 자동 재시도
+
+| 시도 | 대기 시간 | 상태 |
+|------|----------|------|
+| 1회차 | - | 최초 시도 |
+| 2회차 | 2초 | 첫 번째 재시도 |
+| 3회차 | 4초 | 두 번째 재시도 |
+| 실패 | - | `analysis_failed` 이벤트 발송 |
+
+### 로그 파일
+
+| 파일 | 위치 | 내용 |
+|------|------|------|
+| `print_history.log` | `backend/logs/` | 인쇄 성공/실패 기록 |
+| `analysis_failures.log` | `prescription-trigger/logs/` | 분석 실패 상세 기록 |
+| `paai_logs.db` | `backend/db/` | 분석 결과 SQLite 저장 |
+
+### 관련 문서
+
+- `docs/PAAI_AUTO_PRINT_TROUBLESHOOTING.md` - 자동인쇄 트러블슈팅 가이드
+
+---
+
 ## 📝 버전 이력
 
 | 날짜 | 버전 | 변경 내용 |
@@ -427,6 +549,8 @@ OPENAI_MODEL=gpt-4o-mini
 | 2026-02-28 | 1.0 | 초기 아키텍처 문서 작성 |
 | | | 동물약 AI 챗봇 추가 |
 | | | 플로팅 챗봇 UI 구현 |
+| 2026-03-05 | 1.1 | PAAI 시스템 아키텍처 추가 |
+| | | 자동인쇄, WebSocket, 재시도 로직 |
 
 ---