자체 점검 도구
TQS 인증 심사를 요청하기 전에 프로젝트 팀이 자체적으로 규격 부합 여부를 검증할 수 있는 도구와 활용 방법을 정의합니다. 본 장은 자동화 검증 도구 총괄, 도구별 설정 가이드, CI 연동 점검, 종합 리포트 생성 방법을 포함합니다.
33.2.1. 자동화 검증 도구 총괄
TQS 인증에서 요구하는 주요 검증 항목은 자동화 도구를 통해 정량적으로 측정할 수 있습니다. 다음 표는 TQS 자체 점검에 사용하는 핵심 도구와 통과 기준을 정리한 것입니다.
| 도구 | 검증 영역 | 실행 명령어 | 통과 기준 |
|---|---|---|---|
| Spotless | Java 코드 포맷 | mvn spotless:check | 포맷 위반 0건 |
| ESLint | JS/TS 코드 품질 | yarn lint | 에러 0건 |
| Prettier | 코드 포맷 | yarn format:check | 포맷 위반 0건 |
| JaCoCo | 백엔드 테스트 커버리지 | mvn test jacoco:report | 라인 80%, 브랜치 70% |
| Vitest | 프론트엔드 테스트 | yarn test:coverage | 라인 80%, 브랜치 70% |
| Lighthouse | 웹 성능/접근성 | npx lighthouse <URL> | 성능 90점, 접근성 90점 |
| OWASP Dependency-Check | 의존성 보안 | mvn dependency-check:check | CVSS 7.0 이상 취약점 0건 |
모든 도구는 CLI 환경에서 실행할 수 있어야 하며, CI/CD 파이프라인에서 자동으로 실행되도록 구성해야 합니다.
33.2.2. 도구별 설정 가이드
각 도구의 설치 및 기본 설정 방법을 설명합니다.
33.2.2.1. Spotless (백엔드 코드 포맷)
Spotless는 spotless-maven-plugin을 통해 Maven 프로젝트에 통합합니다. pom.xml의 <build> > <plugins> 섹션에 플러그인을 추가해야 합니다.
주요 설정 항목은 다음과 같습니다.
| 설정 항목 | 값 | 설명 |
|---|---|---|
| 포맷터 | Google Java Format | TQS 필수 포맷터 |
| 적용 대상 | src/**/*.java | 전체 Java 소스 |
| 제외 대상 | 자동 생성 코드 | jOOQ 생성 코드 등 |
- 포맷 검사:
mvn spotless:check(위반 시 빌드 실패) - 포맷 적용:
mvn spotless:apply(자동 수정)
33.2.2.2. ESLint (프론트엔드 코드 품질)
ESLint는 Flat Config 형식으로 설정해야 합니다. 프로젝트 루트에 eslint.config.js 파일을 생성합니다.
주요 설정 항목은 다음과 같습니다.
| 설정 항목 | 값 | 설명 |
|---|---|---|
| 설정 형식 | Flat Config | TQS 필수 형식 |
| 파서 | @typescript-eslint/parser | TypeScript 지원 |
| Vue 플러그인 | eslint-plugin-vue | Vue 3 SFC 린트 |
| TypeScript 플러그인 | @typescript-eslint/eslint-plugin | 타입 안전성 규칙 |
any타입 사용 금지 규칙(@typescript-eslint/no-explicit-any)을error로 설정해야 합니다.- Vue Composition API 강제 규칙을 활성화하는 것을 권장합니다.
33.2.2.3. Prettier (코드 포맷)
Prettier는 프로젝트 루트의 .prettierrc 파일로 설정합니다.
TQS에서 권장하는 기본 설정 값은 다음과 같습니다.
| 설정 항목 | 권장 값 | 설명 |
|---|---|---|
printWidth | 100 | 한 줄 최대 길이 |
tabWidth | 2 | 들여쓰기 크기 |
useTabs | false | 공백 사용 |
semi | true | 세미콜론 사용 |
singleQuote | true | 작은따옴표 사용 |
trailingComma | all | 후행 쉼표 사용 |
- 포맷 검사:
yarn format:check또는npx prettier --check . - 포맷 적용:
yarn format또는npx prettier --write .
33.2.2.4. JaCoCo (백엔드 테스트 커버리지)
JaCoCo는 jacoco-maven-plugin을 통해 Maven 프로젝트에 통합합니다. pom.xml에 플러그인을 추가하고 커버리지 임계값을 설정해야 합니다.
TQS 필수 커버리지 기준은 다음과 같습니다.
| 커버리지 유형 | 최소 기준 | 비고 |
|---|---|---|
| 라인 커버리지 | 80% | 필수 |
| 브랜치 커버리지 | 70% | 필수 |
커버리지 측정에서 제외할 수 있는 대상은 다음과 같습니다.
- jOOQ 자동 생성 코드
- 설정 클래스 (
@Configuration) - DTO 및 Record 클래스
- main 메서드가 포함된 애플리케이션 진입점
33.2.2.5. Vitest (프론트엔드 테스트)
Vitest는 vite.config.ts에서 테스트 설정을 관리합니다. 별도의 vitest.config.ts 파일을 사용할 수도 있습니다.
주요 설정 항목은 다음과 같습니다.
| 설정 항목 | 값 | 설명 |
|---|---|---|
| 테스트 환경 | jsdom 또는 happy-dom | DOM 시뮬레이션 |
| 커버리지 프로바이더 | v8 또는 istanbul | 커버리지 측정 엔진 |
| 커버리지 리포터 | text, html, lcov | 리포트 출력 형식 |
- 테스트 실행:
yarn test - 커버리지 측정:
yarn test:coverage - 커버리지 기준은 백엔드와 동일하게 라인 80%, 브랜치 70%를 충족해야 합니다.
33.2.2.6. Lighthouse (웹 성능/접근성)
Lighthouse는 Chrome DevTools 또는 CLI를 통해 실행할 수 있습니다. CI 환경에서는 CLI 방식을 사용합니다.
TQS 필수 점수 기준은 다음과 같습니다.
| 카테고리 | 최소 점수 | 비고 |
|---|---|---|
| 성능 (Performance) | 90점 | 필수 |
| 접근성 (Accessibility) | 90점 | 필수 |
| 권장사항 (Best Practices) | 80점 | 권장 |
| SEO | 80점 | 권장 |
- CLI 설치:
npm install -g lighthouse - 실행:
npx lighthouse <URL> --output=json --output-path=./lighthouse-report.json
33.2.2.7. OWASP Dependency-Check (의존성 보안)
OWASP Dependency-Check는 dependency-check-maven 플러그인을 통해 Maven 프로젝트에 통합합니다.
주요 설정 항목은 다음과 같습니다.
| 설정 항목 | 값 | 설명 |
|---|---|---|
| 실패 임계값 | CVSS 7.0 | 이 점수 이상의 취약점 발견 시 빌드 실패 |
| 리포트 형식 | HTML, JSON | 결과 리포트 출력 형식 |
| 자동 업데이트 | 활성화 | NVD 데이터베이스 자동 갱신 |
- 스캔 실행:
mvn dependency-check:check - CVSS 7.0 이상의 취약점이 1건이라도 발견되면 빌드가 실패합니다.
- 프론트엔드 의존성은
yarn audit또는npm audit으로 별도 점검합니다.
33.2.3. CI 연동 점검
모든 자동화 검증 도구는 CircleCI 파이프라인에 통합하여 매 커밋마다 자동으로 실행되도록 구성해야 합니다.
33.2.3.1. 파이프라인 구성 순서
CI 파이프라인은 다음 순서로 검증 단계를 실행해야 합니다.
| 순서 | 단계 | 실행 도구 | 실패 시 동작 |
|---|---|---|---|
| 1 | 코드 포맷 검사 | Spotless, Prettier | 파이프라인 중단 |
| 2 | 린트 검사 | ESLint | 파이프라인 중단 |
| 3 | 단위 테스트 | JUnit 5, Vitest | 파이프라인 중단 |
| 4 | 커버리지 검증 | JaCoCo, Vitest Coverage | 파이프라인 중단 |
| 5 | 빌드 | Maven, Vite | 파이프라인 중단 |
| 6 | 보안 스캔 | OWASP Dependency-Check | 파이프라인 중단 |
각 단계는 이전 단계가 성공한 경우에만 실행됩니다. 단계 실패 시 후속 단계를 실행하지 않고 즉시 파이프라인을 중단합니다.
33.2.3.2. CI 점검 체크리스트
CI 연동이 올바르게 구성되었는지 다음 항목을 확인해야 합니다.
- 모든 검증 도구가 CI 환경에서 정상적으로 실행되는지 확인합니다.
- 검증 실패 시 파이프라인이 중단되는지 확인합니다.
- 커버리지 리포트가 CI 아티팩트로 저장되는지 확인합니다.
- 보안 스캔 결과가 리포트로 출력되는지 확인합니다.
- 빌드 성공/실패 알림이 팀에 전달되는지 확인합니다.
33.2.4. 종합 리포트 생성
각 도구의 실행 결과를 종합하여 TQS 자체 점검 리포트를 작성해야 합니다. 이 리포트는 심사 요청 시 참고 자료로 활용됩니다.
33.2.4.1. 리포트 포함 항목
종합 리포트에는 다음 항목을 포함해야 합니다.
| 항목 | 내용 | 출처 |
|---|---|---|
| 프로젝트 정보 | 프로젝트명, 버전, 기술 스택 | 수동 작성 |
| 코드 포맷 결과 | Spotless, Prettier 실행 결과 | 도구 실행 로그 |
| 린트 결과 | ESLint 실행 결과, 경고/에러 건수 | ESLint 리포트 |
| 백엔드 커버리지 | 라인/브랜치 커버리지 수치 | JaCoCo 리포트 |
| 프론트엔드 커버리지 | 라인/브랜치 커버리지 수치 | Vitest 리포트 |
| 성능/접근성 점수 | Lighthouse 각 카테고리 점수 | Lighthouse 리포트 |
| 보안 스캔 결과 | 취약점 건수, 최고 CVSS 점수 | OWASP 리포트 |
| CI 파이프라인 상태 | 최근 빌드 성공률, 연속 성공 횟수 | CircleCI 대시보드 |
33.2.4.2. 리포트 작성 기준
- 모든 수치는 도구의 실행 결과에서 직접 추출해야 합니다. 수동으로 수치를 조정해서는 안 됩니다.
- 리포트 작성 시점의 날짜와 실행 환경(OS, 도구 버전)을 명시해야 합니다.
- 미충족 항목이 있는 경우, 해당 항목에 대한 보완 계획과 예상 완료일을 기재해야 합니다.
- 리포트는 심사 요청서와 함께 제출합니다. 리포트 없이 심사를 요청하는 것은 가능하지만, 리포트를 첨부하면 심사 기간을 단축할 수 있습니다.