매뉴얼 명세 embedded-guide v.1.0.0.yaml 를 실제 프론트엔드 코드와 1:1 대조하여 정확성·명확성·보안을 점검했습니다.
결론. 뼈대는 정확하다. 각 페이지가 받는 파라미터 이름·태그 개수·날짜 방식은 코드와 100% 맞다. 다만 집계함수 표가 코드와 어긋나 사용자가 틀린 값을 넣어도 조용히 mean으로 바뀌는 심각한 항목이 하나 있고, 그 외 명확성·보안 관점의 보완점이 있다.
| 매뉴얼 명세 | 코드 확인 |
|---|---|
?embed=true&token=YOUR_TOKEN 기본 형식 | 일치 · auth.global.ts:14,21 |
| embed 시 GNB/탭바/네비 숨김 | 일치 · empty 레이아웃 적용, AppBar/Navigation/TabBar 없음 |
| token으로 인증 | 일치 · loginByXApiKey 세션 교환 후 URL에서 token 제거 |
날짜 포맷 YYYY-MM-DDTHH:mm:ss | 일치 · 5개 페이지 공통 DATETIME_FORMAT |
| 시작 기본값=현재-1일, 종료=현재 | 일치 · DEFAULT_START_OFFSET = -1 |
| 페이지 | 태그 키 | 날짜 방식 | 코드 근거 |
|---|---|---|---|
| CorrelationRegression | tags 복수, 쉼표 | 단일 startDateTime/endDateTime | :849-851, 829/836 |
| ParallelCoordinate | tag 단수 | 다중 period{1..3}Start/End | :558, 613-616 |
| MultiHistogram | tag 단수 | 다중 period{1..3}Start/End | :990, 1048-1053 |
| HistogramBoxPlot | tag 단수 | 단일 startDateTime/endDateTime | :1017, 995/1002 |
| TagTrend | tags 복수, 쉼표 | 단일 startDateTime/endDateTime | :1704-1706, 1683/1690 |
💬 태그가 페이지마다 tag/tags로 갈리고 날짜가 단일/다중으로 갈리는 까다로운 부분인데, 매뉴얼이 이걸 전부 맞게 적어 놓았다. 칭찬할 만하다.
enum: [mean, max, min, sum, count, first, last]commonStore.ts:2-10): mean, min, max, median, mode, first, last| 값 | 매뉴얼 | 코드 | 문제 |
|---|---|---|---|
| mean/min/max/first/last | 있음 | 있음 | OK |
sum | 있음 | 없음 | 미지원 → 넣으면 조용히 mean으로 폴백 |
count | 있음 | 없음 | 미지원 → mean으로 폴백 |
median | 없음 | 있음 | 지원하나 문서 누락 |
mode | 없음 | 있음 | 지원하나 문서 누락 |
영향. 각 페이지는 paramFunc가 유효 목록에 있을 때만 채택하고 없으면 mean으로 되돌린다(CorrelationRegression.vue:864-867). 즉 문서를 믿고 function=sum을 넣으면 에러도 경고도 없이 평균값이 나온다 — 데이터를 잘못 해석하기 딱 좋은 함정.
token은 embed=true가 있어야만 동작 — 미설명 중간코드(auth.global.ts:14-40)에서 token 처리 전체가 if (isEmbed) 블록 안에 있다. embed=true 없이 token만 붙이면 토큰은 완전히 무시되고 일반 로그인 가드로 빠진다. 매뉴얼은 둘 다 "필수"라고만 적어 종속 관계를 설명하지 않는다.
embed 값은 소문자 문자열 "true"만 유효 중간코드: to.query.embed === "true" 엄격 비교. embed=True, embed=TRUE, embed=1은 인식 안 됨. 반면 매뉴얼 스키마는 type: boolean, enum: [true]로 정의 → OpenAPI상 boolean처럼 보이나 실제론 "true 문자열 리터럴"만 허용.
true(소문자)여야 함" 명시.http://10.15.148.30(비 HTTPS)이고, JWT를 URL 쿼리스트링으로 전달.replaceState로 주소창에선 지우지만(auth.global.ts:26-28), 최초 요청 전송·서버 로그 기록은 못 막는다. HTTP 구간이면 평문 전송.10.15.148.30)와 JWT 샘플이 그대로 박혀 있다.https://<your-server> 플레이스홀더로 ④ 임베드 토큰은 짧은 만료·최소 권한으로 발급 가이드.servers ↔ x-examples 서버 불일치 경미servers.url = http://10.15.148.30(운영), 그러나 x-examples 예시는 전부 http://localhost:3000.
tag/tags required: true이나 실제로는 강제되지 않음 경미매뉴얼은 태그를 필수로 표기하나, 코드는 태그가 없으면 에러 없이 빈 검색 UI로 진입한다(if (!isEmbed || !route.query.tags)).
RawData 누락 (의도적일 가능성 높음) 경미RawData.vue:181도 isEmbed를 읽지만 컨테이너 높이만 조정하고 URL 파라미터로 데이터를 자동 조회하지는 않는다. 매뉴얼에서 빠진 것은 합리적이나, iframe으로 띄우면 embed 레이아웃은 적용되므로 한 줄 언급이 혼선을 줄인다.
이 5개 경로는 REST API 엔드포인트가 아니라 브라우저 라우트(HTML 페이지)다. OpenAPI는 API 명세 도구라 responses: 200 text/html로 얼버무릴 수밖에 없고 응답 스키마가 사실상 무의미하다. 실용적으로는 파라미터 정리·검색 목적엔 잘 작동하므로 치명적이진 않다.
authStore.ts의 clearAuth()가 xApiKey를 초기화하지 않는다(:105-116). embed 세션 로그아웃 후에도 플래그가 남으면 apiHistorian.ts:199의 인증 분기가 의도와 다르게 동작할 여지가 있다. (추측 — 실제 로그아웃 시나리오에서 재현 확인 필요)
| 순위 | 항목 | 근거 |
|---|---|---|
| 1 | function enum 수정 → mean,min,max,median,mode,first,last (sum/count 삭제, median/mode 추가) | §2-1 · 잘못된 집계 결과 유발 |
| 2 | HTTPS·토큰 보안 가이드 추가, 예시 서버 IP → 플레이스홀더 | §2-4 |
| 3 | "token은 embed=true에서만 유효" 명시 | §2-2 |
| 4 | "embed 값은 소문자 true 문자열만" 명시 | §2-3 |
| 5 | servers ↔ 예시 서버 통일, RawData 미지원 각주 | §2-5, §2-7 |
frontend/middleware/auth.global.ts:14-40frontend/stores/authStore.ts:153-172 (loginByXApiKey)frontend/plugins/apiHistorian.ts:198-207frontend/stores/common/commonStore.ts:2-10frontend/pages/analytics/{CorrelationRegression,ParallelCoordinate,MultiHistogram,HistogramBoxPlot,TagTrend}.vue