sori.studio/docs/code-audit.md

# 코드·구조 점검 — v1.12.31

2026-10-21 기준. 저장소 구조와 주요 인증·권한·업로드·미디어·DB·배포 경로를 확인했다. 자동 검증은 운영 DB와 분리한다. NAS Docker 앱의 실제 재배포는 이 점검에서 실행하지 않았다.

## 폴더와 Compose 판단

| 대상 | 처리와 이유 |
| --- | --- |
| `pages`, `layouts`, `components`, `composables` | 유지. Nuxt 화면·공통 UI·상태 로직 구분 |
| `server/api`, `server/routes`, `server/repositories`, `server/utils` | 유지. 공개 API·관리자/파일 경로·DB 조회·서버 공통 처리 구분 |
| `lib` | 유지. 서버와 화면이 공유하는 계산·검증 로직 |
| `tests` | 유지. 단위·API·브라우저 회귀 검증 소스이며 운영 컨테이너에서 실행하지 않음 |
| `test-results`, `playwright-report` | 생성물만 정리. 실패 추적용이며 재실행 시 다시 생성됨 |
| `.nuxt`, `.output`, `node_modules` | 개발·빌드·실행에 사용하는 생성물. Git과 Docker 빌드 입력에서 제외 |
| `db/migrations` | 유지. 신규 설치·기존 DB 갱신·격리 테스트에 필요한 SQL 이력 |
| `public/uploads` | 원본 유지. 실제 콘텐츠이므로 빌드 중복 복사만 제거 |
| `docker-compose.yaml` | 유지. NAS Docker 앱에서 사전 빌드한 로컬 이미지 실행 |
| `docker-compose.build.yml` | 유지. 터미널에서 소스로 이미지 빌드·배포 |
| `docker-compose.test.yml` | 유지. 운영과 분리된 폐기 가능한 테스트 DB |

## 확인 후 수정한 항목

- 호출·동적 렌더링 참조가 없는 `ProseButton.vue`, `ProseProduct.vue` 제거. 관련 현재 명세·파일 지도 정리.
- 테스트 결과물·macOS 메타데이터·빈 API 폴더 정리. 실제 업로드·환경 파일·DB 데이터 보존.
- 내부 `_import-jobs` URL 차단이 디스크 경로 정규화 전 실행되어 인코딩된 구분자와 상위 경로 조합으로 우회되는 문제 수정. 수정 전 격리 API에서 200 응답을 재현하고 차단 회귀 검증 추가.
- `.dockerignore`에 업로드·테스트·문서·모든 실제 환경 파일 제외 추가. Nitro도 업로드를 정적 복사하지 않도록 설정. 로컬 업로드 1,263개, 445,443,599바이트가 기존 `.output/public/uploads`에 중복 복사되던 상태 확인. 원본 파일은 유지.
- 운영 마이그레이션의 SQL 실행과 적용 이력을 파일별 단일 트랜잭션으로 변경. 중간 실패 중단과 절대 환경 파일 경로 검증 추가.
- 기존 미디어 API 실패는 프로필 소유자를 `avatarOwner`와 `usage`에 중복 표시하도록 기대하던 테스트 오류로 확인. 기존 명세에 맞추고 프로필 연결 이미지의 미사용 제외·삭제 차단도 함께 검증.

## 남은 우선 작업

1. **의존성 보안 갱신**: 현재 lockfile의 `npm audit`는 영향 패키지 33개(critical 5, high 23, moderate 5)를 보고한다. 직접·간접 의존성이 함께 집계되며 운영에서 악용 가능한 취약점 33개라는 의미는 아니다. 설치된 Nuxt 3.21.9, Vue SSR 3.5.40, Sharp 0.35.3, sanitize-html 2.17.6 및 `devalue`, 고정한 `brace-expansion` 등은 보안 갱신 대상이다. 개발 도구는 비활성화 상태지만 이것이 다른 패키지의 문제를 해결하지는 않는다. 강제 자동 갱신 대신 지원 버전·의존 관계를 맞추고 전체 회귀 검증을 다시 수행해야 한다. [Nuxt 권고](https://github.com/advisories/GHSA-hxcr-hm88-mpq6), [Vue SSR 권고](https://github.com/advisories/GHSA-g2v6-rqmx-r4w6), [Sharp 권고](https://github.com/advisories/GHSA-wq5f-xc86-pv6w).
2. **큰 파일의 점진적 분리**: `analytics-repository.js`, `content-repository.js`, 관리자 네비게이션·설정 화면 등이 크다. 현재 폴더 수보다 파일 내부의 책임 분리가 유지보수 과제다. 해당 기능 수정 시 조회·편집 영역 단위로 나누며 이번 정리에서 일괄 재구성하지 않는다.
3. **NAS 앱 실기 검증**: GUI 재배포가 사전 빌드한 이미지 ID를 사용하는지 확인 필요. 운영 볼륨·업로드 경로와 프로젝트명은 유지한다.

## 검증

- JavaScript 문법 360개 파일, 단위 290건, API 16건, Chromium E2E 13건 통과. 프로덕션 빌드 통과.
- 셸 구문·Compose 3종 설정 구문·운영 실행/빌드 구성 일치와 테스트 DB 외부 볼륨 미사용 확인.
- 프로덕션 빌드를 임시 업로드와 실행 중인 DB가 없는 주소로 실행해 공개 파일 200·조건부 요청 304 확인. 오류 페이지의 DB 의존을 피한 JSON 요청으로 내부 정규/인코딩 경로 3개 모두 404 확인.
- 빌드 산출물 `.output/public/uploads` 미생성, `.output` 실제 파일 합계 28,243,332바이트 확인. 원본 업로드 1,263개·445,443,599바이트 유지.

자동 테스트는 격리 DB·임시 업로드만 사용하며 운영 NAS에는 변경을 실행하지 않았다. 결과 상세는 `docs/update.md`의 v1.12.31에 기록한다. 일상 배포 명령은 기존 `docs/deploy.md`를 사용한다.