From bc210969e2acda1d75e7c54bab486b6b5f080f23 Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Thu, 2 Jul 2026 12:22:19 +0900 Subject: [PATCH] docs: harness gitea token and canonical docs --- CLAUDE.md | 18 +++++++++++++++++- docs/ENGINEERING_HARNESS.md | 9 +++++++++ docs/INDEX.md | 3 ++- 3 files changed, 28 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7acddcc..091cda0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,20 @@ -# CLAUDE.md — TaxBaik 개발 지침 +# CLAUDE.md — TaxBaik 운영 메모 + +## 우선 기준 + +1. [docs/INDEX.md](./docs/INDEX.md) +2. [docs/ENGINEERING_HARNESS.md](./docs/ENGINEERING_HARNESS.md) +3. [docs/DOUZONE_UX_GUIDE.md](./docs/DOUZONE_UX_GUIDE.md) +4. [docs/COMMON_CODE_POLICY.md](./docs/COMMON_CODE_POLICY.md) +5. [docs/COMBO_POLICY.md](./docs/COMBO_POLICY.md) + +이 파일은 실행 절차, 서버 메모, 과거 이력만 둔다. 아키텍처/UX/콤보 기준은 위 문서를 따른다. + +## Gitea Token Rule + +- `GITEA_TOKEN_TAXBAIK`만 사용한다. +- `GITEA_TOKEN`은 사용하지 않는다. +- dispatch 전에는 `GET /api/v1/user`로 토큰 유효성을 먼저 확인한다. ## 🏗️ **아키텍처 리팩토링 (API-First 전환)** diff --git a/docs/ENGINEERING_HARNESS.md b/docs/ENGINEERING_HARNESS.md index c4ffff2..8ecd968 100644 --- a/docs/ENGINEERING_HARNESS.md +++ b/docs/ENGINEERING_HARNESS.md @@ -21,6 +21,7 @@ - Infrastructure는 Dapper SQL과 외부 시스템 구현을 가진다. - Web은 Controller, 공개 Razor Pages SSR, Blazor host, 인증/서빙 설정을 가진다. - Web.Client/Admin UI는 클라이언트 사이드 Blazor WebAssembly로 본다. 서버 DI 서비스에 의존하지 않고 API client만 호출한다. +- 관리자 호스트가 prerender를 사용하더라도 데이터 접근 원칙은 WASM + API-first다. prerender는 초기 마크업용이며 비즈니스 로직의 근거가 아니다. - JavaScript는 최소화한다. 브라우저 API, 인증 토큰 저장, 서드파티 편집기처럼 Blazor/MudBlazor만으로 해결하기 부적절한 경우에만 JS module로 격리한다. - 상속은 프레임워크 요구 또는 명확한 다형성 모델에만 사용한다. 폼/테이블/CRUD 재사용은 기본적으로 컴포넌트 합성과 작은 service/client로 처리한다. @@ -88,6 +89,14 @@ | Deploy | `.gitea/workflows/deploy.yml` | success | | Post Deploy | `.gitea/workflows/browser-e2e.yml` | success | +### Gitea Auth Harness + +- Gitea API와 workflow dispatch에는 `GITEA_TOKEN_TAXBAIK`만 사용한다. +- `GITEA_TOKEN`은 쓰지 않는다. +- 인증 헤더는 `Authorization: token `를 기본으로 한다. +- 토큰 검증은 먼저 `GET /api/v1/user`로 확인하고, 그 다음 `workflow_dispatch`를 실행한다. +- `401 invalid username, password or token`이 나오면 토큰 이름, 공백, 환경 변수 scope를 먼저 확인한다. + ## Stop Conditions - 동일 개념이 3곳 이상 다른 이름/계약으로 구현되면 기능 추가를 중단하고 정리한다. diff --git a/docs/INDEX.md b/docs/INDEX.md index 2fc89b6..06a9a5a 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -1,6 +1,6 @@ # TaxBaik Engineering Index -이 디렉터리의 문서만 현재 개발 기준의 기준점으로 사용한다. 기존 장문 문서는 이 문서에서 참조하지 않으면 보조 자료로만 본다. +이 디렉터리의 문서만 현재 개발 기준의 기준점으로 사용한다. 다른 문서는 보조 자료로만 본다. ## Canonical Documents @@ -26,6 +26,7 @@ - 문서는 짧게 유지한다. 새 문서를 만들기 전에 이 인덱스에 추가할 가치가 있는지 판단한다. - 동일한 기준을 여러 문서에 중복 작성하지 않는다. +- 아키텍처/UX/콤보/공통코드 기준은 `ENGINEERING_HARNESS.md`, `DOUZONE_UX_GUIDE.md`, `COMBO_POLICY.md`, `COMMON_CODE_POLICY.md`만 본다. - WBS 완료 여부는 체크박스가 아니라 수치와 실행 로그로 판단한다. - 코드 변경 시 관련 WBS ID를 커밋/PR 설명 또는 작업 메모에 남긴다. - 공통코드 관련 규칙은 [COMMON_CODE_POLICY.md](./COMMON_CODE_POLICY.md)만 1차 기준으로 사용한다.