kart-server

KART 백엔드: Java 17 / Spring Boot 3.5.7 / KriCommon beta.1.6.9 / SQL Server + MyBatis, 포트 4015.

설정

사내 규약에 따라 DB URL·계정·비밀번호를 src/main/resources/application.yml에 명시한다. KON·KONKIWI·Report 정보는 기존 KART의 KonString·KiwiString·ReportString을 사용한다. local/dev/prod는 공통 설정을 상속하며, API Key 전용 DB 접속정보는 각 프로파일의 kri.auth.apikey.db에 명시한다. JWT는 Contact처럼 common의 기본 서명 설정과 유효기간 86400초를 사용하며 별도 yml 설정을 두지 않는다.

Contact와 동일하게 Intranet URL은 kri.api-url.intranet-extension, API Key는 kri.auth.apikey.key, 헤더는 kri.auth.apikey.header-name에 둔다. 사용자가 제공한 KART 전용 키를 사용한다. 실제 Intranet 로그인과 프로젝트 목록/summary 조회에 사용한다. 키 미설정 또는 Intranet 로그인 실패·장애 시 REPORT_MEMBER 인증을 시도한다.

업무용 SQL Server 풀은 SQL 실행 전까지 연결을 열지 않는다. 공용 API Key 인증은 starter-data-jpa와 MySQL 드라이버를 사용하고 별도의 apiKeyDataSource/EntityManagerFactory/transaction-manager로 분리한다. 기본 Boot JPA 자동 설정은 제외하여 Report DB에 연결되지 않게 한다. API Key가 활성화되면 전용 JPA 초기화 및 preload 과정에서 해당 DB에 연결한다. 테스트는 DB를 비활성화하거나 가상 주소·모의 repository/client를 사용한다. 테스트 및 빌드에서 실제 DB/Intranet을 호출하지 않는다.

테스트 코드와 fixture(src/test)는 로컬에서만 유지하며 .gitignore로 Git에 올리지 않는다. 아래 각 항목의 "검증"·"테스트" 설명은 로컬 테스트 기준이며, 새로 내려받은 저장소에는 테스트가 포함되지 않는다.

1차 API

기능 경로
로그인 POST /api/v1/auth/login
프로젝트 목록 GET /api/v1/project/list
프로젝트 현황 최대 6개 GET /api/v1/project/summary
쿼터 설정 목록 GET /api/v1/quota/{projectType}/{pkey}/list
일별 현황 GET /api/v1/project/{projectType}/{pkey}/progress/day
전체 상태 건수 GET /api/v1/project/{projectType}/{pkey}/progress/type
LOI 현황 GET /api/v1/project/{projectType}/{pkey}/progress/loi

projectType은 0=KON, 1=KIWI이며 pkey에는 legacy 마커를 넣지 않는다. type/loi의 날짜 조건은 startDate/endDate(yyyy-MM-dd)이며 양끝을 포함한다. 날짜를 둘 다 생략하면 전체 기간이다. day는 기존처럼 날짜 범위 파라미터가 없다.

로그인 요청은 {userId,userPw}, 응답은 {accessToken,user,memberRedirect}다. user는 공용 JwtUserClaimsDto다. Intranet 실패/장애 시 is_use=1인 REPORT_MEMBER를 조회하고 모든 REPORT_MEMBER 사용자에게 userRole=9001을 부여한다. is_kri 기반 역할 계산과 특정 계정 관리자 예외는 사용하지 않는다. 로그인 이력은 기존 TB_LOGIN_LOG에 저장하며 저장 실패가 성공한 로그인을 취소하지 않는다.

조회 응답은 DTO 배열이며 기존 값의 의미를 유지하고 필드명은 camelCase로 정리했다. 목록은 projectType,rowNumber,pkey,title,surveyType,status,gkey,mkey,createDate를 반환한다. summary는 프로젝트 정보와 allCount/ongoingCount/screenCount/quotaCount/completeCount를 반환한다. 암호화 security와 ver/iskiwi는 projectType+pkey로 대체한다.

프로젝트 목록/summary는 현재 화면의 v2 KON/KIWI SQL을 기준으로 한다. 목록의 REPORT_MUST_VIEW_PROJECT 기간 예외, KIWI 접두 제목 및 통합 정렬을 유지한다. summary는 소스별 후보 TOP 50 → 상태/날짜 정렬 TOP 6 → 통합 날짜 정렬 최대 6개 순서다. CTE 최적화는 사용자 실환경에서 성능이 악화되어 기존 SQL로 복구했다. 원본 SQL fixture를 회귀 비교 기준으로 유지한다. 추가 최적화는 실제 SQL Server 실행계획과 인덱스, IO/TIME 측정 후 진행한다. v1의 단일 소스 ID 기준과 구분한다.

담당자 제외는 GET /api/v1/user/list에서 S101/S201의 userId를 한 번 조회해 두 소스의 MKEY NOT IN 바인딩 조건으로 적용한다. summary는 후보 TOP 50 선정 전에 제외한다. API 오류/잘못된 응답은 503이며 제외 조건이 빠진 목록을 반환하지 않는다. 정상 빈 사용자 목록은 제외 대상이 없는 것으로 처리한다. 실제 API 목록과 기존 person 테이블의 동등성은 별도 검수가 필요하다.

progress/type은 조사 유형별 그룹이 아니라 전체 상태 건수 1행이다. day는 기존 INDEX 존재 조건과 날짜 정렬을 유지한다. LOI는 완료/비TEST 응답의 정수 평균·2.5% 순위 경계 및 기존 시간 문자열을 유지한다. quota/list는 저장된 설정 JSON을 문자열 그대로 반환한다.

구조와 후속 범위

Contact의 controller/service/dto/persistence/config/common 구조를 따른다. enum은 common/enums에 두고 사용자가 지정한 CodeEnum/Lombok/Jackson 형태를 사용한다. mapper XML은 mybatis/mapper 아래의 ProjectMapper.xml·ProgressMapper.xml·UserMapper.xml·LogMapper.xml·QuotaMapper.xml로 구분하고 SqlSessionTemplate와 transaction-manager를 명시한다.

Repository와 Mapper 인터페이스 구조

MyBatis 호출은 Service → Repository → Mapper 인터페이스 → XML 구조를 사용한다. 업무별 Mapper 인터페이스 13개가 기존 SQL statement 68개에 대응하며, 문자열 statement ID를 Repository에서 직접 호출하지 않는다. Import의 초기화·삭제 작업도 범용 command 대신 작업별 메서드를 사용한다.

Repository는 프로젝트 유형에 따른 KON/KONKIWI 세션 선택, Report DB 세션의 명시적 사용, 조회 파라미터 가공과 Mapper 호출을 담당한다. Service는 기존 업무 규칙과 처리 흐름에 집중하며, 세션 선택이나 MyBatis 파라미터 조립을 Service로 옮겨 복잡도를 높이지 않는다.

  • KON/KONKIWI는 동일한 Mapper 인터페이스와 XML을 공유하고, Repository가 SurveySessionProvider로 선택한 세션에서 Mapper를 가져온다. DB별 Mapper나 SQL을 복제하지 않는다.
  • Project·ShareLink처럼 survey와 Report DB를 함께 사용하는 업무는 Repository에서 메서드별 연결 대상을 명확히 유지한다. Mapper를 특정 기본 DB에 일괄 연결하지 않는다.
  • Mapper 메서드는 명시적인 파라미터와 반환형을 사용한다. SQL 본문과 databaseId=survey/kart 구분, 기존 DB별 트랜잭션 경계와 롤백 동작을 보존한다. Repository 유지만으로 트랜잭션이 보장되는 것은 아니다.
  • XML namespace는 Mapper 인터페이스의 전체 클래스명과 일치시킨다. 각 SqlSessionFactory가 XML을 읽어 Mapper를 등록하며, Repository가 선택한 SqlSessionTemplate의 getMapper로 호출한다. Mapper를 Service에 직접 주입하거나 기본 세션으로 자동 연결하지 않는다.

이 계층을 유지하면 여러 DB를 사용하는 영속성 처리의 복잡도를 Repository에 모아 Service의 복잡도가 증가하는 것을 막고, DB 선택과 SQL 바인딩을 업무 로직과 분리하여 검증할 수 있다.

전환 회귀 검증은 실제 Mapper 프록시를 통한 68개 메서드의 12가지 입력 조합에서 기존 SQL·바인딩 값의 일치를 확인한다. 업로드 초기화 3종은 KON/KONKIWI 각각의 격리 H2에서 실제 Mapper 호출이 선택된 Spring 트랜잭션에 참여하고 실패 시 롤백되는지 검증한다. 이는 실제 SQL Server 및 운영 데이터에 대한 동등성 검수를 대신하지 않는다.

프로젝트 목록·최신 6개 및 파생변수 관리 목록의 조회 권한은 RequestUserContext의 getUserRole()/getUserTeam()을 기준으로 적용한다. 상세 규칙은 아래 조회 권한 항목을 따른다. 공용 JWT/API Key 인증은 유지한다. External 전용 인증과 링크의 프로젝트/페이지 제한은 아래 공유 링크 기능에서 구현한다. 현재 상태를 운영 전환 준비 완료로 간주하지 않는다.

검증

.\gradlew.bat build

테스트는 로그인 fallback·24시간 JWT·부서 제외·소스 분리·목록/summary 정렬·날짜/LOI·SQL 바인딩·7개 경로·공용 보안 필터·지연 풀 생성과 OpenAPI를 검증한다. 생성된 1차 명세는 테스트 후 build/phase1-openapi.json에서 확인할 수 있다. 실제 SQL Server 결과와 기존 응답 표본의 비교 검수는 아직 수행하지 않았다.

Gitea Maven 인증은 사용자 Gradle 설정의 giteaUser/giteaToken 또는 GITEA_MAVEN_USER/GITEA_MAVEN_TOKEN으로 공급한다.

Agent Harness local ID는 kart-server다. .agent 원본을 수정하고 검증하며 생성된 AGENTS.md/CLAUDE.md는 직접 편집하지 않는다.

mapper는 업무별 파일로 나누고 databaseId=survey/kart로 쿼리 등록 대상을 분리한다. ProjectMapper의 mustViewPkeys는 kart 세션(Report DB)을 사용하며 설문 쿼리는 KON/KONKIWI 세션을 사용한다. 사용자 인증과 로그인 이력도 각각 UserRepository/LogRepository에서 kart 세션(Report DB)을 명시한다.

공용 API Key 설정은 enabled/preload-on-startup/admin-api-enabled=true, service-code=kart-server이며 allowed-paths가 빈 목록이므로 경로 제한 없이 API Key 인증을 허용한다. 내부 관리 API 허용 IP는 Contact와 동일한 211.254.145.130이다. 일반 테스트에서는 API Key 활성화·preload·관리 API를 끈다. 전용 분리 테스트는 H2 메모리 DB에만 연결하여 활성 키·서비스 코드 필터 및 업무 DB와의 분리를 검증한다. 실제 키 등록/preload/관리 API 실행은 별도 실환경 검증이 필요하다.

ProjectMapper는 list/summary/mustViewPkeys를 유지하고 ProgressMapper/ProgressRepository는 daily/type/loi와 날짜 범위 조건을 담당한다. 현황 SQL과 API 경로는 분리 전과 동일하다.

2차 API

기능 경로
문항 목록 GET /api/v1/project/{projectType}/{pkey}/question/list
문항 상세 GET /api/v1/project/{projectType}/{pkey}/question/{qid}
스크린 현황 GET /api/v1/project/{projectType}/{pkey}/progress/screen
사용자 정의 현황 URL/파일 목록 GET /api/v1/project/{projectType}/{pkey}/progress/custom
북마크 목록 GET /api/v1/project/{projectType}/{pkey}/bookmark/list?page=TABULATION

문항 상세는 일반/파생 문항을 open·rank·attr 규칙대로 펼친 후 정확한 QID의 첫 행을 배열로 반환한다. 없으면 빈 배열이다. 메타데이터 JSON은 문자열 필드를 유지한다. KIWI 프로필 문항은 userRole=1001일 때만 포함한다. QuestionMapper는 KON/KONKIWI 세션을 사용한다.

스크린 현황은 startDate/endDate(yyyy-MM-dd)를 받으며 기존처럼 마지막 JSON 시간을 선정한 후 날짜 양끝을 포함해 필터링한다. 사용자 정의 현황은 첫 KON report URL과 REPORT_APPEND 첨부 목록이다. append_type=0 파일은 kri.kart.progress.append-directory(기본 ../report_append)에서 존재 여부를 확인하므로 배포 시 기존 파일 디렉터리를 제공해야 한다. 이 API는 파일 다운로드/복사를 하지 않으며 기존 URL·상대 경로를 유지한다.

북마크는 page가 필수이고 값을 임의 변환하지 않는다. 기존 소비자는 TABULATION/CROSSTAB을 사용한다. BookmarkMapper는 kart 세션(Report DB)에서 공개 항목과 인증된 사용자 본인의 비공개 항목을 BOOKMARK_ORDER로 조회한다. userId는 요청 파라미터로 받지 않으며 isMine은 문자열 0/1이다. Report 테이블의 기존 pure pkey 저장을 유지한다.

이번 범위에 쿼터 집계와 auth/session은 포함하지 않는다. 조회 권한은 아래 조회 권한 항목에 따라 적용한다. 개별 프로젝트 API의 공통 접근 검사 및 변경 기능의 역할 제한은 별도 범위다. 테스트가 생성하는 build/phase2-openapi.json에는 1·2차 명세가 포함된다. H2 문항/북마크 SQL 및 복합 문항 변환, 인증·입력 검증·명세·파일 존재 여부를 검증하며 실제 SQL Server 응답/OPENJSON/collation 검수는 별도 필요하다.

방문·활동 로그

  • POST /api/v1/log/visit: {projectType,pkey,logContent}. 프로젝트 정보는 함께 생략할 수 있으며 logContent에 페이지 URL/정보를 보낸다.
  • TB_SITE_LOG: 서버 내부 LogService.writeSiteLog로 기록한다. 별도 HTTP API는 제공하지 않는다.

사용자 ID와 IP는 RequestUserContext에서 가져온다. Report DB의 기존 TB_VISIT_LOG/TB_SITE_LOG 컬럼에 바인딩하여 저장한다. SITE JSON은 기존 프런트의 v2 projectCode/LOGTITLE/LOGCONTENT 형식에 projectType을 추가한다. 방문 로그의 V_PKEY는 순수 pkey이며 프로젝트가 없으면 빈 문자열이다. 스키마 변경은 없다.

방문 로그 응답은 기존처럼 text/plain PASS다. 로그 저장 실패는 경고만 남기는 기존 best-effort 정책을 유지하므로 PASS가 DB 저장 성공을 보장하지는 않는다. 활동 로그는 서버 업무 처리 지점에서 LogService.writeSiteLog를 호출한다. 현재 읽기 기능에는 기존 SITE 로그 지점이 없으며 보고서 집계·북마크 변경·업로드·링크 복사는 후속 구현 때 연결한다. 기존 프런트에서 전송하던 QUOTA VIEW도 후속 쿼터 결과 처리에서 기록한다. AuthService는 LogService.writeLoginLog를 통해 로그인 로그를 기록한다.

파생 변수 목록·북마크 변경

  • GET /api/v1/project/{projectType}/{pkey}/derived/list
  • POST /api/v1/project/{projectType}/{pkey}/bookmark
  • PUT /api/v1/project/{projectType}/{pkey}/bookmark/{bookmarkId}
  • DELETE /api/v1/project/{projectType}/{pkey}/bookmark/{bookmarkId}

파생 목록은 KON/KONKIWI의 DERIVED_VARIABLE 원본 메타데이터·정렬과 기존 문항 펼치기를 사용한다. userRole=1001은 전체 파생변수, 그 외에는 인증된 본인 팀의 GKEY만 조회한다. assign은 현재 프런트에 사용처가 없어 구현하지 않는다.

북마크 요청은 bookmarkPage(생성 시 필수), bookmarkTitle, bookmarkInfo, bookmarkJson(원본 JSON 문자열), isOpen(0/1)이다. 생성·수정은 ID를 text/plain으로, 삭제는 성공 여부를 JSON boolean으로 반환한다. 삭제 성공 시 true이며 화면 메시지는 프런트에서 처리한다. 생성 ID와 페이지별 순번을 유지하며 수정은 소유자·페이지·순번을 변경하지 않는다. JSON 원문과 공용 Report 테이블을 유지하고 모든 값을 바인딩한다. 없는 대상은 404, 변경 중 사라진 대상은 409이며 DB 오류는 공용 오류 처리로 전달한다.

삭제 후 순번 감소는 기존처럼 같은 프로젝트의 모든 페이지에 적용한다. 순번 조정·삭제는 하나의 kart 트랜잭션(Report DB)이다. Insert/Update/Delete Bookmark 활동 로그는 LogService를 통해 별도 트랜잭션으로 기록한다. 삭제 전 로그는 삭제 실패 시에도 남을 수 있으며 감사 로그 실패는 업무 저장을 취소하지 않는다.

테스트는 H2와 모킹된 인증 환경을 사용한다. 실제 SQL Server 결과 및 기존 서비스 응답 표본의 동등성 검수는 별도 필요하다. build/phase3-openapi.json은 테스트에서 생성하는 최신 명세다.

등록 양식·가이드 다운로드

  • GET /api/v1/export/form/question: KON 문항 등록 양식.xlsx 원본 파일.
  • GET /api/v1/project/{projectType}/{pkey}/export/form/data: 등록용 헤더와 별칭 한 행.
  • GET /api/v1/project/{projectType}/{pkey}/export/form/title: QID/문번/문항/Title 수정 양식.
  • GET /api/v1/project/{projectType}/{pkey}/export/guide: 원본 문항·파생 메타데이터의 GUIDE 시트.

기존 application/octet-stream과 서버 파일명을 유지한다. UTF-8 Content-Disposition은 한글 이름을 보존하고 경로·제어문자를 제거한다. 데이터 양식의 파생 헤더는 기존 관리자/DCO에 해당하는 userRole=1001일 때만 추가한다. 가이드는 펼치기 전 메타데이터를 사용하며 KIWI 프로필을 제외한다. 전체 권한 제한은 후속 일괄 적용 대상이다.

현재 설정된 KriCommon beta.1.6.9의 ExcelMapper를 재사용하고 POI 5.5.1을 컴파일 의존성에 명시했다. 공용 자동 열 너비와 빈 셀 생성을 보정해 기존 LoadFromDataTable의 기본 양식을 유지한다. 원본 문항 양식은 재직렬화하지 않는다.

기존 배포 EPPlus 4.5.3.3으로 생성한 합성 fixture와 셀 값·타입·배치·열 너비·행 높이·기본 서식을 비교한다. 실제 SQL Server OPENJSON/collation 및 운영 다운로드 표본 비교는 별도 검수가 필요하다. build/phase4-openapi.json은 테스트가 생성하는 최신 명세다.

일반 보고서 집계·Kiwi 주관식 분석

POST /api/v1/project/{projectType}/{pkey}/statistics/result

{
  "indexes": ["Q1", "Q2"],
  "banners": [["Q2", "Q3"], ["Q4"]],
  "dataScope": "ACTUAL",
  "mode": "STANDARD",
  "percentageDecimals": 2,
  "statisticDecimals": 2
}

banners의 바깥 배열은 가로 묶음, 안쪽 배열은 최대 5단계 중첩이다. 날짜는 startDate/endDate(yyyy-MM-dd)이며 끝 생략 시 당일이다. dataScope는 ACTUAL/TEST/ALL이며 항상 완료 Status=10만 집계한다. 원본·파생 결합과 필요한 KIWI 프로필 결합, 선택한 문항이 포함된 저장 그룹의 투영, 기존 UPPER/FOR XML 처리를 유지한다. KIWI 프로필 메타데이터는 기존 목록처럼 userRole=1001에만 포함한다. 프로젝트/파생변수 관리 목록의 조회 권한은 아래 조회 권한 항목에 적용되어 있으며, 개별 집계 API의 일반 프로젝트 접근 검사는 별도 범위다.

일반 표는 type=TABLE, columns/headerRows/rows를 반환한다. 셀은 columnIndex/rowSpan/colSpan의 논리 좌표와 count/percent/base, 표시 문자열을 갖는다. Total도 N/%를 함께 반환하며 복수·속성 응답의 Total %는 100을 넘을 수 있다. 분모 0 처리는 기존처럼 일반 셀·Total은 0, 척도/값 그룹은 percent=null과 표시="-"다. 숫자 통계는 statisticValue/measurement로 분리한다. PRTMODE를 받지 않으며 표시 선택은 frontend가 처리한다. headerMode=NONE/FLAT/MERGED, transpose, showSubtotals, showValueCodes, showNumericSum, 순서 있는 valueGroups[{label,values}]를 지원한다. TABULATION_0/1은 indexes=[""]로 호출한다. 쿼터 결과는 아래 전용 API로 분리한다. 집계 Excel 출력은 후속 범위다.

필터는 filter의 AST로 입력한다. 그룹 AND/OR/NOT는 children, 조건 EQ/NE/GT/GE/LT/LE/IN/NOT_IN/BETWEEN/IS_ANSWERED/IS_UNANSWERED는 dimensionId, reference=QID|VARIABLE, values를 사용한다. JSON 숫자는 수치 비교, 문자열은 기존 SQL collation처럼 대소문자 무시 비교다. 부정 조건은 일치 응답이 하나라도 있으면 제외하고 해당 키가 없는 응답은 포함하는 기존 NOT EXISTS 의미를 유지한다. IS_ANSWERED는 기존 IS NOT NULL 의미여서 빈 문자열도 포함한다. 필터 문자열을 SQL에 삽입하지 않는다. 필터 깊이는 32, 그룹당 자식은 128까지 허용한다.

주관식 문자열은 indexes=["QID_입력칸"]으로 같은 API를 호출한다. type=TEXT_ANALYSIS와 words[{text,tag,count}]를 반환하며 원문·IDKEY와 기존의 가짜 제목 데이터 행을 노출하지 않는다. 기존 REPORT_NLP_TAG/WORD의 전체·프로젝트·문항 범위 및 사전 점수 10/50/100, SL 포함·품사/길이 조건, 같은 단어의 품사별 별도 빈도와 빈도 내림차순/동률 최초 등장 순서/상위 100개를 유지한다. 문장별 분리는 토큰을 빠뜨리지 않으므로 결과를 전체 토큰 빈도로 집계한다. 별도의 불용어 규칙을 추가하지 않는다.

사용자 결정에 따라 최신 공식 KiwiJava·모델 0.24.0을 사용한다. 기존 DLL은 실제 실행에서 0.15.2로 확인되었으며 기존 모델은 Java 0.20.4에서도 로딩되지 않았다. 최신 모델 적용에 따른 형태소 결과 변화는 허용하되 Report DB 사전·품사 선택·빈도 집계 규칙은 유지한다. 0.24.0의 CONG 모델, default/typo dictionary 로딩, 이형태 통합 비활성, 오타 교정 비활성, match=0을 사용한다. 모델은 kri.kart.nlp.model-directory(기본 ./nlp_model/v0.24.0)에 별도로 설치한다. scripts/setup-kiwi-model.ps1은 공식 모델 다운로드·SHA-256 검증 후 비어 있는 폴더에만 설치한다. 모델은 Git에서 제외한다. Kiwi 라이브러리/모델이 없거나 분석에 실패하면 해당 문항에 status=503, code=KIWI_NLP_UNAVAILABLE인 error 이벤트를 반환하고 다음 문항을 계속한다.

Gradle은 Windows에서 win-x64, Linux에서 lnx-x86-64 또는 lnx-aarch64 JAR을 선택한다. Windows에서 Linux 배포물을 만들 때 ./gradlew.bat bootJar -PkiwiPlatform=lnx-x86-64로 명시한다. 배포 JAR과 JVM 플랫폼이 일치해야 하고 모델도 운영에 별도로 배치한다. Kiwi 및 모델의 라이선스는 공식 저장소의 LGPL-2.1 조건을 확인한다: https://github.com/bab2min/Kiwi/tree/v0.24.0/bindings/java .

검증: 원본 C# Report.cs를 실행한 합성 비교 기준 25개, 필터/좌표/조회 분리/인증·Swagger/API와 실제 Windows Kiwi 0.24.0 분석을 테스트한다. 네이티브 검증은 ./gradlew.bat test '-PkiwiModelDirectory=nlp_model/v0.24.0'로 실행한다. 이 속성이 없으면 해당 네이티브 테스트 1개만 생략한다. build/phase5-openapi.json은 API 테스트에서 생성된다. 실제 SQL Server 결과, Ubuntu 네이티브 실행·운영 성능은 별도 검수 대상이며 합성 테스트 통과로 운영 동등성을 주장하지 않는다.

배열 집계와 NDJSON 스트리밍

같은 POST /api/v1/project/{projectType}/{pkey}/statistics/result 경로에서 단일 index 대신 indexes 배열을 받는다. 단일 문항도 indexes=["Q1"]로 요청한다. 기존 단일 index JSON 응답 계약은 종료한다. 배열은 빈 값/null/null 요소를 허용하지 않으며 STANDARD에서 빈 문자열은 거부한다. TABULATION 모드는 indexes=[""]를 사용한다. 배너·필터·기간·표시 옵션은 배열 전체에 공통 적용한다. 중복 index도 생략하지 않고 요청 위치대로 반환한다.

문항 목록 1회, 필요한 모든 저장 그룹의 합집합을 대상으로 응답 데이터 1회를 조회하고 JSON 변환·공통 필터를 1회 적용한다. 각 문항은 기존 단건 쿼리가 포함했을 응답자 범위만 집계하므로 다른 index의 응답자가 Total에 추가되지 않는다. 주관식의 NLP 태그·사전 조회는 문항별로 유지한다. 요청 간 서버 캐시는 아직 없다. Get Report Data 감사 기록은 사용자 결정에 따라 기존 외부 Referer 조건 없이 모든 일반 통계 배열 요청마다 한 번 남긴다. 쿼터 결과는 QUOTA VIEW만 기록하고 Get Report Data는 기록하지 않는다.

200 Content-Type은 application/x-ndjson;charset=UTF-8이다. 한 줄에 JSON 이벤트 하나를 쓰고 flush하며 순차 계산한다. result에는 기존 TABLE/TEXT_ANALYSIS 응답을 result 필드로 담는다. position은 0부터 시작하는 요청 배열 위치이고 index는 요청값이다.

{"type":"result","position":0,"index":"Q1","result":{"type":"TABLE","questionId":"Q1","...":"..."}}
{"type":"error","position":1,"index":"Q2","status":503,"code":"KIWI_NLP_UNAVAILABLE","message":"문항 집계 처리에 실패했습니다."}
{"type":"complete","total":2,"succeeded":1,"failed":1}

입력·문항·필터 검증과 공통 DB 조회는 스트림 시작 전에 수행한다. 실패 시 기존 HTTP 오류를 반환한다. 스트림 시작 후 문항 계산 오류는 error 이벤트로 반환하고 다음 문항을 계속한다. HTTP 상태는 이미 200이므로 이벤트 status를 확인해야 한다. complete를 받지 못한 종료는 완료로 취급하지 않는다. 내부 경로·응답 원문·예외 상세는 오류 이벤트에 노출하지 않는다.

Spring ResponseBodyEmitter와 기존 applicationTaskExecutor를 사용한다. 스트림 전체 제한은 10분이다. 최초 인증 상태는 Spring Security의 RequestAttributeSecurityContextRepository로 동일 요청의 ASYNC 종료 처리까지 유지하며 세션을 만들거나 최초 인증을 생략하지 않는다. 종료·오류·시간 초과 시 작업 취소를 요청하고 문항 사이에서 중단 상태를 확인한다. 연결 단절은 쓰기 실패 또는 Servlet 콜백으로 감지하며, 진행 중 JDBC/네이티브 계산의 즉시 중단은 보장하지 않는다.

응답 Cache-Control: no-store, X-Accel-Buffering: no를 설정한다. 운영 프록시의 실제 버퍼링·압축·시간 제한은 배포 시 검증해야 한다. 프런트는 @kri/common 0.19.1의 streamPost로 받으며 Next 중계에서도 본문을 모아 JSON으로 재직렬화하면 안 된다. 프런트 연동은 이번 서버 변경에 포함하지 않는다.

배열 순서·중복·문항별 모수·응답 조회 1회·오류 이후 진행·취소와 인증된 MockMvc 스트리밍을 검증한다. 두 번째 계산을 대기시킨 동안 첫 NDJSON 결과가 전달되는 테스트를 포함한다. 기존 C# 계산 비교 기준 25개와 네이티브 Kiwi 검증도 유지한다.

쿼터 집계 결과

POST /api/v1/quota/{projectType}/{pkey}/{quotaOrder}/result

{"dataScope":"ACTUAL","startDate":"2026-10-01","endDate":"2026-10-13"}

빈 객체 {}도 허용하며 기본은 ACTUAL·전체 기간이다. TEST/ALL, 날짜 형식과 끝 날짜 생략 규칙은 공용 집계와 같다. 기존 quota/list는 설정 목록으로 유지한다. 결과는 단일 JSON이며 일반 보고서의 배열 NDJSON과 별개다.

해당 프로젝트와 QSORDER로 QUOTASET을 읽고 기존 front처럼 QSJSON.ROW의 첫 항목만 사용한다. ROW가 [] 또는 [""]이면 행 문항 없이 집계한다. COL은 기존 join("|")에 해당하는 중첩 배너다(묶음당 최대 5단계). 저장 FILTER는 Q| 접두사가 있으면 QID, 없으면 VARIABLE 참조다. AND/OR·괄호·비교·IN/NOT IN·BETWEEN·IS NULL/IS NOT NULL을 공용 AST로 변환한다. SQL 문자열을 실행하거나 삽입하지 않으며 지원하지 않는 저장 문법은 422 QUOTA_FILTER_INVALID로 거부한다. FILTER가 객체이면 공용 AST로 해석한다. client는 ROW/COL/저장 FILTER를 덮어쓰지 않는다.

공용 StatisticsService의 문항/응답 조회·JSON 정규화·필터, StatisticsAggregationService의 완료수 계산, StatisticsTableService의 헤더 구성을 재사용한다. 소계는 기존처럼 출력하지 않는다. 목표와 상태는 같은 survey DB의 QUOTA에서 pkey+QSORDER로 읽는다. 목표는 현재 잔여량 cnt가 아닌 ori_cnt, 사용 여부 IS_USE는 목표 조회에서 제외 조건으로 쓰지 않는다.

응답은 quotaSetId/quotaOrder/title/index/banners/columns/headerRows/rows이다. 셀에는 complete/target/achievementPercent/achievementDisplayText/displayText와 단일 목표에만 quotaId/isUsed가 있다. isUsed는 DB의 원래 문자열(예: "0", "1")이며 여러 목표가 합쳐지면 null이다. 달성률은 기존처럼 소수 2자리다. 목표=0일 때 숫자는 null, achievementState는 UNDEFINED(완료=0, 표시 "-") 또는 POSITIVE_INFINITY(완료>0, 표시 "∞")로 반환한다.

쿼터 헤더는 기존처럼 문항 제목을 제거하고 보기 레이블만 표시한다. 기존 computeQuota처럼 목표 합이 0인 행을 제거한 뒤 남은 사례 행의 완료수 합으로 Total을 다시 계산한다. Total 열은 마지막, Total 행은 행 문항이 있을 때만 마지막에 둔다. 다른 index가 없어서 Total을 전체 응답자 수로 바꾸거나 중복 선택을 제거하지 않는다. 목표가 전혀 없으면 기존 인덱스 예외 대신 rows=[]를 반환한다. 주관식 문자 결과를 완료수 표로 바꾸지 않으며 422 QUOTA_TEXT_UNSUPPORTED로 반환한다. 통계량을 완료수로 변환할 수 없는 문항은 422 QUOTA_STATISTIC_UNSUPPORTED이며 임의의 0으로 대체하지 않는다.

QUOTA VIEW는 설정 조회 후 서버 LogService가 기존 QSTITLE/QSJSON 내용과 인증된 사용자/IP로 한 번 기록한다. 목록 조회에는 남기지 않는다. 설정 없음은 404, 잘못된 요청/문항/날짜는 400, 저장 ROW/COL·쿼터 조건 오류는 422이며 DB 오류를 빈 성공으로 숨기지 않는다. DB 스키마 변경과 공유 DB 실행은 없다.

검증: 원본 C# computeQuota 후처리 합성 비교 기준 8개, 저장 필터, H2 SQL 바인딩/매핑/소스 분리, JWT API/첫 ROW/행 없는 쿼터/단일 응답 조회/사용 여부/감사 로그/Swagger. 실제 SQL Server의 기존·신규 응답 표본과 저장 FILTER 사례 검수는 별도 필요하다. 일반·쿼터 집계 Excel 및 front 연동은 후속 단계다.

공유 링크·External 인증·REPORT_URL 병행 호환

작업 경로
링크 발급/재사용 POST /api/v1/project/{projectType}/{pkey}/share
내부 링크 정보 조회 GET /api/v1/share/{urlKey}
External 랜딩 인증 POST /api/v1/external/{urlKey}/login

발급 JSON은 { "realUrl": "/Report/Crosstab", "mode": "P" }. P=Page Copy, U=URL Copy. 응답은 urlKey/url/realUrl/projectType/pkey/projectTitle/pageOnly이며 SKEY를 반환하지 않는다. 공유 가능한 경로는 기존 /Report/Current, /Report/Quota, /Report/Tabulation, /Report/Crosstab이다. 상대 내부 경로만 허용하며 query/fragment는 탐색 상태로 보존한다. 기존 프런트처럼 문항·필터 선택을 링크에 저장하지 않으며 P는 화면 단위 제한이다. 새로운 프런트도 이 탐색 경로 계약을 따라 연결한다.

신규 REPORT_URL 행에는 PKEY, PROJECT_TYPE와 기존 URL 인코딩 AES-CBC SKEY를 함께 저장한다. 기존 URL_KEY/소유자/페이지 모드를 보존하고 동일 조건이면 재사용한다. 일반 사용자 owner는 기존 REPORT, KON/KIWI identity는 그 이름을 사용한다. 발급 트랜잭션의 UPDLOCK/HOLDLOCK 조회와 키 중복 확인은 신규 서버의 동시 발급을 직렬화한다. 구서버는 같은 락 규약을 사용하지 않으므로 구서버 동시 발급까지 유일성을 보장하지 않는다. 스키마/인덱스 변경, 일괄 보정, SKEY 제거는 실행하지 않는다.

PKEY와 PROJECT_TYPE가 모두 NULL인 행만 내부 SKEY 어댑터로 해석한다. 0=KON, 1=KIWI이며 NEWSSAK/혼합 구분자/부분 NULL/잘못된 유형/프로젝트 없음/새 필드와 SKEY 불일치는 거부한다. 새 필드가 정상이고 SKEY가 없는 행도 지원한다. 운영 호환 키/IV는 사용자 규약에 따라 kri.kart.share.legacy-key/legacy-iv에 저장하며 API/로그 응답으로 노출하지 않는다. 공용 AES는 PBKDF2 키 파생을 사용하므로 기존 raw AES 키에 대한 JCE 어댑터를 REPORT_URL에만 둔다. public-origin 기본값은 기존 https://kart.kric.com이다.

랜딩 POST는 { accessToken, user, link }를 반환한다. user의 userId/userName/userTeam/userCmpn/userRole은 accessToken에 담은 값과 동일하다. 프런트는 반환된 사용자 정보를 검증해서 사용하며 역할을 자체 계산하지 않는다.

로그인 구분 userRole 접근 범위
ReportMemberLogin 9001 기존 계정별 배정 프로젝트 정책
URL Copy (link.pageOnly=false) 9002 공유 프로젝트의 Current/Quota/Tabulation/Crosstab
Page Copy (link.pageOnly=true) 9003 공유 프로젝트의 지정 보고서 화면

External user는 userId=EXTERNAL:{urlKey}, userName=CLIENT, userTeam=KART_EXTERNAL, userCmpn=""를 유지한다. 역할·External 팀/아이디·현재 저장된 링크 종류가 일치해야 하며, 하나라도 불일치하면 거부한다. 9002/9003은 External identity가 누락되어도 일반 사용자 경로로 통과하지 않는다. 기존 9001 External 토큰은 지원하지 않는다. 이 역할 분리에는 DB 스키마·데이터 변경이 없다.

공용 JWT 24시간 정책과 서명 검증을 사용하고, 서버가 발급한 KART_EXTERNAL team/EXTERNAL:urlKey identity로 매 요청 REPORT_URL 범위를 다시 확인한다. 랜딩 POST만 LANDING_CNT를 원자적으로 1 증가시키며 내부 GET/범위 검증은 증가시키지 않는다. POST는 재접속마다 한 번 호출하며 자동 재시도는 카운트를 늘릴 수 있다. 원래 랜딩의 로그인 로그와 발급의 URL Copy 로그는 LogService를 통해 기록한다.

External은 같은 프로젝트의 문항 메타데이터 및 허용 화면 API만 사용할 수 있다. P Current는 기본 현황, P Quota는 쿼터, P Tabulation/Crosstab은 일반 집계와 해당 북마크 조회를 허용한다. Crosstab P는 STANDARD만 허용한다. U는 같은 프로젝트의 위 보고서/쿼터를 허용한다. 외부 URL/파일을 반환하는 progress/custom, 프로젝트 전체 목록·summary, 파생 관리·북마크 쓰기·링크 발급·원자료/등록 양식/가이드 다운로드·정적 파일 접근은 차단한다. 방문 로그도 같은 프로젝트여야 한다. 아래 일반/쿼터 집계 Excel 경로만 해당 공유 화면에서 허용한다. 일반 사용자 역할 제한은 기존 결정대로 별도 단계다.

검증은 원본 .NET SKEY 합성 비교, 저장 필드/링크 재사용/충돌 재시도, SQL 소스/값 바인딩/대소문자 조건/랜딩 증가, 실제 공용 JWT의 페이지·프로젝트·관리 제한과 External NDJSON ASYNC 응답을 포함한다. H2에서는 SQL Server 전용 힌트/콜레이션을 그대로 실행하지 않으며 실제 SQL Server 동시 발급·구서비스 상호 운용·신규 프런트 랜딩 화면은 후속 실환경 검수다.

파생변수 관리

작업 경로
등록 POST /api/v1/project/{projectType}/{pkey}/derived
수정/ID 변경 PUT /api/v1/project/{projectType}/{pkey}/derived/{variableId}
삭제 DELETE /api/v1/project/{projectType}/{pkey}/derived/{variableId}
개별 재계산 POST /api/v1/project/{projectType}/{pkey}/derived/{variableId}/recalculate
전체 재계산 POST /api/v1/project/{projectType}/{pkey}/derived/recalculate

등록/수정 예시:

{
  "variableId": "D1", "variableTitle": "연령 구분", "variableType": "single",
  "variableInfo": {
    "1": {"value": "1", "label": "성인", "condition": "AGE >= 18"},
    "ELSE": {"value": "9", "label": "기타"}
  }
}

variableInfo는 JSON 문자열 대신 순서 있는 객체를 받으며, 저장된 DERIVEDJSON/QUESTIONJSON 구조를 유지한다. variableType은 single/multi/num이다. condition은 기존 VARIABLE 문법 문자열(Q|는 QID) 또는 기존 보고서 filter AST다. 문법 파서는 LegacyFilterService로 쿼터와 공유하며 계산은 StatisticsFilterService를 사용한다. 지원하지 않는 SQL 문법·식은 422로 거부한다. 조건을 SQL로 실행하거나 새 연산/format 해석을 추가하지 않는다. 실제 저장 조건 사례는 공유 DB 검수가 필요하다.

single은 먼저 일치한 규칙, multi는 모든 일치 규칙을 저장한다. ELSE는 미일치 응답에만 적용한다. num은 원본의 open/num 메타데이터 및 기본 변수 응답 키를 그대로 유지한다. 등록·수정 후 실제 완료 응답(Status=10, TEST 제외)을 재계산하며, 전체 재계산은 저장 Qorder 순서로 진행한다. 이전 변수 그룹은 모든 DERIVED_DATA 행에서 정리하고 다른 변수 그룹은 JSON_MODIFY로 보존한다. 빈 그룹은 제거하며 값이 생성된 응답의 DERIVED_DATE만 GETDATE 기존 형식으로 갱신한다. 삭제/ID 변경에서 원본처럼 과거 날짜 키는 별도 삭제하지 않는다.

KON/KONKIWI별 TransactionTemplate과 프로젝트 락을 사용해 정의 저장·순서 조정·JSON 정리·재계산을 함께 롤백한다. kart 트랜잭션(Report DB)으로 survey 쓰기를 묶지 않는다. 변수 중복은 DATA 응답 키/QUESTION/다른 DERIVED_VARIABLE에서 검사한다. actor/team은 인증된 RequestUserContext만 사용하고 기존 SiteLog 이벤트는 LogService를 거친다. 등록·수정은 ID, 삭제는 boolean, 재계산은 variableCount/matchedRespondents를 반환한다. 전체 matchedRespondents는 변수별 일치 건수 합이며 여러 변수에 같은 응답자가 일치하면 반복 집계된다. 프런트가 메시지를 표시한다.

검증: 순차 규칙/다중·ELSE/숫자형 저장/빈 그룹/임의 SQL 거부, H2에서 KIWI 변경 롤백과 KON 영향 없음, rename/delete 순서, SQL 바인딩·소스 분리, CRUD/recalculate JWT API. 공유 DB DML/DDL은 실행하지 않았다.

일반·쿼터 집계 Excel

  • POST /api/v1/project/{projectType}/{pkey}/export/excel/table
  • POST /api/v1/quota/{projectType}/{pkey}/export/excel

기존처럼 프런트에서 표시할 집계 표를 확정해 전달한다. ExportTable JSON 문자열 대신 tables 배열을 받고, PRTMODE 선택과 N/% 행 구성은 프런트가 맡는다. DB를 다시 집계하거나 원자료를 조회하지 않는다. 쿼터의 모든 대상 설정을 한 요청에 보내면 각 설정이 별도 시트가 된다.

{
  "turn": false,
  "tables": [{
    "head": "문항 제목", "vname": "1", "qtype": "single",
    "body": [
      {"label": "항목|1|1", "total": "전체|1|1"},
      {"label": "선택|1|1", "total": "2"}
    ]
  }]
}

body 객체의 키 순서가 열 순서이며 각 행의 키/순서가 동일해야 한다. 셀은 기존 표시 문자열 또는 값|rowSpan|colSpan을 사용한다. 일반 보고서는 목차/테이블, 제목·목차 링크·틀 고정·간격·병합·테두리·맑은 고딕 글꼴·N 괄호·소수 표시·Mean 2자리 및 전치 single의 계 열을 유지한다. 쿼터는 시트 제목/행 높이/완료·목표/자동 너비를 유지하고 달성률과 내부 quotaId/isUsed를 출력하지 않는다. 파일명은 토큰을 포함하지 않는 [REPORT]/[QUOTA]+pkey+KST 시간이다. 응답은 기존 다운로드 controller의 octet-stream/UTF-8 Content-Disposition 방식이다.

워드클라우드는 프런트가 흰 배경 PNG를 렌더링해 table.imagePng에 순수 Base64로 전달한다. SVG 문자열은 수용하지 않으며 누락된 그림을 조용히 성공 처리하지 않는다. 이미지 위치는 기존 데이터 시작 행+30px, 표 오른쪽, 크기는 1000×512px다. PNG당 5MB/4096×4096 한도이며 외부 이미지 주소를 조회하지 않는다. table 최대 1000개, body 최대 10000행, 최대 100만 셀이고 유효하지 않은 표/병합/이미지는 422다. null table/잘못된 DTO는 400이다.

KriCommon ExcelMapper로 workbook을 만들고 기존 양식만 POI로 적용한다. Java 기본 autoSize는 GDI와 다르므로 기존 맑은 고딕 9/10pt 글자 측정 snapshot을 사용한다. BMP glyph 너비와 기본 여백을 함께 저장하며, 합성 비교에서 열 너비 오차는 Excel 1/256문자 단위 한 개 이내다. 다국어 shaping/이모지, 다른 원본 서버 글꼴 버전 및 실제 운영 파일은 별도 표본 검수가 필요하다. Windows DLL/폰트 파일이나 신규 dependency를 서버에 포함하지 않는다.

검증: 원본 MakeExcel/EPPlus 4.5.3.3 생성 파일 5개를 대상으로 일반·전치·쿼터·다단 병합·여러 표·주관식 이미지를 비교한다. 셀 값·유형·서식·글꼴·정렬·병합·테두리·행 높이·열 너비·목차 링크·이미지 픽셀/크기/anchor를 검증하며 이미지 anchor 끝 좌표는 픽셀 반올림 오차 1px 이내다. External 페이지/프로젝트 다운로드 제한과 raw export 차단도 API 검사한다. 실제 프런트 PNG 생성/다운로드 화면과 실제 DB·운영 Excel 대조는 후속 작업이다.

원자료 Excel 다운로드

POST /api/v1/project/{projectType}/{pkey}/export/data

요청 예시:

{
  "type": "COMPLETE",
  "startDate": "2026-10-01",
  "endDate": "2026-10-15"
}

type은 COMPLETE(기본값, 기존 com: Status=10) 또는 INCOMPLETE(기존 not: Status<>10)다. 두 유형 모두 TEST 응답을 제외하며 미완료에서 Status=999를 별도로 제외하지 않는다. 날짜는 둘 다 생략하면 전체, startDate만 있으면 당일, 둘 다 있으면 FN_LAST_TIME(survey_date)의 DATE 양끝 포함 조건이다. endDate만 있거나 역전된 범위/알 수 없는 유형은 400이다. DB 함수의 기존 시간 기준을 유지하며 애플리케이션에서 UTC/KST를 재변환하지 않는다.

파일은 [DATA]pkey_KST시간.xlsx이며 DATA 다음 GUIDE 두 시트다. DATA는 저장 키 헤더 → 변수 별칭 → 응답 행 순서이고 고정 7열/add_column/인증된 userRole=1001의 파생변수/STRUCTURE 순서를 기존 양식 API와 공유한다. GUIDE는 기존 guide API와 같은 원본 메타데이터를 사용한다. 빈 응답 결과에서도 두 헤더 행과 GUIDE를 제공한다. 응답은 octet-stream/UTF-8 Content-Disposition/Cache-Control: no-store다.

원본·파생 응답의 DISTINCT 조인, SQL UPPER/FOR XML PATH 직렬화와 후속 ReplaceUnicodeEmpty, 빈 DAT 제외 및 잘못된 JSON의 빈 값 처리, CAPI(surveytype=2) 면접원 조회와 시작/종료/분 단위 소요시간을 유지한다. KIWI 프로필은 원본 원자료 경로처럼 결합하지 않는다. 원본 쿼리에 ORDER BY가 없어 임의 정렬을 추가하지 않았다. Excel 값은 원본처럼 문자열이며 수식으로 실행하지 않는다. 기존 HTML entity/대문자화/Unicode escape 처리 결과도 임의로 보정하지 않는다.

Common JWT 인증을 유지하고 External 링크 인증은 동일 프로젝트라도 원자료 API를 허용하지 않는다. userRole은 RequestUserContext만 사용하며 query의 userRole로 바꿀 수 없다. 일반 사용자 역할/팀/배정에 따른 접근 제한은 기존 결정대로 추후 일괄 적용한다. 기존 다운로드에는 SiteLog 지점이 없어 새로운 로그 이벤트를 추가하지 않았다.

검증: 원본 makeExportTable 및 Common 메서드/EPPlus 4.5.3.3로 만든 합성 일반·CAPI 파일 2개와 셀 값/유형/빈 셀/별칭/열 순서/시트/너비/서식 비교, survey 전용 동적 SQL의 완료·미완료/기간/CAPI 분기와 값 바인딩, KON/KONKIWI 라우팅, JWT/공유 링크 차단/DTO 검증 API 테스트. 실제 SQL Server 결과·시간 함수/운영 Excel 및 대용량 부하 비교는 별도 검수다. 현재 기존 방식처럼 응답 데이터와 workbook을 메모리에서 생성하며 스트리밍 다운로드나 캐시는 추가하지 않았다. 공유 DB 연결/DDL/DML·의존성 변경은 없다.

문항 제목·문항·응답 데이터 업로드

모두 인증이 필요한 multipart/form-data POST이며 파일 필드 이름은 file이다. 응답 메시지는 프런트에서 만들고 서버는 처리 건수만 반환한다.

경로 동작
/api/v1/project/{projectType}/{pkey}/import/title 4열 양식의 QID로 QUESTIONJSON.explain만 변경
/api/v1/project/{projectType}/{pkey}/import/question 6열 양식으로 문항과 STRUCTURE를 재구성
/api/v1/project/{projectType}/{pkey}/import/data 두 줄 헤더의 응답 파일로 UPLOAD 데이터 교체

성공 응답 예시:

{"processedRows":2,"affectedRows":2,"removedRows":0,"archivedRows":3}

processedRows는 제목 파일의 데이터 행/등록 문항/등록 응답 수다. affectedRows는 제목 UPDATE 영향 행 합 또는 등록 문항·응답 수다. 동일 QID가 여러 번 나오면 제목은 순서대로 갱신하므로 affectedRows는 고유 QID 개수가 아니다. removedRows는 삭제한 QUESTION 또는 이전 UPLOAD 응답 수, archivedRows는 DEL_로 옮긴 완료 응답 수다. 제목 업로드에서는 두 값 모두 0이다. 빈 파일·파일 누락·알 수 없는 형식·파일 내용 검증 실패는 400이며, 존재하지 않는 프로젝트는 404, STRUCTURE 누락/저장 대상 변경은 409다.

xlsx/csv/txt와 기존 20MB 제한을 사용한다. xlsx는 첫 시트의 첫 행을 건너뛰고 셀의 저장된 수식 결과를 읽으며 수식을 재계산하지 않는다. 응답 파일은 첫 행을 열 이름으로 사용한 뒤 별칭 행 하나를 추가로 제거한다. 제목·문항은 열 이름과 무관하게 순서대로 4열/6열로 해석한다. 텍스트 파일은 기존처럼 EUC-KR 기본/BOM UTF-8·UTF-16 자동 감지를 사용하며 CSV는 쉼표, TXT는 탭을 단순 분리한다. CSV 따옴표로 감싼 쉼표/줄바꿈을 새롭게 해석하지 않는다. 텍스트의 제목·문항 양식은 첫 행을 자동 제거하지 않는 기존 동작을 유지한다.

제목 업로드는 qid/variable/title/explain 순서다. 먼저 description/MM_FILE이 아닌 프로젝트 문항의 explain을 빈 문자열로 초기화하고 파일 QID별 explain을 적용한다. variable/title은 수정하지 않는다. 파일에 없는 일반 문항의 explain은 비워지며, 없는 QID는 영향 0, 중복 QID는 마지막 행이 적용된다. 초기화에서 제외된 문항도 파일에 QID를 명시하면 기존처럼 직접 갱신 대상이 된다.

문항 업로드는 variable/explain/qtype/attr_value/max_value/title 순서다. I/S/M/R/C/NPS/N/O와 속성·기타 보기, Q1부터의 QID/Qorder를 유지한다. QUESTION/QOPTION/QUOTASET과 기존 QSORDER 조건에 맞는 QUOTA를 삭제하고 STRUCTURE.QINFO/LINFO를 비운 뒤 저장한다. DERIVED_VARIABLE과 응답 데이터는 이 초기화에서 삭제하지 않는다. STRUCTURE의 문항별 배열/객체는 원본처럼 JSON 문자열 값으로 저장하며 JSON_QUERY로 구조화하지 않는다. 기존 R의 multi dataset/rank 옵션, option.option 중첩, {t}/{T}, 기타/속성 키와 GetStringFromJson의 연속 공백 제거 규칙을 유지한다.

응답 업로드는 기존 UPLOAD 응답 삭제 → TEST가 아닌 Status=10 응답의 PKEY를 DEL_+PKEY로 이동 → 새 SURVEY_TYPE=UPLOAD 응답 등록 순서다. TEST/미완료/다른 프로젝트/기존 DERIVED_DATA는 건드리지 않는다. 헤더의 구분자 앞부분을 중복 제거한 뒤 처음 6개 그룹을 제외하는 원본 규칙을 사용하므로 다운로드 양식의 고정 7열 순서를 유지해야 한다. 복수형 숫자 응답의 보기 키 당김, TQ·속성 그룹, .00 제거, 공백/따옴표 치환, INDEX/평균 시각/마지막 페이지 종료 시각과 빈 Status=10을 보존한다. 변환 결과에 같은 복수 응답 키가 반복되면 원본 JSON처럼 반복 키를 유지한다. IDKEY가 비거나 문항 응답이 없는 행, 정수가 아닌 Status, 파싱할 수 없는 날짜는 초기화 전에 실패한다. 날짜가 비면 KST 현재 시각을 사용한다.

파일 전체 해석·변환을 마친 뒤 초기화/저장을 실행하며 프로젝트별 락과 KON/KONKIWI TransactionTemplate으로 실패 시 모두 롤백한다. LogService의 Upload File 이벤트와 원본 파일 보관은 DB 롤백과 별개로 남을 수 있다. 원본 보관 경로는 kri.kart.upload.directory(기본 ./upload_data)이며 Git에서 제외한다. 파일명에는 충돌 방지 접미사를 붙이고 경로는 입력 파일명으로 정하지 않는다. 인증 주체/IP는 RequestUserContext에서만 받으며 External 링크 인증은 업로드 3종 모두 차단한다. 일반 역할/팀/배정 접근 제한은 기존 결정대로 후속 일괄 적용 대상이다.

검증은 원본 C# uploadQuestion/saveQuestion/saveStructure/uploadProjectData를 SQL 캡처 대역으로 실행해 생성한 합성 문항·응답 파일/JSON 비교, EUC-KR/BOM·파일 검증·보관, 3종×2개 소스 롤백, H2 초기화/문자열 JSON 저장, 매퍼 바인딩/소스 분리, multipart/JWT/External/건수/로그 주체 검사다. 실제 DB 연결·DDL/DML 실행·배포·의존성 변경은 없으며 운영 파일·SQL Server 트리거/제약·동시 운영 검수는 별도로 필요하다.

서비스 연동 누락 점검 및 보완

연동용 프로젝트 검색

GET /api/v1/project/list?projectType=1&intranetCode=261000_part&userTeam=R101&keyword=

검색 조건이 없으면 기존 화면용 KON/KIWI 통합 목록을 그대로 반환한다. 연동 검색을 사용하면 projectType/intranetCode/userTeam을 함께 전달해야 하며 일부만 주면 400이다. keyword는 선택이고 빈 값이면 intranetCode의 첫 _ 앞부분을 PKEY 부분 일치로 검색한다. keyword가 있으면 인트라넷 코드 조건 대신 PKEY 또는 내부 제목 부분 일치를 사용한다. R로 시작하는 팀은 GKEY 일치, 그 외 팀은 GKEY<>M101, 등록일 내림차순이라는 원본 연동 쿼리 조건을 유지한다. SQL LIKE의 %/_ 의미도 원본과 동일하다.

연동 검색은 화면용 목록과 다른 계약이다. 최근 1년/상시 노출/회사 유형/진행 상태/특정 담당자 제외 조건, KIWI 제목 접두사를 추가하지 않는다. 상태/조사 유형도 원본 코드 문자열로 유지한다. 응답은 기존 ProjectListDto에 맞춰 projectType/rowNumber를 함께 반환한다. 검색의 userTeam은 조회 조건이며 인증된 역할이나 팀 권한을 바꾸지 않는다. 연동 검색에도 인증된 역할/팀/배정 조건을 추가로 적용하므로 검색의 userTeam으로 권한 범위를 넓힐 수 없다.

실제 호출처는 Contact의 kart/project-list 프록시와 프로젝트 정보 화면이다. 새 경로/쿼리로 바꾸는 Contact 수정은 이번 범위에 포함하지 않았다. Contact의 기존 skey 발급→공유 링크 발급 흐름은 새 POST /project/{projectType}/{pkey}/share로 한 번에 대체할 수 있다.

응답자별 파생변수 재계산

POST /api/v1/project/{projectType}/{pkey}/derived/respondent/{respondentId}/recalculate

요청 본문은 없고 결과는 variableCount/matchedRespondents다. 기존 전체/개별 변수 재계산과 동일한 계산 모듈을 사용하되, 지정한 프로젝트·IDKEY의 파생 응답만 초기화/저장한다. 정의는 Qorder 순서이며 앞 변수의 결과가 뒤 변수 조건에 반영된다. 대상 응답은 기존처럼 Status=10, SURVEY_TYPE<>TEST다. 미완료/TEST/응답 없음에서도 DERIVED_DATA의 빈 행을 보장하고 해당 응답자의 기존 변수 그룹은 제거하는 원본 동작을 유지한다. DERIVED_DATE의 과거 값은 매칭이 없으면 유지한다. 다른 응답자의 그룹을 일괄 정리하지 않는다.

실제 호출처는 KON 및 KON-KIWI module/survey.js의 설문 END 처리다. 기존 경로는 인증 없이 호출하지만 새 경로는 Common JWT/API Key 인증이 필요하고 External 공유 링크 인증으로는 호출할 수 없다. 기존 소비자가 새 백엔드를 바로 사용하는 것은 아니며 자동으로 이전 서버 호출을 바꾸지 않았다. 향후 설문 시스템 전환 시 서버 측 API Key 호출/프록시가 필요하며 브라우저 코드에 시스템 API Key를 넣지 않는다.

특수 인증의 확인 범위

원본은 KON/KIWI/CLIENT 이름 또는 REPORT_EXTERNAL_SYS의 활성 system_key(PRJCT_/KRIC_SYS_)를 확인해 외부 등급 토큰을 발급한다. 로컬에서 확인한 KART 프런트·Contact·KON/KON-KIWI·프로젝트 소스 중 CLIENT 공유 진입과 KON 공유 링크 생성 호출은 확인했다. PRJCT_/KRIC_SYS_ 등록 키를 실제로 전달하는 소비자는 확인하지 못했다. 이는 운영에서 미사용이라는 판정이 아니며, 등록 데이터나 운영 호출 이력은 조회하지 않았다.

CLIENT는 이미 구현한 REPORT_URL 검증 기반 /external/{urlKey}/login으로 대체한다. 서버 간 호출은 기존 Common API Key 인증으로 검색/공유/재계산 API를 직접 사용할 수 있으므로 이름 문자열만 받는 /encrypt/external 호환 토큰 발급기는 추가하지 않는다. 시스템 키의 prefix/등록 여부만으로 사용자 권한을 발급하거나 API Key를 대신하지 않는다. 수신 API Key는 Common의 service-code=kart-server 등록·claims·활성화 설정에 따라 검증되며, Intranet 호출에 사용하는 발신 키와 자동으로 동일하게 취급하지 않는다. 등록 키를 사용하는 별도 소비자가 확인되면 해당 소비자의 대상 프로젝트/기능 범위와 새 인증 전환 계약을 추가로 확정해야 한다.

검증: 연동 검색 분기/코드 정규화/원본 조건과 H2 결과, 응답자별 SQL 스코프·완료/TEST 제외, 정의 간 의존 순서·비대상 조회 방지·KON/KONKIWI 롤백, JWT 입력/API 및 External 차단. API Key 실등록·실제 소비자 전환·공유 DB·운영 트래픽 검수는 실행하지 않았다. 일반 권한 적용, Common/Contact/기존 설문 소스 수정, DB 변경, 배포와 의존성 변경은 없다.

서버 간 연동은 Common API Key로 각 API를 직접 호출한다. 별도 시스템 로그인이나 API Key→JWT 교환, REPORT_EXTERNAL_SYS 추가 조회는 사용하지 않는다. 일반 사용자 로그인과 REPORT_URL 기반 공유 링크 인증은 유지한다.

조회 권한

  • 프로젝트 목록(화면/연동)과 최신 6개는 공용 인증이 검증한 RequestUserContext만 사용한다. JWT와 API Key 모두 동일하게 적용한다. userRole=1001은 로그인 팀에 따른 제한 및 REPORT_ASSIGN 제한 없이 조회하며 기존 업무 검색/제외 조건은 유지한다.
  • 2001/3001 및 나머지 비관리자 역할의 화면 목록은 기존 v2 분기를 유지한다: 본인 팀이 M101이 아니면 GKEY=M101 제외, R로 시작하면 본인 팀 GKEY만 조회. M101 소속 목록에는 별도 팀 조건이 없다. 최신 6개는 원본 else-if 순서를 유지하여 M101 소속은 M101만, 나머지는 M101 제외이며 R팀의 추가 동일팀 제한은 없다. 두 조회를 임의로 통일하지 않는다.
  • userRole=9001은 위 팀 조건과 REPORT_ASSIGN.member_mail=인증된 userId의 배정 PKEY 조건을 함께 적용한다. 배정 조회는 Report DB에서 요청당 한 번 후 KON/KONKIWI에 전달한다. 빈 배정은 0건이며 원본처럼 is_use를 추가하지 않는다. REPORT_MEMBER의 member_mail을 JWT userId로 그대로 사용하고, 다른 인증도 검증된 userId 그대로 사용한다. 도메인 추가/아이디 추정 변환은 하지 않는다.
  • 프로젝트 권한 조건은 SQL의 정렬/최신 50개 후보 선정 전에 적용한다. must-view는 기간 예외일 뿐 팀/배정 제한을 우회하지 않는다. 연동 요청의 userTeam은 업무 검색 조건으로 유지하고 인증 팀은 별도 파라미터로 전달한다.
  • 파생변수 관리 목록은 userRole=1001만 전체, 그 외는 인증된 본인 팀 GKEY만 조회한다. 일반 문항 목록/집계 메타데이터에는 이 관리 목록 필터를 추가하지 않는다.
  • 적용 범위는 세 조회 조건이다. 변경 API 역할/작성자 제한이나 모든 개별 API의 프로젝트 배정 검사는 새로 추가하지 않는다. 기존 External 프로젝트/페이지 검사, KIWI 프로필/출력 파생 컬럼의 1001 조건, 북마크 공개/본인 비공개 조건은 유지한다.
  • 검증은 격리된 H2의 실제 매퍼 결과·소스 라우팅, 배정 없는/불일치/주입 문자열/최신 50개 이전 필터, JWT/API Key 컨텍스트 및 위조 요청 파라미터 검증으로 수행한다. 공유 DB 접속/스키마 변경/실데이터 정합성 검수는 별도이며 프론트 변경은 없다.
Description
No description provided
Readme 916 KiB
Languages
Java 99.4%
PowerShell 0.6%