개발

요구사항

• 1.26 이상으로 이동하세요. 모듈은 최소 툴체인을 고정합니다.
• Node.js 24(참조 .node-version).
• pnpm 9.12.2, 프론트엔드와 일치 packageManager 필드.
• 설치 프로그램의 종합 릴리스 선택 테스트를 위한 jq입니다.
• Docker은 로컬 개발의 경우 선택 사항이며 컨테이너 확인에만 필요합니다.

저장소 루트에서 모든 Make 대상을 실행합니다.

명령

make clean 데이터베이스나 종속성은 제거되지 않습니다. Air는 Go 소스, 내장 SQL, go.mod, 또는 go.sum 변화. Vite는 백엔드를 다시 시작하지 않고도 HMR을 통해 프런트엔드 코드를 업데이트합니다. 사용 make dev WEB_PORT=5174 기본 프런트엔드 포트가 사용 중일 때.

Makefile은 Air v1.67.4를 통해 실행됩니다. go run; 첫 번째 호출은 이를 다운로드하고 빌드합니다. 전역 Air 설치가 필요하지 않으며 해당 종속성은 애플리케이션 모듈 외부에 유지됩니다. .air.toml 임시 빌드를 무시합니다. bin/air/ 다시 시작하기 전에 서버를 정상적으로 종료할 수 있도록 최대 10초의 시간을 제공합니다. 개발 백엔드 빌드는 CGO를 비활성화하여 프로덕션 빌드를 일치시키고 macOS C 링커 배포 대상 불일치를 방지합니다. 레이스 테스트에서는 여전히 CGO를 사용합니다.

구성

사자 .env.example 활성화하지 않습니다. 셸에서 변수를 내보내거나 단일 명령에 제공합니다.

SUBLANE_LOG_LEVEL=debug make dev
SUBLANE_ADDR=127.0.0.1:9090 ./bin/sublane

WEB_PORT 프런트엔드 포트만 변경됩니다. 백엔드가 수신 대기 127.0.0.1:8080 기본적으로 Vite는 동일하게 읽습니다. SUBLANE_ADDR 백엔드로. 기존 Docker 인스턴스 또는 다른 프로세스가 8080을 사용하는 경우 무료 백엔드 포트를 선택합니다.

SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174

make dev Air나 Vite를 시작하기 전에 백엔드 주소를 확인하고, 점유되어 있으면 실패합니다. 이렇게 하면 바인드 실패 후에도 Air가 계속 실행되는 동안 새 프런트엔드가 관련이 없거나 이전 백엔드에 자동으로 연결되는 것을 방지할 수 있습니다. 시작할 때 make dev-api 그리고 make dev-web 별도로, 동일하게 통과 SUBLANE_ADDR 두 명령 모두에.

API 프록시는 호스트(changeOrigin: false) 동일 출처 인증의 경우. 빈 테스트 데이터 디렉터리로 시작하여 설정을 연습하고 합성 자격 증명을 사용하는 양식을 통해 관리자를 만듭니다. 데이터베이스를 삭제하여 작동 중인 인스턴스를 재설정하지 마십시오.

테스트

백엔드 테스트에는 환경 검증, 새로운 SQLite 초기화, 일회성 설정/경합/롤백, 멤버 수명 주기, 사용자별 세션 제한, 비활성화 시간 취소, 역할 기반 API 액세스, 원본/본문 확인, 속도 제한, 준비 실패 및 API/정적 자산 경계가 포함됩니다. 프런트엔드 테스트에는 역할 인식 라우팅 및 메뉴, 구성원 생성/상태 변경, 설정 유효성 검사, 로그인 오류, 로그아웃 및 교차 ID 캐시 지우기, 만료, 응답 유효성 검사, 탐색 및 지속적인 테마/언어 선택이 포함됩니다. 합성 설비와 임시 데이터베이스만 사용하십시오.

개발 중에 집중 테스트를 실행합니다.

go test ./internal/server -run TestRoutesAndAssetBoundary -count=1
pnpm --dir web test src/App.test.tsx

브라우저 확인에는 데스크톱 및 좁은 레이아웃, 모바일 탐색, 직접 경로 다시 로드, 언어 변경, 밝음/어두움/시스템 테마 및 연결이 끊긴 백엔드가 포함되어야 합니다. 단위 테스트는 이러한 검사를 대체하지 않습니다.

Codex 어댑터 테스트

어댑터 테스트에서는 실제 계정을 사용하지 않습니다. 프로덕션 엔드포인트 선택이 고정된 상태로 유지되는 동안 전송 연결을 통해 로컬 가짜 업스트림을 주입합니다. 격리된 임시 구성 및 합성 모델 출력을 사용하여 설치된 Codex CLI를 실행하려면:

SUBLANE_TEST_CODEX=1 go test ./internal/server -run TestCodexCLIProtocol -count=1 -v

일반 테스트 모음에서는 이 선택형 외부 클라이언트 테스트를 건너뜁니다. 개발자의 기존 내용을 읽지 마십시오. auth.json 또는 테스트용 키체인. 라이브 공급자 및 데스크톱 승인에는 명시적으로 승인된 계정이 필요합니다. 해당 결과를 프로토콜 적용 범위와 별도로 기록합니다.

번역 추가

1. 영어 키 추가 web/src/locales/en.ts.
2. 동일한 키를 추가하세요. web/src/locales/zh.ts 그리고 모든 추가 로케일 JSON 사전. 보간 변수를 유지하고 각 언어에 필요한 복수 범주를 제공합니다.
3. 사용 useTranslation() 그리고 t() ARIA 라벨을 포함한 구성 요소.
4. 달리다 pnpm --dir web typecheck 데스크탑과 좁은 폭에서 더 긴 번역을 검사합니다. 아랍어 오른쪽에서 왼쪽 레이아웃을 확인하고 코드와 식별자를 왼쪽에서 오른쪽으로 유지하세요.

지원되는 언어는 영어, 중국어 간체, 중국어 번체, 일본어, 한국어, 스페인어, 프랑스어, 독일어, 포르투갈어, 러시아어 및 아랍어입니다. 요청 시 추가 애플리케이션 사전이 로드됩니다. 웹사이트에는 영어 주제가 포함되어 있습니다. content/docs/ 그리고 번역 content/<locale>/, 일치하는 슬러그, 현지화된 탐색, 검색 및 Markdown 내보내기가 포함됩니다. 새로운 번역은 기계의 도움을 받아 원어민의 검토가 필요합니다.

UI 기본 설정은 브라우저에 따라 다릅니다. 이는 팀 설정이 아니며 SQLite에 기록되지 않습니다.

HTTP 경로 및 데이터베이스 쿼리

HTTP 경로는 표준과 함께 chi를 사용합니다. net/http 핸들러. 리소스는 자체적으로 등록합니다. Get, Head, Post, 그리고 Patch 내부 핸들러 Route 여러 떼. 관리자가 보호하는 라우터에 관리 경로를 추가합니다. internal/server/server.go. 공개 인증 및 개인 키 경로는 명시적인 예외입니다. 세션, 역할 및 게이트웨이 전달자 인증은 라우터 수준을 통해 실행됩니다. Use, 메서드 오류와 알 수 없는 경로는 물론 일치하는 엔드포인트도 보호합니다. 공개 로그인/설정 사용 With 오리진 검증 및 조절을 위해. 핸들러에 메서드 또는 경로 디스패치 스위치를 다시 도입하지 마세요.

각 서브라우터는 JSON을 설치합니다. NotFound 그리고 MethodNotAllowed 핸들러. 405 핸들러는 파생됩니다. Allow chi가 등록한 경로에서 다음을 통해 Match, 애플리케이션 핸들러를 실행하지 않고. 상태 확인, 시스템 상태 및 정적 자산은 명시적으로 HEAD를 등록합니다. 다른 API는 선언된 메서드를 유지합니다. SPA는 루트의 GET/HEAD에만 등록되며 예약된 API 대체를 처리할 수 없습니다.

명명된 SQL 쿼리 작성 internal/storage/queries/, 도메인별로 그룹화됩니다. sqlc.yaml 통합 초기화 SQL을 스키마로 사용하고 생성합니다. internal/storage/db/. 달리다 make generate 쿼리, 스키마 또는 생성기 구성을 변경한 후. SQL 커밋 및 생성이 함께 진행됩니다. 생성된 파일을 수동으로 편집하지 마십시오. 도메인 서비스는 검증 및 트랜잭션을 자체적으로 수행하며 쿼리를 바인딩합니다. WithTx(tx), 행을 공개 응답 유형으로 변환합니다.

Makefile은 sqlc를 v1.31.1에 고정하고 이를 통해 실행합니다. go run; 첫 번째 호출에서는 도구를 다운로드하고 빌드합니다. Go에서는 생성기와 호환되는 도구 체인을 다운로드할 수 있습니다. 생성을 위해 글로벌 sqlc 설치, 클라우드 서비스 또는 데이터베이스 연결이 필요하지 않습니다. 생성기 종속성은 애플리케이션의 모듈 종속성 그래프 외부에 있습니다. 생성된 파일에는 버전이 지정되므로 일반 Go 빌드 및 프로덕션 컨테이너에는 sqlc가 필요하지 않습니다. make checkCI를 포함한 가 실행됩니다. make generate-check 오래된 생성 코드를 다시 작성하지 않고 거부합니다.

시험판 스키마 변경

001_schema.sql을 포함한 internal/storage/migrations/의 기존 파일을 보존하세요. 구조 변경은 순서가 지정된 추가 마이그레이션으로 적용하고 internal/storage/queries/의 명명된 쿼리를 갱신합니다. 시작할 때 지원되는 데이터베이스에 누락된 마이그레이션을 적용합니다. 001_settings.sql이 있는 초기 비호환 구조는 거부합니다. make generate, make generate-check와 관련 저장소 테스트를 실행하세요. sqlc는 구조를 검증하지만 실행 중인 데이터베이스를 마이그레이션하지 않습니다.

문제 해결

• 백엔드 루트 반환 frontend_not_built: 개발을 위해 포트 5173에서 Vite를 사용하거나 실행하십시오. make build 그리고 시작 bin/sublane.
• 프런트엔드에 연결 실패가 표시됩니다. Go 프로세스가 실행 중이고 Vite의 프록시가 구성된 주소를 가리키는지 확인하세요.
• 이미 사용 중인 포트: WEB_PORT Vite를 제어합니다. SUBLANE_ADDR 백엔드와 Vite 프록시를 제어합니다. 예를 들어 무료 백엔드 주소를 선택하세요. SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174. 관련 없는 프로세스를 종료하지 마십시오.
• Go는 툴체인을 다운로드합니다. 이는 설치된 Go가 다음보다 오래되었을 때 예상됩니다. go.mod 필요합니다.
• Docker 빌드를 연결할 수 없습니다: Docker 엔진을 시동한 다음 실행하세요 docker compose -f docker.compose.yaml config --quiet 그리고 docker compose -f docker.compose.yaml -f docker.compose.build.yaml build.
• 언어 또는 테마는 계속 변경됩니다. 기본 설정은 의도적으로 브라우저 로컬 저장소에 저장됩니다. 기본값을 복원하려면 기본 설정에서 변경하세요.

유지

유지하다 go.sum 그리고 web/pnpm-lock.yaml 버전 관리하에 있습니다. 종속성 업그레이드를 별도의 변경 사항으로 실행하고 타사 라이선스 공지를 보존하세요. 현지화, 이름 지정 및 접근성 변경 사항을 검토하지 않고 로컬 구성 요소 위에 최신 Shadcn 관리 트리를 복사하지 마십시오.

포장 및 출시 확인

보다 전개 컨테이너 연기 테스트 및 릴리스 작업 태그로 트리거되는 파이프라인의 경우. make test 내장된 노드 릴리스 메타데이터 테스트 및 임시 저장소 게시 테스트가 포함됩니다. make lint 릴리스/연기 스크립트 구문을 확인합니다. CI는 두 기본 Linux 아키텍처 모두에서 컨테이너를 빌드하고 테스트한 다음 릴리스 워크플로에서 정확히 테스트된 이미지를 게시하고 해당 바이너리를 추출합니다. 풀 요청 확인에는 레지스트리 자격 증명이 사용되지 않습니다.