From d2120d93a9fa8ccd41a441526fa1d001894a998d Mon Sep 17 00:00:00 2001 From: happybell80 Date: Wed, 15 Oct 2025 12:17:47 +0900 Subject: [PATCH 1/5] =?UTF-8?q?docs:=20=EC=8B=9C=EC=8A=A4=ED=85=9C=20?= =?UTF-8?q?=EB=A9=94=ED=8A=B8=EB=A6=AD=20=EB=AC=B8=EC=84=9C=20=EB=AF=B8?= =?UTF-8?q?=ED=95=B4=EA=B2=B0=20=EC=84=B9=EC=85=98=20=EC=A0=9C=EA=B1=B0=20?= =?UTF-8?q?=EB=B0=8F=20=ED=95=B4=EA=B2=B0=20=EC=99=84=EB=A3=8C=20=ED=91=9C?= =?UTF-8?q?=EC=8B=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - "미해결 문제" → "최종 해결 (2025-07-15)" - Prometheus + Grafana 대체 사실 명시 - frontend-base/backend/metrics_database.py 참조 추가 - "후속 작업" 섹션 삭제 (완료됨) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../250714_system_metrics_implementation.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/troubleshooting/250714_system_metrics_implementation.md b/troubleshooting/250714_system_metrics_implementation.md index 8511d95..73071b5 100644 --- a/troubleshooting/250714_system_metrics_implementation.md +++ b/troubleshooting/250714_system_metrics_implementation.md @@ -108,10 +108,12 @@ backend/ - `GET /admin/metrics/history/{period}` - 기간별 메트릭 히스토리 - `POST /admin/metrics/collect` - 수동 메트릭 수집 -## 미해결 문제 -**현재 상태**: 테이블 구조 불일치로 인한 메트릭 데이터 삽입 실패 -**증상**: `column "timestamp" of relation "system_metrics" does not exist` -**예상 원인**: 코드 내 일부 SQL 쿼리에서 여전히 `timestamp` 컬럼 참조 +## 최종 해결 (2025-07-15) + +**상태**: 메트릭 수집 비활성화 (Prometheus + Grafana로 대체) +**관련 파일**: frontend-base/backend/metrics_database.py:58-60, 78-80, 148-150 +**해결 방법**: system_metrics 테이블 사용 중단, TODO 주석 처리 +**참고**: 아래 Prometheus + Grafana 방식으로 완전 전환 ## 학습 포인트 1. **Docker 네트워크**: 컨테이너간 통신 시 서비스 이름 사용 @@ -120,13 +122,7 @@ backend/ 4. **데이터베이스 스키마**: 코드와 실제 테이블 구조 일치 중요성 5. **PostgreSQL 인증**: Docker 환경에서 비밀번호 설정 필요 -## 후속 작업 -1. 테이블 구조 불일치 문제 완전 해결 -2. 메트릭 데이터 수집 정상 동작 확인 -3. 그래프에 실제 데이터 표시 검증 -4. 성능 최적화 및 에러 핸들링 개선 - -## (*update*) `node-exporter` + `Prometheus` + `Grafana` 를 이용한 compute 자원 모니터링 +## `node-exporter` + `Prometheus` + `Grafana` 를 이용한 compute 자원 모니터링 해당 문서는 직접 개발하는 방식이 아닌 기존에 널리 쓰이는
`node-exporter` + `Prometheus` + `Grafana`를 이용하여
From 893e613981476771b6dde35a0a0ca921065c7e24 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Wed, 15 Oct 2025 12:39:19 +0900 Subject: [PATCH 2/5] =?UTF-8?q?docs:=20FastAPI=20=EA=B5=AC=EC=A1=B0=20?= =?UTF-8?q?=EC=9B=90=EC=B9=99=EC=97=90=20LangGraph=20=EC=9B=8C=ED=81=AC?= =?UTF-8?q?=ED=94=8C=EB=A1=9C=EC=9A=B0=20=EA=B7=9C=EC=B9=99=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 복잡한 다단계 처리는 LangGraph 적극 활용 - 체크포인트 필수 (PostgresSaver) - stateless 금지 (프레임워크 가치 없음) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- 300_architecture/311_FastAPI_구조_원칙.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/300_architecture/311_FastAPI_구조_원칙.md b/300_architecture/311_FastAPI_구조_원칙.md index 15ce208..c920f06 100644 --- a/300_architecture/311_FastAPI_구조_원칙.md +++ b/300_architecture/311_FastAPI_구조_원칙.md @@ -93,6 +93,11 @@ utils ## 5. 코드 작성 원칙 +### LangGraph 워크플로우 +- **복잡한 다단계 처리**: LangGraph 적극 활용 +- **체크포인트 필수**: PostgresSaver로 부분 재시도 가능하게 구현 +- **stateless 금지**: 체크포인트 없는 LangGraph는 일반 함수와 동일, 프레임워크 가치 없음 + ### router 계층 ```python # ✅ 올바름 From 0be1548ccce4e963b614708327bbf428247a5b6b Mon Sep 17 00:00:00 2001 From: happybell80 Date: Wed, 15 Oct 2025 13:06:47 +0900 Subject: [PATCH 3/5] =?UTF-8?q?docs:=20Slack=20Lists=20=EB=8F=99=EC=A0=81?= =?UTF-8?q?=20=EB=A7=A4=ED=95=91=20=EB=B0=8F=20LLM=20=EC=97=90=EB=9F=AC=20?= =?UTF-8?q?=EB=B3=B5=EA=B5=AC=20=ED=95=B4=EA=B2=B0=20=EB=B0=A9=EC=95=88=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 - Slack Lists 컬럼 조회 API + 동적 매핑으로 하드코딩 제거 - LangGraph 체크포인트 + LLM 기반 에러 분석 노드 추가 - 페이로드 수정 후 재시도 구조 설계 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- ...015_claude_coldmail_ir_analysis_failure.md | 35 +++++++++++++++---- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/troubleshooting/251015_claude_coldmail_ir_analysis_failure.md b/troubleshooting/251015_claude_coldmail_ir_analysis_failure.md index 8f43d90..258755a 100644 --- a/troubleshooting/251015_claude_coldmail_ir_analysis_failure.md +++ b/troubleshooting/251015_claude_coldmail_ir_analysis_failure.md @@ -60,19 +60,40 @@ PDF 업로드 실패 → document_id = None → RAG 검색 0건 → IR 분석 "N **개선**: 중복 시 기존 document_id 반환 (멱등성 보장) -### 2. IR 분석 실패 감지 +### 2. Slack Lists 동적 컬럼 매핑 -**위치**: rb8001/app/services/coldmail_processor.py +**문제**: 하드코딩된 컬럼 ID (Col09HQTDUM0T 등) - Lists 필드 변경 시 코드 수정 필요 -**추가**: 모든 필드 "N/A" 시 처리 실패로 간주, 로그 기록 +**해결**: +1. skill-slack에 Lists 컬럼 조회 API 추가 (`GET /api/v1/lists/{list_id}/columns`) +2. coldmail_processor.py에서 컬럼명으로 동적 매핑 (`"회사명" → Col09HQTDUM0T`) +3. 컬럼 누락 시 해당 필드만 skip, 나머지 전송 -### 3. LangGraph 체크포인트 활성화 +**효과**: Lists 구조 변경 시 코드 수정 불필요 -**위치**: workflows/coldmail_workflow.py:145 +### 3. LangGraph 체크포인트 + LLM 기반 에러 복구 -**현재**: `workflow.compile()` (stateless) +**위치**: workflows/coldmail_workflow.py -**개선**: PostgresSaver 추가로 IR 분석 실패 시 해당 노드만 재시도 가능 +**현재 구조** (stateless): +``` +메일 조회 → PDF 업로드 → IR 분석 → Slack 전송 +``` + +**개선 구조** (체크포인트 + 에러 복구): +``` +메일 조회 → PDF 업로드 → IR 분석 → Slack 전송 + ↓ (400 에러) + LLM 에러 분석 → 페이로드 수정 → 재전송 +``` + +**구현**: +1. PostgresSaver 체크포인트 활성화 +2. Slack 전송 실패 시 에러 메시지 + 원본 payload를 LLM에게 전달 +3. LLM structured output으로 수정된 payload 받아서 재시도 +4. 각 노드별 실패 시 해당 지점부터 재시도 (처음부터 재실행 방지) + +**제약**: Slack API가 상세 에러 정보 제공해야 LLM이 수정 가능 --- From 1068b3d0a2461365dc8012a54207266bf082f732 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Wed, 15 Oct 2025 18:24:24 +0900 Subject: [PATCH 4/5] =?UTF-8?q?docs:=20Slack=20=EB=B4=87=20=EC=84=A4?= =?UTF-8?q?=EC=B9=98=20workspace=5Fid=20=EC=BB=AC=EB=9F=BC=20=EC=98=A4?= =?UTF-8?q?=EB=A5=98=20=ED=8A=B8=EB=9F=AC=EB=B8=94=EC=8A=88=ED=8C=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: workspace_member 테이블에 존재하지 않는 workspace_id 컬럼 조회 시도 원인: DB 스키마 변경 후 slack.py:408-413 쿼리 미반영 해결: user.team_id 직접 조회로 수정 필요 (로컬 개발자) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- ...251015_slack_install_workspace_id_error.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 troubleshooting/251015_slack_install_workspace_id_error.md diff --git a/troubleshooting/251015_slack_install_workspace_id_error.md b/troubleshooting/251015_slack_install_workspace_id_error.md new file mode 100644 index 0000000..cced1a0 --- /dev/null +++ b/troubleshooting/251015_slack_install_workspace_id_error.md @@ -0,0 +1,54 @@ +# Slack 봇 설치 workspace_id 컬럼 오류 + +**날짜**: 2025-10-15 +**작성자**: 51123 서버 관리자 +**관련 파일**: `auth-server/app/providers/slack.py:408-418` + +--- + +## 문제 상황 + +Slack 연동 버튼 클릭 시 Internal Server Error: +``` +column "workspace_id" does not exist +LINE 2: SELECT workspace_id + FROM workspace_member +``` + +**에러 로그**: auth-server 로그에서 sqlalchemy.exc.ProgrammingError 확인 + +## 원인 분석 + +### DB 구조 +- workspace_member 테이블: workspace_id 컬럼 없음 (id, user_id, role, is_active만 존재) +- slack.py:408-413: 존재하지 않는 컬럼 조회 시도 + +### 실제 관계 +- user.team_id → team.id +- Workspace = Team (workspace.py:113) +- user.team_id가 workspace_id 역할 + +## 해결 방안 + +**로컬 개발자 수정 필요**: slack.py:407-423 + +- slack.py:408-413: workspace_member 쿼리 제거 +- user.team_id 직접 조회로 변경 +- User 모델 import 추가 필요 (app.models.user) + +## 교훈 + +### DB 스키마 검증 누락 +- workspace_member.workspace_id 존재 가정 +- 실제 테이블 구조 미확인 +- 교훈: 쿼리 작성 전 \d 명령으로 테이블 구조 확인 필수 + +### 스키마 변경 후 코드 미반영 +- Git 히스토리: 9월 workspace 관련 수정 다수 (커밋 455af87, 59ae0ab) +- DB 스키마 변경 후 참조 쿼리 미검증 +- 교훈: 스키마 변경 시 Grep으로 전체 참조 검색 후 일괄 수정 + +### 중간 테이블 설계 오류 +- workspace_member에 workspace/team FK 누락 +- user.team_id로 직접 조회해야 하는 구조 +- 교훈: 다대다 중간 테이블은 양쪽 FK 필수 From e38b337832cb30e99f88dd7287c208d03ea1978e Mon Sep 17 00:00:00 2001 From: happybell80 Date: Wed, 15 Oct 2025 18:33:07 +0900 Subject: [PATCH 5/5] =?UTF-8?q?docs:=20Slack=20=EB=B4=87=20=EC=84=A4?= =?UTF-8?q?=EC=B9=98=20=EC=98=A4=EB=A5=98=20=EB=AC=B8=EC=84=9C=20=EC=88=98?= =?UTF-8?q?=EC=A0=95=20(=EC=99=84=EB=B2=BD=ED=95=9C=20=EC=A7=80=EC=8B=9C?= =?UTF-8?q?=EC=84=9C=EB=A1=9C)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 해결 방안: 구체적인 수정 위치 및 내용 명시 - 교훈: Raw SQL 위험성, ORM 사용 권장 추가 - 코드 블록 제거, 파일명:줄번호 형식 준수 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- ...251015_slack_install_workspace_id_error.md | 33 ++++++++++--------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/troubleshooting/251015_slack_install_workspace_id_error.md b/troubleshooting/251015_slack_install_workspace_id_error.md index cced1a0..4c03fa9 100644 --- a/troubleshooting/251015_slack_install_workspace_id_error.md +++ b/troubleshooting/251015_slack_install_workspace_id_error.md @@ -30,25 +30,28 @@ LINE 2: SELECT workspace_id ## 해결 방안 -**로컬 개발자 수정 필요**: slack.py:407-423 +**수정 파일**: auth-server/app/providers/slack.py -- slack.py:408-413: workspace_member 쿼리 제거 -- user.team_id 직접 조회로 변경 -- User 모델 import 추가 필요 (app.models.user) +**수정 내용**: +- slack.py:408-413: text() 쿼리 삭제 +- slack.py:408: db.query(User).filter(User.id == user_id).first()로 변경 +- slack.py:409-410: user.team_id 존재 확인 (없으면 HTTPException 404) +- slack.py:418: workspace_id = user.team_id + +**참고**: User는 slack.py:19에 이미 import됨 ## 교훈 ### DB 스키마 검증 누락 -- workspace_member.workspace_id 존재 가정 -- 실제 테이블 구조 미확인 -- 교훈: 쿼리 작성 전 \d 명령으로 테이블 구조 확인 필수 +- workspace_member.workspace_id 존재 가정, 실제 컬럼 없음 +- tables.md 또는 psql \d 명령으로 테이블 구조 미확인 +- 교훈: 쿼리 작성 전 tables.md 참조 또는 DB 직접 확인 필수 -### 스키마 변경 후 코드 미반영 -- Git 히스토리: 9월 workspace 관련 수정 다수 (커밋 455af87, 59ae0ab) -- DB 스키마 변경 후 참조 쿼리 미검증 +### Raw SQL 사용 위험 +- text() 쿼리 사용 시 컴파일 타임 타입 체크 불가 +- 런타임에만 에러 발견 +- 교훈: ORM (db.query(Model)) 사용으로 타입 안전성 확보 + +### 스키마 변경 추적 부족 +- DB 스키마 변경 후 참조 코드 미검증 - 교훈: 스키마 변경 시 Grep으로 전체 참조 검색 후 일괄 수정 - -### 중간 테이블 설계 오류 -- workspace_member에 workspace/team FK 누락 -- user.team_id로 직접 조회해야 하는 구조 -- 교훈: 다대다 중간 테이블은 양쪽 FK 필수