FastAPI AI 서버의 설계·결정·구현 기록입니다. 공용 계약의 단일 원본은 Team-PinLog/docs의 static/05_AI_설계.md입니다. 이 디렉터리의 문서는 그 계약을 참조만 하고, 구현 방법을 다룹니다.
모든 문서가 공유하는 전제는 Context 불변성입니다(계약 §4.2):
동일한 context_id는 항상 동일한 Context 본문을 의미한다.
수정은 구 Context 삭제와 신 Context 생성의 조합이며 새 context_id를 받습니다. 따라서 본문 세대를 구분하는 버전 개념이 없습니다. 수정 도중 발생하는 경합도 별도 장치 없이 삭제 경합 방어가 함께 처리합니다.
| 구역 | 내용 |
|---|---|
spec/ |
설계·구현 명세. "무엇을 만들 것인가" |
proposals/ |
제안·결정(P 번호)과 미결 사항. "왜 그렇게 정했나" |
implements/ |
구현 리포트. "어떻게 만들었나" |
troubleshooting/ |
문제 해결 |
WORKLOG.md |
시간순 작업 로그 |
development/ |
Jira→PR 워크플로와 코드 리뷰 운영 규칙 |
- architecture.md — 어디에 무엇이 있는지 (모듈·계층·DB 세션 경계, 구조도)
- context-processing.md — 주 파이프라인
POST /internal/v1/context/process - state-machine.md · deletion-race-control.md · partial-resume.md — 데이터 정합성을 지키는 세 명세
- keyword-preset.md · personal-search.md · model-profile.md — 기능별 상세
- failure-recovery.md · integration-tests.md — 운영과 검증
구현 명세와 계약이 어긋나면 계약이 우선합니다. 계약 변경은 이 레포가 아니라 docs 레포에서 합니다.