ai-study 작업 규칙

전역 = C:\dev\CLAUDE.md, 리포 = C:\dev\ai-study\CLAUDE.md. 여기엔 ai-study 인프라 함정만 쌓는다.

서버 4개 (전부 HKCU Run 자동시작 · 스크립트는 작업본 `C:\dev\ai-study\tools\`)

이름	포트	인터프리터	역할
`ai_study_site`	8801 (127.0.0.1)	py312w	운영 서빙 `prod\site` — `--prefix /study` 필수
`ai_study_test`	8803 (0.0.0.0)	py39w	테스트 서빙 작업본 `site` (312w는 방화벽 차단)
`ai_study_hook`	8802	py312w	GitHub webhook → prod git pull
`ai_study_qa`	8804	py312w	QA·과제 API

공개 = Tailscale Funnel /study→8801 · /study-qa→8804 · /study-hook→8802.
서버 스크립트는 작업본에서 돈다 → tools/*.py 수정은 재기동만으로 운영 반영(push 불필요). site/ 내용물만 push 대상.

🆕 신규

가입 = 토큰이 곧 초대장(26.8.22 페페 지시 · 팀장 승인 폐지). 토큰만 맞으면 status=approved + 즉시 sid. 함정 3개 = ①비번 6자 미만 계정은 자가가입 불가(서버 len(pw)<6·login.html minlength="6") → 짧은 비번을 지정받으면 규칙을 낮추지 말고 data/users.json에 계정을 직접 만든다(비번 규칙 완화는 site/ 변경 = push/운영배포까지 끌고 온다). 해시 = pbkdf2_hmac('sha256', pw, bytes.fromhex(salt), 200000), salt = secrets.token_hex(16). ②토큰 키(member 슬러그) 1계정 제한 — 같은 member로 두 번 가입하면 409. 그래서 미리 계정을 만들어 두면 그 토큰으론 더 못 가입한다. ③data/는 gitignore + 서버가 파일을 직접 읽음 → 토큰·계정 추가는 저장 즉시 반영(push 불필요), 단 NAMES 등 tools/*.py 수정은 qa_server 재기동이 있어야 먹는다.
Funnel은 마운트 프리픽스를 떼고 넘긴다 — 리다이렉트는 직접 복원해야 한다(26.8.11 장애). https://…/study/ 요청이 8801에 /로 도착한다. 8/3 로그인 게이트(5987736)의 미인증 302가 Location: /login.html을 그대로 내보내 funnel 루트(/→8788, 죽어 있음)로 튕겨 공개 사이트 전체가 502였다. 정적 에셋·login.html은 200이라 포트·프로세스 점검으로는 멀쩡해 보인다 — 죽은 건 서버가 아니라 리다이렉트 목적지다. → serve_site.py --prefix /study로 공개경로 복원, --selftest 5항목이 두 마운트 방식(프리픽스 붙은 채/뗀 채)을 함께 검증. 앞으로 8801에서 302를 만드는 코드를 건드리면 --selftest 먼저 돌린다.
git-bash에서 --prefix /study는 C:/Program Files/Git/study로 바꿔치기된다(MSYS 경로변환). → MSYS_NO_PATHCONV=1 prefix, 그리고 serve_site.py가 /로 시작 안 하면 즉시 종료(조용한 오설정 = 같은 장애 재발). HKCU Run은 Explorer가 띄우므로 무관.
"홈페이지 죽었다" 1차 점검 순서 = ①netstat -ano | grep ":880" 4포트 ②공개 URL을 curl -sL로 끝까지 추적(로컬 200이어도 공개 경로에서 나갈 수 있다) ③tailscale funnel status 매핑 ④프록시 대상 포트 개별 curl.