docs: 로드맵에 휴대폰 앱 1.0.1 을 운영에 올린 것을 적는다

배포 뒤 고친 앱 1.0.1 을 11월 12일 올리고 실기기에서 확인했다. 「고치는 중」 줄을 운영 줄로 옮기고 앱 판을 1.0.1 로 고친다.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.claude/agents/backend-dev.md

@@ -26,7 +26,7 @@ tools: Read, Grep, Glob, Edit, Write, Bash, Skill
 
 ## 작업 순서
 
-1. 만들기 전에 `/nestjs` 의 "템플릿 기본 제공 골격"에서 재사용할 패턴을 찾는다. 같은 역할을 새로 만들지 않는다.
+1. 만들기 전에 `/nestjs` 의 "기본 골격"에서 재사용할 패턴을 찾는다. 같은 역할을 새로 만들지 않는다.
 2. 실패 경로마다 에러 코드를 정한다. 코드 없는 실패는 만들지 않는다 ([[error-codes]]).
 3. 목록 API 면 페이지네이션을 적용한다 ([[response-format]]).
 4. Swagger 데코레이터를 함께 쓴다 ([[api-design]]).

.claude/rules/checklist.md

@@ -1,11 +1,11 @@
-# 작업 점검 & 신규 프로젝트 셋업
+# 작업 점검 & 새 환경 셋업
 
-> 이 저장소는 **재사용 템플릿**이다. 클론해 어떤 프로젝트든 시작할 수 있도록, 여기에는 **언제나 유효한 공용 규칙**만 둔다(특정 시점의 구현 상태는 두지 않는다).
-> 각 스택이 기본 제공하는 골격과 확장 규칙은 [[nestjs]] · [[vue3]] · [[flutter]] · [[docker]] 스킬 참조.
+> 여기에는 **언제나 유효한 점검 규칙**만 둔다(특정 시점의 구현 상태는 두지 않는다 — 지금 상태는 각 스킬 · API 계약 · [로드맵](../../docs/roadmap.md)).
+> 각 스택에 이미 있는 골격과 확장 규칙은 [[nestjs]] · [[vue3]] · [[flutter]] · [[docker]] 스킬 참조.
 
 ---
 
-## 1. 신규 프로젝트 셋업 (클론 직후 1회)
+## 1. 새 개발 환경 · 새 서버 셋업 (처음 한 번)
 
 - [ ] 루트 `.env.{env}.example` → `.env.{env}` 복사 후 **placeholder 값 교체** (`change-me-*` 가 남아 있으면 안 된다, [[env-structure]])
       운영은 `BACKEND_API_URL`·`CORS_ORIGIN` 을 **실제 도메인**으로 — `localhost`/`example.com` 이 남으면 기동 실패한다
@@ -85,10 +85,10 @@
 
 ## 6. 기능 확장 시 따르는 순서
 
-새 기능은 만들기 전에, 해당 스킬의 **"템플릿 기본 제공 골격"** 에서 재사용할 패턴을 먼저 찾는다(같은 역할을 새로 만들지 말 것).
+새 기능은 만들기 전에, 해당 스킬의 **"기본 골격"** 에서 재사용할 패턴을 먼저 찾는다(같은 역할을 새로 만들지 말 것).
 
 1. 해당 디렉터리 스킬 규칙 확인 ([[nestjs]] / [[vue3]] / [[flutter]])
-2. 기본 제공 골격(인터셉터·필터·에러 레지스트리·dio client·예제 모듈)에서 패턴 재사용
+2. 기본 골격(인터셉터·필터·에러 레지스트리·dio client·예제 모듈)에서 패턴 재사용
 3. 표준 응답/에러 흐름 준수 ([[response-format]] · [[error-codes]] · [[api-design]])
 4. 실패 경로마다 에러 코드 지정 — `BusinessException('CODE')` 로 던진다
 5. env 신규 값은 루트 `.env` 부터 ([[env-structure]])

.claude/rules/coding-common.md

@@ -18,6 +18,7 @@ description: 세 클라이언트(backend/frontend/flutter) 공통 코딩 규칙
 - 절대경로 alias 사용 (TS `@/`, Dart `package:`), 깊은 상대경로(`../../`) 지양
   — backend/frontend 모두 `@/` → `src/` 로 설정되어 있다 (backend 는 `tsconfig.json` paths + jest `moduleNameMapper`)
 - **자동 생성 파일은 직접 수정하지 않는다** — `*.generated.ts`, `*.g.dart` 는 생성 스크립트를 통해서만 바꾼다 ([[error-codes]])
+- 소스에 보이지 않는 글자(nbsp · U+2028 · U+FEFF 등)는 `\uXXXX` 이스케이프로 적되, **저장한 뒤 바이트로 확인한다** — 편집 도구가 U+00A0 이상의 이스케이프를 실제 글자로 풀어 저장한 일이 있다(2026-11-10 — 정규식 안의 U+2028 이 줄 끝이 되어 컴파일 실패, 16단계에서는 U+FEFF). 풀리면 `String.fromCharCode(0x2028)` 처럼 글자 코드로 만든다
 
 ## 네이밍 규약
 

.claude/rules/env-structure.md

@@ -5,7 +5,7 @@ description: 환경변수 단일 진실 공급원(SSOT) 구조 — 루트 .env.{
 
 # 환경변수 구조 (단일 진실 공급원: 루트 `.env`)
 
-이 템플릿은 **루트 `.env.{APP_ENV}` 가 모든 설정의 단일 진실 공급원(SSOT)** 이다.
+이 저장소는 **루트 `.env.{APP_ENV}` 가 모든 설정의 단일 진실 공급원(SSOT)** 이다.
 값을 한 곳에서만 관리하기 위해, 서비스(backend/frontend)는 자체 env에 값을 중복 작성하지 않고 **루트 → docker-compose 가 주입한 값을 그대로 사용**한다.
 
 ```

.claude/rules/security.md

@@ -64,7 +64,7 @@
   `img onerror` 같은 처리기가 실행된다. CSP 가 막아도 그것에만 기대지 않는다 ([[vue3]] 체크리스트 "외부 HTML")
 ### 파일 업로드
 
-템플릿은 `modules/upload` 에 로컬 디스크 기준 골격을 제공한다. 새 업로드 엔드포인트는 이 패턴을 복제한다.
+`modules/upload` 에 로컬 디스크 기준 골격이 있다. 새 업로드 엔드포인트는 이 패턴을 복제한다.
 
 - **확장자와 MIME 을 둘 다** 검사한다 (`upload.config.ts`). 확장자만 보면 위장이 쉽고,
   MIME 만 보면 클라이언트가 보낸 값이라 신뢰할 수 없다.

.claude/rules/testing.md

@@ -5,7 +5,7 @@ description: 세 스택 공통 테스트 규칙 — 테스트 위치/네이밍,
 
 # 테스트 규칙
 
-> 템플릿은 각 스택에 테스트 러너가 준비되어 있다 — backend `jest`, frontend `vitest`, flutter `flutter_test`.
+> 각 스택에 테스트 러너가 준비되어 있다 — backend `jest`, frontend `vitest`, flutter `flutter_test`.
 > 새 로직을 추가하면 최소한의 테스트를 함께 작성한다.
 
 ## 공통 원칙

.claude/skills/docker/SKILL.md

@@ -85,7 +85,7 @@ sudo docker compose --env-file .env.production logs -f backend
     이 경로만 오류 로그를 `error` 부터 남긴다: 본문을 임시 파일에 받는다는 warn 이 조각마다 남았다),
     그 밖은 1m(백엔드 JSON 파서 한도). 앞의 두 값은 루트 env 한 곳만 고치면 백엔드와 nginx 가 함께 바뀐다 (frontend 컨테이너만 다시 만들면 된다).
     JSON 한도(1m·4m)는 계약과 백엔드 코드의 고정값이라 env 로 바꾸지 않는다 — 바꾸려면 계약·백엔드 파서·`frontend/nginx.conf` 를 함께 고친다.
-  - 시간 제한: `/api/messages`·`/api/drafts`·`/api/message-deletions`·`/api/mail-events` · 대용량 조각 · 대용량 받기 90s, `/api/mail-attachments` 150s, 그 밖의 `/api` 는 nginx 기본 60s (`proxy_read_timeout`).
+  - 시간 제한: `/api/messages`·`/api/drafts`·`/api/message-deletions`·`/api/mail-events` · 대용량 조각 · 대용량 받기 · 휴대폰 앱 받기 90s, `/api/mail-attachments` 150s, 그 밖의 `/api` 는 nginx 기본 60s (`proxy_read_timeout`).
     응답 전체가 아니라 백엔드에서 "두 번 읽는 사이"의 시간이다 — 실시간 알림은 1시간 이어져도 25초마다 오는 ping 이 새로 세게 한다(머리글이 오지 않으면 90초에 504).
   - **실시간 알림(SSE) `/api/mail-events`**(계약 2절 "실시간 알림"): 이 경로만 버퍼링 · 캐시 · 압축을 끄고 `X-Accel-Buffering` 을 앞으로 넘긴다
     (외부 프록시가 nginx 계열이면 그쪽도 이 응답만 버퍼링을 끈다). 버퍼링을 켜 두면 머리글을 첫 이벤트까지, 백엔드가 청크 없이 닫아 끝내는 응답이면 끝까지 붙잡는다(2026-10-28 확인).
@@ -106,13 +106,19 @@ sudo docker compose --env-file .env.production logs -f backend
       `nginx-api-errors.conf`(이름 있는 오류 location — `@api_not_found` 404 `RES_001` 포함). 공개 화면 `/s/` 는 `no-referrer`(주소에 토큰) · `noindex` · `no-cache`.
     - 받기 `GET /api/public-links/{token}/files/…` · `GET /api/messages/{id}/large-files/…` 는 SSE 처럼 버퍼링 · 압축을 끄고 `X-Accel-Buffering` 을 넘긴다
       (기본값이면 받는 사람마다 1GB 까지 임시 파일에 받아 둔다). Range · If-Range 는 그대로 — 206 · 416 은 백엔드가 만든다.
+      **휴대폰 앱(APK) 받기 `GET /api/app-releases/android/latest/file`**(2026-11-08 — 계약 1절 "휴대폰 앱 받기", 포털 · 로그인한 직원, 판마다 65MB 안팎 — 기기 종류 셋(ABI)이 한 파일에 든다)도 같은 줄들이다 —
+      머리글을 대용량 받기와 같은 도우미(`backend/src/shared/utils/download-headers.ts` — `X-Accel-Buffering: no`)가 만든다. 정보 `GET /api/app-releases/android/latest`(JSON)는 받기 location 에 들지 않고,
+      공개 내려받기 server 에서는 그 밖의 `/api` 처럼 404 `RES_001` 이다.
       머리글 버퍼는 `proxy_buffer_size 16k` + `proxy_busy_buffers_size 16k`(둘이 함께 — 하나만이면 `nginx -t` 가 실패) — 한글 255자 이름이면 머리글이 3.5KB 라 기본 4KB 에 아슬아슬하다.
       버퍼링을 끈 받기에서 `proxy_read_timeout` 은 돌지 않고, 받는 쪽이 60초 동안 하나도 받지 않으면 `send_timeout`(기본 60s)으로 끊는다 — 느려도 조금씩 받으면 이어진다(2026-10-30 확인).
     - **동시 연결 상한**(`limit_conn` — 받기가 연결 둘과 백엔드의 파일을 잡으므로): 클라이언트 주소마다 공개 10 · 앱 안 30(사무실 NAT), 서버 전체는 경로마다 따로 공개 400 · 앱 안 200
       (함께 세면 바깥 IP 몇십 개로 직원의 앱 안 받기까지 막힌다 — 2026-10-30 리뷰).
+      휴대폰 앱 받기는 앱 안 받기의 그릇(`download_app_ip` 30 · `download_app_total` 200)을 함께 쓴다 — 둘 다 로그인한 직원의 받기라 막으려는 것이 같고, 그릇(받기 600 개 — `worker_connections` 셈)을 늘리지 않으려고.
+      판이 나온 날 사무실 휴대폰이 한꺼번에 받다 대용량 받기와 합쳐 주소마다 30 에 닿으면 넘은 받기만 429 다(잠시 뒤 다시 — 처리 중인 요청만 센다).
       넘으면 429 `REQ_001`(JSON). 클라이언트 주소는 `X-Forwarded-For` 의 **마지막 칸**(외부 프록시가 이어 붙인 값 — 없으면 접속 주소)이다 — 앞 칸을 꾸며도 바뀌지 않는다.
       8080 에 프록시를 건너뛰고 바로 붙는 길이 있으면 주소마다 한도는 피한다(경로마다 서버 전체 한도는 그대로) — 그 길을 막는 것이 ACG · proxy 네트워크다. IPv6 는 /64 로 묶지 않는다.
-      ⚠️ **받기 location 은 `/api/` 블록 바로 안의 대소문자를 가리지 않는 정규식 하나씩이다**(공개 `~* ^/api/public-links/.+/files/`, 앱 안 `~* ^/api/messages/.+/large-files/`) —
+      ⚠️ **받기 location 은 `/api/` 블록 바로 안의 대소문자를 가리지 않는 정규식 하나씩이다**(공개 `~* ^/api/public-links/.+/files/`, 앱 안 `~* ^/api/messages/.+/large-files/`,
+      휴대폰 앱 `~* ^/api/app-releases/.+/file` — 끝을 묶지 않는다: 끝의 `/` 같은 꼴도 상한을 타게) —
       백엔드 라우팅이 대소문자를 가리지 않던 때 `/FILES/` · `/api/Messages/…` 처럼 글자 하나로 상한과 `X-Accel-Buffering` 넘김을 비켜 갔다(2026-10-30 리뷰).
       같은 블록의 prefix 에 `^~` 가 있으면 그 아래 경로는 블록의 정규식을 건너뛰므로 `/api/messages` 는 `^~` 없이 둔다. id · 토큰 칸은 `.+`(nginx 는 `%2F` 를 풀어 location 을 고른다).
       포털이 닫는 공개 API 도 `~* ^/api/public-links(?:/|$)` 다. 백엔드도 라우팅이 대소문자를 가린다(두 겹 — [[nestjs]] "전역 HTTP 설정").
@@ -216,7 +222,8 @@ sudo docker compose --env-file .env.production logs -f backend
       긴 한글 이름 파일의 받기 응답 머리글(3.5KB)이 4k 를 넘으면 그 받기만 502 다.
 - 업로드 중 임시 디스크: 백엔드는 첨부를 `/tmp/arasystem-mail-uploads`(컨테이너 쓰기 계층)에, nginx 는 요청 본문을 자기 임시 폴더에 받는다.
   필요한 공간은 동시 업로드 수 × 20MB 정도. backend 를 `read_only` 로 바꾸면 그 경로에 **tmpfs 가 아닌 볼륨**을 붙인다 (tmpfs 는 메모리 한도에 잡힌다).
-- **업로드 파일은 named volume `<PROJECT_NAME>_uploads` 에 쌓인다** (`/api/files`, 메일 서명 그림은 그 안의 `mail-signatures/` — 서명 표와 함께 백업한다). 호스트 디렉터리(`./data/uploads`)를 쓰지 않는 이유 —
+- **업로드 파일은 named volume `<PROJECT_NAME>_uploads` 에 쌓인다** (`/api/files`, 메일 서명 그림은 그 안의 `mail-signatures/` — 서명 표와 함께 백업한다,
+  휴대폰 앱 APK 는 그 안의 `app-releases/` — 판마다 65MB 안팎 · 지우는 명령이 없어 올린 판이 모두 남는다 · 매일 백업에 든다). 호스트 디렉터리(`./data/uploads`)를 쓰지 않는 이유 —
   `sudo docker compose` 가 없는 디렉터리를 root 소유로 만들어 backend(node, UID 1000)가 쓰지 못한다. 새 named volume 은 이미지의
   `/app/uploads`(node 소유) 소유자를 물려받는다 (2026-10-27 운영 이미지로 확인). 개발만 `./data/uploads` 바인드 마운트다.
   백업은 매일 백업(`ops/` — 아래 "백업 · 감시")에 든다.
@@ -333,7 +340,8 @@ docker compose -f docker-compose.runner.yml --env-file .env up -d
   `docker-compose.remote-proxy.yml` 도 이 잡이 본다 — 게시 주소를 준 `config -q` · proxy 네트워크가 빠졌는지 · 값이 없으면 멈추는지, 그리고 `frontend-bind-check` 를
   `compose run`(프로젝트 이름 `ci-bind-<run_id>`, DB 이미지)으로 받을 값 · 거절할 값을 하나씩 돌린다.
   11단계부터는 nginx 를 두 꼴(공개 호스트를 가를 때 · 아닐 때)로 `nginx -t` 하고 렌더링 결과(server 이름 · 포털이 닫는지 · 받기 영역 400 · 200)와 틀린 `SHARE_PUBLIC_URL` 의 기동 거부를 본다.
-  "대용량 받기 경로 시험"은 같은 이미지에 가짜 백엔드를 얹어 받기 경로의 대소문자 · `%2F` · 겹 `/` 변형이 모두 상한(429 JSON) · `X-Accel-Buffering` 을 타는지 실제 요청으로 본다.
+  "대용량 받기 경로 시험"은 같은 이미지에 가짜 백엔드를 얹어 받기 경로의 대소문자 · `%2F` · 겹 `/` 변형이 모두 상한(429 JSON) · `X-Accel-Buffering` 을 타는지 실제 요청으로 본다
+  (휴대폰 앱 받기 `…/file` 도 — 앱 안 받기와 그릇을 함께 쓰는지 · 공개 호스트는 404 인지 · 정보 경로 `…/latest` 는 타지 않는지. "nginx 설정 검사"는 `limit_conn download_app_*` 가 두 꼴 모두 둘씩인지 센다).
   "닫는 경로 시험"(12단계)은 같은 가짜 백엔드로 두 server × 닫는 경로 셋(`/api/internal` · `/api/health` · 공개 API)의 변형이 nginx 가 직접 낸 JSON 인지 본다 —
   대소문자 · 겹 `/` · `%2F` · `%69` · `%5C` · `..` · absolute-form · 끝 `/` 는 404, 날 `\` · `#` · 0xA0 는 400, 쿼리의 `\` 는 통과, `/api/internals` 같은 이웃 경로는 백엔드로 넘어간다
   (경계 확인은 wget — busybox `nc` 는 표준 입력이 끝나면 닫아 프록시를 거친 응답을 받지 못한다). 정적 검사는 include 와 `if ($request_target_rejected)` 를 지시어로만 센다(주석 처리한 줄은 세지 않는다).

.claude/skills/flutter/SKILL.md

@@ -10,10 +10,10 @@ description: Flutter 모바일 앱(flutter/) 개발 규칙 — Dart Sound Null S
 
 ---
 
-## 템플릿 기본 제공 골격
+## 기본 골격
 
-> 이 템플릿은 네트워크 · 세션 · 라우터 · 모듈 틀을 **기본 제공**한다. 새 코드는 이 파일들의 패턴을 재사용한다(같은 역할을 새로 만들지 말 것).
-> 앱 이름 "ARA SYSTEM", 식별자 `kr.it.arasystem.app`(Android applicationId · iOS bundle id — 스토어에 올린 뒤에는 못 바꾼다), 패키지 `arasystem_app`.
+> 네트워크 · 세션 · 라우터 · 모듈 틀이 이미 있다. 새 코드는 이 파일들의 패턴을 재사용한다(같은 역할을 새로 만들지 말 것).
+> 앱 이름 "ARA SYSTEM", 식별자 `kr.it.arasystem.app`(Android applicationId · iOS bundle id — 직원 휴대폰에 설치한 뒤에는 못 바꾼다: 식별자가 다르면 다른 앱이라 그 위에 설치되지 않는다), 패키지 `arasystem_app`.
 
 | 제공 항목 | 위치 | 비고 |
 | --- | --- | --- |
@@ -25,9 +25,9 @@ description: Flutter 모바일 앱(flutter/) 개발 규칙 — Dart Sound Null S
 | 앱 로그인 저장소 | `lib/features/auth/data/` | 계약 1절 "앱 로그인"(`/auth/app/login` · `refresh` · `logout`(리프레시 토큰 + Bearer) + Bearer `me`, 인터셉터 줄 밖의 세션 확인 `readSessionDirect`). 실패는 늘 `DioException`(`error` 에 `ApiException` — 응답 모양이 틀리면 `SYS_001`, `apiFailure()`). 모델은 손으로 쓴다(`AppLoginResult` · `AuthSessionInfo` · `SessionRestriction` — 모르는 제한은 `unknown`). 로그인 화면이 칸에 보이는 실패(`kLoginInlineCodes`)는 알리지 않는다 |
 | **로그인 화면 (네 단계 — `App1Login`)** | `lib/features/auth/presentation/pages/`(login · login_code · password_change · two_factor_setup · restricted_login) · `widgets/`(`login_frame` · `login_fields` · `login_parts`) · 글 `core/constants/login_texts.dart`(제목은 `screen_titles.dart`) · `data/`(`two_factor_repository` · `support_contact_repository` · `authenticator_launcher`) | 노티파이어의 제한 단계 API(`attempt` · `passedCodeStep` · `heldLoginListenable` · `changePassword` · `enableTwoFactor` · `finishRestrictedStep` → `RestrictedStepResult { done, needsPassword, stale }`). 로그인 비밀번호는 두 제한 단계에서만 10분 쥔다(모르는 제한 · 제한이 풀리면 지움). 칸 · 상자에 보이는 코드만 알림을 끈다(`kLoginInlineCodes` · `kLoginCodeInlineCodes` · `kPasswordChangeInlineCodes` · `kTwoFactorSetupInlineCodes` — 앱 디자인 README 의 표), `AUTH_002` 는 스낵바 없이 로그인 화면 상자만. 2단계 키 · otpauth 주소는 그 화면 State 에만. **url_launcher**: `canLaunchUrl` 은 쓰지 않는다(debug 판이 주소째 로그를 남긴다) — `launchUrl(externalNonBrowserApplication)` 만, 실패 예외에 주소가 들어 있어 삼킨다, `<queries>` 는 필요 없다. 한글 줄바꿈은 `shared/widgets/keep_all_text.dart`(시험은 `findCopy`). 보안 설정 요청 한도 `kSecuritySettingTimeout` 30초 |
 | **메일 목록 (`App1MailList`)** · 앱 틀 | `lib/features/mail/` — data(models · `mail_repository.dart`) · domain(`mailbox_tree` · `mail_list_merge` · `mail_bulk` — 순수 함수) · presentation(`pages/mail_list_page.dart` · providers · widgets), 틀 `core/router/app_shell.dart` · `shell_bar.dart`, `core/utils/`(`app_foreground` · `accessible_navigation` · `korean_format`), `shared/widgets/confirm_dialog.dart`, 시험 도구 `test/support/mail_fakes.dart` · `mail_harness.dart` | **틀은 Scaffold 가 아니다**(Column + 탭 막대 — 탭 안 화면마다 자기 Scaffold 를 둔다, 없으면 스낵바 · Material 조상이 없다). 탭 막대는 `MediaQuery.removePadding(removeTop)` 으로 감싸고, 화면이 숨기려면 `ShellBarHidden`(모듈마다 센다 — 보이는지는 TickerMode). Scaffold 는 넓은 단추 자리에 안전 영역을 넘기지 않으니 Scaffold 밖에서 읽어 넘긴다. 목록 상태는 메일함마다(`mailListProvider(String?)` autoDispose), 세션이 바뀌면 `mailAccountProvider` 로 처음부터. 알림은 두 갈래 — 단추 있는 `mailToastProvider`(한 번에 하나 · 화면 낭독기 켠 동안 닫지 않음) · 단추 없는 `mailNoticeSinkProvider`(전역 스낵바). 생명주기 안에서는 프로바이더를 바꾸지 않는다(그린 뒤 · 마이크로태스크), 다른 노티파이어 인스턴스를 든 노티파이어는 세션이 바뀐 뒤 다시 읽는다. 가짜 서버는 응답이 한 프레임 안에 오므로 "받는 중이 끝나는 순간"을 기다리는 위젯을 만들지 않는다 |
-| **메일 읽기 (`App1Reader`)** | `lib/features/mail/` — domain(`mail_html`(두 번째 정화 · 중첩 비용 · CSP 문서 · 중계 그림 바꿔 넣기) · `mail_images` · `mail_links` · `compose_request` · `mail_body_notices`) · `data/`(`models/message_detail.dart` · `mail_link_launcher.dart`) · presentation(`pages/message_reader_page.dart` · `providers/message_reader_controller.dart` · `attachment_downloads.dart` · widgets `mail_body_view` · `reader_*`), 시험 도구 `test/support/fake_webview.dart`(`WebViewPlatform.instance`) · `file_fakes.dart` | **WebView 에는 `buildMailDocument` 의 문서만 넣는다**(CSP 를 맨 앞 · JS 끔 · 처음 문서 말고는 탐색을 막음 · 안드로이드는 파일 · content 접근 · 위치 · 섞인 내용 끔, 아래 틀(iframe)의 탐색은 판정을 거치지 않으니 막는 것은 정화(내용째 버림)와 CSP 다). 받은 HTML 은 서버가 정화했어도 `sanitizeMailHtml` 을 한 번 더 지난다 — package:html 은 `parse().body`(`parseFragment` 는 맨 위 형제가 많으면 제곱), 그 전에 `htmlNestingCost`(선형 · 파서보다 깊게 센다)로 한도를 보고, 바로 할지 isolate 로 보낼지는 `mailBodyBuildPlaceOf` 하나로 고른다. 중계 그림은 Dio(Bearer)로 받아 `data:` 로 넣고 토큰은 WebView 에 가지 않는다 — 문서에 싣는 양은 **나온 횟수까지** 센다(`resolveProxiedImages`). 응답은 그 요청이 바꾼 칸만 지금 요약에 덮는다(`_applyResponse`). 메일 id 마다 autoDispose 프로바이더(라우트 `ValueKey(id)`) · 받기 세대 · 본문 세대 · 세션 세대로 늦은 응답을 버린다. 목록에는 `MailChange(updated, removedIds)` 로 알린다. 쓰기 화면을 여는 값은 웹과 같은 쿼리(`replyTo` · `all` · `forward` · `draft` — `composeIntentOf`), mailto 로 채울 값은 go_router `extra` 의 `ComposePrefill` |
+| **메일 읽기 (`App1Reader`)** | `lib/features/mail/` — domain(`mail_html`(두 번째 정화 · 중첩 비용 · CSP 문서 · 중계 그림 바꿔 넣기) · `mail_images` · `mail_links` · `compose_request` · `mail_body_notices`) · `data/`(`models/message_detail.dart` · `mail_link_launcher.dart`) · presentation(`pages/message_reader_page.dart` · `providers/message_reader_controller.dart` · `attachment_downloads.dart` · widgets `mail_body_view` · `reader_*`), 시험 도구 `test/support/fake_webview.dart`(`WebViewPlatform.instance`) · `file_fakes.dart` | **WebView 에는 `buildMailDocument` 의 문서만 넣는다**(CSP 를 맨 앞 · JS 끔 · 처음 문서 말고는 탐색을 막음 · 안드로이드는 파일 · content 접근 · 위치 · 섞인 내용 끔, 아래 틀(iframe)의 탐색은 판정을 거치지 않으니 막는 것은 정화(내용째 버림)와 CSP 다). **보이는 것이 없는 본문이면 본문 칸(WebView)을 두지 않는다**(2026-11-12 — 첨부만 있는 메일에서 아래 절반이 빈 칸으로 남고 첨부가 위 절반에서 잘렸다): 판정은 정화 길이 함께 낸다(`SanitizedMailBody.hasVisibleContent` — 남긴 글 가운데 `core/utils/visible_text.dart` 의 `hasVisibleText`(공백 · 제어 문자 · Default_Ignorable(제로폭 · 방향 표시 · 한글 채움 등) · 점자 빈칸은 보이지 않음)인 글, 주소가 남은 그림(`_attributesOf` 가 src 를 맨 앞에 쓰는 모양에 기댄다 — 외부 그림은 받기 전에도), 글 없이 그려지는 `hr` · `li` · `details` · `q`. 꾸밈(style · bgcolor · border)만은 치지 않는다. 고르는 본문(`displayedHtmlBody`)은 그대로) → 상태 `bodyEmpty` → 머리의 최대 높이가 화면 전체(`kReaderHeadMaxFraction` 대신 — 그림 받는 진행 막대 자리만 뺀다 · 0 아래로 내려가지 않게), 아래 막대가 없는 메일(예약)은 머리 스크롤에 시스템 아래 여백을 더한다. 문서를 만들기 전(`document == null`)은 지금처럼 본문 자리의 진행 줄. 받은 HTML 은 서버가 정화했어도 `sanitizeMailHtml` 을 한 번 더 지난다 — package:html 은 `parse().body`(`parseFragment` 는 맨 위 형제가 많으면 제곱), 그 전에 `htmlNestingCost`(선형 · 파서보다 깊게 센다)로 한도를 보고, 바로 할지 isolate 로 보낼지는 `mailBodyBuildPlaceOf` 하나로 고른다. 중계 그림은 Dio(Bearer)로 받아 `data:` 로 넣고 토큰은 WebView 에 가지 않는다 — 문서에 싣는 양은 **나온 횟수까지** 센다(`resolveProxiedImages`). 응답은 그 요청이 바꾼 칸만 지금 요약에 덮는다(`_applyResponse`). 메일 id 마다 autoDispose 프로바이더(라우트 `ValueKey(id)`) · 받기 세대 · 본문 세대 · 세션 세대로 늦은 응답을 버린다. 목록에는 `MailChange(updated, removedIds)` 로 알린다. 쓰기 화면을 여는 값은 웹과 같은 쿼리(`replyTo` · `all` · `forward` · `draft` — `composeIntentOf`), mailto 로 채울 값은 go_router `extra` 의 `ComposePrefill` |
 | 받은 파일 · 고른 파일 · 형식 | `lib/core/files/` — `downloaded_files.dart`(`DownloadedFileStore` · `CacheDirFileStore` · `FileOpener`) · `picked_files.dart`(`PickedFileStore` · `PlatformPickedFileStore` — 채널의 `pick`) · `file_names.dart`(`safeFileName` · `displayFileName`) · `file_types.dart`(`fileOpenTypeOf` · `isBlockedFileOpen`), 안드로이드 `MainActivity.kt`(채널 `kr.it.arasystem.app/files`) · `res/xml/downloaded_file_paths.xml` · 매니페스트의 FileProvider `${applicationId}.downloads` | 모듈 공통(메일 첨부 · 나중의 파일 모듈). 자리는 `cacheDir/downloads/<무작위 16자>/<정리한 이름>` 뿐 — **짝 셋**: Dart `kDownloadedFilesFolder` · `downloaded_file_paths.xml` 의 cache-path · `MainActivity.kt` 의 `DOWNLOADS_DIR`(채널 이름도 짝). Kotlin 은 canonical 경로로 그 폴더 안인지 다시 보고 읽기 권한을 한 번만 준다. 파일 여는 플러그인(open_filex 등)은 쓰지 않는다 — 저장소 권한 · 기기 전체 경로를 더한다. 열 형식은 확장자 먼저(`package:mime`), 보낸 쪽 형식은 확장자를 모를 때만 — 형식 글 모양 검사는 짝: Kotlin `MIME_PATTERN` · `GENERIC_TYPE`. 막는 형식(웹 문서 · svg · 설치 파일 · 인증서)은 받지도 않는다. **고른 파일**(메일 쓰기 2차): 고르는 창(`ACTION_GET_CONTENT` — 권한 없음 · `*/*` · 여러 개)으로 고른 파일을 `cacheDir/uploads/<무작위 16자>/<정리한 이름>` 에 복사본으로 둔다 — **짝 둘**: Dart `kPickedFilesFolder` · `MainActivity.kt` 의 `UPLOADS_DIR`(다른 앱에 건네지 않아 FileProvider xml 에는 없다). 채널 인자 · 답의 칸 · 값도 짝이다 — Dart `PlatformPickedFileStore.pick` · `PickResult.parse` · `PickedFile.fromChannel` ↔ Kotlin `ARG_*` · `KEY_*` · `OUTCOME_*` · `STATUS_*`. Kotlin 은 `content://` 만 읽고, Dart 사전 검사와 같은 차례(개수 → 형식 → 파일당 → 합계 — `copyPicked` ↔ `precheckPickedFile`)로 넣을 파일만 복사한다 — 미리 거르기일 뿐 판정은 Dart 가 다시 한다. 확장자를 떼는 규칙도 짝(Kotlin `displayFileName` · `extensionOf` · `isDartWhitespace` ↔ Dart `displayFileName` · `extensionOf` · `trim()`). 복사본 이름은 Kotlin `safeFileName`(Dart 와 같은 규칙), 보이고 보내는 이름은 `displayFileName` 이다. 복사 스레드는 Throwable 까지 잡아 한 번만 답한다. 고르기와 모두 지우기는 차례로 돌고, 지우기는 기호 링크를 푼 경로로 복사본 폴더 바로 아래 한 칸만 지운다. `pick` 은 그 차례 안에서 `kPickTimeout`(10분) 시한을 둔다 — 넘으면 `timedOut`(Dart 에만 있는 결과)으로 끝내고 차례를 넘긴다(늦게 온 복사본은 다음 정리에). 파일 고르는 플러그인은 쓰지 않는다(권한 · 기기 전체 경로) |
-| **메일 쓰기 (`App1Compose` — 1차 · 2차)** | `lib/core/people/`(사람 고르기 — 주소 칩 · 추천 맞추기 · 그룹, 모듈 공통. 표본 표 `test/core/people/recipient_match_samples.dart` 는 웹 · 백엔드와 **세 쪽 짝**) · `features/mail/domain/`(`compose_body` 직렬화 · `compose_fit`(`buildInitialQuote`) · `mail_quote` · `compose_draft_body`(`buildDraftBody` · `draftBodyPlaceOf`) · `compose_reply` · `compose_send` · `compose_attachments`(2차 — 형식 표 · 한도 · 사전 검사) · `compose_signature` · `html_nodes`) · `data/`(`compose_models` · `compose_payload` · `repositories/compose_repository.dart`) · presentation(`pages/message_compose_page.dart` · `providers/compose_controller.dart`(화면마다 하나 — `ComposeArgs.instance`, autoDispose) · `draft_autosave.dart` · `attachment_uploads.dart`(`AttachmentUploadQueue` — 둘씩 · 취소 · 다시 올리기) · `signature_image_provider.dart` · widgets `compose_*`) · `core/utils/utf16_length.dart` · 시험 도구 `test/support/compose_fakes.dart` | 본문 모양은 계약 2절 "앱이 만드는 모양". 웹 짝(`mail-address.ts` · `recipient-match.ts` · `MAIL_HTML_STYLES` · `docToText` · `fit-draft` · `DRAFT_*` · `shouldRenewSendKey`)은 각 파일 머리말에 적었다 — 한쪽을 고치면 둘 다. **package:html 의 `text` · `querySelectorAll` · `innerHtml` · `outerHtml` 은 깊이만큼 되풀이한다** — 쓰기 화면은 `html_nodes.dart`(되풀이 없는 글 모으기 · 찾기 · 직렬화)를 쓰고, 저장본 · 원문은 읽기 화면과 같은 한도 · 문턱(`mailBodyBuildPlaceOf`)으로 그 자리 · isolate · 읽지 않음을 고른다. **화면을 떠나도 끝까지 가야 하는 일(보내기)은 기다림을 시작하기 전에 `ref.keepAlive()` 를 잡고 try/finally 로 놓는다**(2026-11-07 리뷰 — 저장을 기다리는 사이 내려가 메일이 나가지 않았다). 임시 저장은 Timer 만 쓴다(시험은 `tester.pump` 로 시간을 넘긴다). 보내기 결과는 `mailToastProvider` 의 마감 알림(목록 · 읽기 화면이 그린다). 서버와 같은 한도를 거는 칸은 `Utf16LengthLimitFormatter`(UTF-16 단위). **첨부(2차)**: 형식 표 `kMailAttachmentTypes` 는 **짝: 백엔드 `attachment.policy.ts` 의 `ATTACHMENT_TYPES`** — 시험이 그 파일을 읽어 표와 `MAX_ATTACHMENTS_PER_MESSAGE` 를 맞춰 본다 (앱 CI 는 flutter/ 가 바뀐 커밋에서만 돈다 — 백엔드 표만 고친 커밋에서는 이 시험이 돌지 않으니 함께 고친다). 사전 검사는 웹 `precheckAttachment` 의 차례, 보내기 막기는 웹 `sendBlockOf` 의 차례(가져오는 중은 올리는 중 다음). 저장소 `uploadAttachment`(multipart `file` · 확장자의 정식 형식 · 보내기 5분 · 받기 60초 · 알림 끔 — 401 뒤에는 FormData 를 복제해 복사본을 처음부터 다시 읽는다) · `getAttachmentLimits`(`GET /api/mail-quota`). 다 올리면 서버의 이름 · 크기로 싣는다(이름 255자 — 웹과 같다, 2026-11-07 리뷰). `MAIL_004` 뒤 다시 올릴 수 없는 고른 파일은 `problem: missing` 으로 막는다(웹 `markMissing`). 시험 도구 `FakePickedFiles`(`test/support/file_fakes.dart`) · `FakeComposeBackend` 의 `uploads` · `uploadGates` · `quota` · `quotaGate` · `FakeServer.readRequestBodies` |
+| **메일 쓰기 (`App1Compose` — 1차 · 2차)** | `lib/core/people/`(사람 고르기 — 주소 칩 · 추천 맞추기 · 그룹, 모듈 공통. 표본 표 `test/core/people/recipient_match_samples.dart` 는 웹 · 백엔드와 **세 쪽 짝**) · `features/mail/domain/`(`compose_body` 직렬화 · `compose_fit`(`buildInitialQuote`) · `mail_quote` · `compose_draft_body`(`buildDraftBody` · `draftBodyPlaceOf`) · `compose_reply` · `compose_send` · `compose_attachments`(2차 — 형식 표 · 한도 · 사전 검사) · `compose_signature` · `html_nodes`) · `data/`(`compose_models` · `compose_payload` · `repositories/compose_repository.dart`) · presentation(`pages/message_compose_page.dart` · `providers/compose_controller.dart`(화면마다 하나 — `ComposeArgs.instance`, autoDispose) · `draft_autosave.dart` · `attachment_uploads.dart`(`AttachmentUploadQueue` — 둘씩 · 취소 · 다시 올리기) · `signature_image_provider.dart` · widgets `compose_*`) · `core/utils/utf16_length.dart` · 시험 도구 `test/support/compose_fakes.dart` | 본문 모양은 계약 2절 "앱이 만드는 모양". 웹 짝(`mail-address.ts` · `recipient-match.ts` · `MAIL_HTML_STYLES` · `docToText` · `fit-draft` · `DRAFT_*` · `shouldRenewSendKey`)은 각 파일 머리말에 적었다 — 한쪽을 고치면 둘 다. **package:html 의 `text` · `querySelectorAll` · `innerHtml` · `outerHtml` 은 깊이만큼 되풀이한다** — 쓰기 화면은 `html_nodes.dart`(되풀이 없는 글 모으기 · 찾기 · 직렬화)를 쓰고, 저장본 · 원문은 읽기 화면과 같은 한도 · 문턱(`mailBodyBuildPlaceOf`)으로 그 자리 · isolate · 읽지 않음을 고른다. **화면을 떠나도 끝까지 가야 하는 일(보내기)은 기다림을 시작하기 전에 `ref.keepAlive()` 를 잡고 try/finally 로 놓는다**(2026-11-07 리뷰 — 저장을 기다리는 사이 내려가 메일이 나가지 않았다). 임시 저장은 Timer 만 쓴다(시험은 `tester.pump` 로 시간을 넘긴다). 보내기 결과는 `mailToastProvider` 의 마감 알림(목록 · 읽기 화면이 그린다). 서버와 같은 한도를 거는 칸은 `Utf16LengthLimitFormatter`(UTF-16 단위). **첨부(2차)**: 형식 표 `kMailAttachmentTypes` 는 **짝: 백엔드 `attachment.policy.ts` 의 `ATTACHMENT_TYPES`** — 시험이 그 파일을 읽어 표와 `MAX_ATTACHMENTS_PER_MESSAGE` 를 맞춰 본다 (앱 CI 는 flutter/ 가 바뀐 커밋에서만 돈다 — 백엔드 표만 고친 커밋에서는 이 시험이 돌지 않으니 함께 고친다). 사전 검사는 웹 `precheckAttachment` 의 차례, 보내기 막기는 웹 `sendBlockOf` 의 차례(가져오는 중은 올리는 중 다음). 저장소 `uploadAttachment`(multipart `file` · 확장자의 정식 형식 · 보내기 5분 · 받기 60초 · 알림 끔 — 401 뒤에는 FormData 를 복제해 복사본을 처음부터 다시 읽는다) · `getAttachmentLimits`(`GET /api/mail-quota`). 다 올리면 서버의 이름 · 크기로 싣는다(이름 255자 — 웹과 같다, 2026-11-07 리뷰). `MAIL_004` 뒤 다시 올릴 수 없는 고른 파일은 `problem: missing` 으로 막는다(웹 `markMissing`). 시험 도구 `FakePickedFiles`(`test/support/file_fakes.dart`) · `FakeComposeBackend` 의 `uploads` · `uploadGates` · `quota` · `quotaGate` · `FakeServer.readRequestBodies`. **칸 줄**은 `ComposeFieldRow`(`widgets/compose_recipient_field.dart`) 하나 — 칸 이름 72 · 글자 15 · 간격 6 · 여백 4 4 4 16, 칸 이름 · 오른쪽 단추는 첫 줄(`ComposeFieldRow.lineHeight` 48)의 가운데(받는 사람은 `firstLineHeight` 로 칩 줄 40 을 넘겨 칩이 여러 줄이어도 첫 칩 줄에 맞춘다), 아래 선은 `foregroundDecoration` 이라 초점으로 굵어져도 칸이 움직이지 않는다. 입력칸은 `borderlessInputDecoration`(2026-11-12 — 아래 함정). 본문 칸 최소 높이는 `composeBodyMinHeightOf`(원본 메일이 있으면 150 · 없으면 240 — 서명과 상관없다, 보드 App1Compose) |
 | **메일 검색 (`App1Search` — 1차 · `App1SearchConditions` — 2차)** | domain `search_text`(**짝: 웹 `search-match.ts` · `mail-search.ts` · 백엔드 `search-text.ts`** — 표본 표는 시험이 `backend/test/search-text-samples.ts` 의 FOLD · GRAM 을 직접 읽는다 · `test/support/ts_table.dart`) · `search_highlight`(짝: 웹 `search-highlight.ts`) · `search_conditions`(2차 — **짝: 웹 `mail-search.ts` · `mail-vacation.ts`** — 조건 다듬기 · 합친 낱말 수 · 기간 · after/before(기기 시간대 0시 → UTC, 끝 날짜는 다음 날 0시) · 강조 쿼리 · "나") · `data/models/mail_search.dart` · `mail_repository`(`searchMessages` — 응답의 `Date` 로 서버 시각 · `searchIndexStatus` · `getMessage(highlight)`) · presentation(`pages/mail_search_page` · `providers/mail_search_controller`(화면마다 — `MailSearchArgs.instance`, autoDispose) · `mail_search_state`(`waitsForMore`) · `mail_search_view` · widgets `mail_search_bar`(+ 공용 `LineBreaksToSpacesFormatter`) · `mail_search_states` · `highlighted_text` · `mail_search_conditions_sheet`(2차)) · `core/utils/js_case.dart` | 탭 안 `/mail/search`(시작한 메일함은 `extra` 의 `MailSearchStart`, 검색어는 주소에 싣지 않는다). 이어 찾기는 한 차례 `kMailSearchFillMaxRequests`(5) · 20통, 모자라면 [더 찾기]로 멈춘다. 검색 세대 + `CancelToken`(새 검색 · 화면 닫기에 끊는다), 준비 상태는 따로 세대. 결과는 `MailChange` 와 붙잡힌 줄 다시 받기(보낼 시각 + 2초)만 반영한다. **강조 위치는 그 응답의 글에만**. 읽기 키는 `MessageReaderArgs(id, highlight)`, 결과에서 연 메일은 `MailSearchOpen`. 조건(2차)은 화면 상태 `MailSearchState.conditions` 로 이어 찾기 · 새로고침 · 다시 시도 · 찾을 곳 바꾸기에 이어지고, "나"는 `mailSelfProvider`. 시트 가림막은 테마의 바닥 시트 가림막(`AppColors.backdrop` — 옮기기 시트도), 날짜 창은 `showDatePicker(barrierColor:)` · 머리 22(`datePickerTheme`). 노랑 `AppColors.searchMark` 는 **짝: 웹 `--color-search-mark` · `mail_html.dart` 의 mark**. 시험 도구는 `FakeMailBackend` 의 `defaultSearch`(받은 시각 내림차순 · `searchCursorAfter` 는 그 줄 다음부터) · `move` · `searchResponder` · `searchGate` · `searchHighlights` · `highlightDetails` · `searchIndex` |
 | HTTP 클라이언트 | `lib/core/api/dio_client.dart` · `dio_provider.dart` | Dio 둘: 화면용(인터셉터 줄 `ResponseInterceptor` → `AuthInterceptor` → `ErrorNotifyInterceptor`)과 갱신 · 다시 보내기 · 로그인 없는 앱 설정용(언래핑만 — `publicDioProvider`. 인증 인터셉터는 요청을 한 줄로 세워 앞 요청의 미리 갱신을 기다리게 하므로, 앱을 띄우자마자 묻는 앱 설정은 줄 밖으로 보낸다). baseUrl=dotenv `API_URL`(`api_config.dart`), User-Agent `ARASYSTEM-App/<판> (Android <판>; <기종>)`(`user_agent.dart`). `LogInterceptor` 는 넣지 않는다(비밀번호 · 토큰). 시험은 `httpClientAdapterProvider` 로 가짜 서버를 끼운다 |
 | 언래핑 · 코드 정규화 | `lib/core/api/response_interceptor.dart` · `api_error_mapper.dart` | `{success,data}→data`(스트림 · 바이트는 그대로 — 그 **실패** 본문은 64KB 까지 읽어 `error.code` 를 꺼낸다(`decodeRawErrorBody`). 스트림을 받는 도중의 실패는 인터셉터를 거치지 않아 부르는 쪽이 `SYS_001` 로 알린다(`DownloadInterrupted`). 비동기 처리기는 무슨 일이 있어도 `handler.next` 로 끝낸다 — 던지면 요청이 매달린다), 200 + `success:false` 도 실패, 실패는 모두 `DioException.error` 에 `ApiException`. 상태 → 코드 폴백(웹 `resolveCodeByStatus` 와 같다) |
@@ -36,13 +36,15 @@ description: Flutter 모바일 앱(flutter/) 개발 규칙 — Dart Sound Null S
 | **인증 인터셉터** | `lib/core/api/auth_interceptor.dart` · `token_refresher.dart` | `QueuedInterceptor`. Bearer 붙이기 · 액세스 토큰이 없거나 30초 안에 끝나면 미리 갱신 · 401 이면 갱신 한 번 → 원래 요청 한 번 다시(로그인 · 갱신 · 로그아웃 제외 — `ApiPaths.noRefresh`). 갱신은 `TokenRefresher` 가 **한 번에 하나**(동시 401 은 토큰 세대를 보고 묶는다). 갱신 401 · 유예 응답(`tokens: null`) → 토큰 지움 + `AUTH_002` + 세션 끝, 5xx · 연결 끊김은 세션을 두고 그 코드로 알림, 갱신 중 로그아웃이면 받은 토큰을 버리고 서버 세션도 끝낸다. 갱신의 일시 장애는 같은 토큰 세대에서 5초 동안 다시 쓴다(`kRefreshFailureReuse` — 연결이 끊긴 동안 줄 선 요청마다 갱신하지 않게). `AUTH_010` 은 세션 노티파이어에 다시 맞춰 달라고 하고(`requestRecheck` — 안전 한도 65초) renewed 면 한 번 다시 보낸다 · restricted · stale 은 알리지 않는다 · unknown 은 알린다(웹 `recheckRestriction` 과 같은 결). 같은 토큰으로 줄 선 `AUTH_010` 은 한 번만 묻는다(그사이 새 토큰이면 묻지 않고 다시 보내고, restricted 는 그 세대 동안 · unknown 은 5초 다시 쓴다). **다시 보낸 요청의 실패도 첫 요청과 같은 규칙**(401 · `AUTH_010` 마다 한 번씩 — `kAuthRetriedExtraKey` · `kRestrictionRetriedExtraKey`). **요청을 보낸 세션이 끝났으면**(세션 세대 `kSessionGenerationExtraKey` 가 다르다 — 로그아웃 · 세션 끝 · 그 뒤 다른 직원 로그인) 어떤 실패든 조용히 끝낸다 — 401 은 사용자가 로그아웃했으면 `AUTH_001` 그대로, 세션이 끝났으면 `AUTH_002`. 실패를 내보내기 전에 Bearer · 비밀 본문을 지운다(`withoutSecrets`). 처리기는 뜻밖의 예외에도 꼭 부른다(`SYS_001`). 이 인터셉터의 오류 처리 안에서 보내는 요청(갱신 · 세션 확인 · 다시 보내기)은 모두 안쪽 Dio — 같은 줄로 보내면 서로 기다린다 |
 | 오류 알림 | `lib/core/api/error_notifier.dart` | 전역 `ScaffoldMessenger` 키 하나로 스낵바(웹 `showErrorUI` 자리). 같은 코드는 3초 안에 다시 띄우지 않는다. 요청마다 끄기: `Options(extra: {kSilentExtraKey: true})` 또는 코드 목록(`ApiOptions.silentFor`) — `request_flags.dart`. **비밀이 든 요청**(비밀번호 · 코드 · 리프레시 토큰이 본문에)은 `ApiOptions.secret(...)` 으로 보낸다 — 실패 예외의 본문을 비워 던져 화면이 `AsyncValue` 로 상태에 두어도 된다 |
 | 토큰 보관 | `lib/core/storage/` — `token_store.dart` · `secure_store.dart` · `first_run_marker.dart` | 리프레시 토큰만 `flutter_secure_storage`(키 상수 `kRefreshTokenKey`), 액세스 토큰은 메모리. 새 토큰은 받자마자 저장(로그인 저장이 실패하면 그 세션을 끝내고 `SYS_001`, 갱신 저장이 실패하면 이번 실행은 메모리의 새 토큰으로 이어 가고 다음 읽기 · 저장 때 다시 쓴다). 보안 저장소 일은 부른 차례대로 하나씩(로그인 저장과 로그아웃 지우기가 엇갈리지 않게). 토큰 세대 `generation` · 세션 세대 `sessionGeneration`(지울 때만 오른다), 로그아웃은 `signOut()`(메모리를 곧바로 비우고 서버 logout 에 쓸 토큰을 돌려준다). 만료는 기기 시계로 보지 않는다 — 응답의 `Date`(서버 시각, `core/api/server_time.dart`)로 남은 시간을 재고 받은 때부터 센다. 첫 실행 표시(`shared_preferences` — 참 · 거짓 하나)가 없으면 보안 저장소를 모두 지운다(iOS Keychain 은 앱을 지워도 남는다). Android 는 백업을 껐다(`AndroidManifest` · `res/xml/data_extraction_rules.xml`) |
-| 테마 | `lib/core/theme/` | 색은 웹 `tokens.css` 를 `ColorScheme` 에 손으로 대응(`app_colors.dart` · `app_theme.dart` — 시드 생성 쓰지 않음, Material 에 없는 색은 `AppExtraColors`). 간격 · 모서리 `AppSpacing` · `AppRadius`, 누르는 곳 최소 48dp(`AppSize.touchMin`). 글자는 `app_typography.dart` 한 곳 — 화면 글 15 · 입력 칸 16 · 위 막대 제목 18 · 메일 본문 15/1.75 는 확정(`docs/design/app/README.md`), 그 밖의 역할은 임시 값 |
+| 테마 | `lib/core/theme/` | 색은 웹 `tokens.css` 를 `ColorScheme` 에 손으로 대응(`app_colors.dart` · `app_theme.dart` — 시드 생성 쓰지 않음, Material 에 없는 색은 `AppExtraColors`). 간격 · 모서리 `AppSpacing` · `AppRadius`, 누르는 곳 최소 48dp(`AppSize.touchMin`). 글자는 `app_typography.dart` 한 곳 — 화면 글 15 · 입력 칸 16 · 위 막대 제목 18 · 메일 본문 15/1.75 는 확정(`docs/design/app/README.md`), 그 밖의 역할은 임시 값. 테두리 없는 입력칸(칸 줄이 아래 선 · 초점을 그리는 쓰기 화면 · 검색 막대)은 `borderlessInputDecoration` — 테마의 입력칸 테두리를 물려받지 않는다 |
 | 글꼴 | `assets/fonts/` · `assets/licenses/pretendard-ofl.txt` · `core/theme/app_fonts.dart` | Pretendard 1.3.9 정적 OTF 넷(400 · 500 · 600 · 700 — 웹 npm `pretendard` 와 같은 파일). OFL 1.1 글을 `LicenseRegistry` 에 올린다(설정 › 앱 정보 › 오픈소스 라이선스) |
 | **새 메일 알림 (`App1Push`)** | `lib/core/push/` — 포트 `push_messaging.dart`(FCM 은 `firebase_push_messaging.dart` — 띄우지 못하면 `UnavailablePushMessaging`) · `notification_system.dart`(채널 · 알림 지우기 · 휴대폰 설정 열기 — 안드로이드 `NewMailNotifications.kt`, 채널 `kr.it.arasystem.app/notifications`) · `push_preferences.dart`(이 휴대폰의 값 — `shared_preferences`, 참 · 거짓과 FID 하나뿐) · `push_state.dart`(상태 · 설정 줄 모습 `pushRowStatusOf` · 권하기 줄 `showsPushOffer`) · `push_controller.dart`(앱에 하나 — `PushRegistrar` 를 구현) · `push_registration.dart`(서버 저장소 · `pushRegistrarProvider`) · `push_events.dart`(앞에서 받음 · 누름 — 라우터 `core/router/push_navigation.dart` 가 누른 알림을 늘 메일 받은편지함으로) · `push_target.dart` · 글 `push_texts.dart`. 화면 `features/mail/presentation/widgets/push_offer_line.dart` · `features/settings/presentation/widgets/settings_notification_row.dart` | **보낼 조건** = 받을 수 있는 휴대폰 ∧ 서버가 보낼 수 있음(app-config `pushAvailable` — 모르면 보낼 수 있는 것으로) ∧ 메일을 쓸 수 있는 세션(세션 노티파이어의 `register` · 제한 단계는 `pause`) ∧ 이 휴대폰에서 켬 ∧ 권한 ∧ 새 메일 채널. 맞추기 `_reconcile` 하나가 PUT · DELETE 를 고른다. **PUT** 은 세션이 열릴 때 한 번 · FID 가 바뀔 때 · 켤 때만(앞으로 올 때마다가 아니다), **DELETE** 는 끌 때와 권한 · 채널이 꺼진 것을 알았을 때만 — 로그아웃 · 세션 끝은 FCM `unregister()` 만(서버 줄은 서버가 세션과 함께 지운다, 풀지 못하면 `pendingUnregister` 로 다음 실행 · 앞으로 옴에 다시). **봤음** `DELETE …/unseen` 은 앞으로 올 때 · 앞에서 받은 새 메일 알림 때, 30초 간격 + 끝 한 번 — 앱이 앞에 있을 때만 보내고, 기다리는 동안 뒤로 가면 그 자리에서 보낸다(끝까지 기다리면 그사이 온 메일까지 본 것으로 센다). 앞에서 받은 알림 뒤의 봤음은 받은 때 + 1.5초(`kPushSeenAfterMessageDelay`)보다 일찍 보내지 않는다 — 서버는 seen_at 의 초부터 같은 초를 세고 받은 시각은 초 단위라, 곧바로 보내면 열지 않은 그 메일이 다음 알림에 다시 세어진다(2026-11-08 실기기). 켜기 · 끄기는 서버가 답한 뒤에 바꾼다(실패는 그 코드의 사전 문구 — 등록 소식이 없으면 `SYS_001`). **켜기가 실패하면 이 휴대폰의 값을 끔으로 둔다**(처음 값 켬에서 허락하고 켰어도 — 스위치는 꺼진 채, 저절로 다시 하지 않는다). 서버 일은 멈춘(`pause`) 바로 그 차례에도 보내지 않는다(`_canReachServer` 가 컨트롤러의 세션 값도 본다). FCM `register` · `unregister` 는 우리가 한 줄로 세운다(플러그인이 스레드 풀에서 돈다), `onRegistered` 는 방송이라 `register` 전에 듣는다. **풀기는 기다리기 전에 등록 세대를 올리고 등록을 내려 둔다** — 풀기가 실패하거나 오래 걸려도 같은 실행의 다음 로그인이 그 뒤에 다시 등록하고(같은 FID 의 PUT 이 서버의 앞 직원 줄을 지운다), 풀기 앞의 등록은 끝나도 마친 것으로 치지 않으며 "풀지 못한 등록" 표시도 지우지 않는다. 풀기가 줄에 있는 동안 온 등록 소식은 쓰지 않는다. 앱이 앞에 있으면 FCM 이 알림을 그리지 않는다 — 앞에서 받은 새 메일 알림은 메일 목록이 바로 새 메일을 확인한다(`mail_state_watcher`). 알림 데이터는 **모듈 이름과 종류**(`{ module: 'mail', kind: 'new-mail' }` · `session-ended`). FID · 주소 · 토큰을 로그 · 디버그 출력에 남기지 않는다. 시험 도구 `test/support/push_fakes.dart`(가짜 FCM · 알림창 · 값 · 서버) · `push_screen_harness.dart`(앱 전체 + 진짜 컨트롤러 — `ProviderHarness.recordPush = false`). 다른 시험대는 기기 등록을 기록하는 가짜(`RecordingPushRegistrar`)이고 컨트롤러는 FCM 이 없어 조용하다 |
-| **앱 설정 · 업데이트 화면** | `lib/core/app_config/`(`app_config.dart` — 판 비교 `AppVersion` · 모양, `app_config_repository.dart`, `app_config_controller.dart` — `appUpdateRequiredProvider` · `pushAvailableProvider`) · `core/router/session_redirect.dart`(`updateRequired` 가 세션보다 먼저) · `features/app_update/`(모듈이 아니다 — 화면 · `AppStoreLauncher` · 글) | `GET /api/app-config` 는 띄울 때 한 번 · 앞으로 올 때 마지막으로 받은 지 1시간이 지났으면(실패는 1분 간격으로 다시) — 알리지 않고 막지 않는다. 404 `RES_001` 은 옛 서버(최소 판 없음 · 알림 쓸 수 없음). 판은 숫자 1~3칸 · 칸마다 4자리까지(서버의 판 칸 `APP_VERSION_PATTERN` 과 같다 — `-` · `+` 뒤는 버린다), 이 앱의 판을 모르면 막지 않는다. 업데이트 화면으로 옮길 때 쓰기 화면은 마저 저장한다(`ComposeController.detach(saveRemaining: true)` — 화면이 밖에서 닫힌 때도). [Play 스토어 열기]는 `market://details` → 웹 주소, 패키지 이름은 `appPackageNameProvider`(main 이 기기 정보로) |
-| **설정 탭 (`App1Shell` · `App1Push` ④)** | `lib/features/settings/` — `settings_routes.dart`(`/settings` · `/settings/licenses` · 모듈이 내놓은 절) · `presentation/pages/settings_page.dart` · `widgets/settings_notification_row.dart` · `settings_texts.dart` | 한 화면(내 정보 · 알림 · 모듈 절 · 앱 정보 · 문의 · [로그아웃]). 문의는 로그인 화면과 같은 저장소(`supportContactProvider`), [로그아웃]은 확인 창(`shared/widgets/confirm_dialog.dart` — 처음 초점 [취소]). 스위치 색은 테마의 `switchTheme`(보드 — 켬 청록 · 끔 테두리 · 누를 수 없음 회색) |
+| **앱 설정 · 업데이트 화면** | `lib/core/app_config/`(`app_config.dart` — 판 비교 `AppVersion` · 모양, `app_config_repository.dart`, `app_config_controller.dart` — `appUpdateRequiredProvider` · `pushAvailableProvider`) · `core/router/session_redirect.dart`(`updateRequired` 가 세션보다 먼저) · `features/app_update/`(모듈이 아니다 — 화면 · 글) · `core/app_download/`([새 버전 받기] — 받기 화면 주소 `app_download_link.dart` · 런처 `AppDownloadLauncher` · 글, 업데이트 화면과 설정 › 앱 정보가 함께 쓴다) | `GET /api/app-config` 는 띄울 때 한 번 · 앞으로 올 때 마지막으로 받은 지 1시간이 지났으면(실패는 1분 간격으로 다시) — 알리지 않고 막지 않는다. 404 `RES_001` 은 옛 서버(최소 판 없음 · 알림 쓸 수 없음). 판은 숫자 1~3칸 · 칸마다 4자리까지(서버의 판 칸 `APP_VERSION_PATTERN` 과 같다 — `-` · `+` 뒤는 버린다), 이 앱의 판을 모르면 막지 않는다. 업데이트 화면으로 옮길 때 쓰기 화면은 마저 저장한다(`ComposeController.detach(saveRemaining: true)` — 화면이 밖에서 닫힌 때도). 앱은 스토어에 올리지 않고 사내에 직접 나눠 준다(2026-11-08 — 빌드 · 서명 · 올리기는 `flutter/README.md` "사내 배포"). [새 버전 받기]는 포털의 휴대폰 앱 받기 화면 `<API_URL 의 출처>/app`(`appDownloadPageUrlOf` — `/api` 를 뗀 출처 + 경로, 짝: 웹 `mobile-app.ts` 의 `MOBILE_APP_PATH`)을 바깥 브라우저로(`LaunchMode.externalApplication` — `canLaunchUrl` 은 쓰지 않는다) 연다. 열지 못하면 스킴 없는 주소를 담아 알린다(`openAppDownloadPage` — 두 화면이 같은 알림). 앱 설정 계약은 받는 곳 주소를 싣지 않는다 |
+| **설정 탭 (`App1Shell` · `App1Push` ④)** | `lib/features/settings/` — `settings_routes.dart`(`/settings` · `/settings/licenses` · `/settings/release-notes`(+ `/:noteId`) · 모듈이 내놓은 절) · `presentation/pages/settings_page.dart` · `widgets/settings_notification_row.dart` · `settings_texts.dart` | 한 화면(내 정보 · 알림 · 모듈 절 · 앱 정보(앱 버전 · 업데이트 내역(목록 → 글, 아래 행) · [새 버전 받기] — 끝 아이콘이 바깥으로 여는 아이콘, 업데이트 화면과 같은 런처 · 오픈소스 라이선스) · 문의 · [로그아웃]). 문의는 로그인 화면과 같은 저장소(`supportContactProvider`), [로그아웃]은 확인 창(`shared/widgets/confirm_dialog.dart` — 처음 초점 [취소]). 스위치 색은 테마의 `switchTheme`(보드 — 켬 청록 · 끔 테두리 · 누를 수 없음 회색) |
+| **업데이트 내역 (`ReleaseNotes` B — 2026-11-10)** | `lib/features/settings/` — data(`models/release_note.dart` · `repositories/release_notes_repository.dart`) · presentation(`pages/release_notes_page.dart` · `release_note_page.dart` · providers `release_notes_providers.dart` · `release_notes_list_controller.dart` · `release_note_controller.dart` · widgets `release_notes_parts.dart` · 글 `release_notes_texts.dart`), 달력 날짜 `core/utils/calendar_date.dart`(`CalendarDate`) + `korean_format.dart` 의 `koreanCalendarDate`, 시험 도구 `test/support/release_notes_fakes.dart`(`FakeReleaseNotesBackend` · 보드의 네 글 `kBoardReleaseNotes`) | 계약 7절(`GET /api/release-notes?cursor=&limit=` · `GET /api/release-notes/{id}` — 올리는 API 없음, 글은 서버의 글 파일). 설정 › 앱 정보의 앱 버전 다음 줄 → 목록 `/settings/release-notes` → 글 `/settings/release-notes/:noteId`(둘 다 `parentNavigatorKey: rootNavigatorKey`, 글은 목록 라우트의 자식이라 주소로 바로 열어도 아래에 목록). 목록은 `releaseNotesListProvider`(autoDispose — 화면을 열 때마다 새로 받는다 · 첫 쪽 · [다시 시도]는 `silent`, [더 보기]는 알림 + 받은 줄 그대로 · 겹친 id 는 건너뜀), 글은 `releaseNoteProvider(id)`(autoDispose family · `silent` — 없는 글 404 `RES_001` 은 [목록으로], 그 밖은 [다시 시도]). 둘 다 `releaseNotesAccountProvider`(세션의 주소 — 메일의 `mailAccountProvider` 와 같은 규칙, 모듈끼리 import 하지 않아 따로)를 듣고 세션이 바뀌면 처음부터 · 세대(`_seq`)와 시작할 때의 Ref 로 늦은 응답을 버린다. 응답 모양이 틀리면 `ReleaseNotesMalformedResponse`(`SYS_001` — 인터셉터를 다 지난 뒤라 [더 보기]만 컨트롤러가 `errorNotifierProvider` 로 알린다, 메일 `DownloadInterrupted` 와 같은 결). **날짜는 `CalendarDate` 로만**(`YYYY-MM-DD` 를 글로 나눠 쥔다 — `DateTime` 으로 바꾸지 않는다, 없는 날은 모양 틀림). 다른 글 줄은 `context.pushReplacement`(쌓지 않는다 — 뒤로는 늘 목록, go_router 17 은 void 를 돌려준다). 글은 서버 글 그대로(마크다운 해석 · 링크 없음) · 한글 줄바꿈 `KeepAllText`(시험은 `findCopy`). [더 보기]는 받는 동안 누름만 무시한다(초점 지키기 — 메일 검색 [더 찾기]와 같다) — 도는 표시가 있어 시험은 `pumpAndSettle` 대신 `pump(100ms)` |
+| 불러오기 상태 틀 | `lib/shared/widgets/load_states.dart` · `load_state_texts.dart` | 가운데 상태 `StateLayout`(아이콘 원 72 · 제목 · 글 · 단추) · 받지 못함 `LoadErrorView`(사전 문구 · 문의 코드 · [다시 시도] — `RES_001` + `onLeave` 면 `leaveLabel` 단추, 둘은 함께 준다) · 뼈대 `LoadingSkeleton`(화면 낭독기 한 줄 + 막대는 읽지 않음) · `SkeletonBar`(메일은 모서리 4, 업데이트 내역은 `rounded`) · `traceCodeOf`. 2026-11-10 메일 목록(`mail_list_states.dart` 의 `MailStateLayout` · `MailListError` · `_SkeletonBar`)에서 모양 · 동작 그대로 옮겼다 — 메일 목록 · 검색 · 읽기 · 쓰기와 업데이트 내역이 쓴다. 메일 줄 꼴의 뼈대(`MailListSkeleton`) · 빈 메일함 · 목록 끝 · 30일 줄은 메일에 남았다. `MailListTexts.retry` · `traceCode` 는 `LoadStateTexts` 를 가리킨다 |
 | 자리 화면 | `lib/shared/widgets/placeholder_page.dart` | 화면은 캔버스로 확인받은 뒤 만든다 — 그때까지 이름(과 갈 곳)만 보이는 자리 화면. 확정되면 라우트 묶음의 builder 를 바꾼다 |
-| 예제 feature(템플릿) | `lib/features/user/` | 목록 페이지네이션(`{items, pageInfo}` — 단건 + 커서 목록) 예제로만 남긴 템플릿. 앱 API 에 `/users` 는 없다 |
+| 예제 feature(참조용) | `lib/features/user/` | 목록 페이지네이션(`{items, pageInfo}` — 단건 + 커서 목록) 예제로만 남겼다. 앱 API 에 `/users` 는 없다 |
 | 시험 도구 | `test/support/` — `fakes.dart` · `provider_harness.dart` | 가짜 서버(`FakeServer` — HttpClientAdapter) · 메모리 보안 저장소 · 손 시계(`ManualClock`) · 알림 기록(`RecordingNotifier`). 고정 대기 없이 Completer 로 차례를 맞춘다 ([[testing]]) |
 
 > **확장 시 따르는 규칙** (아래 "프로젝트 구조"는 목표 구조 — 기능 추가 시 점진적으로 채운다):
@@ -80,6 +82,7 @@ lib/
 │   ├── constants/              ← 앱 이름 · 로그인 단계 화면 이름 · 앱 판
 │   ├── modules/                ← 모듈 목록(app_modules — 웹과 짝) · 라우트 묶음 꼴(module_routes)
 │   ├── app_config/             ← 앱 설정(최소 판 · 알림을 보낼 수 있는가)
+│   ├── app_download/           ← [새 버전 받기] — 포털의 휴대폰 앱 받기 화면 주소 · 런처 · 글 (업데이트 화면 · 설정이 함께 쓴다)
 │   ├── push/                   ← 새 메일 알림(FCM · 채널 · 서버 등록 맞추기) · 알림 → 경로
 │   ├── router/                 ← 라우터 · 탭 막대 · redirect · 모듈 묶음 모으기(module_registry)
 │   ├── storage/                ← 토큰 보관 · 보안 저장소 · 첫 실행 표시
@@ -102,7 +105,7 @@ lib/
 │   ├── settings/               ← 모듈 — 주소 /settings/... (다른 모듈의 설정 절을 받아 붙인다)
 │   └── user/                   ← 예제(참조용)
 └── shared/
-    └── widgets/                ← 앱 공통 위젯 (자리 화면 등)
+    └── widgets/                ← 앱 공통 위젯 (자리 화면 · 확인 창 · 불러오기 상태 틀 등)
 ```
 
 ---
@@ -292,7 +295,7 @@ await tokenStore.clear(byUser: true);     // 로그아웃 (세션 끝은 byUser
 - [ ] **모듈**: 새 기능은 그 모듈 폴더(`features/<모듈>/`)와 라우트 묶음 안에. 모듈끼리 import 하지 않는다 — 함께 쓰는 것은 `core/` · `shared/`. 모듈 목록을 바꾸면 웹 `app-modules.ts` 도(짝).
 - [ ] **화면**: 캔버스로 확인받은 뒤 만든다 — 그때까지 자리 화면(`PlaceholderPage`). 글자 크기는 `textTheme` 역할 이름으로만, 누르는 곳은 48dp 이상.
 - [ ] **권장 패키지**: 새 패키지는 배포 2주가 지난 판만, `pubspec.yaml` 추가 후 `flutter pub get`. 모델 생성기를 넣을 때는 위 "모델 생성기" 주의(build.yaml `generate_for`).
-- [ ] **analyze/test**: 커밋 전 `flutter analyze` (Warning 0) + `flutter test` 통과. 배포 판은 `flutter build apk` 로 한 번 본다(release 매니페스트에 INTERNET 권한이 있어야 네트워크가 된다).
+- [ ] **analyze/test**: 커밋 전 `flutter analyze` (Warning 0) + `flutter test` 통과. 배포 판(release)은 우리 서명 키(`android/key.properties` — 저장소 밖 keystore)와 `google-services.json` 이 있고 `flutter/.env` 의 `API_URL` 이 운영 포털의 https 주소일 때만 만든다 — 하나라도 아니면 Gradle 이 까닭을 알리고 멈춘다(debug 키로 조용히 서명하지 않고, 개발 주소가 든 판이 나가지 않게 — 알리는 글에 주소 값은 싣지 않는다, `flutter/README.md` "사내 배포"). 만들면 release 매니페스트에 INTERNET 권한이 있어야 네트워크가 된다는 것도 본다.
       Kotlin(`MainActivity.kt`)을 고쳤으면 커밋 전에 `flutter build apk --debug` 로 컴파일을 본다 — CI 는 안드로이드를 빌드하지 않고,
       Kotlin 쪽 짝(고른 파일의 미리 거르기 · 이름 규칙)에는 시험이 없다(Dart 가 판정을 다시 하고, 어긋남은 앱 README 의 실기기 목록으로 본다).
       Flutter 판은 위 "Flutter 판"(3.41.9) — CI 도 같은 판이다.
@@ -309,6 +312,11 @@ await tokenStore.clear(byUser: true);     // 로그아웃 (세션 끝은 byUser
       가짜 서버는 요청 본문을 읽지 않아 보내는 진행(onSendProgress)이 오지 않는다 — 진행을 보려면 `FakeServer.readRequestBodies` 를 켠다.
       InkWell 에 길게 누르기 처리가 없으면 길게 눌렀다 뗄 때 onTap 이 돈다 — 열지 않을 줄은 길게 누르기를 받아 두고 아무것도 하지 않는다(검색 결과 줄).
       두 줄 TextField 에도 Scrollable 이 있다 — 목록 스크롤은 ListView 아래에서 찾는다(`find.descendant`).
+      go_router 17 의 `context.pushReplacement` · `replace` 는 void 다(`push` 만 Future) — 바꿔 끼울 화면은 `pushReplacement`(새 page key — 앞 화면의 PageStorage 스크롤 자리를 물려받지 않는다, 업데이트 내역의 다른 글 줄).
+      짜임을 둘로 가르는 화면(읽기 화면의 본문 칸 있음 · 없음)은 두 짜임에 같은 자리의 같은 위젯을 두고 값(`ConstrainedBox` 의 maxHeight)만 바꾼다 — `Flexible` · `Expanded` 로 바꿔 끼우면 그 아래 State(펼친 받는 사람 등)가 새로 만들어진다. 시험은 위치로 본다(머리 스크롤 칸의 아래 끝 = 아래 막대의 위 끝).
+      `InputDecoration.collapsed` 는 테두리 없는 칸이 아니다 — `border` 만 없애고 `enabledBorder` · `focusedBorder` 등을 비워 두면 TextField 가 그 칸을 테마의 `inputDecorationTheme`(둥근 테두리 · 초점은 청록 2)로 채우고, InputDecorator 는 `border` 보다 그 칸들을 먼저 쓴다(2026-11-12 — 쓰기 화면의 칸마다 글자를 감싼 테두리). 칸 줄이 선을 따로 그리는 칸은 `borderlessInputDecoration`(`core/theme/app_theme.dart` — 여섯 테두리 모두 없음 · 여백 0)을 쓴다. `lib/` 에 `InputDecoration.collapsed(` 가 들어오면 시험(`test/core/theme/borderless_input_decoration_test.dart`)이 실패한다. 칸의 테두리는 `test/support/input_borders.dart` 의 `expectBorderlessInput`(평소 · 초점 · 꺼짐마다 InputDecorator 가 받은 꾸밈)으로 본다.
+      화면을 그림으로 견줄 때(임시 시험 — 저장소에 남기지 않는다): `setUpAll` 에서 `FontLoader('Pretendard')` 에 `assets/fonts/Pretendard-*.otf` 넷을, `FontLoader('MaterialIcons')` 에 SDK 의 `bin/cache/artifacts/material_fonts/materialicons-regular.otf` 를 올리고(그러지 않으면 글자가 네모), 맨 위 repaint boundary(RenderView)의 `OffsetLayer.toImage(paintBounds)` 를 `tester.runAsync` 안에서 PNG 로 쓴다. 화면 크기는 `MailAppHarness.pump(size:)`.
+      화면 아래 끝까지 닿는 스크롤(읽기 화면의 빈 본문 + 아래 막대 없는 예약 메일 등)은 `MediaQuery.paddingOf(context).bottom` 을 스크롤 끝 여백으로 더한다 — Scaffold 는 bottomNavigationBar 가 있을 때만 몸통의 아래 padding 을 0 으로 만든다. 시험은 `tester.view.padding = FakeViewPadding(bottom: 48 * 3)`(물리 픽셀 — 시험대는 3배) + `addTearDown(tester.view.resetPadding)`.
 - [ ] **린트로 강제되는 항목**: `dynamic` 호출·`print`·`const` 누락·await 누락·작은따옴표·import 정렬 (`analysis_options.yaml`).
 - [ ] **env**: `flutter/.env.example` → `.env` 복사 후 `API_URL` 설정 (Android 에뮬레이터는 `10.0.2.2`).
       `.env` 는 `pubspec.yaml` 의 asset 이라 **없으면 `flutter analyze` 가 경고**한다.

.github/workflows/ci.yml

@@ -236,6 +236,11 @@ jobs:
             [ "$n" -eq 2 ] || { echo "::error::internal-api-closed.conf 를 넣은 server 가 둘이 아닙니다 ($form: $n)"; exit 1; }
             n=$(printf '%s\n' "$conf" | awk '$1 == "if" && $2 == "($request_target_rejected)" { c++ } END { print c + 0 }')
             [ "$n" -eq 2 ] || { echo "::error::원문 요청 대상 검사(if \$request_target_rejected)가 든 server 가 둘이 아닙니다 ($form: $n)"; exit 1; }
+            # 앱 안 받기 · 휴대폰 앱 받기(2026-11-08)가 같은 그릇(download_app_*)을 쓴다 — 포털의 두 location 에 하나씩, 두 꼴 모두 둘이다
+            for want in 'download_app_ip 30;' 'download_app_total 200;'; do
+              n=$(printf '%s\n' "$conf" | awk -v want="$want" '$1 == "limit_conn" && ($2 " " $3) == want { c++ } END { print c + 0 }')
+              [ "$n" -eq 2 ] || { echo "::error::limit_conn $want 이 든 location 이 둘(앱 안 받기 · 휴대폰 앱 받기)이 아닙니다 ($form: $n)"; exit 1; }
+            done
           done
           # 잘못된 값은 기동을 멈춰야 한다 (frontend/nginx-env.envsh — 앞자리 0, 경로가 붙은 백엔드 주소, 출처가 아닌 공개 내려받기 주소)
           if docker run --rm -e PROJECT_NAME=ci -e MAIL_ATTACHMENT_MAX_SIZE_MB=08 "$tag" nginx -t; then
@@ -253,7 +258,9 @@ jobs:
       # 대용량 받기 경로(11단계)를 실제 요청으로 본다 — 백엔드(Express)는 경로의 대소문자를 가리지 않아, 받기 location(동시 연결 수 · 버퍼링 끔 ·
       # X-Accel-Buffering 넘김 · 머리글 버퍼 16k)과 포털이 닫은 공개 API 는 대소문자 · %2F · 겹 / 변형도 같은 곳을 타야 한다 (frontend/nginx.conf 머리말).
       # 위 단계의 이미지에 가짜 백엔드(같은 컨테이너의 127.0.0.1:3000 — 늘 X-Accel-Buffering: no 를 붙인다. ?hold=1 이면 10MB 를 1KB/s 로,
-      # ?pad=1 이면 머리글 6KB)를 더해 네트워크 없이 띄운다. 그 머리글은 받기 location 을 탄 요청만 클라이언트까지 온다 — 그것으로 location 을 가른다
+      # ?pad=1 이면 머리글 6KB)를 더해 네트워크 없이 띄운다. 그 머리글은 받기 location 을 탄 요청만 클라이언트까지 온다 — 그것으로 location 을 가른다.
+      # 휴대폰 앱(APK) 받기(/api/app-releases/…/file — 2026-11-08)도 본다: 같은 변형이 받기 location 을 타고 앱 안 받기와 그릇(주소마다 30)을 함께 쓰는지,
+      # 공개 호스트는 404 로 닫는지, 정보 경로(…/latest — JSON)는 받기 location 밖인지
       - name: 대용량 받기 경로 시험
         run: |
           base="ci-nginx-config:${{ github.run_id }}"
@@ -290,26 +297,42 @@ jobs:
           release() { killall wget >/dev/null 2>&1; sleep 2; }
           PUBLIC="/api/public-links/$T/files/$F /api/Public-Links/$T/FILES/$F /api/PUBLIC-LINKS/$T/Files/$F /api//public-links/$T/files/$F /api/public%2Dlinks/$T/files/$F"
           INAPP="/api/messages/M1/large-files/$F /api/Messages/M1/LARGE-FILES/$F /api/MESSAGES/M1/Large-Files/$F /api//messages/M1/large-files/$F /api/messages/M1%2Fx/large-files/$F"
+          # 휴대폰 앱 받기 — 끝의 / · %66(f) 꼴도. 정보 경로는 받기 location 밖이다
+          APK="/api/app-releases/android/latest/file /api/App-Releases/Android/Latest/FILE /api/APP-RELEASES/android/latest/File /api//app-releases/android/latest/file /api/app-releases/android%2Flatest/file /api/app-releases/android/latest/file/ /api/app-releases/android/latest/%66ile"
+          INFO="/api/app-releases/android/latest /api/App-Releases/Android/Latest /api/app-releases/android/latest/"
 
           echo "== 받기 location 을 탄다(X-Accel-Buffering) · 포털은 공개 API 를 닫는다 — 대소문자 · %2F · 겹 / 변형도"
           for p in $PUBLIC; do expect "200 xab" files.ci.test "$p"; expect "404 -" portal.ci.test "$p"; done
           for p in $INAPP; do expect "200 xab" portal.ci.test "$p"; done
+          echo "== 휴대폰 앱 받기도 받기 location 을 탄다 · 공개 호스트는 닫는다 · 정보 경로는 /api 그대로"
+          for p in $APK; do expect "200 xab" portal.ci.test "$p"; expect "404 -" files.ci.test "$p"; done
+          for p in $INFO; do expect "200 -" portal.ci.test "$p"; expect "404 -" files.ci.test "$p"; done
           expect "200 -" files.ci.test "/api/Public-Links/$T"
           expect "200 -" portal.ci.test "/api/Messages/M1"
           expect "200 xab" files.ci.test "/api/Public-Links/$T/files/$F?pad=1"
           expect "200 xab" portal.ci.test "/api/Messages/M1/large-files/$F?pad=1"
+          expect "200 xab" portal.ci.test "/api/App-Releases/android/latest/file?pad=1"
           echo "== nginx 가 끝내는 /api 응답은 JSON"
           expect_raw "404 application/json RES_001" files.ci.test GET /api/auth/me
           expect_raw "413 application/json FILE_002" files.ci.test POST /api/auth/login "Content-Length: 2000000"
           expect_raw "404 application/json RES_001" portal.ci.test GET "/api/Public-Links/$T/files/$F"
-          echo "== 동시 연결 — 주소마다 공개 10 · 앱 안 30. 붙잡아 둔 뒤 변형으로 하나 더"
+          expect_raw "404 application/json RES_001" files.ci.test GET /api/app-releases/android/latest/file
+          echo "== 동시 연결 — 주소마다 공개 10 · 앱 안 30(휴대폰 앱 받기와 함께). 붙잡아 둔 뒤 변형으로 하나 더"
           hold files.ci.test "/api/public-links/$T/files/$F" 10
           for p in $PUBLIC; do expect "429 -" files.ci.test "$p"; done
           expect_raw "429 application/json REQ_001" files.ci.test GET "/api/Public-Links/$T/files/$F"
           expect "200 xab" portal.ci.test "/api/messages/M1/large-files/$F"
+          expect "200 xab" portal.ci.test "/api/app-releases/android/latest/file"
           release
           hold portal.ci.test "/api/messages/M1/large-files/$F" 30
-          for p in $INAPP; do expect "429 -" portal.ci.test "$p"; done
+          for p in $INAPP $APK; do expect "429 -" portal.ci.test "$p"; done
+          expect_raw "429 application/json REQ_001" portal.ci.test GET "/api/App-Releases/android/latest/FILE"
+          expect "200 -" portal.ci.test "/api/app-releases/android/latest"
+          expect "200 xab" files.ci.test "/api/public-links/$T/files/$F"
+          release
+          hold portal.ci.test "/api/app-releases/android/latest/file" 30
+          for p in $APK $INAPP; do expect "429 -" portal.ci.test "$p"; done
+          expect "200 -" portal.ci.test "/api/app-releases/android/latest"
           expect "200 xab" files.ci.test "/api/public-links/$T/files/$F"
           release
           echo "fails=$fails"

CLAUDE.md

@@ -1,6 +1,7 @@
 # 프로젝트 개요
 
-이 저장소는 **풀스택 모노레포 기본 템플릿**이다. 누구나 클론하여 바로 개발을 시작할 수 있도록 공통 규칙과 언어별 규칙을 정의한다.
+이 저장소는 **ARA SYSTEM** — 사내 그룹웨어(첫 모듈은 메일: 웹메일 · 휴대폰 앱)다. 백엔드 · 웹 · 앱과 메일 엔진 · 운영 설정을 한 저장소에서 다루고, 여기에 공통 규칙과 스택별 규칙을 둔다.
+프로젝트 소개 · 문서 지도는 [`README.md`](README.md), 작업 차례는 [`docs/roadmap.md`](docs/roadmap.md).
 
 | 디렉터리    | 스택           | 역할                     | 개발 규칙 (스킬)                          |
 | ----------- | -------------- | ------------------------ | ----------------------------------------- |

README.md

@@ -1,109 +1,97 @@
-# 풀스택 모노레포 기본 템플릿
+# ARA SYSTEM
 
-NestJS(백엔드) · Vue 3(웹) · Flutter(모바일)를 하나의 저장소에서 운영하는 풀스택 템플릿입니다.
-세 클라이언트는 **동일한 표준 응답 포맷**과 **공통 에러 코드 맵**을 공유하며, Docker Compose로 한 번에 구동됩니다.
+사내 그룹웨어다. 첫 모듈은 **메일** — 웹메일(포털)과 휴대폰 앱(안드로이드)이다.
+메일 엔진(Stalwart)이 메일을 주고받고, 우리 서버(NestJS)가 엔진을 감싸 웹과 앱에 같은 API 를 준다. 화면은 직접 만든다(Vue 3 · Flutter).
+`@arasystem.it.kr` 메일은 2026-11-05 옛 서버(mailcow)에서 옮겨 와 전 직원이 쓰고 있다.
+
+## 지금
+
+- 운영: 메일 1~13단계. 메일 14단계(자체 검색 색인 · 같은 대화)와 앱 첫 판 · 휴대폰 앱 받기는 main 에 합쳤고 서버 배포를 기다린다.
+- 개발 중: 메일 15단계(메일 · 메일함 다루기). 다음은 16단계(개인 설정 — 주소록 가져오기 · 여러 서명 등).
+- 단계별 내용 · 다음 차례 · 미뤄 둔 후보는 [`docs/roadmap.md`](./docs/roadmap.md).
 
 ## 구성
 
-| 디렉터리    | 스택           | 역할                     | 포트(기본) |
-| ----------- | -------------- | ------------------------ | ---------- |
-| `backend/`  | NestJS + TypeORM | REST API 서버          | 3000       |
-| `frontend/` | Vue 3 + Vite   | 웹 프론트엔드            | 5173       |
-| `flutter/`  | Flutter + Riverpod | 모바일 앱            | -          |
-| `db`        | PostgreSQL     | 데이터베이스             | 5432       |
-| `redis`     | Redis          | 캐시 / 세션 (**기본 비활성**) | 6379       |
-| `mail`      | Stalwart (JMAP) | 사내 메일 엔진 — 직원 로그인 = 메일 계정 (profile `mail`, [`mail/README.md`](./mail/README.md)) | 운영 25·465·993·443 / 개발 관리 8180 |
-| `mailpit`   | Mailpit        | **개발 전용** — 사내 도메인 밖으로 보낸 메일 수집 | 8025 |
+| 이름 | 스택 | 하는 일 | 포트(개발) |
+| --- | --- | --- | --- |
+| `backend/` | NestJS · TypeORM | 웹 · 앱이 함께 쓰는 REST API — 메일 엔진 중계, 로그인 세션, 검색 색인, 앱 알림, 대용량 첨부 | 3000 |
+| `frontend/` | Vue 3 · Vite | 웹메일 화면. 운영은 nginx 가 화면과 같은 주소의 `/api` 를 백엔드로 넘긴다 | 5173 |
+| `flutter/` | Flutter · Riverpod | 휴대폰 앱(안드로이드 — 스토어 없이 사내 배포) | - |
+| `db` | PostgreSQL 15 | 로그인 세션 · 설정 · 검색 색인 · 대용량 첨부 기록 등 | 5432 |
+| `mail` | Stalwart | 메일 엔진(JMAP · IMAP · SMTP) — 직원 로그인 = 메일 계정 | 관리 8180(운영은 25 · 465 · 993 · 443) |
+| `mail-resolver` | unbound | 메일 엔진 전용 DNS(스팸 차단 목록 · DNSSEC) | - |
+| `clamav` | ClamAV | 대용량 첨부 악성 검사(운영은 늘, 개발은 profile `clamav`) | - |
+| `mailpit` | Mailpit | 개발 전용 — 바깥 주소로 보낸 메일을 모은다 | 8025 |
+| `redis` | Redis | 기본 꺼짐 — 서버를 여러 대로 늘릴 때의 자리 | 6379 |
+| `ops/` | 셸 · systemd | 운영 서버의 백업(restic) · 15분 점검 · 부팅 때 되살리기 | - |
+| `ci/` | Gitea Actions 러너 | PR 마다 lint · 시험 · 빌드 · 인프라 검사 | - |
+
+## 문서 지도
+
+| 알고 싶은 것 | 문서 |
+| --- | --- |
+| 서버 · 웹 · 앱이 함께 지키는 API 약속 | [`docs/mail/api-contract.md`](./docs/mail/api-contract.md) |
+| 웹 화면 디자인 · 화면 문구 규칙 · 단계별 화면 | [`docs/design/webmail/README.md`](./docs/design/webmail/README.md) — 디자인 원본은 같은 폴더의 `*.dc.html`(캔버스 보드) |
+| 앱 화면 | [`docs/design/app/README.md`](./docs/design/app/README.md) |
+| 메일 엔진 설정 · 운영 배포 · 백업 · 감시 · 전환 | [`mail/README.md`](./mail/README.md) |
+| 앱 개발 실행 · 사내 배포(서명 키 · APK 올리기) | [`flutter/README.md`](./flutter/README.md) |
+| CI 러너 | [`ci/README.md`](./ci/README.md) |
+| 개발 규칙(공통 · 스택별 · 역할) | [`CLAUDE.md`](./CLAUDE.md) · 아래 "개발 규칙" |
+| 로드맵 | [`docs/roadmap.md`](./docs/roadmap.md) |
+| 로고 · 색 | [`docs/brand/`](./docs/brand/) |
 
 ## 사전 요구사항
 
-- Docker / Docker Compose — backend·frontend·db·redis 구동 (컨테이너 안 런타임은 Node 24 LTS — `node:24.22.1-alpine3.24` 고정, 갱신 규칙은 docker 스킬 "Node 버전")
-- Node.js **24 LTS 권장** — 호스트에서 프론트엔드 dev 서버·메일 setup 스크립트를 실행할 때 필요하다.
-  프론트 `engines` 는 `^20.19.0 || >=22.12.0` 이라 20.19 이상이면 돌아가지만, 이미지·CI(24)와 맞추는 것을 권장한다
-  (메일 setup 스크립트는 `--env-file` 때문에 20.6 이상)
-- Flutter SDK `^3.11` — 모바일 앱 실행용 (compose 대상 아님)
+- Docker / Docker Compose — 백엔드 · DB · 메일 엔진(컨테이너 안 Node 는 24 LTS 로 고정 — docker 스킬 "Node 버전")
+- Node.js 24 LTS — 호스트에서 웹 개발 서버 · 메일 setup 스크립트를 돌릴 때
+- Flutter 3.41.9(Dart 3.11.5) — 앱(compose 대상이 아니다 — [`flutter/README.md`](./flutter/README.md))
 
-## 빠른 시작 (Docker)
+## 빠른 시작 (개발)
 
 ```bash
-# 1) 환경변수 파일 생성 (예제 복사)
-#    실제 설정값은 루트 .env.development 한 곳에서 관리한다 (SSOT).
-#    backend/frontend 는 docker-compose 가 값을 주입하므로 예제만 복사하면 된다.
-cp .env.development.example .env.development                       # ← 여기에만 값 입력
-cp backend/.env.development.example backend/.env.development       # (존재 필요: JWT 등 고유 시크릿)
-# frontend 는 compose 가 빌드 시 값을 주입하므로 자체 env 복사 불필요
+# 1) 환경변수 파일 — 값은 루트 .env.development 한 곳에 쓴다(SSOT)
+cp .env.development.example .env.development
+cp backend/.env.development.example backend/.env.development   # 있어야 한다(JWT 등 백엔드 고유 비밀)
 
-# 2) 백엔드 스택 기동 (backend + db, 기본 COMPOSE_PROFILES=mail 이면 mail + mailpit 포함)
+# 2) 백엔드 스택 — backend + db, 기본 COMPOSE_PROFILES=mail 이면 mail · mail-resolver · mailpit 까지
 docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d
 
-# 2-1) 메일 엔진 초기화 — 처음 한 번 (여러 번 실행해도 안전, mail/README.md)
+# 3) 메일 엔진 초기화 — 처음 한 번(여러 번 돌려도 안전하다). 개발 시험 계정도 여기서 만든다(mail/README.md)
 node --env-file=.env.development mail/scripts/setup.mjs
 
-# 3) 의존성 변경 시에만 --build
-docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d --build
-
-# 4) 프론트엔드는 호스트에서 직접 띄운다 (컨테이너보다 수십 배 빠르다)
+# 4) 웹은 호스트에서 띄운다 — /api 는 vite 프록시가 백엔드 컨테이너로 넘긴다
 cd frontend && npm install && npm run dev
 ```
 
-기동 후:
+- 웹 <http://localhost:5173> · API <http://localhost:3000/api> · Swagger <http://localhost:3000/api-docs>
+- 의존성을 바꿨을 때만 `up -d --build`(백엔드는 `--renew-anon-volumes` 도 — docker 스킬).
+- 백엔드를 처음 띄우면 watch 빌드에 수십 분이 걸릴 수 있다(Windows 바인드 마운트). 브랜치를 바꿨다고 다시 시작하지 않는다.
+- 웹을 컨테이너로 띄워야 하면 `--profile frontend`(느리다 — 호스트 vite 와 함께 띄우지 않는다). 운영(`docker-compose.yml` 단독)은 nginx 정적 호스팅이다.
+- 포트는 루트 `.env.{env}` 를 따른다(`FRONTEND_PORT` · `BACKEND_PORT` — `vite.config.ts` 가 직접 읽는다). 포트가 이미 쓰이면 다른 포트로 옮기지 않고 실패한다.
+- Redis 는 뜨지 않는다. 필요해지면 `COMPOSE_PROFILES` 에 `redis` 를 더한다.
 
-- 웹: <http://localhost:5173>
-- API: <http://localhost:3000/api>
-- Swagger 문서: <http://localhost:3000/api-docs>
+전체 실행 · 배포 명령은 [`.claude/skills/docker/SKILL.md`](./.claude/skills/docker/SKILL.md).
 
-> **개발 환경에서 프론트엔드는 컨테이너로 뜨지 않습니다.**
-> vite 를 컨테이너에서 돌리면 소스가 Windows 바인드 마운트 너머에 있어 첫 서빙까지 수 분이 걸립니다.
-> 호스트에서 `npm run dev` 로 띄우면 1~2초이고, `/api` 요청은 vite 프록시가 백엔드 컨테이너로 넘깁니다.
-> 컨테이너로 띄워야 한다면 `--profile frontend` 를 붙이세요 (아래 "프론트엔드 실행 방식" 참조).
-> 운영(`docker-compose.yml` 단독)은 그대로 nginx 정적 호스팅으로 동작합니다.
-
-> Redis 는 기본적으로 뜨지 않습니다. 필요해지면 루트 `.env.{env}` 에 `COMPOSE_PROFILES=redis` 를 설정하세요.
-
-### 프론트엔드 실행 방식
-
-| 방식 | 명령 | 첫 서빙 | 용도 |
-| --- | --- | --- | --- |
-| **호스트 vite (개발 기본)** | `cd frontend && npm run dev` | 1~2초 (최초 의존성 사전번들 10초 내외) | 일상 개발 |
-| 컨테이너 vite (선택) | `docker compose ... --profile frontend up -d` | 수 분 (Windows 바인드 마운트) | 호스트에 Node 를 둘 수 없을 때 |
-| nginx 정적 (운영) | `docker compose --env-file .env.production up -d --build` | - | 배포 |
-
-> 컨테이너 방식을 상시 사용하려면 루트 `.env.development` 에 `COMPOSE_PROFILES=frontend` 를 넣습니다.
-> (redis 와 함께 켤 때는 `COMPOSE_PROFILES=frontend,redis`)
-> 호스트 vite 와 컨테이너 vite 는 같은 호스트 포트를 쓰므로 **동시에 띄우지 마세요.**
-
-> **포트는 루트 `.env.{env}` 를 따릅니다.** 호스트에서 띄우는 vite 도 `FRONTEND_PORT` 로 열리고,
-> `/api` 프록시 대상은 `BACKEND_PORT` 에서 나옵니다 — `vite.config.ts` 가 루트 env 를 직접 읽습니다.
-> 포트가 이미 사용 중이면 조용히 다른 포트로 옮기지 않고 **실패**합니다
-> (`CORS_ORIGIN` 과 compose 포트 매핑이 그 값에 묶여 있어, 말없이 옮겨가면 원인 모르게 어긋납니다).
-
-전체 실행/배포 명령어는 [`.claude/skills/docker/SKILL.md`](./.claude/skills/docker/SKILL.md) 참조.
-
-## 모바일 앱 실행 (Flutter)
-
-Flutter 는 Docker Compose 대상이 아니므로 로컬에서 직접 실행합니다.
+## 앱 실행 (Flutter)
 
 ```bash
 cd flutter && cp .env.example .env && flutter pub get && flutter run
 ```
 
-> `flutter/.env` 의 `API_URL` 을 백엔드 주소로 설정합니다. (Android 에뮬레이터는 `http://10.0.2.2:3000/api`)
+`flutter/.env` 의 `API_URL` 을 백엔드 주소로 둔다(Android 에뮬레이터는 `http://10.0.2.2:3000/api`). 실기기 · 새 메일 알림 · 사내 배포는 [`flutter/README.md`](./flutter/README.md).
 
 ## 환경변수
 
-`.env*` 는 커밋하지 않습니다. 각 디렉터리의 `*.example` 파일을 복사해 사용하세요.
+`.env*` 는 커밋하지 않는다. 각 자리의 `*.example` 을 복사해 쓴다. **루트 `.env.{env}` 가 단일 진실 공급원(SSOT)**이다 — backend · frontend 는 compose 가 루트 값을 넣어 준다
+(구조는 [`.claude/rules/env-structure.md`](./.claude/rules/env-structure.md)).
 
-**루트 `.env.{env}` 가 단일 진실 공급원(SSOT)** 입니다. backend·frontend 는 docker-compose 가
-루트 값을 주입하므로 자체 env 에 값을 중복 작성하지 않습니다. (자세한 위임 구조는 [`CLAUDE.md`](./CLAUDE.md) 의 "환경변수 구조" 참조)
+| 파일 | 용도 | 값을 쓰는 곳 |
+| --- | --- | --- |
+| `.env.{env}.example` | 루트 — 모든 설정의 SSOT(compose 가 넣어 준다) | 여기 |
+| `backend/.env.{env}.example` | 백엔드 고유 비밀(JWT · 앱 알림 키 등)만 | 최소(파일은 있어야 한다) |
+| `flutter/.env.example` | 앱 — `API_URL`(compose 대상이 아니다) | 따로 |
 
-| 파일                          | 용도                                     | 값 작성 위치          |
-| ----------------------------- | ---------------------------------------- | --------------------- |
-| `.env.{env}.example`          | 루트 — 모든 설정의 SSOT (compose 주입)   | ✅ 여기에 작성        |
-| `backend/.env.{env}.example`  | 백엔드 — 고유 시크릿(JWT 등)만           | 최소 (존재 필수)      |
-| `frontend/.env.{env}.example` | 프론트 — API 주소는 같은 출처의 `/api` 고정(빌드 arg) | 작성 불필요          |
-| `flutter/.env.example`        | 모바일 — `API_URL` (compose 비대상)      | ✅ 독립 관리          |
-
-`{env}` = `development` | `production`
+`{env}` = `development` | `production`. 운영 서버의 백업 · 점검 설정은 `/etc/arasystem/`(`ops/ops.env.example` — mail/README "백업").
 
 ## 표준 응답 포맷
 
@@ -114,97 +102,74 @@ cd flutter && cp .env.example .env && flutter pub get && flutter run
 // 실패 — 사용자에게 보이는 모든 실패는 에러 코드를 가진다
 { "success": false, "error": { "code": "VAL_001", "message": "...", "traceId": "3f1c0a2e-..." } }
 
-// 목록 — data 안의 형태가 고정되어 있다
+// 목록 — data 안의 꼴이 정해져 있다
 { "success": true, "data": { "items": [], "pageInfo": { "hasNext": false, "nextCursor": null, "total": 0 } } }
 ```
 
-`traceId` 는 요청마다 발급되는 추적 ID(`x-request-id` 헤더와 동일)로, 서버 로그에 같은 값이 남습니다.
-사용자 문의가 들어오면 이 값으로 로그를 검색하면 됩니다.
+`traceId` 는 요청마다 붙는 추적 ID(`x-request-id` 헤더와 같다)라 서버 로그에 같은 값이 남는다 — 문의가 오면 이 값으로 로그를 찾는다.
+`/api/health` 는 예외다(모니터링 도구가 읽는 원본 꼴).
 
-> `/api/health` 는 예외입니다. 모니터링 도구가 읽는 엔드포인트라 래퍼 없이 원본 형식을 반환합니다.
-
-### 에러 코드는 한 곳에서 관리됩니다
+### 에러 코드는 한 곳에서
 
 ```
-backend/src/common/errors/error-codes.ts   ← 여기만 수정
+backend/src/common/errors/error-codes.ts   ← 여기만 고친다
         │  cd backend && npm run sync:error-codes
         ├─▶ frontend/src/shared/constants/error-codes.generated.ts   (자동 생성)
         └─▶ flutter/lib/core/api/error_lexicon.g.dart                (자동 생성)
 ```
 
-생성 파일은 직접 수정하지 마세요. CI 가 동기화 여부를 검사합니다.
-자세한 규칙은 [`.claude/rules/error-codes.md`](./.claude/rules/error-codes.md) 참조.
+생성 파일은 직접 고치지 않는다. CI 가 맞는지 본다 — [`.claude/rules/error-codes.md`](./.claude/rules/error-codes.md).
 
-## 로컬 개발 (Docker 없이)
-
-DB 는 컨테이너로 띄우고 앱만 호스트에서 실행하는 방식이 가장 간단합니다.
+## 커밋 전 검사
 
 ```bash
-# 1) DB 만 컨테이너로 기동 (127.0.0.1:5432 로 노출된다)
-docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d db
-
-# 2) backend — DB_HOST 기본값이 localhost 라 그대로 붙는다
-cd backend && npm ci && npm run start:dev
-
-# 3) frontend — vite dev 서버가 /api 를 localhost:3000 으로 프록시한다 (개발 기본 방식)
-cd frontend && npm ci && npm run dev
-
-# 4) flutter
-cd flutter && flutter pub get && flutter run
-```
-
-> 프론트엔드의 API 요청은 `/api` 상대경로로 나가고 vite dev 프록시가 백엔드로 넘깁니다.
-> 백엔드를 다른 주소에서 띄웠다면 `VITE_DEV_API_PROXY` 로 대상을 바꾸세요.
-
-### 커밋 전 검사
-
-```bash
-cd backend  && npm run lint && npm run test && npm run build
-cd frontend && npm run lint && npm run type-check && npm run test:unit
+# backend — 컨테이너 안에서(의존성 · lock 이 Linux 기준이라 호스트에서 npm install 하지 않는다)
+docker exec arasystem-backend npm run lint
+docker exec arasystem-backend npm run test                          # 메모리가 빠듯하면 -- --maxWorkers=2
+docker exec arasystem-backend npx jest --config ./test/jest-e2e.json   # e2e — DB · 메일 엔진이 떠 있어야 한다
+# frontend · flutter — 호스트에서
+cd frontend && npm run lint && npm run type-check && npm run test:unit   # 시간대가 걸린 화면을 고쳤으면 TZ=UTC 로도
 cd flutter  && flutter analyze && flutter test
 ```
 
-lint 는 `--max-warnings 0` 이라 경고 하나만 있어도 실패합니다. 자동 수정은 `npm run lint:fix`.
-같은 검사를 CI([`.github/workflows/ci.yml`](./.github/workflows/ci.yml))가 PR 마다 수행합니다.
+컨테이너 이름은 `<PROJECT_NAME>-backend`(개발 기본 `arasystem`). lint 는 `--max-warnings 0` 이라 경고 하나도 실패다. 같은 검사를 CI(`.github/workflows/ci.yml` · `ci-flutter.yml`)가 PR 마다 한다.
 
-> ⚠️ **의존성을 추가·제거할 때는 컨테이너 안에서** 실행하세요.
-> Windows 에서 `npm install` 하면 Linux 전용 패키지가 lock 에서 잘려 Docker 빌드가 깨집니다.
-> ```bash
-> docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development exec backend npm install <패키지>
-> ```
+> ⚠️ **백엔드 의존성은 컨테이너 안에서만 바꾼다** — Windows 에서 `npm install` 하면 Linux 전용 패키지가 lock 에서 빠져 Docker 빌드가 깨진다.
+> `docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development exec backend npm install <패키지>`
 
 ## 개발 규칙
 
-| 영역      | 문서                                              |
-| --------- | ------------------------------------------------- |
-| 공통/보안 | [`CLAUDE.md`](./CLAUDE.md) · [`.claude/rules/`](./.claude/rules/) |
-| 응답·에러 | [`response-format.md`](./.claude/rules/response-format.md) · [`error-codes.md`](./.claude/rules/error-codes.md) |
-| API 설계  | [`api-design.md`](./.claude/rules/api-design.md)   |
-| 로깅      | [`logging.md`](./.claude/rules/logging.md)         |
-| 체크리스트 | [`checklist.md`](./.claude/rules/checklist.md)    |
-| NestJS    | [`.claude/skills/nestjs/SKILL.md`](./.claude/skills/nestjs/SKILL.md)   |
-| Vue 3     | [`.claude/skills/vue3/SKILL.md`](./.claude/skills/vue3/SKILL.md)       |
-| Flutter   | [`.claude/skills/flutter/SKILL.md`](./.claude/skills/flutter/SKILL.md) |
-| Docker    | [`.claude/skills/docker/SKILL.md`](./.claude/skills/docker/SKILL.md)   |
-| 역할 분담 | [`.claude/agents/README.md`](./.claude/agents/README.md)               |
+| 영역 | 문서 |
+| --- | --- |
+| 입구 · 공통 | [`CLAUDE.md`](./CLAUDE.md) · [`.claude/rules/`](./.claude/rules/) |
+| 응답 · 에러 | [`response-format.md`](./.claude/rules/response-format.md) · [`error-codes.md`](./.claude/rules/error-codes.md) |
+| API 설계 | [`api-design.md`](./.claude/rules/api-design.md) |
+| 로깅 · 보안 | [`logging.md`](./.claude/rules/logging.md) · [`security.md`](./.claude/rules/security.md) |
+| 점검 목록 | [`checklist.md`](./.claude/rules/checklist.md) |
+| NestJS | [`.claude/skills/nestjs/SKILL.md`](./.claude/skills/nestjs/SKILL.md) |
+| Vue 3 | [`.claude/skills/vue3/SKILL.md`](./.claude/skills/vue3/SKILL.md) |
+| Flutter | [`.claude/skills/flutter/SKILL.md`](./.claude/skills/flutter/SKILL.md) |
+| Docker · 운영 | [`.claude/skills/docker/SKILL.md`](./.claude/skills/docker/SKILL.md) |
+| 역할 분담 | [`.claude/agents/README.md`](./.claude/agents/README.md) |
+
+새 화면은 캔버스 보드로 먼저 확인받은 뒤 만든다(디자인 README). 화면 · 알림 글은 디자인 README 「화면 문구 — 사용자에게 말하듯」을 따른다.
 
 ## 디렉터리 구조
 
 ```
 .
-├── backend/    # NestJS API (Controller / Service / DTO / 공통 필터·인터셉터)
-├── frontend/   # Vue 3 (pages / components / composables / stores / router)
-├── flutter/    # Flutter (core / features / shared)
-├── docker-compose.yml         # 베이스 정의
-├── docker-compose.dev.yml     # 개발 오버라이드 (핫리로드, 포트 노출)
-├── CLAUDE.md   # 프로젝트 개요 + 공통 규칙 @import
-├── .github/
-│   ├── workflows/ci.yml       # lint·test·build + 에러 코드 동기화 + 인프라(compose·Dockerfile·nginx) 검사
-│   └── pull_request_template.md
-├── ci/                        # CI 러너 (Gitea Actions) — 앱 스택과 분리
-└── .claude/
-    ├── settings.json   # Claude Code 권한·환경 설정
-    ├── rules/          # 공통 규칙 (코딩·응답 포맷·에러 코드·API 설계·로깅·보안·환경변수·테스트)
-    ├── skills/         # 도메인별 개발 규칙 (nestjs·vue3·flutter·docker)
-    └── agents/         # 역할별 규칙 (개발 3종·테스터·리뷰어·인프라·사용자/관리자 관점)
+├── backend/      # NestJS API — modules/(auth · mail · contacts · file-storage · push · ops 등) · common · shared
+├── frontend/     # Vue 3 웹메일 — pages · components · composables · stores · router, 운영 nginx 설정
+├── flutter/      # 휴대폰 앱 — core · features · shared
+├── mail/         # 메일 엔진 setup 스크립트 · DNS 리졸버 · ClamAV 설정 · 운영 문서(README)
+├── ops/          # 운영 서버의 백업 · 점검 · 부팅 되살리기(systemd)
+├── docs/         # API 계약 · 화면 디자인(캔버스 보드) · 브랜드 · 로드맵
+├── ci/           # CI 러너(Gitea Actions) — 앱 스택과 따로 띄운다
+├── data/         # 개발용 바인드 마운트 자리(내용은 커밋하지 않는다)
+├── docker-compose.yml               # 운영 · 개발 공통 정의
+├── docker-compose.dev.yml           # 개발 오버라이드(핫리로드 · 127.0.0.1 포트)
+├── docker-compose.remote-proxy.yml  # 리버스 프록시가 다른 서버에 있을 때(운영 선택)
+├── CLAUDE.md     # 개발 규칙의 입구(.claude/ 의 규칙을 불러온다)
+├── .github/      # CI 워크플로(ci.yml · ci-flutter.yml) · PR 양식
+└── .claude/      # rules(공통 규칙) · skills(스택별 규칙) · agents(역할) · 설정
 ```

backend/Dockerfile

@@ -43,6 +43,8 @@ COPY package*.json ./
 RUN npm ci --omit=dev && npm cache clean --force
 
 COPY --from=builder /app/dist ./dist
+# 업데이트 내역 글(글 파일 하나가 글 하나 — 계약 7절) — 서버가 기동 · 요청 때 /app/release-notes 를 읽기만 한다(modules/release-notes — 쓰지 않는다)
+COPY --from=builder /app/release-notes ./release-notes
 
 # 업로드 저장 위치(compose 의 UPLOAD_DIR=/app/uploads)와 대용량 첨부 파일 위치(FILE_STORAGE_DIR=/app/files — 11단계) — node 소유로 만들어 둔다.
 # 운영 compose 는 여기에 named volume 을 붙이는데, 새 볼륨은 이 디렉터리의 소유자를 물려받아 node 가 쓸 수 있다.

backend/README.md

@@ -1,98 +1,36 @@
-<p align="center">
-  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
-</p>
+# backend — ARA SYSTEM API (NestJS)
 
-[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
-[circleci-url]: https://circleci.com/gh/nestjs/nest
+웹 · 앱이 함께 쓰는 REST API 다(`/api`). 메일 엔진(Stalwart)을 JMAP 으로 감싸고, 로그인 세션 · 설정 · 검색 색인 · 앱 알림 · 대용량 첨부 · 운영 도구를 맡는다.
 
-  <p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
-    <p align="center">
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
-<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
-<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
-<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
-<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
-  <a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" alt="Donate us"/></a>
-    <a href="https://opencollective.com/nest#sponsor"  target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
-  <a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow" alt="Follow us on Twitter"></a>
-</p>
-  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
-  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
+- 모듈 지도 · 개발 규칙: [`.claude/skills/nestjs/SKILL.md`](../.claude/skills/nestjs/SKILL.md)
+- API 약속(웹 · 앱과 함께): [`docs/mail/api-contract.md`](../docs/mail/api-contract.md)
+- 공통 규칙(응답 꼴 · 에러 코드 · 로그 · 보안): [`CLAUDE.md`](../CLAUDE.md)
 
-## Description
+## 실행 — 컨테이너로
 
-[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
-
-## Project setup
+백엔드는 늘 컨테이너로 띄운다. 의존성 · lock 이 Linux 기준이라 **호스트에서 `npm install` 하지 않는다**(바꿀 때도 컨테이너 안에서 — nestjs 스킬 "의존성 추가/제거").
 
 ```bash
-$ npm install
+# 저장소 루트에서 — 개발 스택(backend + db + 메일 엔진)
+docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d
+docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development logs -f backend
 ```
 
-## Compile and run the project
+- 처음 띄우면 마이그레이션을 한 번 돌리고 watch 빌드를 시작한다(Windows 바인드 마운트라 수십 분 걸릴 수 있다). 코드를 고치면 저절로 다시 뜬다.
+- Swagger: <http://localhost:3000/api-docs>
+
+## 시험 · 검사
 
 ```bash
-# development
-$ npm run start
-
-# watch mode
-$ npm run start:dev
-
-# production mode
-$ npm run start:prod
+docker exec arasystem-backend npm run lint                             # 경고 0
+docker exec arasystem-backend npm run test                             # 단위 — 메모리가 빠듯하면 -- --maxWorkers=2
+docker exec arasystem-backend npx jest --config ./test/jest-e2e.json   # e2e — DB · 메일 엔진 필요
 ```
 
-## Run tests
+컨테이너 이름은 `<PROJECT_NAME>-backend`(개발 기본 `arasystem`). Git Bash 에서 컨테이너 안 경로를 줄 때는 `MSYS_NO_PATHCONV=1` 을 붙인다.
 
-```bash
-# unit tests
-$ npm run test
+## 자주 하는 일
 
-# e2e tests
-$ npm run test:e2e
-
-# test coverage
-$ npm run test:cov
-```
-
-## Deployment
-
-When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.
-
-If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:
-
-```bash
-$ npm install -g @nestjs/mau
-$ mau deploy
-```
-
-With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
-
-## Resources
-
-Check out a few resources that may come in handy when working with NestJS:
-
-- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
-- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
-- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
-- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
-- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
-- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
-- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
-- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).
-
-## Support
-
-Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
-
-## Stay in touch
-
-- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
-- Website - [https://nestjs.com](https://nestjs.com/)
-- Twitter - [@nestframework](https://twitter.com/nestframework)
-
-## License
-
-Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
+- **에러 코드**: `src/common/errors/error-codes.ts` 만 고치고 호스트에서 `cd backend && npm run sync:error-codes`(웹 · 앱 사전이 함께 바뀐다).
+- **DB 스키마**: 엔티티를 고친 뒤 `docker exec arasystem-backend npm run migration:generate -- src/migrations/<이름>` → 만든 SQL 을 눈으로 확인 → 엔티티와 함께 커밋(nestjs 스킬 "DB 마이그레이션").
+- **운영 도구**(운영 서버 안 명령 — 입사 · 비밀번호 재설정 · 휴대폰 앱 올리기 등): `sudo docker exec -it <PROJECT_NAME>-backend node dist/cli/ops.js` — 계약 6절 · mail/README.

backend/release-notes/2026-11-12.md

@@ -0,0 +1,51 @@
+# 휴대폰 앱이 나왔고, 메일 검색과 여러 설정이 좋아졌습니다
+
+- 11월 5일 새 웹메일로 옮긴 뒤 새로 생기거나 바뀐 것을 모았습니다. 앞으로 바뀌는 것도 이곳에서 알려 드리겠습니다.
+
+## 휴대폰 앱
+- 안드로이드 휴대폰에서 쓰는 ARA SYSTEM 앱이 나왔습니다. 메일을 읽고 쓰고 찾을 수 있고, 답장과 전달, 첨부 파일 보내기도 됩니다.
+- 앱 받기: PC 웹메일에서 [설정] → [휴대폰 앱]을 열고 휴대폰 카메라로 QR 코드를 찍어 주세요.
+  휴대폰 브라우저에서 웹메일에 로그인한 뒤 [앱 내려받기]를 누르고, 설치를 묻는 안내가 나오면 허용해 주세요.
+- 앱에는 웹메일과 같은 메일 주소와 비밀번호로 로그인합니다. 2단계 인증을 켜 두셨다면 인증 앱의 코드도 넣어 주세요.
+- 새 메일이 오면 휴대폰 알림으로 알려 드립니다. 앱의 [설정] → [새 메일 알림]에서 켜고 끌 수 있고,
+  알림에는 새 메일이 몇 통인지만 나오며 보낸 사람이나 제목은 나오지 않습니다.
+- 아이폰용 앱은 아직 없습니다. 아이폰에서는 브라우저로 웹메일을 쓰거나 기본 메일 앱에 회사 메일을 연결해 주세요.
+  연결 방법은 웹메일의 [설정] → [메일 프로그램 연결]에서 볼 수 있습니다.
+
+## 웹메일과 휴대폰 앱
+- 메일 검색이 빨라졌고, 보낸 사람, 받는 사람, 제목, 본문, 기간, 첨부로 나눠 찾을 수도 있습니다.
+  웹메일은 검색 칸의 [조건]을, 앱은 검색 화면의 [조건으로 찾기]를 눌러 주세요.
+- 찾은 말에는 노란 표시가 붙어 목록과 본문에서 금방 찾을 수 있습니다.
+- 메일을 읽다가 [이동]을 누르면 바로 다른 메일함으로 옮길 수 있습니다.
+- 업데이트 뒤 하루쯤은 새 검색을 준비하느라 검색 화면에 안내가 나올 수 있습니다. 그동안에도 찾기는 됩니다.
+
+## 웹메일 · 메일 읽기와 정리
+- 메일을 열면 그 메일과 주고받은 메일이 아래에 대화로 모여 나옵니다.
+  [모두 펼치기]로 한꺼번에 읽고, 펼친 메일의 [답장]으로 바로 답할 수 있습니다.
+- 목록 위의 [대화로 묶기]를 켜면 메일 목록도 대화별로 묶입니다.
+- 목록의 메일을 끌어다 왼쪽 메일함에 놓으면 그 메일함으로 옮겨집니다.
+- 메일함 이름 옆 [⋯] → [옮기기]로 메일함을 다른 메일함 아래로 옮길 수 있습니다.
+  하위 메일함이 있는 메일함도 [⋯] → [지우기]로 한꺼번에 지울 수 있고, 안에 있던 메일은 휴지통으로 옮겨집니다.
+- 보낸 사람을 차단할 때 받은편지함에 있는 그 사람의 메일도 스팸메일함으로 함께 옮길 수 있습니다.
+  메일을 읽다가 [⋯] → [보낸 사람 차단]을 누르고, 창에서 받은편지함의 메일도 옮기는 칸을 켜 주세요.
+- 예약한 메일을 기다리지 않고 바로 보낼 수 있습니다. 왼쪽의 [예약됨]에서 메일을 열고 [지금 보내기]를 눌러 주세요.
+
+## 웹메일 · 주소록
+- 다른 메일이나 휴대폰에서 내보낸 연락처 파일을 한 번에 가져올 수 있습니다.
+  [주소록]에서 [가져오기]를 누르고 파일을 고르면, 넣기 전에 몇 명이 들어가는지 먼저 확인할 수 있습니다.
+- vCard, CSV, 엑셀 파일을 넣을 수 있고, 네이버, Google, 아이폰, Outlook에서 내보낸 파일도 됩니다.
+- 이미 주소록에 있는 연락처는 건너뜁니다. 넣은 뒤 나오는 알림의 [되돌리기]를 누르면 이번에 넣은 연락처를 한꺼번에 지울 수 있습니다.
+- 내 주소록을 파일로 내보낼 수도 있습니다. [주소록]에서 [내보내기]를 누르고 vCard나 CSV를 골라 주세요. 그룹 하나만 내보낼 수도 있습니다.
+
+## 웹메일 · 설정
+- 서명을 10개까지 만들어 두고 골라 쓸 수 있습니다. [설정] → [서명]에서 [새 서명]으로 만들고,
+  [메일에 넣을 서명]에서 [새 메일]과 [답장과 전달]에 넣을 서명을 따로 고를 수 있습니다.
+- 메일을 쓰다가 아래의 [서명]을 누르면 다른 서명으로 바꿀 수 있습니다.
+- 부재중 자동 응답을 굵게, 색깔 같은 글자 모양으로 꾸며 쓸 수 있습니다. [설정] → [부재중 자동 응답]
+- 부재중 자동 응답에서 회사 밖에서 온 메일에는 [사내와 같은 응답], [보내지 않기], [따로 쓰기] 가운데 골라 답할 수 있습니다.
+- 휴대폰을 바꾸셨다면 2단계 인증을 새 휴대폰으로 직접 옮길 수 있습니다.
+  [설정] → [2단계 인증] → [휴대폰 바꾸기]를 누르고 안내를 따라 주세요. 지금 휴대폰의 코드와 비밀번호가 필요합니다.
+
+## 그 밖에
+- 화면의 안내 글을 더 알기 쉬운 말로 다듬었습니다.
+- 앞으로 새로 생기거나 바뀌는 것은 이 업데이트 내역에 올립니다. 웹메일과 앱 모두 [설정] → [업데이트 내역]에서 볼 수 있습니다.

backend/release-notes/README.md

@@ -0,0 +1,41 @@
+# 업데이트 내역 글
+
+직원이 웹메일과 휴대폰 앱의 설정에서 읽는 「업데이트 내역」의 글입니다. 글 하나가 파일 하나이고, 웹과 앱이 같은 글을 보여 줍니다. 올리는 화면은 없습니다.
+
+## 글을 더하는 법
+
+1. 이 폴더에 파일을 하나 더합니다. 파일 이름은 글의 날짜입니다(`2026-11-18.md`). 같은 날 두 번째 글은 `2026-11-18-2.md`로 씁니다.
+2. 커밋하고 배포합니다(백엔드를 다시 빌드). 웹과 앱에 함께 나옵니다. Gitea 웹 화면에서 파일을 더하거나 고쳐도 됩니다.
+
+고치거나 지울 때도 그 파일만 다룹니다. 목록에는 최근 글이 위에 나옵니다(날짜 차례, 같은 날은 뒤 번호가 위).
+
+## 파일 안
+
+```
+# 메일 검색이 빨라지고 휴대폰 앱이 나왔습니다
+<!-- 배포 날짜가 정해지면 파일 이름을 그날로 바꿉니다 -->
+
+## 휴대폰 앱
+- 안드로이드 휴대폰 앱이 나왔습니다. 웹메일의 [설정] → [휴대폰 앱]에서 받을 수 있습니다.
+- 앱에서 메일을 읽고 쓰고 찾을 수 있고, 새 메일이 오면 휴대폰으로 알려 드립니다.
+  알림에는 새 메일이 몇 통인지만 나오고, 보낸 사람이나 제목은 나오지 않습니다.
+```
+
+| 줄 | 뜻 |
+| --- | --- |
+| `# 제목` | 파일의 첫 줄이고 꼭 있어야 합니다. 목록의 한 줄과 글 화면의 제목이 됩니다(100자까지). |
+| `## 머리` | 묶음 머리입니다. 휴대폰 앱, 메일 검색처럼 어디 이야기인지 씁니다(40자까지). |
+| `- 한 줄` | 앞에 점이 붙은 한 줄입니다(500자까지). 쓴 글이 그대로 나옵니다. |
+| (빈칸 두 개) 글 | 앞 줄에 띄어쓰기 하나로 이어 붙습니다. 긴 줄을 파일에서 나눠 쓸 때 씁니다. |
+| `<!-- … -->` | 메모입니다. 화면에 나오지 않습니다. 줄 앞에서 시작합니다(앞에 빈칸은 있어도 되지만, 글 뒤에 붙여 쓰지는 않습니다). 여러 줄로 써도 됩니다. |
+| `- `(머리 없이) | 머리 없는 묶음입니다. 고친 것 한두 줄처럼 짧은 글에 씁니다. 제목 바로 아래에 씁니다. |
+
+## 지킬 것
+
+- 날짜는 파일 이름에서 읽으니 파일 안에 다시 쓰지 않습니다. 있는 날짜여야 합니다(`2026-02-30.md`는 안 됩니다).
+- 파일 이름은 글 주소가 됩니다. 날짜를 고치면 주소도 바뀌어, 그전 주소로 들어오면 없는 글 화면이 나옵니다.
+- 글 하나에 줄(`- `)이 하나는 있어야 하고, 묶음 머리 아래에도 줄이 하나는 있어야 합니다.
+- 굵게, 링크, 그림, 표, `###`, 하위 목록은 쓸 수 없습니다. 쓴 글이 그대로 나옵니다. 단추나 메뉴 이름은 `[설정] → [휴대폰 앱]`처럼 씁니다.
+- 이 폴더에는 이 안내(`README.md`)와 글 파일만 둡니다. 파일은 UTF-8로 저장합니다.
+- 형식이 틀린 글은 시험(CI)이 막습니다. 미리 보려면 backend 폴더에서 `npm run test -- release-notes`를 돌립니다. 그래도 배포되면 서버는 그 글만 건너뛰고 로그에 파일 이름과 줄 번호를 남깁니다. 서버는 그대로 뜹니다.
+- 앱은 옛 판이어도 새 글을 받으니, 앱 이야기를 쓸 때 새 판을 내지 않아도 됩니다.

backend/src/app.module.ts

@@ -10,6 +10,7 @@ import { ClientIpThrottlerGuard } from '@/common/guards/client-ip-throttler.guar
 import { OriginGuard } from '@/common/guards/origin.guard';
 import { AccountSecurityModule } from '@/modules/account-security/account-security.module';
 import { AppConfigModule } from '@/modules/app-config/app-config.module';
+import { AppReleasesModule } from '@/modules/app-releases/app-releases.module';
 import { AuthModule } from '@/modules/auth/auth.module';
 import { ContactsModule } from '@/modules/contacts/contacts.module';
 import { FileSharingModule } from '@/modules/file-sharing/file-sharing.module';
@@ -17,6 +18,7 @@ import { FileStorageModule } from '@/modules/file-storage/file-storage.module';
 import { HealthModule } from '@/modules/health/health.module';
 import { MailModule } from '@/modules/mail/mail.module';
 import { PushModule } from '@/modules/push/push.module';
+import { ReleaseNotesModule } from '@/modules/release-notes/release-notes.module';
 import { SystemSettingsModule } from '@/modules/system-settings/system-settings.module';
 import { UploadModule } from '@/modules/upload/upload.module';
 import { UserModule } from '@/modules/user/user.module';
@@ -86,6 +88,10 @@ const THROTTLE_DEFAULT_LIMIT = 100; // 구간당 IP별 최대 요청 수
     PushModule,
     // 앱 설정 (앱 1단계) — GET /api/app-config (로그인 없음 — 최소 판 · 알림을 보낼 수 있는지)
     AppConfigModule,
+    // 휴대폰 앱 받기 (사내 배포) — 최신 판 정보 · APK 파일 (로그인 필요). 올리기는 운영 도구다
+    AppReleasesModule,
+    // 업데이트 내역 — 목록 · 글 (로그인 필요). 글은 저장소의 backend/release-notes 폴더(글 파일 하나가 글 하나), 올리는 API 는 없다
+    ReleaseNotesModule,
     UploadModule,
     UserModule,
   ],

backend/src/migrations/1794140434961-AddAppReleases.ts

@@ -0,0 +1,32 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * 휴대폰 앱 판 표 (docs/mail/api-contract.md 1절 "휴대폰 앱 받기" — 사내 배포, 2026-11-08).
+ * - app_releases: 운영 도구 「휴대폰 앱 올리기」가 올린 판마다 한 줄 — 플랫폼 · 판 · 크기 · SHA-256 · 디스크 이름(file_key UUID) · 올린 이(운영자 이름) · 올린 때.
+ *   file_key 유일 인덱스(디스크 이름은 한 줄에만), (platform, created_at) 인덱스(최신 = 그 플랫폼에서 가장 늦게 올린 줄)
+ * 기존 표의 칸 · 행은 건드리지 않는다 — 표를 새로 만들기만 한다.
+ * (엔티티: modules/app-releases/app-release.entity.ts — migration:generate 의 결과(이 표의 세 문장뿐이었다)를 그대로 옮겼다)
+ */
+export class AddAppReleases1794140434961 implements MigrationInterface {
+  name = 'AddAppReleases1794140434961';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `CREATE TABLE "app_releases" ("id" uuid NOT NULL, "platform" character varying(16) NOT NULL, "version" character varying(16) NOT NULL, "size_bytes" bigint NOT NULL, "sha256" character(64) NOT NULL, "file_key" uuid NOT NULL, "uploaded_by" character varying(100) NOT NULL, "created_at" TIMESTAMP WITH TIME ZONE NOT NULL, CONSTRAINT "PK_e5b28b6fe128172639b75251cd1" PRIMARY KEY ("id"))`,
+    );
+    await queryRunner.query(
+      `CREATE UNIQUE INDEX "UQ_app_releases_file_key" ON "app_releases" ("file_key") `,
+    );
+    await queryRunner.query(
+      `CREATE INDEX "IDX_app_releases_platform_created_at" ON "app_releases" ("platform", "created_at") `,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP INDEX "public"."IDX_app_releases_platform_created_at"`,
+    );
+    await queryRunner.query(`DROP INDEX "public"."UQ_app_releases_file_key"`);
+    await queryRunner.query(`DROP TABLE "app_releases"`);
+  }
+}

backend/src/migrations/1794269810995-MultipleMailSignatures.ts

@@ -0,0 +1,115 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * 여러 서명 (docs/mail/api-contract.md 2절 "서명" — 16단계).
+ * mail_signatures 를 "한 사람에 한 줄(열쇠 = 주소)"에서 "서명마다 한 줄(열쇠 = id)"로 바꾼다 — 표를 새로 만들지 않고 고쳐 쓴다
+ * (퇴사 마무리는 그대로 주소로 이 표의 줄을 지운다 — modules/ops/ops-data.service.ts).
+ * - 지금 서명은 "기본 서명"이라는 이름의 서명 하나가 되고, 만든 시각은 저장한 시각이다. **내용이 비어 있던 서명(서식 · 텍스트가 모두 없거나 공백뿐)은 옮기지 않는다**(보드 결정)
+ * - 두 체크(is_for_new · is_for_reply — 그 서명을 새 메일 · 답장과 전달에 넣는다)는 「메일에 넣을 서명」 둘의 표시가 된다 — 켠 곳의 기본이 그 서명, 끈 곳은 넣지 않음.
+ *   칸 이름만 바꿔 값을 그대로 둔다(migration:generate 는 칸을 지우고 새로 만들어 값을 잃는다). 처음 값은 false(새로 만든 서명은 기본이 아니다)
+ * - 한 사람에 기본 하나씩 — 부분 유일 인덱스 둘. 목록(만든 차례)은 (user_email, created_at) 인덱스
+ * - 서명 그림 표(mail_signature_images)는 그대로 — 그림은 모든 서명이 함께 쓴다
+ * 되돌리기(down): 한 사람에 한 줄만 남긴다 — 「새 메일」 기본 → 「답장 · 전달」 기본 → 먼저 만든 서명 차례로 하나, **나머지 서명은 지운다**.
+ * 남긴 서명의 두 표시가 옛 두 체크가 된다. 옛 서버는 서명을 다음에 저장할 때 그 서명이 가리키지 않는 그림을 지운다.
+ * (엔티티: modules/mail-signature/mail-signature.entity.ts — migration:generate 의 결과에서 이름(PK · 인덱스)은 그대로 두고 값을 지키게 고쳤다)
+ */
+export class MultipleMailSignatures1794269810995 implements MigrationInterface {
+  name = 'MultipleMailSignatures1794269810995';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // 내용이 비어 있던 서명은 옮기지 않는다 — 서식 · 텍스트 모두 없거나 공백뿐 (서비스는 빈 서식을 null 로 저장해 왔다)
+    await queryRunner.query(
+      `DELETE FROM "mail_signatures" WHERE ("body_html" IS NULL OR "body_html" !~ '\\S') AND ("body_text" IS NULL OR "body_text" !~ '\\S')`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ADD "id" uuid NOT NULL DEFAULT gen_random_uuid()`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ALTER COLUMN "id" DROP DEFAULT`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ADD "name" character varying(64) NOT NULL DEFAULT '기본 서명'`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ALTER COLUMN "name" DROP DEFAULT`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ADD "created_at" TIMESTAMP WITH TIME ZONE`,
+    );
+    await queryRunner.query(
+      `UPDATE "mail_signatures" SET "created_at" = "updated_at"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ALTER COLUMN "created_at" SET NOT NULL`,
+    );
+    // 두 체크 → 「메일에 넣을 서명」 둘의 표시 (값은 그대로)
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" RENAME COLUMN "is_for_new" TO "is_new_message_default"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ALTER COLUMN "is_new_message_default" SET DEFAULT false`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" RENAME COLUMN "is_for_reply" TO "is_reply_default"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ALTER COLUMN "is_reply_default" SET DEFAULT false`,
+    );
+    // 열쇠 — 주소 → 서명 id
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" DROP CONSTRAINT "PK_4846a94ce96c5f4fe400f449a7f"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ADD CONSTRAINT "PK_d210af8f68aec58b45e5f2ea02b" PRIMARY KEY ("id")`,
+    );
+    await queryRunner.query(
+      `CREATE UNIQUE INDEX "UQ_mail_signatures_reply_default" ON "mail_signatures" ("user_email") WHERE "is_reply_default"`,
+    );
+    await queryRunner.query(
+      `CREATE UNIQUE INDEX "UQ_mail_signatures_new_message_default" ON "mail_signatures" ("user_email") WHERE "is_new_message_default"`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX "IDX_mail_signatures_user_email_created_at" ON "mail_signatures" ("user_email", "created_at") `,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // 한 사람에 한 줄만 — 「새 메일」 기본 → 「답장 · 전달」 기본 → 먼저 만든 서명 차례로 남기고 나머지는 지운다
+    await queryRunner.query(
+      `DELETE FROM "mail_signatures" AS "s" USING (SELECT "id", row_number() OVER (PARTITION BY "user_email" ORDER BY "is_new_message_default" DESC, "is_reply_default" DESC, "created_at" ASC, "id" ASC) AS "rank" FROM "mail_signatures") AS "ranked" WHERE "s"."id" = "ranked"."id" AND "ranked"."rank" > 1`,
+    );
+    await queryRunner.query(
+      `DROP INDEX "public"."IDX_mail_signatures_user_email_created_at"`,
+    );
+    await queryRunner.query(
+      `DROP INDEX "public"."UQ_mail_signatures_new_message_default"`,
+    );
+    await queryRunner.query(
+      `DROP INDEX "public"."UQ_mail_signatures_reply_default"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" DROP CONSTRAINT "PK_d210af8f68aec58b45e5f2ea02b"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ADD CONSTRAINT "PK_4846a94ce96c5f4fe400f449a7f" PRIMARY KEY ("user_email")`,
+    );
+    // 남긴 서명의 표시 → 옛 두 체크 (처음 값은 옛 그대로 true)
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" RENAME COLUMN "is_reply_default" TO "is_for_reply"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ALTER COLUMN "is_for_reply" SET DEFAULT true`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" RENAME COLUMN "is_new_message_default" TO "is_for_new"`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" ALTER COLUMN "is_for_new" SET DEFAULT true`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE "mail_signatures" DROP COLUMN "created_at"`,
+    );
+    await queryRunner.query(`ALTER TABLE "mail_signatures" DROP COLUMN "name"`);
+    await queryRunner.query(`ALTER TABLE "mail_signatures" DROP COLUMN "id"`);
+  }
+}

backend/src/modules/account-security/account-security.provider.ts

@@ -43,6 +43,14 @@ export type TwoFactorEnableResult = 'enabled' | 'refused' | 'unknown';
  */
 export type TwoFactorDisableResult = 'disabled' | 'code-rejected' | 'unknown';
 
+/**
+ * 2단계 인증 휴대폰 바꾸기의 엔진 판단 (16단계 — 켠 채 새 비밀로) — 비밀번호는 부르는 쪽이 먼저 확인한다:
+ * - replaced: 바꿨다 — 옛 비밀은 바로 죽는다
+ * - code-rejected: 엔진이 받지 않았다 — 지금 휴대폰의 코드 틀림 (엔진은 비밀번호 틀림과 코드 틀림을 가르지 않는다)
+ * - unknown: 결과를 알 수 없게 끝났다 — 엔진은 otpUrl 을 가려 보여 주므로 다시 읽어도 가를 수 없다
+ */
+export type TwoFactorReplaceResult = 'replaced' | 'code-rejected' | 'unknown';
+
 export interface AccountSecurityProvider {
   /** 엔진에서 2단계 인증이 켜져 있는가 — 엔진이 기준이다 (계약 5절 "2단계 인증") */
   isTwoFactorEnabled(user: string): Promise<boolean>;
@@ -64,6 +72,17 @@ export interface AccountSecurityProvider {
     otpCode: string,
   ): Promise<TwoFactorDisableResult>;
 
+  /**
+   * 2단계 인증을 켠 채 휴대폰(비밀)을 바꾼다 (16단계) — 지금 비밀번호 · 지금 휴대폰의 코드 · 새 otpauth 주소를 한 요청으로.
+   * 2단계가 꺼지는 틈이 없다. 엔진은 새 비밀의 코드를 보지 않는다 — 새 휴대폰의 코드 확인은 부르는 쪽(TwoFactorService)이 먼저 한다
+   */
+  replaceTwoFactor(
+    user: string,
+    currentPassword: string,
+    otpCode: string,
+    otpauthUrl: string,
+  ): Promise<TwoFactorReplaceResult>;
+
   /** 앱 비밀번호 목록 (차례는 부르는 쪽이 정한다) */
   listAppPasswords(user: string): Promise<AppPasswordRecord[]>;
 

backend/src/modules/account-security/dto/two-factor.dto.ts

@@ -101,6 +101,53 @@ export class TwoFactorActivationDto {
   currentPassword!: string;
 }
 
+/** POST /api/two-factor/enrollments/{id}/verification (16단계 — 휴대폰 바꾸기 ①) */
+export class TwoFactorVerificationDto {
+  @ApiProperty({
+    description:
+      '새 휴대폰 인증 앱의 숫자 6자리 — 등록의 비밀로 서버가 확인한다(앞뒤 30초까지)',
+    example: '123456',
+  })
+  @OtpCodeField()
+  otpCode!: string;
+}
+
+/** POST /api/two-factor/enrollments/{id}/verification → 200 */
+export class TwoFactorVerifiedDto {
+  @ApiProperty({
+    description:
+      '늘 true — 등록에 "확인됨"을 달았다(10분 안에 바꾸기를 보낸다)',
+    example: true,
+  })
+  verified!: true;
+}
+
+/** POST /api/two-factor/replacements (16단계 — 휴대폰 바꾸기 ②) */
+export class TwoFactorReplacementDto {
+  @ApiProperty({
+    description:
+      '확인한 등록의 enrollmentId (POST /api/two-factor/enrollments → …/verification)',
+    example: '1f0c2a5e-3c1d-4b8e-9f57-6e2d1b0a9c44',
+  })
+  @IsUUID('all', { message: '2단계 인증 등록 정보가 올바르지 않습니다.' })
+  enrollmentId!: string;
+
+  @ApiProperty({
+    description: '지금 휴대폰 인증 앱의 숫자 6자리 — 엔진이 확인한다',
+    example: '654321',
+  })
+  @OtpCodeField()
+  currentOtpCode!: string;
+
+  @ApiProperty({
+    description: `지금 비밀번호 (${MAX_PASSWORD_LENGTH}자 이하, 앱 비밀번호는 받지 않는다)`,
+    format: 'password',
+    example: 'current-password',
+  })
+  @CurrentPasswordField()
+  currentPassword!: string;
+}
+
 /** POST /api/two-factor/deactivation */
 export class TwoFactorDeactivationDto {
   @ApiProperty({

backend/src/modules/account-security/two-factor-enrollment-id.pipe.ts

@@ -0,0 +1,21 @@
+import { Injectable, PipeTransform } from '@nestjs/common';
+import { isUUID } from 'class-validator';
+
+import { BusinessException } from '@/common/errors/business.exception';
+
+/**
+ * 경로의 2단계 인증 등록 id (16단계 — `/api/two-factor/enrollments/{id}/verification`) — UUID 가 아니면 400 VAL_001.
+ * 켜기 · 바꾸기 본문의 enrollmentId(IsUUID)와 같은 규칙이다 (모양은 맞는데 없는 등록은 서비스가 409 AUTH_008)
+ */
+@Injectable()
+export class TwoFactorEnrollmentIdPipe implements PipeTransform<
+  unknown,
+  string
+> {
+  transform(value: unknown): string {
+    if (typeof value === 'string' && isUUID(value, 'all')) return value;
+    throw new BusinessException('VAL_001', {
+      context: { reason: 'malformed-two-factor-enrollment-id' },
+    });
+  }
+}

backend/src/modules/account-security/two-factor-enrollments.ts

@@ -12,13 +12,16 @@ export interface TwoFactorEnrollment {
   readonly secret: Buffer;
   /** 끝나는 때 (epoch ms) */
   readonly expiresAt: number;
+  /** 새 휴대폰의 코드로 확인했다 — 휴대폰 바꾸기(16단계)는 확인한 등록으로만 한다 */
+  readonly verified?: boolean;
 }
 
 /**
  * 기다리는 2단계 인증 등록 (계약 5절 "2단계 인증") — 직원마다 하나, 10분.
- * 새로 시작하면 앞의 것을 버린다. 켜면(또는 시간이 지나면) 지운다 — 켠 뒤의 비밀은 엔진에만 있다(서버 · DB · 로그 어디에도 두지 않는다).
+ * 새로 시작하면 앞의 것을 버린다. 켜거나 휴대폰을 바꾸면(또는 시간이 지나면) 지운다 — 그 뒤의 비밀은 엔진에만 있다(서버 · DB · 로그 어디에도 두지 않는다).
+ * 켜기와 휴대폰 바꾸기(16단계 — 켜져 있을 때의 등록)가 같은 자리를 쓴다.
  *
- * ⚠️ 프로세스 메모리다 — 인스턴스를 늘리면 공유 저장소로 옮긴다(10분짜리 항목). 그대로면 다른 인스턴스로 간 켜기가 409 AUTH_008 이다.
+ * ⚠️ 프로세스 메모리다 — 인스턴스를 늘리면 공유 저장소로 옮긴다(10분짜리 항목). 그대로면 다른 인스턴스로 간 켜기 · 바꾸기가 409 AUTH_008 이다.
  */
 @Injectable()
 export class TwoFactorEnrollments {
@@ -45,6 +48,14 @@ export class TwoFactorEnrollments {
     return enrollment.id === id ? enrollment : null;
   }
 
+  /** 그 id 의 등록에 "확인됨"을 단다 (새 휴대폰의 코드가 맞았다) — 등록이 없거나 지났거나 바뀌었으면 false */
+  markVerified(email: string, id: string, now: number = Date.now()): boolean {
+    const enrollment = this.find(email, id, now);
+    if (!enrollment) return false;
+    this.pending.set(email, { ...enrollment, verified: true });
+    return true;
+  }
+
   /** 등록을 버린다 — 비밀 바이트도 지운다 */
   forget(email: string): void {
     const enrollment = this.pending.get(email);

backend/src/modules/account-security/two-factor.controller.ts

@@ -5,6 +5,7 @@ import {
   HttpCode,
   HttpStatus,
   Ip,
+  Param,
   Post,
   UseGuards,
 } from '@nestjs/common';
@@ -25,8 +26,12 @@ import {
   TwoFactorActivationDto,
   TwoFactorDeactivationDto,
   TwoFactorEnrollmentDto,
+  TwoFactorReplacementDto,
   TwoFactorStatusDto,
+  TwoFactorVerificationDto,
+  TwoFactorVerifiedDto,
 } from './dto/two-factor.dto';
+import { TwoFactorEnrollmentIdPipe } from './two-factor-enrollment-id.pipe';
 import {
   TwoFactorService,
   type TwoFactorStatusView,
@@ -50,7 +55,7 @@ function toStatusDto(status: TwoFactorStatusView): TwoFactorStatusDto {
   'AUTH_001',
   '로그인 필요 (쿠키 없음 · 만료 · 끊은 세션) · 웹메일로 다루지 않는 계정(메일 엔진 관리자 등)',
 )
-// 13단계 — 상태 · 등록 · 켜기는 제한된 세션(비밀번호 바꾸기 · 2단계 켜기 전)도 부른다(@AllowRestrictedSession). 끄기는 403 AUTH_010
+// 13단계 — 상태 · 등록 · 켜기는 제한된 세션(비밀번호 바꾸기 · 2단계 켜기 전)도 부른다(@AllowRestrictedSession). 끄기 · 휴대폰 바꾸기(16단계 — 확인 · 바꾸기)는 403 AUTH_010
 @Controller('two-factor')
 export class TwoFactorController {
   constructor(private readonly twoFactor: TwoFactorService) {}
@@ -80,18 +85,19 @@ export class TwoFactorController {
   @AllowRestrictedSession()
   @NoStore()
   @ApiOperation({
-    summary: '2단계 인증 등록 시작 — 비밀과 otpauth 주소 (꺼져 있을 때만)',
+    summary:
+      '2단계 인증 등록 시작 — 비밀과 otpauth 주소 (꺼져 있으면 켜기용 · 켜져 있으면 휴대폰 바꾸기용)',
     description:
-      '서버가 160비트 비밀을 만들어 10분 동안 서버 메모리에만 둔다(켜면 엔진에만 남는다). 직원마다 기다리는 등록은 하나 — 새로 시작하면 앞의 것은 버린다. ' +
+      '서버가 160비트 비밀을 만들어 10분 동안 서버 메모리에만 둔다(켜거나 바꾸면 엔진에만 남는다). 직원마다 기다리는 등록은 하나 — 새로 시작하면 앞의 것은 버린다. ' +
+      '16단계부터 켜져 있어도 받는다(휴대폰 바꾸기 — …/verification → /api/two-factor/replacements). 켜진 채 이 등록으로 켜기를 보내면 409 AUTH_008 이다. ' +
       '응답은 Cache-Control: private, no-store.',
   })
   @ApiStandardResponse(TwoFactorEnrollmentDto, {
     status: 201,
     description: '등록 — 비밀 · otpauth 주소는 이 응답에만',
   })
-  @ApiErrorResponse('AUTH_008', '이미 켜져 있음 — 화면은 상태를 다시 받는다')
   @ApiErrorResponse('REQ_001', '같은 직원의 2단계 인증 바꾸기가 처리 중')
-  @ApiErrorResponse('MAIL_001', '메일 엔진 장애')
+  @ApiErrorResponse('MAIL_001', '메일 엔진 설정 없음')
   async enroll(
     @CurrentUser() user: AuthenticatedUser,
   ): Promise<TwoFactorEnrollmentDto> {
@@ -104,6 +110,93 @@ export class TwoFactorController {
     };
   }
 
+  @Post('enrollments/:id/verification')
+  @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: '휴대폰 바꾸기 ① — 새 휴대폰의 코드 확인 (16단계)',
+    description:
+      '새 휴대폰의 코드를 등록의 비밀로 확인하고(앞뒤 30초) 등록에 "확인됨"을 단다 — 엔진은 등록 때 코드를 보지 않는다. 엔진에는 아직 아무것도 바꾸지 않는다. ' +
+      '받은 코드는 2분 동안 다시 받지 않는다(코드 실패 한도 · 같은 코드 막기는 켜기 · 끄기와 같다). 확인은 등록에 남는다(10분) — [이전]으로 돌아와도 다시 확인하지 않아도 된다. ' +
+      '제한된 세션은 403 AUTH_010.',
+  })
+  @ApiStandardResponse(TwoFactorVerifiedDto, { description: '확인했다' })
+  @ApiErrorResponse(
+    'AUTH_006',
+    'AUTH_006 코드 틀림 · 2분 안에 다시 쓴 코드 / VAL_001 코드 · 등록 id 형식 오류 (모두 400)',
+  )
+  @ApiErrorResponse(
+    'AUTH_008',
+    '등록이 없음 · 10분 지남 · 더 새 등록으로 바뀜 — 화면은 처음부터 다시(새 등록)',
+  )
+  @ApiErrorResponse(
+    'AUTH_010',
+    '제한된 세션 — 먼저 비밀번호를 바꾸거나 2단계 인증을 켠다 (13단계)',
+  )
+  @ApiErrorResponse(
+    'REQ_001',
+    '코드 실패 한도(같은 주소 15분 5회 · 24시간 20회) · 처리 중',
+  )
+  async verifyEnrollment(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param('id', TwoFactorEnrollmentIdPipe) id: string,
+    @Body() dto: TwoFactorVerificationDto,
+    @Ip() ip: string,
+  ): Promise<TwoFactorVerifiedDto> {
+    await this.twoFactor.verifyEnrollment(
+      user.email,
+      { enrollmentId: id, otpCode: dto.otpCode },
+      { ip },
+    );
+    return { verified: true };
+  }
+
+  @Post('replacements')
+  @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary:
+      '휴대폰 바꾸기 ② — 지금 휴대폰의 코드와 지금 비밀번호로 바꾼다 (16단계)',
+    description:
+      '①에서 확인한 등록만 받는다. 지금 비밀번호를 먼저 확인하고(틀리면 AUTH_005 — 로그인 실패 한도로 센다, 그사이 2단계가 꺼졌으면 AUTH_008) ' +
+      '지금 휴대폰의 코드와 새 비밀을 엔진 요청 하나로 보낸다 — 2단계가 꺼지는 틈이 없고 옛 휴대폰의 코드는 바로 막힌다. ' +
+      '지금 코드가 틀리거나 2분 안에 다시 쓴 코드면 AUTH_006(코드 실패로 센다 — 등록은 남아 다시 보낼 수 있다). ' +
+      '결과를 모르면 503 MAIL_001 — 엔진이 비밀을 가려 보여 주어 다시 읽어도 가를 수 없다(등록은 남는다). 켠 때(enabledAt)는 그대로, 로그인된 기기는 끊지 않는다. ' +
+      '제한된 세션은 403 AUTH_010.',
+  })
+  @ApiStandardResponse(TwoFactorStatusDto, { description: '바꿨다' })
+  @ApiErrorResponse(
+    'AUTH_006',
+    'AUTH_006 지금 코드 틀림 · 2분 안에 다시 쓴 코드 / AUTH_005 지금 비밀번호 틀림 · 앱 비밀번호 / VAL_001 형식 오류 (모두 400)',
+  )
+  @ApiErrorResponse(
+    'AUTH_008',
+    '등록이 없음 · 10분 지남 · 더 새 등록 · 확인(①)하지 않은 등록 · 그사이 다른 곳에서 꺼짐 — 화면은 처음부터 다시',
+  )
+  @ApiErrorResponse(
+    'AUTH_010',
+    '제한된 세션 — 먼저 비밀번호를 바꾸거나 2단계 인증을 켠다 (13단계)',
+  )
+  @ApiErrorResponse('REQ_001', '코드 실패 한도 · 비밀번호 실패 한도 · 처리 중')
+  @ApiErrorResponse(
+    'MAIL_001',
+    '메일 엔진 장애 · 결과를 알 수 없음(가를 수 없다 — 다시 보내기 전에 새 휴대폰의 코드로 로그인되는지 본다)',
+  )
+  async replace(
+    @CurrentUser() user: AuthenticatedUser,
+    @Body() dto: TwoFactorReplacementDto,
+    @Ip() ip: string,
+  ): Promise<TwoFactorStatusDto> {
+    const status = await this.twoFactor.replace(
+      user.email,
+      {
+        enrollmentId: dto.enrollmentId,
+        currentOtpCode: dto.currentOtpCode,
+        currentPassword: dto.currentPassword,
+      },
+      { ip },
+    );
+    return toStatusDto(await this.twoFactor.withPolicy(user.email, status));
+  }
+
   @Post('activation')
   @AllowRestrictedSession()
   @HttpCode(HttpStatus.OK)

backend/src/modules/account-security/two-factor.service.spec.ts

@@ -16,6 +16,7 @@ import type {
   AccountSecurityProvider,
   TwoFactorDisableResult,
   TwoFactorEnableResult,
+  TwoFactorReplaceResult,
 } from './account-security.provider';
 import { TwoFactorCodeGuard } from './two-factor-code-guard';
 import { TwoFactorEnrollments } from './two-factor-enrollments';
@@ -114,7 +115,10 @@ describe('TwoFactorService (2단계 인증 켜기 · 끄기 — 계약 5절)', (
   let provider: jest.Mocked<
     Pick<
       AccountSecurityProvider,
-      'isTwoFactorEnabled' | 'enableTwoFactor' | 'disableTwoFactor'
+      | 'isTwoFactorEnabled'
+      | 'enableTwoFactor'
+      | 'disableTwoFactor'
+      | 'replaceTwoFactor'
     >
   >;
   let mail: { verifyCredentials: jest.Mock };
@@ -160,6 +164,10 @@ describe('TwoFactorService (2단계 인증 켜기 · 끄기 — 계약 5절)', (
         engineEnabled = false;
         return Promise.resolve('disabled');
       }),
+      replaceTwoFactor: jest.fn<
+        Promise<TwoFactorReplaceResult>,
+        [string, string, string, string]
+      >(() => Promise.resolve('replaced')),
     };
     mail = {
       verifyCredentials: jest.fn(() =>
@@ -376,7 +384,7 @@ describe('TwoFactorService (2단계 인증 켜기 · 끄기 — 계약 5절)', (
     ).toBe('AUTH_008');
   });
 
-  it('그사이 다른 곳에서 켜졌으면 등록 · 켜기 모두 409 AUTH_008', async () => {
+  it('그사이 다른 곳에서 켜졌으면 켜기는 409 AUTH_008 — 등록은 켜져 있어도 받는다(16단계 휴대폰 바꾸기용 · 엔진에 묻지 않는다)', async () => {
     const { enrollment, code } = await enroll();
     engineEnabled = true;
 
@@ -395,9 +403,11 @@ describe('TwoFactorService (2단계 인증 켜기 · 끄기 — 계약 5절)', (
         )
       )?.code,
     ).toBe('AUTH_008');
-    expect((await failureOf(service.startEnrollment(ARA)))?.code).toBe(
-      'AUTH_008',
-    );
+    provider.isTwoFactorEnabled.mockClear();
+    await expect(service.startEnrollment(ARA)).resolves.toMatchObject({
+      secret: expect.stringMatching(/^[A-Z2-7]{32}$/) as unknown,
+    });
+    expect(provider.isTwoFactorEnabled).not.toHaveBeenCalled();
   });
 
   it('켜기의 결과를 모르면 엔진을 다시 읽어 켜졌으면 성공, 아니면 503 MAIL_001', async () => {
@@ -579,6 +589,251 @@ describe('TwoFactorService (2단계 인증 켜기 · 끄기 — 계약 5절)', (
     }
   });
 
+  describe('휴대폰 바꾸기 (16단계 — 켠 채 새 비밀로)', () => {
+    const OLD_CODE = '135790';
+    const enabledAt = new Date('2026-10-31T00:12:00.000Z');
+
+    beforeEach(() => {
+      engineEnabled = true;
+      table.rows.set(ARA, { userEmail: ARA, enabledAt });
+      // 엔진 대역 — 지금 휴대폰의 코드는 OLD_CODE 하나만 맞다
+      provider.replaceTwoFactor.mockImplementation((_user, _password, code) =>
+        Promise.resolve(code === OLD_CODE ? 'replaced' : 'code-rejected'),
+      );
+    });
+
+    /** 등록하고 새 휴대폰의 코드로 확인한다 */
+    const verified = async () => {
+      const { enrollment, code } = await enroll();
+      const newCode = code();
+      await service.verifyEnrollment(
+        ARA,
+        { enrollmentId: enrollment.enrollmentId, otpCode: newCode },
+        { ip: IP },
+      );
+      return { enrollment, newCode, code };
+    };
+
+    const replace = (
+      enrollmentId: string,
+      overrides: { currentOtpCode?: string; currentPassword?: string } = {},
+      ip = IP,
+    ) =>
+      service.replace(
+        ARA,
+        {
+          enrollmentId,
+          currentOtpCode: OLD_CODE,
+          currentPassword: PASSWORD,
+          ...overrides,
+        },
+        { ip },
+      );
+
+    it('① 새 휴대폰의 코드를 등록의 비밀로 확인(엔진에 묻지 않는다) → ② 지금 비밀번호(본인 Basic 402) → 지금 코드와 새 주소를 엔진 한 요청 — 켠 때는 그대로, 등록은 지운다', async () => {
+      const { enrollment, newCode } = await verified();
+      expect(mail.verifyCredentials).not.toHaveBeenCalled();
+      expect(provider.replaceTwoFactor).not.toHaveBeenCalled();
+      expect(codes.isUsed(ARA, newCode)).toBe(true);
+
+      const status = await replace(enrollment.enrollmentId);
+
+      expect(status).toEqual({ isEnabled: true, enabledAt });
+      expect(mail.verifyCredentials).toHaveBeenCalledWith(ARA, PASSWORD);
+      expect(provider.replaceTwoFactor).toHaveBeenCalledWith(
+        ARA,
+        PASSWORD,
+        OLD_CODE,
+        enrollment.otpauthUrl,
+      );
+      expect(codes.isUsed(ARA, OLD_CODE)).toBe(true);
+      expect(table.rows.get(ARA)?.enabledAt).toEqual(enabledAt);
+      expect(logs).toContain(
+        '2단계 인증 휴대폰을 바꿨습니다: a***@arasystem.test',
+      );
+      expect(logs.join('\n')).not.toMatch(
+        new RegExp(`${OLD_CODE}|${newCode}|${PASSWORD}|otpauth`),
+      );
+      // 등록은 지웠다 — 같은 등록으로 다시 바꾸지 못한다
+      expect((await failureOf(replace(enrollment.enrollmentId)))?.code).toBe(
+        'AUTH_008',
+      );
+    });
+
+    it('확인하지 않은 등록은 409 AUTH_008 — 등록을 버린다(처음부터) · 없는 등록 · 다른 id 도 AUTH_008', async () => {
+      const { enrollment, code } = await enroll();
+      expect((await failureOf(replace(enrollment.enrollmentId)))?.code).toBe(
+        'AUTH_008',
+      );
+      // 버렸다 — 확인도 할 수 없다
+      expect(
+        (
+          await failureOf(
+            service.verifyEnrollment(
+              ARA,
+              { enrollmentId: enrollment.enrollmentId, otpCode: code() },
+              { ip: IP },
+            ),
+          )
+        )?.code,
+      ).toBe('AUTH_008');
+      expect(
+        (await failureOf(replace('00000000-0000-4000-8000-000000000000')))
+          ?.code,
+      ).toBe('AUTH_008');
+      expect(mail.verifyCredentials).not.toHaveBeenCalled();
+      expect(provider.replaceTwoFactor).not.toHaveBeenCalled();
+    });
+
+    it('① 새 휴대폰의 코드가 틀리면 400 AUTH_006 — 코드 실패로 센다(15분 5회 → REQ_001), 확인되지 않는다', async () => {
+      const { enrollment, code } = await enroll();
+      const wrong = code() === '000000' ? '111111' : '000000';
+      for (let i = 0; i < TWO_FACTOR_CODE_ADDRESS_LIMIT; i += 1) {
+        expect(
+          (
+            await failureOf(
+              service.verifyEnrollment(
+                ARA,
+                { enrollmentId: enrollment.enrollmentId, otpCode: wrong },
+                { ip: `198.51.100.${i}` },
+              ),
+            )
+          )?.code,
+        ).toBe('AUTH_006');
+      }
+      expect(
+        (
+          await failureOf(
+            service.verifyEnrollment(
+              ARA,
+              { enrollmentId: enrollment.enrollmentId, otpCode: code() },
+              { ip: IP },
+            ),
+          )
+        )?.code,
+      ).toBe('REQ_001');
+      expect((await failureOf(replace(enrollment.enrollmentId)))?.code).toBe(
+        'AUTH_008',
+      );
+    });
+
+    it('② 지금 비밀번호가 틀리면 400 AUTH_005(로그인 실패로 센다) · 앱 비밀번호 모양은 묻지 않고 AUTH_005 — 엔진에 보내지 않고 등록은 남는다', async () => {
+      const { enrollment } = await verified();
+      mail.verifyCredentials.mockResolvedValueOnce(INVALID);
+      expect(
+        (
+          await failureOf(
+            replace(enrollment.enrollmentId, { currentPassword: 'wrong' }),
+          )
+        )?.code,
+      ).toBe('AUTH_005');
+      mail.verifyCredentials.mockClear();
+      expect(
+        (
+          await failureOf(
+            replace(enrollment.enrollmentId, {
+              currentPassword: `app_${'a'.repeat(36)}`,
+            }),
+          )
+        )?.context,
+      ).toMatchObject({ reason: 'app-password-shape' });
+      expect(mail.verifyCredentials).not.toHaveBeenCalled();
+      expect(provider.replaceTwoFactor).not.toHaveBeenCalled();
+      // 등록은 남았다 — 비밀번호만 고쳐 다시 보낸다
+      await expect(replace(enrollment.enrollmentId)).resolves.toMatchObject({
+        isEnabled: true,
+      });
+    });
+
+    it('② 그사이 다른 곳에서 꺼졌으면(본인 Basic 200) 409 AUTH_008 — 엔진에 보내지 않고 등록을 버린다', async () => {
+      const { enrollment } = await verified();
+      engineEnabled = false;
+      expect((await failureOf(replace(enrollment.enrollmentId)))?.code).toBe(
+        'AUTH_008',
+      );
+      expect(provider.replaceTwoFactor).not.toHaveBeenCalled();
+      engineEnabled = true;
+      expect((await failureOf(replace(enrollment.enrollmentId)))?.code).toBe(
+        'AUTH_008',
+      );
+    });
+
+    it('② 엔진이 지금 코드를 받지 않으면(forbidden) 400 AUTH_006 — 코드 실패로 센다, 등록은 남아 맞는 코드로 다시 보낼 수 있다', async () => {
+      const { enrollment, newCode } = await verified();
+      expect(
+        (
+          await failureOf(
+            replace(enrollment.enrollmentId, { currentOtpCode: '246800' }),
+          )
+        )?.code,
+      ).toBe('AUTH_006');
+      // 다시 쓴 코드(①에서 쓴 새 휴대폰의 코드)는 엔진에 묻지 않고 AUTH_006
+      provider.replaceTwoFactor.mockClear();
+      expect(
+        (
+          await failureOf(
+            replace(enrollment.enrollmentId, { currentOtpCode: newCode }),
+          )
+        )?.code,
+      ).toBe('AUTH_006');
+      expect(provider.replaceTwoFactor).not.toHaveBeenCalled();
+
+      await expect(replace(enrollment.enrollmentId)).resolves.toMatchObject({
+        isEnabled: true,
+      });
+    });
+
+    it('② 결과를 모르면 503 MAIL_001 — 다시 읽지 않는다(가를 수 없다), 코드는 쓰지 않은 것으로, 등록은 남는다', async () => {
+      const { enrollment } = await verified();
+      provider.replaceTwoFactor.mockResolvedValueOnce('unknown');
+      provider.isTwoFactorEnabled.mockClear();
+
+      const failure = await failureOf(replace(enrollment.enrollmentId));
+      expect(failure?.code).toBe('MAIL_001');
+      expect(failure?.context).toMatchObject({
+        reason: 'two-factor-replace-outcome-unknown',
+      });
+      expect(provider.isTwoFactorEnabled).not.toHaveBeenCalled();
+      expect(codes.isUsed(ARA, OLD_CODE)).toBe(false);
+      await expect(replace(enrollment.enrollmentId)).resolves.toMatchObject({
+        isEnabled: true,
+      });
+    });
+
+    it('같은 직원의 바꾸기가 처리 중이면 확인 · 바꾸기 모두 429 REQ_001', async () => {
+      const { enrollment, code } = await enroll();
+      const release = locks.acquire(ARA);
+      try {
+        expect(
+          (
+            await failureOf(
+              service.verifyEnrollment(
+                ARA,
+                { enrollmentId: enrollment.enrollmentId, otpCode: code() },
+                { ip: IP },
+              ),
+            )
+          )?.code,
+        ).toBe('REQ_001');
+        expect((await failureOf(replace(enrollment.enrollmentId)))?.code).toBe(
+          'REQ_001',
+        );
+      } finally {
+        release();
+      }
+    });
+
+    it('켠 때 기록을 읽지 못해도 바꾸기는 성공 — enabledAt null · error 로그', async () => {
+      const { enrollment } = await verified();
+      table.repository.findOneBy.mockRejectedValueOnce(new Error('db down'));
+      await expect(replace(enrollment.enrollmentId)).resolves.toEqual({
+        isEnabled: true,
+        enabledAt: null,
+      });
+      expect(errors.join('\n')).toContain('켠 때 기록을 읽지 못했습니다');
+    });
+  });
+
   describe('끄기', () => {
     beforeEach(() => {
       engineEnabled = true;

backend/src/modules/account-security/two-factor.service.ts

@@ -31,6 +31,7 @@ import { TwoFactorCodeGuard } from './two-factor-code-guard';
 import {
   TwoFactorEnrollments,
   enrollmentExpiry,
+  type TwoFactorEnrollment,
 } from './two-factor-enrollments';
 import { TwoFactorLocks } from './two-factor-locks';
 import { TwoFactorPolicyService } from './two-factor-policy.service';
@@ -74,7 +75,9 @@ function errorMessage(error: unknown): string {
 /**
  * 2단계 인증 켜기 · 끄기 (계약 5절 "2단계 인증") — **엔진이 기준이다**(켜짐은 엔진의 x:AccountPassword 로 본다).
  *
- * - 등록: 서버가 160비트 비밀을 만들어 10분 동안 메모리에만 둔다 (TwoFactorEnrollments). 이미 켜져 있으면 409 AUTH_008
+ * - 등록: 서버가 160비트 비밀을 만들어 10분 동안 메모리에만 둔다 (TwoFactorEnrollments). 켜져 있어도 받는다 — 휴대폰 바꾸기용(16단계)
+ * - 휴대폰 바꾸기(16단계): ① 새 휴대폰의 코드를 등록의 비밀로 확인해 등록에 "확인됨"을 단다(verifyEnrollment) ② 지금 비밀번호(본인 Basic 402) →
+ *   지금 휴대폰의 코드와 새 otpauth 주소를 엔진 한 요청으로(replace — 2단계가 꺼지는 틈이 없다). 결과를 모르면 MAIL_001(다시 읽어도 가를 수 없다)
  * - 켜기: 받은 코드를 등록의 비밀로 **먼저** 확인한다(±1 단계 — 엔진은 등록 때 코드를 보지 않는다, 잘못 등록하면 직원이 끄지도 못한다).
  *   둘 다 틀렸으면 코드부터 알린다. 그다음 지금 비밀번호를 본인 Basic 으로 확인하고(틀리면 AUTH_005 — 로그인 실패 한도로 센다,
  *   402 면 그사이 다른 곳에서 켜짐 → AUTH_008) 대리 접근으로 엔진에 otpauth 주소를 넣는다.
@@ -134,18 +137,13 @@ export class TwoFactorService {
     return this.reconcile(address, enabled);
   }
 
-  /** POST /api/two-factor/enrollments — 꺼져 있을 때만 */
+  /**
+   * POST /api/two-factor/enrollments — 꺼져 있으면 켜기용, 켜져 있으면 휴대폰 바꾸기용(16단계) — 같은 등록이다.
+   * 엔진에 묻지 않는다: 켜기는 비밀번호 확인(402)이, 바꾸기는 엔진이 지금 코드로 가른다
+   */
   async startEnrollment(user: string): Promise<TwoFactorEnrollmentView> {
     const address = this.requireEmployee(user);
-    return this.locks.run(address, async () => {
-      if (await this.provider.isTwoFactorEnabled(address)) {
-        throw new BusinessException('AUTH_008', {
-          context: {
-            reason: 'two-factor-already-enabled',
-            email: maskEmail(address),
-          },
-        });
-      }
+    return this.locks.run(address, () => {
       const now = Date.now();
       const enrollment = {
         id: randomUUID(),
@@ -154,15 +152,181 @@ export class TwoFactorService {
       };
       this.enrollments.put(address, enrollment);
       const secret = encodeBase32(enrollment.secret);
-      return {
+      return Promise.resolve({
         enrollmentId: enrollment.id,
         secret,
         otpauthUrl: this.otpauthUrl(address, secret),
         expiresAt: new Date(enrollment.expiresAt),
-      };
+      });
     });
   }
 
+  /**
+   * POST /api/two-factor/enrollments/{id}/verification — 새 휴대폰의 코드를 등록의 비밀로 확인하고 등록에 "확인됨"을 단다 (16단계 휴대폰 바꾸기 ①).
+   * 엔진은 등록 때 코드를 보지 않으므로 서버가 먼저 본다. 코드 확인은 켜기 · 끄기와 같은 코드 가드(실패 한도 · 2분 다시 쓰기 막기 — 받은 코드는 기억한다).
+   * 등록이 없음 · 10분 지남 · 더 새 등록이면 AUTH_008, 코드 틀림 AUTH_006. 엔진에 묻지 않는다
+   */
+  async verifyEnrollment(
+    user: string,
+    input: { readonly enrollmentId: string; readonly otpCode: string },
+    client: SecurityClient,
+  ): Promise<void> {
+    const address = this.requireEmployee(user);
+    const ip = client.ip || 'unknown';
+    return this.locks.run(address, async () => {
+      const enrollment = this.requireEnrollment(address, input.enrollmentId);
+      await this.codes.check<undefined>(
+        { email: address, ip },
+        input.otpCode,
+        () =>
+          Promise.resolve(
+            verifyTotp(enrollment.secret, input.otpCode, Date.now()) === null
+              ? { kind: 'rejected' as const }
+              : { kind: 'accepted' as const, value: undefined },
+          ),
+      );
+      if (!this.enrollments.markVerified(address, input.enrollmentId)) {
+        // 코드를 보는 사이 10분이 지났다
+        throw this.enrollmentMissing(address, 'two-factor-enrollment-expired');
+      }
+    });
+  }
+
+  /**
+   * POST /api/two-factor/replacements — 2단계 인증을 켠 채 휴대폰을 바꾼다 (16단계 ②). 확인한 등록 · 지금 휴대폰의 코드 · 지금 비밀번호.
+   * 1. 등록이 확인됨이 아니면 AUTH_008(등록을 버린다 — 처음부터)
+   * 2. 지금 비밀번호를 본인 Basic 으로 — 402 여야 한다(켜짐 · 비밀번호 맞음). 401 · 앱 비밀번호 모양은 AUTH_005(로그인 실패 한도로 센다 — 모양은 세지 않는다),
+   *    200 이면 그사이 다른 곳에서 꺼졌다 → AUTH_008(등록을 버린다). 엔진은 비밀번호 틀림과 코드 틀림을 가르지 않아 비밀번호를 먼저 본다
+   * 3. 다시 쓴 코드 · 코드 실패 차지(끄기와 같은 결) → 엔진 한 요청(지금 코드 + 새 otpauth 주소). forbidden 은 지금 코드 틀림 AUTH_006,
+   *    결과를 모르면 MAIL_001(엔진은 otpUrl 을 가려 다시 읽어도 가를 수 없다 — 그 코드는 쓰지 않은 것으로, 등록은 남긴다)
+   * 4. 바꾸면 등록의 비밀을 지운다. 켠 때(enabledAt)는 그대로. 로그인된 기기는 끊지 않는다(켜기 · 끄기와 같다)
+   */
+  async replace(
+    user: string,
+    input: {
+      readonly enrollmentId: string;
+      readonly currentOtpCode: string;
+      readonly currentPassword: string;
+    },
+    client: SecurityClient,
+  ): Promise<TwoFactorStatus> {
+    const address = this.requireEmployee(user);
+    const ip = client.ip || 'unknown';
+    return this.locks.run(address, async () => {
+      const enrollment = this.requireEnrollment(address, input.enrollmentId);
+      if (enrollment.verified !== true) {
+        this.enrollments.forget(address);
+        throw this.enrollmentMissing(
+          address,
+          'two-factor-enrollment-unverified',
+        );
+      }
+      if (isAppPasswordShape(input.currentPassword)) {
+        throw this.currentPasswordRejected(address, 'app-password-shape');
+      }
+      const otpauthUrl = this.otpauthUrl(
+        address,
+        encodeBase32(enrollment.secret),
+      );
+
+      const ticket = this.attempts.begin({ email: address, ip });
+      try {
+        const check = await this.mail.verifyCredentials(
+          address,
+          input.currentPassword,
+        );
+        if (check.kind === 'invalid') {
+          ticket.fail();
+          throw this.currentPasswordRejected(
+            address,
+            'current-password-rejected',
+          );
+        }
+        if (check.kind === 'valid') {
+          // 엔진에서 그사이 꺼졌다 — 바꿀 것이 없다. 처음부터(켜기)
+          ticket.succeed();
+          this.enrollments.forget(address);
+          throw new BusinessException('AUTH_008', {
+            context: {
+              reason: 'two-factor-disabled-elsewhere',
+              email: maskEmail(address),
+            },
+          });
+        }
+        // 402 — 켜져 있고 비밀번호가 맞다. 코드 단계가 끝날 때까지 같은 주소의 다른 시도는 처리 중이다
+        ticket.verified();
+
+        await this.codes.check<undefined>(
+          { email: address, ip },
+          input.currentOtpCode,
+          async () => {
+            const outcome = await this.provider.replaceTwoFactor(
+              address,
+              input.currentPassword,
+              input.currentOtpCode,
+              otpauthUrl,
+            );
+            if (outcome === 'code-rejected')
+              return { kind: 'rejected' as const };
+            if (outcome === 'unknown') {
+              throw new BusinessException('MAIL_001', {
+                context: {
+                  reason: 'two-factor-replace-outcome-unknown',
+                  email: maskEmail(address),
+                },
+              });
+            }
+            return { kind: 'accepted' as const, value: undefined };
+          },
+        );
+        ticket.succeed();
+      } finally {
+        ticket.abort();
+      }
+
+      // 엔진에서 바뀌었다 — 등록의 비밀을 지운다
+      this.enrollments.forget(address);
+      this.logger.log(`2단계 인증 휴대폰을 바꿨습니다: ${maskEmail(address)}`);
+      return { isEnabled: true, enabledAt: await this.readEnabledAt(address) };
+    });
+  }
+
+  /** 기다리는 등록 — 없음 · 10분 지남 · 더 새 등록이면 AUTH_008 */
+  private requireEnrollment(
+    address: string,
+    enrollmentId: string,
+  ): TwoFactorEnrollment {
+    const enrollment = this.enrollments.find(address, enrollmentId);
+    if (!enrollment) {
+      throw this.enrollmentMissing(address, 'two-factor-enrollment-missing');
+    }
+    return enrollment;
+  }
+
+  private enrollmentMissing(
+    address: string,
+    reason: string,
+  ): BusinessException {
+    return new BusinessException('AUTH_008', {
+      context: { reason, email: maskEmail(address) },
+    });
+  }
+
+  /** 켠 때 기록 — 읽지 못하면 error 로그만 남기고 null (엔진에서는 이미 바뀌었다) */
+  private async readEnabledAt(address: string): Promise<Date | null> {
+    try {
+      return (
+        (await this.settings.findOneBy({ userEmail: address }))?.enabledAt ??
+        null
+      );
+    } catch (error) {
+      this.logger.error(
+        `[SYS_001]${traceTag()} 2단계 인증 휴대폰을 바꿨지만 켠 때 기록을 읽지 못했습니다(엔진에서는 바뀌었다): user=${maskEmail(address)}, reason=${errorMessage(error)}`,
+      );
+      return null;
+    }
+  }
+
   /** POST /api/two-factor/activation */
   async activate(
     user: string,

backend/src/modules/app-releases/apk-file.spec.ts

@@ -0,0 +1,223 @@
+import { execFileSync } from 'child_process';
+import { createHash, randomBytes } from 'crypto';
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  truncateSync,
+  writeFileSync,
+} from 'fs';
+import { open } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { forEachChunk, inspectApk, type ApkInspection } from './apk-file';
+import {
+  APK_MAX_BYTES,
+  APK_MIN_BYTES,
+  APK_ZIP_SIGNATURE,
+} from './app-releases.constants';
+
+/** zip 머리 + 무작위 내용 */
+function apkBytes(size: number): Buffer {
+  return Buffer.concat([
+    APK_ZIP_SIGNATURE,
+    randomBytes(size - APK_ZIP_SIGNATURE.length),
+  ]);
+}
+
+const sha256 = (data: Buffer) =>
+  createHash('sha256').update(data).digest('hex');
+
+/** 검사가 막은 까닭 (통과했으면 연 파일을 닫고 'ok') */
+async function problemOf(inspection: ApkInspection): Promise<string> {
+  if (inspection.ok) {
+    await inspection.apk.close();
+    return 'ok';
+  }
+  return inspection.problem;
+}
+
+/** 이 시험을 root 로 돌리는가 — root 는 권한과 상관없이 읽는다 */
+const runningAsRoot = process.getuid?.() === 0;
+const onWindows = process.platform === 'win32';
+
+describe('inspectApk — 운영자가 넣은 APK 검사 (휴대폰 앱 올리기)', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'apk-file-'));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  const file = (name: string, data: Buffer) => {
+    const path = join(dir, name);
+    writeFileSync(path, data);
+    return path;
+  };
+
+  it('통과하면 크기 · SHA-256 · 파일 이름과 연 파일을 준다 — 연 파일로 다시 읽을 수 있다', async () => {
+    const data = apkBytes(64 * 1024);
+    const path = file('ARA-SYSTEM-1.0.0.apk', data);
+
+    const inspection = await inspectApk(path);
+    expect(inspection.ok).toBe(true);
+    if (!inspection.ok) return;
+    const { apk } = inspection;
+    try {
+      expect(apk).toMatchObject({
+        path,
+        fileName: 'ARA-SYSTEM-1.0.0.apk',
+        sizeBytes: data.length,
+        sha256: sha256(data),
+      });
+      const again = Buffer.alloc(data.length);
+      await apk.handle.read(again, 0, again.length, 0);
+      expect(again.equals(data)).toBe(true);
+    } finally {
+      await apk.close();
+    }
+  });
+
+  it('이름은 .apk 로 끝나야 한다 (대소문자는 가리지 않는다) — 이름이 틀리면 열지도 않는다', async () => {
+    const data = apkBytes(APK_MIN_BYTES);
+    await expect(
+      problemOf(await inspectApk(file('ARA-SYSTEM-1.0.0.APK', data))),
+    ).resolves.toBe('ok');
+    for (const name of ['ARA-SYSTEM-1.0.0.zip', 'ARA-SYSTEM-1.0.0', 'apk']) {
+      await expect(problemOf(await inspectApk(file(name, data)))).resolves.toBe(
+        'not-apk-name',
+      );
+    }
+    await expect(
+      problemOf(await inspectApk(join(dir, 'none.zip'))),
+    ).resolves.toBe('not-apk-name');
+  });
+
+  it('없는 경로 · 폴더 · 파일이 아닌 것은 알린다', async () => {
+    await expect(
+      problemOf(await inspectApk(join(dir, 'none.apk'))),
+    ).resolves.toBe('missing');
+    await expect(
+      problemOf(await inspectApk(join(dir, 'no-dir', 'x.apk'))),
+    ).resolves.toBe('missing');
+
+    mkdirSync(join(dir, 'folder.apk'));
+    await expect(
+      problemOf(await inspectApk(join(dir, 'folder.apk'))),
+    ).resolves.toBe('not-file');
+  });
+
+  (onWindows ? it.skip : it)(
+    '바로가기(심볼릭 링크)는 따라가지 않는다',
+    async () => {
+      const target = file('real.apk', apkBytes(APK_MIN_BYTES));
+      symlinkSync(target, join(dir, 'link.apk'));
+      await expect(
+        problemOf(await inspectApk(join(dir, 'link.apk'))),
+      ).resolves.toBe('symlink');
+    },
+  );
+
+  (onWindows ? it.skip : it)(
+    '파이프(FIFO)를 열 때 멈추지 않는다 — 일반 파일이 아니라고 알린다',
+    async () => {
+      const path = join(dir, 'pipe.apk');
+      try {
+        execFileSync('mkfifo', [path]);
+      } catch {
+        // mkfifo 가 없는 환경 — 이 시험은 건너뛴다 (개발 컨테이너 · CI 에는 있다)
+        return;
+      }
+      await expect(problemOf(await inspectApk(path))).resolves.toBe('not-file');
+    },
+  );
+
+  (onWindows || runningAsRoot ? it.skip : it)(
+    '읽을 권한이 없으면 알린다 (docker cp 는 root 소유로 넣는다)',
+    async () => {
+      const path = file('locked.apk', apkBytes(APK_MIN_BYTES));
+      chmodSync(path, 0o000);
+      await expect(problemOf(await inspectApk(path))).resolves.toBe(
+        'unreadable',
+      );
+    },
+  );
+
+  it('크기 — 1KB 아래 · 200MB 위는 받지 않는다(큰 파일은 읽지 않고 크기로만), 경계는 받는다', async () => {
+    await expect(
+      problemOf(
+        await inspectApk(file('small.apk', apkBytes(APK_MIN_BYTES - 1))),
+      ),
+    ).resolves.toBe('too-small');
+    await expect(
+      problemOf(await inspectApk(file('edge.apk', apkBytes(APK_MIN_BYTES)))),
+    ).resolves.toBe('ok');
+
+    // 빈 곳만 있는 큰 파일(디스크를 쓰지 않는다) — 머리를 읽기 전에 크기로 막는다
+    const large = join(dir, 'large.apk');
+    writeFileSync(large, APK_ZIP_SIGNATURE);
+    truncateSync(large, APK_MAX_BYTES + 1);
+    await expect(problemOf(await inspectApk(large))).resolves.toBe('too-large');
+  });
+
+  it('zip 머리(PK\\x03\\x04)가 아니면 APK 가 아니다', async () => {
+    const notZip = Buffer.concat([
+      Buffer.from('<html>'),
+      randomBytes(APK_MIN_BYTES),
+    ]);
+    await expect(
+      problemOf(await inspectApk(file('page.apk', notZip))),
+    ).resolves.toBe('not-zip');
+    // 빈 디렉터리 머리(PK\x05\x06 — 빈 zip)도 APK 가 아니다
+    const emptyZip = Buffer.concat([
+      Buffer.from([0x50, 0x4b, 0x05, 0x06]),
+      Buffer.alloc(APK_MIN_BYTES),
+    ]);
+    await expect(
+      problemOf(await inspectApk(file('empty.apk', emptyZip))),
+    ).resolves.toBe('not-zip');
+  });
+});
+
+describe('forEachChunk — 연 파일을 처음부터 끝까지', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'apk-chunks-'));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('조각을 차례로 넘기고 읽은 크기가 맞으면 true — 다르면(그사이 바뀜) false', async () => {
+    const data = randomBytes(3 * 1024 * 1024 + 17);
+    const path = join(dir, 'data.bin');
+    writeFileSync(path, data);
+    const handle = await open(path, 'r');
+    try {
+      const parts: Buffer[] = [];
+      await expect(
+        forEachChunk(handle, data.length, (chunk) => {
+          parts.push(Buffer.from(chunk));
+        }),
+      ).resolves.toBe(true);
+      expect(Buffer.concat(parts).equals(data)).toBe(true);
+      expect(parts.length).toBeGreaterThan(1);
+
+      // 생각한 것보다 짧다(줄었다) · 길다(늘었다) — 넘게 읽히면 거기서 멈춘다(끝까지 읽지 않는다)
+      await expect(
+        forEachChunk(handle, data.length + 1, () => undefined),
+      ).resolves.toBe(false);
+      let seen = 0;
+      await expect(
+        forEachChunk(handle, 10, (chunk) => {
+          seen += chunk.length;
+        }),
+      ).resolves.toBe(false);
+      expect(seen).toBeLessThanOrEqual(10);
+    } finally {
+      await handle.close();
+    }
+  });
+});

backend/src/modules/app-releases/apk-file.ts

@@ -0,0 +1,172 @@
+import { createHash } from 'crypto';
+import { constants } from 'fs';
+import { open, type FileHandle } from 'fs/promises';
+import { basename, extname } from 'path';
+
+import {
+  APK_EXTENSION,
+  APK_MAX_BYTES,
+  APK_MIN_BYTES,
+  APK_ZIP_SIGNATURE,
+} from './app-releases.constants';
+
+/**
+ * 운영자가 컨테이너 안에 넣은 APK 읽기 (운영 도구 「휴대폰 앱 올리기」 — 계약 1절 "휴대폰 앱 받기").
+ * 파일 하나를 한 번 열고, 그 열린 파일(같은 inode)로 검사 · SHA-256 · 저장소에 들이기를 모두 한다 —
+ * 검사한 뒤 경로가 다른 파일로 바뀌어도 들이는 것은 검사한 그 파일이다(내용이 바뀌면 들일 때 다시 센 SHA-256 이 막는다)
+ */
+
+/** 읽을 수 없는 까닭 — 운영 도구가 한국어로 알린다 (modules/ops/app-release-commands.ts) */
+export type ApkProblem =
+  /** 이름이 .apk 로 끝나지 않는다 */
+  | 'not-apk-name'
+  /** 그 경로에 없다 */
+  | 'missing'
+  /** 바로가기(심볼릭 링크)다 — 따라가지 않는다 */
+  | 'symlink'
+  /** 일반 파일이 아니다 (폴더 · 장치 · 파이프 · 소켓) */
+  | 'not-file'
+  /** 읽을 권한이 없다 (docker cp 는 root 소유로 넣는다 — 원본이 644 가 아니면 node 가 읽지 못한다) */
+  | 'unreadable'
+  | 'too-small'
+  | 'too-large'
+  /** zip 머리(PK\x03\x04)가 아니다 */
+  | 'not-zip'
+  /** 읽는 동안 크기가 바뀌었다 (아직 복사 중) */
+  | 'changed';
+
+/** 검사를 마친 APK — 다 쓰면 close() (부르는 쪽이 닫는다) */
+export interface InspectedApk {
+  /** 운영자가 넣은 경로 그대로 — 실행 기록 · 바뀔 것에 보인다(감사용) */
+  readonly path: string;
+  /** 경로의 마지막 이름 — 판을 짐작하는 데만 쓴다(디스크 · 내려받는 이름이 되지 않는다) */
+  readonly fileName: string;
+  readonly sizeBytes: number;
+  /** SHA-256 (소문자 16진수) */
+  readonly sha256: string;
+  /** 연 파일 — 저장소에 들일 때 처음부터 다시 읽는다 */
+  readonly handle: FileHandle;
+  close(): Promise<void>;
+}
+
+export type ApkInspection =
+  | { readonly ok: true; readonly apk: InspectedApk }
+  | { readonly ok: false; readonly problem: ApkProblem };
+
+/** 한 번에 읽는 양 */
+const READ_CHUNK_BYTES = 1024 * 1024;
+
+/**
+ * 열기 — 바로가기를 따라가지 않고(O_NOFOLLOW — 그 경로가 링크면 ELOOP), 파이프 · 장치를 열 때 멈추지 않게(O_NONBLOCK — 일반 파일 읽기에는 영향이 없다).
+ * 일반 파일인지는 연 뒤 fstat 으로 본다. Windows 에는 두 표시가 없다(0)
+ */
+const OPEN_FLAGS =
+  constants.O_RDONLY |
+  (constants.O_NOFOLLOW ?? 0) |
+  (constants.O_NONBLOCK ?? 0);
+
+function problem(kind: ApkProblem): ApkInspection {
+  return { ok: false, problem: kind };
+}
+
+/** 열지 못한 까닭 → 알릴 것 (모르는 오류는 null — 그대로 던진다) */
+function openProblem(error: unknown): ApkProblem | null {
+  switch ((error as NodeJS.ErrnoException | null)?.code) {
+    case 'ENOENT':
+    case 'ENOTDIR':
+      return 'missing';
+    case 'ELOOP':
+      return 'symlink';
+    case 'EACCES':
+    case 'EPERM':
+      return 'unreadable';
+    // 소켓 등 — 열 수 없는 특수 파일
+    case 'ENXIO':
+    case 'EISDIR':
+      return 'not-file';
+    default:
+      return null;
+  }
+}
+
+/**
+ * 연 파일을 처음부터 끝까지 차례로 읽어 조각마다 부른다 — 읽은 바이트 수가 `size` 와 다르면(그사이 파일이 바뀜) false.
+ * 넘게 읽히면 거기서 멈춘다. 조각 버퍼는 다음 읽기에 다시 쓴다 — 부르는 쪽은 그 안에서 다 쓴다(해시 · 쓰기를 기다린 뒤 돌아온다)
+ */
+export async function forEachChunk(
+  handle: FileHandle,
+  size: number,
+  onChunk: (chunk: Buffer) => Promise<void> | void,
+): Promise<boolean> {
+  const buffer = Buffer.alloc(Math.max(1, Math.min(READ_CHUNK_BYTES, size)));
+  let position = 0;
+  for (;;) {
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+    if (bytesRead === 0) return position === size;
+    position += bytesRead;
+    if (position > size) return false;
+    await onChunk(buffer.subarray(0, bytesRead));
+  }
+}
+
+/** 열린 파일의 SHA-256 — 크기가 바뀌었으면 null */
+async function sha256Of(
+  handle: FileHandle,
+  size: number,
+): Promise<string | null> {
+  const hash = createHash('sha256');
+  const complete = await forEachChunk(handle, size, (chunk) => {
+    hash.update(chunk);
+  });
+  return complete ? hash.digest('hex') : null;
+}
+
+/**
+ * 운영자가 넣은 경로의 APK 를 검사한다 — 이름(.apk) · 일반 파일 · 크기(1KB ~ 200MB) · zip 머리 · SHA-256.
+ * 큰 파일은 크기를 본 뒤에야 읽는다(200MB 를 넘는 파일은 읽지 않는다). 통과하면 연 파일째 돌려준다 — 부르는 쪽이 닫는다
+ */
+export async function inspectApk(path: string): Promise<ApkInspection> {
+  if (extname(path).toLowerCase() !== APK_EXTENSION) {
+    return problem('not-apk-name');
+  }
+  let handle: FileHandle;
+  try {
+    handle = await open(path, OPEN_FLAGS);
+  } catch (error) {
+    const reason = openProblem(error);
+    if (reason === null) throw error;
+    return problem(reason);
+  }
+  let handedOver = false;
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile()) return problem('not-file');
+    if (stats.size < APK_MIN_BYTES) return problem('too-small');
+    if (stats.size > APK_MAX_BYTES) return problem('too-large');
+
+    const head = Buffer.alloc(APK_ZIP_SIGNATURE.length);
+    const { bytesRead } = await handle.read(head, 0, head.length, 0);
+    if (bytesRead !== head.length || !head.equals(APK_ZIP_SIGNATURE)) {
+      return problem('not-zip');
+    }
+
+    const sha256 = await sha256Of(handle, stats.size);
+    if (sha256 === null) return problem('changed');
+
+    handedOver = true;
+    const opened = handle;
+    return {
+      ok: true,
+      apk: {
+        path,
+        fileName: basename(path),
+        sizeBytes: stats.size,
+        sha256,
+        handle: opened,
+        close: () => opened.close(),
+      },
+    };
+  } finally {
+    if (!handedOver) await handle.close();
+  }
+}

backend/src/modules/app-releases/app-release-storage.spec.ts

@@ -0,0 +1,154 @@
+import { createHash, randomBytes } from 'crypto';
+import {
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from 'fs';
+import { open, type FileHandle } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import {
+  AppReleaseFileChangedError,
+  AppReleaseStorage,
+} from './app-release-storage';
+
+const KEY = '3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d';
+const OTHER_KEY = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
+const sha256 = (data: Buffer) =>
+  createHash('sha256').update(data).digest('hex');
+
+describe('AppReleaseStorage (휴대폰 앱 파일 — 업로드 볼륨의 app-releases/)', () => {
+  let root: string;
+  let dir: string;
+  let storage: AppReleaseStorage;
+  let source: FileHandle;
+  const data = randomBytes(2 * 1024 * 1024 + 5);
+
+  beforeEach(async () => {
+    root = mkdtempSync(join(tmpdir(), 'app-release-storage-'));
+    // 아직 없는 하위 폴더 — 처음 들일 때 만든다
+    dir = join(root, 'app-releases');
+    storage = new AppReleaseStorage(dir);
+    const sourcePath = join(root, 'ARA-SYSTEM-1.0.0.apk');
+    writeFileSync(sourcePath, data);
+    source = await open(sourcePath, 'r');
+  });
+
+  afterEach(async () => {
+    await source.close();
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  const expected = () => ({ sizeBytes: data.length, sha256: sha256(data) });
+
+  it('들이면 <key>.apk 만 남는다(임시 파일 없음 · 소유자만 쓴다) — 열고 · 있는지 보고 · 지운다', async () => {
+    await storage.importFile(source, KEY, expected());
+
+    expect(readdirSync(dir)).toEqual([`${KEY}.apk`]);
+    expect(readFileSync(join(dir, `${KEY}.apk`)).equals(data)).toBe(true);
+    if (process.platform !== 'win32') {
+      expect(statSync(join(dir, `${KEY}.apk`)).mode & 0o777).toBe(0o640);
+    }
+
+    const opened = await storage.open(KEY);
+    expect(opened?.sizeBytes).toBe(data.length);
+    await opened?.handle.close();
+    await expect(storage.exists(KEY)).resolves.toBe(true);
+
+    await storage.remove(KEY);
+    await storage.remove(KEY);
+    await expect(storage.exists(KEY)).resolves.toBe(false);
+    await expect(storage.open(KEY)).resolves.toBeNull();
+  });
+
+  it('들이는 동안 다시 센 SHA-256 · 크기가 검사 때와 다르면 들이지 않고 아무것도 남기지 않는다', async () => {
+    await expect(
+      storage.importFile(source, KEY, {
+        ...expected(),
+        sha256: sha256(Buffer.from('other')),
+      }),
+    ).rejects.toBeInstanceOf(AppReleaseFileChangedError);
+    expect(readdirSync(dir)).toEqual([]);
+
+    await expect(
+      storage.importFile(source, KEY, {
+        ...expected(),
+        sizeBytes: data.length - 1,
+      }),
+    ).rejects.toBeInstanceOf(AppReleaseFileChangedError);
+    await expect(
+      storage.importFile(source, KEY, {
+        ...expected(),
+        sizeBytes: data.length + 1,
+      }),
+    ).rejects.toBeInstanceOf(AppReleaseFileChangedError);
+    expect(readdirSync(dir)).toEqual([]);
+  });
+
+  it('쓰다 실패해도(원본을 읽지 못함) 반쯤 쓴 임시 파일을 남기지 않는다', async () => {
+    const broken = {
+      read: jest.fn().mockRejectedValue(new Error('EIO')),
+    } as unknown as FileHandle;
+    await expect(storage.importFile(broken, KEY, expected())).rejects.toThrow(
+      'EIO',
+    );
+    expect(readdirSync(dir)).toEqual([]);
+  });
+
+  it('같은 키의 임시 파일이 있으면(다른 올리기가 쓰는 중) 덮어쓰지도 지우지도 않는다', async () => {
+    await storage.importFile(source, OTHER_KEY, expected());
+    writeFileSync(join(dir, `${KEY}.apk.part`), 'someone else');
+
+    await expect(storage.importFile(source, KEY, expected())).rejects.toThrow();
+    expect(readFileSync(join(dir, `${KEY}.apk.part`), 'utf8')).toBe(
+      'someone else',
+    );
+  });
+
+  it('서버가 만든 키(소문자 UUID)가 아니면 경로로 쓰지 않는다', async () => {
+    for (const key of [
+      '../../etc/passwd',
+      `../${KEY}`,
+      `${KEY}/x`,
+      KEY.toUpperCase(),
+      `${KEY}.apk`,
+      '',
+    ]) {
+      await expect(storage.importFile(source, key, expected())).rejects.toThrow(
+        '휴대폰 앱 파일 키 형식이 올바르지 않습니다.',
+      );
+      await expect(storage.open(key)).rejects.toThrow();
+      await expect(storage.exists(key)).rejects.toThrow();
+      await expect(storage.remove(key)).rejects.toThrow();
+    }
+  });
+
+  it('멈춘 올리기의 오래된 임시 파일만 지운다 — 새 임시 파일 · 판 파일 · 다른 이름은 그대로, 폴더가 없으면 0', async () => {
+    await expect(storage.removeStaleParts(new Date())).resolves.toBe(0);
+
+    await storage.importFile(source, OTHER_KEY, expected());
+    const old = join(dir, `${KEY}.apk.part`);
+    const fresh = join(dir, '0f8fad5b-d9cb-469f-a165-70867728950e.apk.part');
+    const stranger = join(dir, 'notes.part');
+    for (const path of [old, fresh, stranger]) writeFileSync(path, 'x');
+    const longAgo = new Date(Date.now() - 2 * 60 * 60 * 1000);
+    utimesSync(old, longAgo, longAgo);
+    utimesSync(stranger, longAgo, longAgo);
+
+    await expect(
+      storage.removeStaleParts(new Date(Date.now() - 60 * 60 * 1000)),
+    ).resolves.toBe(1);
+    expect(readdirSync(dir).sort()).toEqual(
+      [
+        `${OTHER_KEY}.apk`,
+        '0f8fad5b-d9cb-469f-a165-70867728950e.apk.part',
+        'notes.part',
+      ].sort(),
+    );
+  });
+});

backend/src/modules/app-releases/app-release-storage.ts

@@ -0,0 +1,197 @@
+import { createHash } from 'crypto';
+import {
+  mkdir,
+  open,
+  readdir,
+  rename,
+  stat,
+  unlink,
+  type FileHandle,
+} from 'fs/promises';
+import { join } from 'path';
+
+import { forEachChunk } from './apk-file';
+import { APK_EXTENSION, APP_RELEASE_DIR } from './app-releases.constants';
+
+/** 서버가 만든 키(소문자 UUID)만 경로로 만든다 — 바깥 값이 경로가 되지 않게 (`../../etc/passwd` 같은 값) */
+const FILE_KEY =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** 쓰는 중인 임시 파일의 꼬리 — `<key>.apk.part` */
+const PART_SUFFIX = '.part';
+/** 임시 파일 이름 — 정리할 때 이 꼴만 지운다 */
+const PART_FILE_NAME =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.apk\.part$/;
+
+/** 파일 권한 — 소유자만 쓴다 (그룹은 읽기만) — 서명 그림 · 대용량 첨부 저장과 같다 */
+const FILE_MODE = 0o640;
+
+function isMissing(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT';
+}
+
+async function unlinkIfExists(path: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+}
+
+/** 버퍼를 끝까지 쓴다 (한 번에 다 쓰지 못할 수 있다) */
+async function writeAll(
+  out: FileHandle,
+  data: Buffer,
+  position: number,
+): Promise<void> {
+  let done = 0;
+  while (done < data.length) {
+    const { bytesWritten } = await out.write(
+      data,
+      done,
+      data.length - done,
+      position + done,
+    );
+    done += bytesWritten;
+  }
+}
+
+/** 저장소에 들이는 동안 원본이 검사한 것과 달라졌다 (SHA-256 · 크기) — 들이지 않았다 */
+export class AppReleaseFileChangedError extends Error {
+  override readonly name = 'AppReleaseFileChangedError';
+
+  constructor() {
+    super('APK 가 검사한 뒤 바뀌었습니다.');
+  }
+}
+
+/** 연 판 파일 — 크기는 열린 파일에서(fstat). 부르는 쪽이 닫거나 읽기 흐름에 넘긴다 */
+export interface OpenedAppReleaseFile {
+  readonly handle: FileHandle;
+  readonly sizeBytes: number;
+}
+
+/** 들이는 파일이 맞아야 할 값 — 검사 때 센 것 */
+export interface ExpectedAppReleaseFile {
+  readonly sizeBytes: number;
+  readonly sha256: string;
+}
+
+/**
+ * 휴대폰 앱 파일 저장소 — 업로드 볼륨의 하위 폴더(APP_RELEASE_DIR) 안 `<file_key>.apk`.
+ * 폴더 그대로 정적 서빙하지 않는다 — 내려줄 때는 서비스가 형식 · 머리글을 정한다 (.claude/rules/security.md "파일 업로드").
+ * 모듈은 useFactory 로 만든다(생성자의 폴더 인자를 DI 가 찾지 않게) — 테스트는 임시 폴더를 넘긴다
+ */
+export class AppReleaseStorage {
+  constructor(private readonly dir: string = APP_RELEASE_DIR) {}
+
+  /** 판 파일을 연다 — 없으면 null */
+  async open(fileKey: string): Promise<OpenedAppReleaseFile | null> {
+    let handle: FileHandle;
+    try {
+      handle = await open(this.pathOf(fileKey), 'r');
+    } catch (error) {
+      if (isMissing(error)) return null;
+      throw error;
+    }
+    try {
+      return { handle, sizeBytes: (await handle.stat()).size };
+    } catch (error) {
+      await handle.close();
+      throw error;
+    }
+  }
+
+  /** 판 파일이 있는가 (운영 도구의 목록) */
+  async exists(fileKey: string): Promise<boolean> {
+    try {
+      await stat(this.pathOf(fileKey));
+      return true;
+    } catch (error) {
+      if (isMissing(error)) return false;
+      throw error;
+    }
+  }
+
+  /**
+   * 운영자가 넣은 APK(검사하며 연 파일)를 들인다 — `<key>.apk.part` 에 쓰고(wx — 덮어쓰지 않는다) 디스크에 내려쓴 뒤 `<key>.apk` 로 이름을 바꾼다.
+   * 쓰면서 다시 센 SHA-256 · 크기가 검사 때와 다르면(검사한 뒤 원본이 바뀜) AppReleaseFileChangedError.
+   * 어떻게 실패해도 반쯤 쓴 임시 파일을 남기지 않는다 — 이름을 바꾸기 전에는 `<key>.apk` 가 생기지 않는다
+   */
+  async importFile(
+    source: FileHandle,
+    fileKey: string,
+    expected: ExpectedAppReleaseFile,
+  ): Promise<void> {
+    const finalPath = this.pathOf(fileKey);
+    const partPath = `${finalPath}${PART_SUFFIX}`;
+    await mkdir(this.dir, { recursive: true });
+    const out = await open(partPath, 'wx', FILE_MODE);
+    let closed = false;
+    let renamed = false;
+    try {
+      const hash = createHash('sha256');
+      let written = 0;
+      const complete = await forEachChunk(
+        source,
+        expected.sizeBytes,
+        async (chunk) => {
+          hash.update(chunk);
+          await writeAll(out, chunk, written);
+          written += chunk.length;
+        },
+      );
+      if (!complete || hash.digest('hex') !== expected.sha256) {
+        throw new AppReleaseFileChangedError();
+      }
+      // 이름을 바꾸기 전에 디스크에 내려쓴다 — 표에 넣은 판의 파일이 전원이 꺼져도 남게
+      await out.datasync();
+      closed = true;
+      await out.close();
+      await rename(partPath, finalPath);
+      renamed = true;
+    } finally {
+      if (!closed) await out.close().catch(() => undefined);
+      if (!renamed) await unlinkIfExists(partPath);
+    }
+  }
+
+  /** 판 파일을 지운다 — 이미 없으면 그대로 (표에 넣지 못했을 때 되돌리기) */
+  async remove(fileKey: string): Promise<void> {
+    await unlinkIfExists(this.pathOf(fileKey));
+  }
+
+  /**
+   * 멈춘 올리기(도구가 쓰는 중에 끊김)가 남긴 임시 파일 가운데 `olderThan` 보다 오래된 것을 지운다 → 지운 수.
+   * 폴더가 없으면 0. 그사이 지워진 것은 건너뛴다
+   */
+  async removeStaleParts(olderThan: Date): Promise<number> {
+    let names: string[];
+    try {
+      names = await readdir(this.dir);
+    } catch (error) {
+      if (isMissing(error)) return 0;
+      throw error;
+    }
+    let removed = 0;
+    for (const name of names.filter((entry) => PART_FILE_NAME.test(entry))) {
+      const path = join(this.dir, name);
+      try {
+        if ((await stat(path)).mtime >= olderThan) continue;
+        await unlink(path);
+        removed += 1;
+      } catch (error) {
+        if (!isMissing(error)) throw error;
+      }
+    }
+    return removed;
+  }
+
+  private pathOf(fileKey: string): string {
+    if (!FILE_KEY.test(fileKey)) {
+      // 서버가 만든 키가 아니다 — 버그이므로 응답 코드 없는 내부 오류로 둔다 (SYS_001)
+      throw new Error('휴대폰 앱 파일 키 형식이 올바르지 않습니다.');
+    }
+    return join(this.dir, `${fileKey}${APK_EXTENSION}`);
+  }
+}

backend/src/modules/app-releases/app-release-version.spec.ts

@@ -0,0 +1,61 @@
+import { startCpuTimer } from '@/../test/cpu-time';
+import {
+  appReleaseFileName,
+  compareAppVersions,
+  isAppVersion,
+  versionInFileName,
+} from './app-release-version';
+
+describe('휴대폰 앱 버전 (사내 배포)', () => {
+  it('버전 글 — 숫자 셋을 점으로(칸마다 1~4자리 · 앞자리 0 없이), 앱 알림 등록의 appVersion 과 같은 규칙', () => {
+    for (const version of ['1.0.0', '0.0.1', '10.20.30', '1234.0.9999']) {
+      expect(isAppVersion(version)).toBe(true);
+    }
+    for (const version of [
+      '',
+      '1.0',
+      '1.0.0.1',
+      '01.0.0',
+      '1.00.0',
+      '1.0.0-beta',
+      '1.0.0+5',
+      'v1.0.0',
+      '12345.0.0',
+      ' 1.0.0',
+      '1.0.0\n',
+    ]) {
+      expect(isAppVersion(version)).toBe(false);
+    }
+  });
+
+  it('칸마다 숫자로 견준다 — 글자 차례가 아니다(1.10.0 > 1.9.0)', () => {
+    expect(compareAppVersions('1.10.0', '1.9.0')).toBeGreaterThan(0);
+    expect(compareAppVersions('1.9.9', '2.0.0')).toBeLessThan(0);
+    expect(compareAppVersions('1.2.3', '1.2.3')).toBe(0);
+    expect(compareAppVersions('0.9.0', '1.0.0')).toBeLessThan(0);
+    expect(compareAppVersions('1.0.10', '1.0.2')).toBeGreaterThan(0);
+  });
+
+  it('파일 이름에서 버전을 찾는다 — 없거나 규칙에 맞지 않으면 null', () => {
+    expect(versionInFileName('ARA-SYSTEM-1.2.3.apk')).toBe('1.2.3');
+    expect(versionInFileName('ARA-SYSTEM-v10.0.1.APK')).toBe('10.0.1');
+    expect(versionInFileName('app-release-1.0.0+12.apk')).toBe('1.0.0');
+    expect(versionInFileName('app-release.apk')).toBeNull();
+    // 네 칸 · 다섯 자리 · 앞자리 0 — 판으로 보지 않는다
+    expect(versionInFileName('ARA-SYSTEM-1.2.3.4.apk')).toBeNull();
+    expect(versionInFileName('ARA-SYSTEM-12345.0.0.apk')).toBeNull();
+    expect(versionInFileName('ARA-SYSTEM-01.0.0.apk')).toBeNull();
+  });
+
+  it('파일 이름에서 찾기는 긴 이름에도 길이에 비례한다 (숫자 · 점이 잔뜩 든 이름)', () => {
+    const name = `${'1.'.repeat(100_000)}apk`;
+    const cpuMs = startCpuTimer();
+    expect(versionInFileName(name)).toBeNull();
+    // 지금 수 ms — 한도는 넉넉히(부하에서 는다 · .claude/rules/testing.md)
+    expect(cpuMs()).toBeLessThan(1_000);
+  });
+
+  it('내려받는 파일 이름 — ARA-SYSTEM-<버전>.apk', () => {
+    expect(appReleaseFileName('1.0.0')).toBe('ARA-SYSTEM-1.0.0.apk');
+  });
+});

backend/src/modules/app-releases/app-release-version.ts

@@ -0,0 +1,43 @@
+import {
+  APP_VERSION_MAX_LENGTH,
+  APP_VERSION_PATTERN,
+} from '@/modules/push/push.constants';
+import { APK_EXTENSION } from './app-releases.constants';
+
+/**
+ * 휴대폰 앱 판 (순수 함수) — 판 글은 앱 알림 등록의 `appVersion` 과 **같은 규칙**이다(push.constants 의 APP_VERSION_PATTERN —
+ * `숫자.숫자.숫자`, 칸마다 1~4자리 · 앞자리 0 없이). 앱 설정의 최소 판(app-config)도 같은 꼴로 칸마다 숫자로 견준다
+ */
+
+/** 파일 이름 안의 판 후보 — 앞뒤가 숫자 · 점으로 이어지지 않는 `x.y.z` (`1.2.3.4` 의 일부는 판으로 보지 않는다). 칸마다 4자리까지라 길이에 비례한다 */
+const VERSION_IN_NAME =
+  /(?<![0-9.])([0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,4})(?![0-9]|\.[0-9])/;
+
+/** 판 글인가 — 길이를 먼저 본다(정규식 전에) */
+export function isAppVersion(text: string): boolean {
+  return (
+    text.length <= APP_VERSION_MAX_LENGTH && APP_VERSION_PATTERN.test(text)
+  );
+}
+
+/** 두 판을 칸마다 숫자로 견준다 — a 가 낮으면 음수, 같으면 0, 높으면 양수 (둘 다 판 글이어야 한다) */
+export function compareAppVersions(a: string, b: string): number {
+  const left = a.split('.').map(Number);
+  const right = b.split('.').map(Number);
+  for (let index = 0; index < left.length; index += 1) {
+    const difference = left[index] - right[index];
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
+/** 운영자가 넣은 파일 이름에서 판을 찾는다 (`ARA-SYSTEM-1.2.3.apk` → `1.2.3`) — 없거나 판 규칙에 맞지 않으면 null */
+export function versionInFileName(fileName: string): string | null {
+  const match = VERSION_IN_NAME.exec(fileName);
+  return match && isAppVersion(match[1]) ? match[1] : null;
+}
+
+/** 직원이 내려받는 파일 이름 — 서버가 검사한 판으로만 만든다 (`ARA-SYSTEM-1.0.0.apk`) */
+export function appReleaseFileName(version: string): string {
+  return `ARA-SYSTEM-${version}${APK_EXTENSION}`;
+}

backend/src/modules/app-releases/app-release.entity.ts

@@ -0,0 +1,63 @@
+import { Column, Entity, Index, PrimaryColumn } from 'typeorm';
+
+import { BIGINT_NUMBER } from '@/shared/utils/bigint-column';
+import {
+  APP_RELEASES_TABLE,
+  APP_RELEASE_UPLOADER_MAX_LENGTH,
+  type AppReleasePlatform,
+} from './app-releases.constants';
+
+/** 플랫폼 이름 길이 — 'android' (push_registrations.platform 과 같다) */
+const PLATFORM_COLUMN_LENGTH = 16;
+/** 판 길이 — 'NNNN.NNNN.NNNN' 까지 (push_registrations.app_version 과 같다) */
+const VERSION_COLUMN_LENGTH = 16;
+/** SHA-256 — 소문자 16진수 64자 */
+const SHA256_HEX_LENGTH = 64;
+
+/**
+ * 나눠 주는 휴대폰 앱 한 판 (계약 1절 "휴대폰 앱 받기" — 사내 배포) — 운영 도구 「휴대폰 앱 올리기」가 한 줄씩 넣는다.
+ *
+ * - "최신" = 그 플랫폼에서 가장 늦게 올린 줄(created_at) — 판 번호가 아니다. 옛 APK 를 다시 올리면 그것이 최신이 된다(되돌리기 길)
+ * - 파일은 업로드 볼륨의 `app-releases/<file_key>.apk` — 디스크 이름은 서버가 만든 UUID 뿐이다(운영자가 넣은 파일 이름 · 경로를 쓰지 않는다)
+ * - 지우는 명령은 없다 — 옛 판은 표 · 볼륨에 남는다(되돌리기 · 문의 대응). 직원 주소로 키링한 표가 아니라 퇴사 마무리와 상관없다
+ */
+@Entity({ name: APP_RELEASES_TABLE })
+@Index('IDX_app_releases_platform_created_at', ['platform', 'createdAt'])
+export class AppReleaseEntity {
+  /** 판 id — 서버가 만든 UUID (내려받기 응답의 ETag) */
+  @PrimaryColumn({ type: 'uuid' })
+  id!: string;
+
+  /** 플랫폼 — 지금은 android 만 */
+  @Column({ type: 'varchar', length: PLATFORM_COLUMN_LENGTH })
+  platform!: AppReleasePlatform;
+
+  /** 판 (`1.0.0` — 앱의 versionName. 앱 알림 등록의 appVersion 과 같은 규칙) */
+  @Column({ type: 'varchar', length: VERSION_COLUMN_LENGTH })
+  version!: string;
+
+  /** 파일 크기(바이트) — 내려받기의 Content-Length · 범위 계산이 이 값을 쓴다(디스크의 크기와 다르면 내려주지 않는다) */
+  @Column({ name: 'size_bytes', type: 'bigint', transformer: BIGINT_NUMBER })
+  sizeBytes!: number;
+
+  /** 파일의 SHA-256 (소문자 16진수) — 운영자가 빌드한 파일과 견준다 */
+  @Column({ type: 'char', length: SHA256_HEX_LENGTH })
+  sha256!: string;
+
+  /** 디스크의 파일 이름(확장자 빼고) — 서버가 만든 UUID */
+  @Index('UQ_app_releases_file_key', { unique: true })
+  @Column({ name: 'file_key', type: 'uuid' })
+  fileKey!: string;
+
+  /** 올린 이 — 운영 도구를 시작할 때 넣은 운영자 이름 */
+  @Column({
+    name: 'uploaded_by',
+    type: 'varchar',
+    length: APP_RELEASE_UPLOADER_MAX_LENGTH,
+  })
+  uploadedBy!: string;
+
+  /** 올린 때 — 최신을 가르는 차례 · 화면의 "올린 날"(`releasedAt`) */
+  @Column({ name: 'created_at', type: 'timestamptz' })
+  createdAt!: Date;
+}

backend/src/modules/app-releases/app-releases.constants.ts

@@ -0,0 +1,49 @@
+import { join } from 'path';
+
+import { UPLOAD_DIR } from '@/modules/upload/upload.config';
+
+/**
+ * 휴대폰 앱 받기 (사내 배포 — 계약 1절 "휴대폰 앱 받기", 2026-11-08) — 한도 · 형식 · 자리를 한 곳에 모은다.
+ * 앱은 스토어 없이 직접 빌드한 APK 를 포털에 로그인한 직원에게만 나눠 준다.
+ * 올리기는 API 가 없다 — 서버 B 의 운영 도구 「휴대폰 앱 올리기」(modules/ops/app-release-commands.ts)
+ */
+
+/** 표 이름 — app-release.entity.ts 와 같다 */
+export const APP_RELEASES_TABLE = 'app_releases';
+
+/** 나눠 주는 플랫폼 — 지금은 안드로이드만 (아이폰은 나중 거리) */
+export const APP_RELEASE_PLATFORMS = ['android'] as const;
+export type AppReleasePlatform = (typeof APP_RELEASE_PLATFORMS)[number];
+
+/** APK 의 형식 — 내려받기 응답의 Content-Type (휴대폰이 설치 파일로 알아본다) */
+export const APK_CONTENT_TYPE = 'application/vnd.android.package-archive';
+
+/** 확장자 — 운영자가 넣은 파일 이름에서 본다(대소문자는 가리지 않는다) · 내려받는 파일 이름에 붙인다 */
+export const APK_EXTENSION = '.apk';
+
+/** zip 의 로컬 파일 머리 `PK\x03\x04` — APK 는 zip 이다 */
+export const APK_ZIP_SIGNATURE: Readonly<Buffer> = Buffer.from([
+  0x50, 0x4b, 0x03, 0x04,
+]);
+
+/** 크기 한도 — 1KB 아래는 APK 가 아니다, 200MB 위는 받지 않는다(지금 앱은 30MB 남짓) */
+export const APK_MIN_BYTES = 1024;
+export const APK_MAX_BYTES = 200 * 1024 * 1024;
+
+/**
+ * 파일 자리 — 업로드 볼륨(modules/upload 와 같은 UPLOAD_DIR)의 하위 폴더. 이름은 `<file_key>.apk` 뿐이다.
+ * 운영은 named volume `<PROJECT_NAME>_uploads`(매일 백업에 든다), 개발은 바인드 마운트 (.claude/skills/docker/SKILL.md)
+ */
+export const APP_RELEASE_DIR = join(UPLOAD_DIR, 'app-releases');
+
+/** 운영 도구 「휴대폰 앱 목록」이 보이는 판 수 — 최근 것부터 */
+export const APP_RELEASE_LIST_LIMIT = 10;
+
+/** 올린 이(운영자 이름) 길이 — 운영 도구의 운영자 이름 한도(ops-audit-log.entity.ts 의 OPS_OPERATOR_MAX_LENGTH)와 같다 */
+export const APP_RELEASE_UPLOADER_MAX_LENGTH = 100;
+
+/**
+ * 멈춘 올리기가 남긴 임시 파일(`*.apk.part`)을 지우는 나이 — 올리기를 시작할 때 이보다 오래된 것만 지운다.
+ * 다른 운영자가 막 쓰는 중인 임시 파일은 건드리지 않게 넉넉히 둔다(200MB 를 쓰는 데 몇 초다)
+ */
+export const APP_RELEASE_STALE_PART_MS = 60 * 60 * 1000;

backend/src/modules/app-releases/app-releases.controller.ts

@@ -0,0 +1,87 @@
+import {
+  Controller,
+  Get,
+  HttpStatus,
+  Req,
+  Res,
+  UseFilters,
+  UseGuards,
+} from '@nestjs/common';
+import {
+  ApiCookieAuth,
+  ApiOperation,
+  ApiProduces,
+  ApiResponse,
+  ApiTags,
+} from '@nestjs/swagger';
+import type { Request, Response } from 'express';
+
+import {
+  ApiErrorResponse,
+  ApiSessionErrors,
+  ApiStandardResponse,
+} from '@/common/decorators/api-standard-response.decorator';
+import { NoStore } from '@/common/decorators/no-store.decorator';
+import { SkipTransform } from '@/common/decorators/skip-transform.decorator';
+import { HttpExceptionFilter } from '@/common/filters/http-exception.filter';
+import { JwtAuthGuard } from '@/common/guards/jwt-auth.guard';
+import { APK_CONTENT_TYPE } from './app-releases.constants';
+import { AppReleasesService } from './app-releases.service';
+import { AppReleaseDto } from './dto/app-release.dto';
+
+/**
+ * 휴대폰 앱 받기 (사내 배포 — 계약 1절 "휴대폰 앱 받기", 2026-11-08) — 포털에 로그인한 직원만 받는다(웹 쿠키 · 앱 Bearer — JwtAuthGuard).
+ * 제한된 세션(새 비밀번호 · 2단계 켜기 전)은 403 AUTH_010 — `@AllowRestrictedSession()` 을 달지 않는다.
+ * 올리기는 API 가 없다 — 서버 B 의 운영 도구 「휴대폰 앱 올리기」(modules/ops/app-release-commands.ts).
+ *
+ * "올린 판이 없음"(404)은 화면이 설정을 열 때마다 묻는 예상된 상태라 debug 로만 남긴다 — 표에는 있는데 파일이 없는 404 는 서비스가 error 로 따로 남긴다
+ */
+@ApiTags('App')
+@ApiCookieAuth()
+@UseGuards(JwtAuthGuard)
+@ApiSessionErrors()
+@UseFilters(new HttpExceptionFilter({ quietStatuses: [HttpStatus.NOT_FOUND] }))
+@Controller('app-releases')
+export class AppReleasesController {
+  constructor(private readonly releases: AppReleasesService) {}
+
+  @Get('android/latest')
+  @NoStore()
+  @ApiOperation({
+    summary: '안드로이드 앱의 최신 판 정보',
+    description:
+      '최신 = 가장 늦게 올린 판(올린 시각 — 버전 번호가 아니다). 옛 APK 를 다시 올리면 그것이 최신이 된다. ' +
+      '올린 판이 없으면 404 RES_001 — 화면은 "아직 받을 수 있는 앱이 없습니다" 칸을 보인다(알림 끔). Cache-Control: private, no-store.',
+  })
+  @ApiStandardResponse(AppReleaseDto, { description: '최신 판 정보' })
+  @ApiErrorResponse('RES_001', '올린 판이 없다')
+  latest(): Promise<AppReleaseDto> {
+    return this.releases.latestInfo('android');
+  }
+
+  @Get('android/latest/file')
+  @SkipTransform()
+  @ApiOperation({
+    summary:
+      '안드로이드 앱의 최신 판 파일 (GET · HEAD · Range — 표준 래퍼 없음)',
+    description:
+      `늘 ${APK_CONTENT_TYPE} + Content-Disposition: attachment; filename="ARA-SYSTEM-<버전>.apk" + nosniff + sandbox CSP + private, no-store. ` +
+      '강한 ETag("<판 id>") · Last-Modified(올린 때) · Accept-Ranges: bytes — 대용량 첨부 받기와 같은 머리글이고 형식만 APK 다. ' +
+      'Range 하나면 206, 여럿 · 형식 오류면 200 전체, 처음이 크기 이상이면 416(본문 없음). HEAD 는 머리글만. ' +
+      '올린 판이 없거나 그 파일이 없으면 404 RES_001. 화면은 첨부 내려받기처럼 이동 전에 세션을 확인한다.',
+  })
+  @ApiProduces(APK_CONTENT_TYPE)
+  @ApiResponse({
+    status: HttpStatus.OK,
+    description: 'APK 파일 (206 — 범위)',
+    schema: { type: 'string', format: 'binary' },
+  })
+  @ApiResponse({
+    status: HttpStatus.REQUESTED_RANGE_NOT_SATISFIABLE,
+    description: '받을 수 없는 범위 — Content-Range: bytes */<크기>, 본문 없음',
+  })
+  @ApiErrorResponse('RES_001', '올린 판이 없다 · 그 파일이 없다')
+  async file(@Req() req: Request, @Res() res: Response): Promise<void> {
+    await this.releases.serveLatestFile(req, res, 'android');
+  }
+}

backend/src/modules/app-releases/app-releases.module.ts

@@ -0,0 +1,28 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { AppReleaseStorage } from './app-release-storage';
+import { AppReleaseEntity } from './app-release.entity';
+import { AppReleasesController } from './app-releases.controller';
+import { AppReleasesRepository } from './app-releases.repository';
+import { AppReleasesService } from './app-releases.service';
+
+/**
+ * 휴대폰 앱 받기 모듈 (사내 배포 — 계약 1절 "휴대폰 앱 받기") — 최신 판 정보 · 파일(`/api/app-releases/android/latest` · `/file`).
+ * 판은 표 app_releases, 파일은 업로드 볼륨의 `app-releases/`. 올리기는 운영 도구가 같은 서비스 · 저장소를 다시 엮어 쓴다(modules/ops/ops.module.ts).
+ * 이 모듈은 다른 기능 모듈을 가져오지 않는다
+ */
+@Module({
+  imports: [TypeOrmModule.forFeature([AppReleaseEntity])],
+  controllers: [AppReleasesController],
+  providers: [
+    AppReleasesRepository,
+    {
+      provide: AppReleaseStorage,
+      useFactory: () => new AppReleaseStorage(),
+    },
+    AppReleasesService,
+  ],
+  exports: [AppReleasesService],
+})
+export class AppReleasesModule {}

backend/src/modules/app-releases/app-releases.repository.ts

@@ -0,0 +1,39 @@
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import type { Repository } from 'typeorm';
+
+import { AppReleaseEntity } from './app-release.entity';
+import type { AppReleasePlatform } from './app-releases.constants';
+
+/** 늦게 올린 것부터 — 같은 시각이면 id 로 차례를 정한다(늘 같은 답) */
+const NEWEST_FIRST = { createdAt: 'DESC', id: 'DESC' } as const;
+
+/** 휴대폰 앱 판 표 (app_releases) */
+@Injectable()
+export class AppReleasesRepository {
+  constructor(
+    @InjectRepository(AppReleaseEntity)
+    private readonly rows: Repository<AppReleaseEntity>,
+  ) {}
+
+  /** 그 플랫폼에서 가장 늦게 올린 판 — 없으면 null */
+  latest(platform: AppReleasePlatform): Promise<AppReleaseEntity | null> {
+    return this.rows.findOne({ where: { platform }, order: NEWEST_FIRST });
+  }
+
+  /** 늦게 올린 것부터 `limit` 개 */
+  recent(
+    platform: AppReleasePlatform,
+    limit: number,
+  ): Promise<AppReleaseEntity[]> {
+    return this.rows.find({
+      where: { platform },
+      order: NEWEST_FIRST,
+      take: limit,
+    });
+  }
+
+  async insert(release: AppReleaseEntity): Promise<void> {
+    await this.rows.insert(release);
+  }
+}

backend/src/modules/app-releases/app-releases.service.spec.ts

@@ -0,0 +1,358 @@
+import { Logger } from '@nestjs/common';
+import { randomBytes } from 'crypto';
+import {
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'fs';
+import type { Request, Response } from 'express';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { PassThrough } from 'stream';
+
+import { BusinessException } from '@/common/errors/business.exception';
+import { inspectApk, type InspectedApk } from './apk-file';
+import { AppReleaseStorage } from './app-release-storage';
+import { AppReleaseEntity } from './app-release.entity';
+import { APK_ZIP_SIGNATURE } from './app-releases.constants';
+import type { AppReleasesRepository } from './app-releases.repository';
+import { AppReleasesService } from './app-releases.service';
+
+/** 표 대역 — 늦게 올린 것부터 (실제 차례는 e2e 가 PostgreSQL 로 본다) */
+class FakeRepository {
+  readonly rows: AppReleaseEntity[] = [];
+  insertFailure: Error | null = null;
+
+  private newestFirst(platform: string): AppReleaseEntity[] {
+    return this.rows
+      .filter((row) => row.platform === platform)
+      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+  }
+
+  latest(platform: string) {
+    return Promise.resolve(this.newestFirst(platform)[0] ?? null);
+  }
+
+  recent(platform: string, limit: number) {
+    return Promise.resolve(this.newestFirst(platform).slice(0, limit));
+  }
+
+  insert(release: AppReleaseEntity) {
+    if (this.insertFailure) return Promise.reject(this.insertFailure);
+    this.rows.push(release);
+    return Promise.resolve();
+  }
+}
+
+/** 응답 대역 — 흘려보낸 바이트 · 상태 · 머리글을 모은다 */
+class FakeResponse extends PassThrough {
+  statusCode = 200;
+  readonly headers = new Map<string, string>();
+  readonly received: Buffer[] = [];
+
+  constructor() {
+    super();
+    this.on('data', (part: Buffer) => this.received.push(part));
+  }
+
+  status(code: number): this {
+    this.statusCode = code;
+    return this;
+  }
+
+  setHeader(name: string, value: string): this {
+    this.headers.set(name.toLowerCase(), value);
+    return this;
+  }
+
+  get body(): Buffer {
+    return Buffer.concat(this.received);
+  }
+}
+
+const request = (method: string, headers: Record<string, string> = {}) =>
+  ({ method, headers }) as unknown as Request;
+
+async function codeOf(run: () => Promise<unknown>): Promise<string | null> {
+  try {
+    await run();
+    return null;
+  } catch (error) {
+    return error instanceof BusinessException ? error.code : 'NOT_BUSINESS';
+  }
+}
+
+describe('AppReleasesService — 휴대폰 앱 받기 (사내 배포)', () => {
+  let root: string;
+  let releaseDir: string;
+  let repository: FakeRepository;
+  let service: AppReleasesService;
+  let errors: string[];
+  const content = Buffer.concat([APK_ZIP_SIGNATURE, randomBytes(4096)]);
+
+  /** 운영자가 넣은 것처럼 — 임시 폴더의 APK 를 검사해 연 파일째 */
+  async function inspected(data: Buffer = content): Promise<InspectedApk> {
+    const path = join(root, `in-${randomBytes(4).toString('hex')}.apk`);
+    writeFileSync(path, data);
+    const inspection = await inspectApk(path);
+    if (!inspection.ok) throw new Error(inspection.problem);
+    return inspection.apk;
+  }
+
+  async function publish(
+    version: string,
+    at: Date,
+    data: Buffer = content,
+  ): Promise<AppReleaseEntity> {
+    const apk = await inspected(data);
+    try {
+      return await service.publish(
+        apk,
+        { platform: 'android', version, uploadedBy: '운영자 김' },
+        at,
+      );
+    } finally {
+      await apk.close();
+    }
+  }
+
+  async function serve(req: Request): Promise<FakeResponse> {
+    const res = new FakeResponse();
+    await service.serveLatestFile(req, res as unknown as Response, 'android');
+    return res;
+  }
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'app-releases-'));
+    releaseDir = join(root, 'app-releases');
+    repository = new FakeRepository();
+    service = new AppReleasesService(
+      repository as unknown as AppReleasesRepository,
+      new AppReleaseStorage(releaseDir),
+    );
+    errors = [];
+    jest.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
+    jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation((message: unknown) => {
+        errors.push(String(message));
+      });
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('최신 판 정보 — 올린 판이 없으면 404 RES_001, 있으면 가장 늦게 올린 판(버전 번호가 아니다)', async () => {
+    expect(await codeOf(() => service.latestInfo('android'))).toBe('RES_001');
+
+    await publish('1.2.0', new Date('2026-11-18T01:00:00.000Z'));
+    const older = await publish('1.1.0', new Date('2026-11-19T01:23:45.000Z'));
+    await expect(service.latestInfo('android')).resolves.toEqual({
+      version: '1.1.0',
+      sizeBytes: content.length,
+      releasedAt: older.createdAt.toISOString(),
+    });
+  });
+
+  it('올리기 — 볼륨에 <file_key>.apk 하나 · 표에 한 줄(크기 · SHA-256 · 올린 이)', async () => {
+    const release = await publish(
+      '1.0.0',
+      new Date('2026-11-18T01:23:45.000Z'),
+    );
+    expect(repository.rows).toEqual([release]);
+    expect(release).toMatchObject({
+      platform: 'android',
+      version: '1.0.0',
+      sizeBytes: content.length,
+      uploadedBy: '운영자 김',
+    });
+    expect(release.sha256).toMatch(/^[0-9a-f]{64}$/);
+    expect(release.fileKey).not.toBe(release.id);
+    expect(readdirSync(releaseDir)).toEqual([`${release.fileKey}.apk`]);
+  });
+
+  it('올리기 — 표에 넣지 못하면 들인 파일을 지우고 던진다(반쯤 올린 판을 남기지 않는다)', async () => {
+    repository.insertFailure = new Error('db down');
+    const apk = await inspected();
+    try {
+      await expect(
+        service.publish(apk, {
+          platform: 'android',
+          version: '1.0.0',
+          uploadedBy: '운영자 김',
+        }),
+      ).rejects.toThrow('db down');
+    } finally {
+      await apk.close();
+    }
+    expect(repository.rows).toEqual([]);
+    expect(readdirSync(releaseDir)).toEqual([]);
+  });
+
+  it('올리기 — 버전 글이 아니면 아무것도 하지 않고 던진다(부르는 쪽이 먼저 본다)', async () => {
+    const apk = await inspected();
+    try {
+      await expect(
+        service.publish(apk, {
+          platform: 'android',
+          version: '1.0',
+          uploadedBy: '운영자 김',
+        }),
+      ).rejects.toThrow('휴대폰 앱 버전 형식이 올바르지 않습니다.');
+    } finally {
+      await apk.close();
+    }
+    expect(existsSync(releaseDir)).toBe(false);
+  });
+
+  it('올리기 — 멈춘 올리기가 남긴 한 시간 넘은 임시 파일을 먼저 지운다', async () => {
+    const warn = jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined);
+    await publish('1.0.0', new Date('2026-11-18T01:00:00.000Z'));
+    const stale = join(
+      releaseDir,
+      '0f8fad5b-d9cb-469f-a165-70867728950e.apk.part',
+    );
+    writeFileSync(stale, 'half');
+
+    // 지금 시각(파일의 고친 때)보다 두 시간 뒤에 올린다
+    await publish('1.0.1', new Date(Date.now() + 2 * 60 * 60 * 1000));
+    expect(existsSync(stale)).toBe(false);
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('임시 파일 1개를 지웠습니다'),
+    );
+  });
+
+  describe('파일 응답 (Range · HEAD)', () => {
+    let release: AppReleaseEntity;
+
+    beforeEach(async () => {
+      release = await publish('1.0.0', new Date('2026-11-18T01:23:45.000Z'));
+    });
+
+    it('전체 200 — APK 형식 · 이름 · 대용량 받기와 같은 머리글(nosniff · sandbox · no-store · ETag · Accept-Ranges · X-Accel-Buffering)', async () => {
+      const res = await serve(request('GET'));
+      expect(res.statusCode).toBe(200);
+      expect(res.body.equals(content)).toBe(true);
+      expect(Object.fromEntries(res.headers)).toEqual({
+        'content-type': 'application/vnd.android.package-archive',
+        'content-disposition': 'attachment; filename="ARA-SYSTEM-1.0.0.apk"',
+        'x-content-type-options': 'nosniff',
+        'content-security-policy': "default-src 'none'; sandbox",
+        'cache-control': 'private, no-store',
+        'referrer-policy': 'no-referrer',
+        'x-robots-tag': 'noindex',
+        'accept-ranges': 'bytes',
+        etag: `"${release.id}"`,
+        'last-modified': release.createdAt.toUTCString(),
+        'x-accel-buffering': 'no',
+        'content-length': String(content.length),
+      });
+    });
+
+    it('범위 하나 206 · 끝 N 바이트 · 처음이 크기 이상이면 416(본문 없음) · If-Range 가 다르면 전체 200 · HEAD 는 머리글만', async () => {
+      const partial = await serve(request('GET', { range: 'bytes=0-99' }));
+      expect(partial.statusCode).toBe(206);
+      expect(partial.body.equals(content.subarray(0, 100))).toBe(true);
+      expect(partial.headers.get('content-range')).toBe(
+        `bytes 0-99/${content.length}`,
+      );
+      expect(partial.headers.get('content-length')).toBe('100');
+
+      const suffix = await serve(request('GET', { range: 'bytes=-10' }));
+      expect(suffix.statusCode).toBe(206);
+      expect(suffix.body.equals(content.subarray(content.length - 10))).toBe(
+        true,
+      );
+
+      const unsatisfiable = await serve(
+        request('GET', { range: `bytes=${content.length}-` }),
+      );
+      expect(unsatisfiable.statusCode).toBe(416);
+      expect(unsatisfiable.headers.get('content-range')).toBe(
+        `bytes */${content.length}`,
+      );
+      expect(unsatisfiable.headers.get('content-length')).toBe('0');
+      expect(unsatisfiable.body.length).toBe(0);
+
+      const changed = await serve(
+        request('GET', { range: 'bytes=0-9', 'if-range': '"other"' }),
+      );
+      expect(changed.statusCode).toBe(200);
+      expect(changed.body.length).toBe(content.length);
+      const resumed = await serve(
+        request('GET', { range: 'bytes=10-', 'if-range': `"${release.id}"` }),
+      );
+      expect(resumed.statusCode).toBe(206);
+      expect(resumed.body.equals(content.subarray(10))).toBe(true);
+
+      const head = await serve(request('HEAD', { range: 'bytes=0-1' }));
+      expect(head.statusCode).toBe(206);
+      expect(head.headers.get('content-length')).toBe('2');
+      expect(head.body.length).toBe(0);
+    });
+
+    it('표에는 있는데 파일이 없거나 크기가 다르면 404 RES_001 — 머리글을 쓰지 않고, 운영자가 알게 error 로그', async () => {
+      writeFileSync(join(releaseDir, `${release.fileKey}.apk`), 'cut');
+      const res = new FakeResponse();
+      expect(
+        await codeOf(() =>
+          service.serveLatestFile(
+            request('GET'),
+            res as unknown as Response,
+            'android',
+          ),
+        ),
+      ).toBe('RES_001');
+      expect(res.headers.size).toBe(0);
+      expect(errors.join('\n')).toContain('크기가 표와 다름');
+
+      rmSync(join(releaseDir, `${release.fileKey}.apk`));
+      expect(await codeOf(() => serve(request('GET')))).toBe('RES_001');
+      expect(errors.join('\n')).toContain('파일 없음');
+      expect(errors.join('\n')).toContain(`release=${release.id}`);
+    });
+
+    it('올린 판이 없으면 404 RES_001 (머리글을 쓰기 전에)', async () => {
+      repository.rows.length = 0;
+      const res = new FakeResponse();
+      expect(
+        await codeOf(() =>
+          service.serveLatestFile(
+            request('GET'),
+            res as unknown as Response,
+            'android',
+          ),
+        ),
+      ).toBe('RES_001');
+      expect(res.headers.size).toBe(0);
+    });
+
+    it('서버 종료가 시작되면 새 받기는 시작하지 않는다(연결을 끊는다 — 받는 쪽이 이어 받는다)', async () => {
+      service.beforeApplicationShutdown();
+      const res = await serve(request('GET'));
+      expect(res.destroyed).toBe(true);
+      expect(res.body.length).toBe(0);
+    });
+
+    it('목록 — 늦게 올린 것부터, 디스크에 파일이 있는지 함께', async () => {
+      const newer = await publish(
+        '1.0.1',
+        new Date('2026-11-19T01:00:00.000Z'),
+      );
+      rmSync(join(releaseDir, `${release.fileKey}.apk`));
+      await expect(service.listRecent('android', 10)).resolves.toEqual([
+        { release: newer, hasFile: true },
+        { release, hasFile: false },
+      ]);
+      await expect(service.listRecent('android', 1)).resolves.toEqual([
+        { release: newer, hasFile: true },
+      ]);
+    });
+  });
+});

backend/src/modules/app-releases/app-releases.service.ts

@@ -0,0 +1,325 @@
+import {
+  type BeforeApplicationShutdown,
+  HttpStatus,
+  Injectable,
+  Logger,
+} from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import type { Request, Response } from 'express';
+import type { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+
+import { BusinessException } from '@/common/errors/business.exception';
+import { currentRequestId, traceTag } from '@/shared/logger/request-context';
+import { downloadHeaders } from '@/shared/utils/download-headers';
+import { decideRange } from '@/shared/utils/http-range';
+import { isStreamAbortError } from '@/shared/utils/stream-abort';
+import { inspectApk, type ApkInspection, type InspectedApk } from './apk-file';
+import {
+  AppReleaseStorage,
+  type OpenedAppReleaseFile,
+} from './app-release-storage';
+import { appReleaseFileName, isAppVersion } from './app-release-version';
+import { AppReleaseEntity } from './app-release.entity';
+import {
+  APK_CONTENT_TYPE,
+  APP_RELEASE_STALE_PART_MS,
+  type AppReleasePlatform,
+} from './app-releases.constants';
+import { AppReleasesRepository } from './app-releases.repository';
+import type {
+  AppReleaseInfo,
+  AppReleaseListing,
+  AppReleasePublish,
+} from './app-releases.types';
+
+/** 버전 글이 아닌 줄(표를 손으로 고침)의 내려받는 이름 — 따옴표 안에 바깥 글이 들어가지 않게 */
+const FALLBACK_FILE_NAME = 'ARA-SYSTEM.apk';
+
+/** 머리글 하나 (여럿이면 첫 값) */
+function firstHeader(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function reasonOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * 휴대폰 앱 받기 (사내 배포 — 계약 1절 "휴대폰 앱 받기") — 직원은 최신 판 정보 · 파일을 받고(로그인 필요), 운영 도구가 판을 올린다.
+ * "최신" = 그 플랫폼에서 가장 늦게 올린 판(올린 시각 — 버전 번호가 아니다). 옛 APK 를 다시 올리면 그것이 최신이 된다(되돌리기 길).
+ *
+ * 파일 응답은 대용량 첨부 받기(file-sharing.service.ts 의 serveFile)와 같은 꼴이다 — 머리글은 shared/utils/download-headers.ts, 범위는 http-range.ts.
+ * 로그: 내려받기 성공은 남기지 않는다. 표에는 있는데 파일이 없거나 크기가 다르면 error(운영자가 다시 올린다)
+ */
+@Injectable()
+export class AppReleasesService implements BeforeApplicationShutdown {
+  private readonly logger = new Logger(AppReleasesService.name);
+  /** 지금 흘려보내는 파일 응답 — 서버 종료 때 끊는다 */
+  private readonly streaming = new Set<Response>();
+  private shuttingDown = false;
+
+  constructor(
+    private readonly repository: AppReleasesRepository,
+    private readonly storage: AppReleaseStorage,
+  ) {}
+
+  /**
+   * 서버 종료(HTTP 서버를 닫기 전) — 흘려보내는 파일 응답을 끊는다. 느린 내려받기가 종료 유예(30초)를 다 쓰지 않게 —
+   * 브라우저는 Range 로 이어 받는다(대용량 첨부 받기와 같은 결). 그 뒤에 온 받기는 시작하지 않는다
+   */
+  beforeApplicationShutdown(): void {
+    this.shuttingDown = true;
+    for (const res of this.streaming) res.destroy();
+    this.streaming.clear();
+  }
+
+  // ── 직원 (로그인 필요 — app-releases.controller.ts) ────────────────────────────
+
+  /** 최신 판 정보 — 올린 판이 없으면 404 RES_001 */
+  async latestInfo(platform: AppReleasePlatform): Promise<AppReleaseInfo> {
+    const release = await this.requireLatest(platform);
+    return {
+      version: release.version,
+      sizeBytes: release.sizeBytes,
+      releasedAt: release.createdAt.toISOString(),
+    };
+  }
+
+  /**
+   * 최신 판 파일을 내려준다 (GET · HEAD). 실패는 머리글을 쓰기 **전에** 던진다(전역 필터가 표준 실패 형식으로):
+   * 올린 판이 없음 · 파일이 없거나 표의 크기와 다름 404 RES_001.
+   * 범위: 없으면 200 전체, 하나면 206, 처음이 크기 이상이면 416(본문 없음 — 래핑 예외). HEAD 는 머리글만
+   */
+  async serveLatestFile(
+    req: Request,
+    res: Response,
+    platform: AppReleasePlatform,
+  ): Promise<void> {
+    const release = await this.requireLatest(platform);
+    const file = await this.openFileOf(release);
+    let handedOver = false;
+    try {
+      const size = release.sizeBytes;
+      const etag = `"${release.id}"`;
+      const decision = decideRange(
+        firstHeader(req.headers.range),
+        firstHeader(req.headers['if-range']),
+        size,
+        { etag, lastModified: release.createdAt },
+      );
+      this.writeFileHeaders(res, release, etag);
+      if (decision.kind === 'unsatisfiable') {
+        res.status(HttpStatus.REQUESTED_RANGE_NOT_SATISFIABLE);
+        res.setHeader('Content-Range', `bytes */${size}`);
+        res.setHeader('Content-Length', '0');
+        res.end();
+        return;
+      }
+      const range =
+        decision.kind === 'partial'
+          ? { start: decision.start, end: decision.end }
+          : undefined;
+      res.status(range ? HttpStatus.PARTIAL_CONTENT : HttpStatus.OK);
+      res.setHeader(
+        'Content-Length',
+        String(range ? range.end - range.start + 1 : size),
+      );
+      if (range) {
+        res.setHeader(
+          'Content-Range',
+          `bytes ${range.start}-${range.end}/${size}`,
+        );
+      }
+      if (req.method === 'HEAD') {
+        res.end();
+        return;
+      }
+      if (this.shuttingDown) {
+        // 종료 중 — 시작하지 않는다. 연결을 끊으면 받는 쪽이 다시 시도한다
+        res.destroy();
+        return;
+      }
+      // 흐름이 끝나거나 망가지면 파일도 닫는다 (autoClose 기본값)
+      const stream = file.handle.createReadStream(
+        range ? { start: range.start, end: range.end } : {},
+      );
+      handedOver = true;
+      await this.stream(stream, res, release);
+    } finally {
+      if (!handedOver) await file.handle.close();
+    }
+  }
+
+  // ── 운영 도구 (modules/ops/app-release-commands.ts) ─────────────────────────────
+
+  /** 운영자가 넣은 경로의 APK 를 검사한다 — 통과하면 연 파일째(부르는 쪽이 닫는다) */
+  inspect(path: string): Promise<ApkInspection> {
+    return inspectApk(path);
+  }
+
+  /** 그 플랫폼의 최신 판 — 없으면 null */
+  latest(platform: AppReleasePlatform): Promise<AppReleaseEntity | null> {
+    return this.repository.latest(platform);
+  }
+
+  /** 늦게 올린 것부터 `limit` 개 — 디스크에 파일이 있는지 함께 */
+  async listRecent(
+    platform: AppReleasePlatform,
+    limit: number,
+  ): Promise<AppReleaseListing[]> {
+    const releases = await this.repository.recent(platform, limit);
+    return Promise.all(
+      releases.map(async (release) => ({
+        release,
+        hasFile: await this.storage.exists(release.fileKey),
+      })),
+    );
+  }
+
+  /**
+   * 판을 올린다 — 검사한 APK 를 볼륨에 들이고(임시 이름 → 디스크에 내려쓰기 → 이름 바꾸기) 표에 한 줄 넣는다. 넣은 순간 최신이 된다.
+   * 들이는 동안 원본이 바뀌었으면 AppReleaseFileChangedError(파일도 표도 그대로). 표에 넣지 못하면 들인 파일을 지우고 던진다 —
+   * 반쯤 올린 판을 남기지 않는다. 시작할 때 멈춘 올리기가 남긴 오래된 임시 파일을 지운다
+   */
+  async publish(
+    apk: InspectedApk,
+    input: AppReleasePublish,
+    now: Date = new Date(),
+  ): Promise<AppReleaseEntity> {
+    if (!isAppVersion(input.version)) {
+      // 부르는 쪽(운영 도구)이 먼저 본다 — 여기까지 오면 버그
+      throw new Error('휴대폰 앱 버전 형식이 올바르지 않습니다.');
+    }
+    await this.removeStaleParts(now);
+    const release = Object.assign(new AppReleaseEntity(), {
+      id: randomUUID(),
+      platform: input.platform,
+      version: input.version,
+      sizeBytes: apk.sizeBytes,
+      sha256: apk.sha256,
+      fileKey: randomUUID(),
+      uploadedBy: input.uploadedBy,
+      createdAt: now,
+    } satisfies AppReleaseEntity);
+    await this.storage.importFile(apk.handle, release.fileKey, {
+      sizeBytes: apk.sizeBytes,
+      sha256: apk.sha256,
+    });
+    try {
+      await this.repository.insert(release);
+    } catch (error) {
+      // 표에 없는 파일은 누구도 받지 않는다 — 지워 둔다
+      await this.storage
+        .remove(release.fileKey)
+        .catch((removeError: unknown) =>
+          this.logger.error(
+            `[SYS_001] 표에 넣지 못한 휴대폰 앱 파일을 지우지도 못했습니다 — 볼륨에 남습니다: file=${release.fileKey}, reason=${reasonOf(removeError)}`,
+          ),
+        );
+      throw error;
+    }
+    this.logger.log(
+      `휴대폰 앱을 올렸습니다: platform=${release.platform}, version=${release.version}, release=${release.id}, size=${release.sizeBytes}`,
+    );
+    return release;
+  }
+
+  // ── 내부 ────────────────────────────────────────────────────────────────
+
+  private async requireLatest(
+    platform: AppReleasePlatform,
+  ): Promise<AppReleaseEntity> {
+    const release = await this.repository.latest(platform);
+    if (release === null) {
+      throw new BusinessException('RES_001', {
+        context: { reason: 'app-release-none', platform },
+      });
+    }
+    return release;
+  }
+
+  /** 그 판의 파일 — 없거나 표의 크기와 다르면 error 로그 + 404 RES_001 (직원에게는 올린 판이 없는 것과 같다) */
+  private async openFileOf(
+    release: AppReleaseEntity,
+  ): Promise<OpenedAppReleaseFile> {
+    const file = await this.storage.open(release.fileKey);
+    if (file !== null && file.sizeBytes === release.sizeBytes) return file;
+    if (file !== null) await file.handle.close();
+    const missing = file === null;
+    this.logger.error(
+      `[RES_001]${traceTag()} 휴대폰 앱 파일을 내려줄 수 없습니다(${missing ? '파일 없음' : '크기가 표와 다름'}) — 운영 도구로 다시 올려 주세요: release=${release.id}, platform=${release.platform}, version=${release.version}`,
+    );
+    throw new BusinessException('RES_001', {
+      context: {
+        reason: missing
+          ? 'app-release-file-missing'
+          : 'app-release-file-size-mismatch',
+        release: release.id,
+      },
+    });
+  }
+
+  /** 파일 응답의 머리글 — 대용량 첨부 받기와 같은 꼴이고 형식만 APK 다 (shared/utils/download-headers.ts) */
+  private writeFileHeaders(
+    res: Response,
+    release: AppReleaseEntity,
+    etag: string,
+  ): void {
+    const fileName = isAppVersion(release.version)
+      ? appReleaseFileName(release.version)
+      : FALLBACK_FILE_NAME;
+    for (const [header, value] of downloadHeaders({
+      contentType: APK_CONTENT_TYPE,
+      // 이름은 검사한 버전으로 만든 ASCII 뿐이다 — RFC 5987 이름(filename*)이 필요 없다
+      contentDisposition: `attachment; filename="${fileName}"`,
+      etag,
+      lastModified: release.createdAt,
+    })) {
+      res.setHeader(header, value);
+    }
+  }
+
+  private async stream(
+    stream: Readable,
+    res: Response,
+    release: AppReleaseEntity,
+  ): Promise<void> {
+    // 흐름 오류는 처리기가 끝난 뒤에 올 수 있다 — 추적 ID 를 지금 잡아 둔다
+    const traceId = currentRequestId() ?? 'unknown';
+    this.streaming.add(res);
+    try {
+      // 파일을 여는 사이 종료가 시작됐으면 흘려보내지 않는다 (종료 때 끊을 목록에 들기 전이었다)
+      if (this.shuttingDown) res.destroy();
+      await pipeline(stream, res);
+    } catch (error) {
+      // 받는 쪽이 끊었거나 종료로 끊었다 — 장애가 아니다. 디스크 오류 등만 남긴다
+      if (!isStreamAbortError(error)) {
+        this.logger.error(
+          `[SYS_001][${traceId}] 휴대폰 앱 전송이 멈췄습니다: release=${release.id}, reason=${reasonOf(error)}`,
+        );
+      }
+      if (!res.destroyed) res.destroy();
+    } finally {
+      this.streaming.delete(res);
+    }
+  }
+
+  /** 멈춘 올리기가 남긴 오래된 임시 파일 — 정리하지 못해도 올리기는 이어 한다 */
+  private async removeStaleParts(now: Date): Promise<void> {
+    try {
+      const removed = await this.storage.removeStaleParts(
+        new Date(now.getTime() - APP_RELEASE_STALE_PART_MS),
+      );
+      if (removed > 0) {
+        this.logger.warn(
+          `멈춘 휴대폰 앱 올리기가 남긴 임시 파일 ${removed}개를 지웠습니다.`,
+        );
+      }
+    } catch (error) {
+      this.logger.warn(
+        `멈춘 휴대폰 앱 올리기의 임시 파일을 정리하지 못했습니다 — 올리기는 이어 합니다: reason=${reasonOf(error)}`,
+      );
+    }
+  }
+}

backend/src/modules/app-releases/app-releases.types.ts

@@ -0,0 +1,24 @@
+import type { AppReleaseEntity } from './app-release.entity';
+import type { AppReleasePlatform } from './app-releases.constants';
+
+/** 최신 판 정보 — `GET /api/app-releases/android/latest` 의 data (계약 1절 "휴대폰 앱 받기") */
+export interface AppReleaseInfo {
+  readonly version: string;
+  readonly sizeBytes: number;
+  /** 올린 때 — ISO 8601 UTC */
+  readonly releasedAt: string;
+}
+
+/** 운영 도구가 올리는 판 */
+export interface AppReleasePublish {
+  readonly platform: AppReleasePlatform;
+  readonly version: string;
+  /** 운영자 이름 — 운영 도구를 시작할 때 넣은 이름 */
+  readonly uploadedBy: string;
+}
+
+/** 운영 도구 「휴대폰 앱 목록」의 한 줄 — 디스크에 파일이 있는지 함께 */
+export interface AppReleaseListing {
+  readonly release: AppReleaseEntity;
+  readonly hasFile: boolean;
+}

backend/src/modules/app-releases/dto/app-release.dto.ts

@@ -0,0 +1,26 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+import type { AppReleaseInfo } from '../app-releases.types';
+
+/** GET /api/app-releases/android/latest 의 응답 (계약 1절 "휴대폰 앱 받기") */
+export class AppReleaseDto implements AppReleaseInfo {
+  @ApiProperty({
+    description:
+      '버전 — 앱의 versionName(`숫자.숫자.숫자`, 칸마다 1~4자리 · 앞자리 0 없이). 내려받는 파일 이름은 `ARA-SYSTEM-<버전>.apk`',
+    example: '1.0.0',
+  })
+  version!: string;
+
+  @ApiProperty({
+    description: 'APK 파일 크기(바이트)',
+    example: 32_505_856,
+  })
+  sizeBytes!: number;
+
+  @ApiProperty({
+    description:
+      '올린 때 (ISO 8601 UTC) — 화면의 "올린 날". 최신 = 가장 늦게 올린 판(버전 번호가 아니다)',
+    example: '2026-11-18T01:23:45.000Z',
+  })
+  releasedAt!: string;
+}

backend/src/modules/contacts/address-book.ts

@@ -320,12 +320,14 @@ export function weightAfterChanges(
 export interface WrittenChanges {
   readonly createdIds: ReadonlyMap<string, string>;
   readonly cards: ReadonlyMap<string, AddressBookCard>;
+  /** 엔진이 받지 않은 만들기의 key — 가져오기(일부만 받음)에만 있다. 옮기지 않는다 */
+  readonly refusedKeys?: ReadonlySet<string>;
 }
 
 /**
  * 엔진이 받은 바꾸기를 기억한 주소록에 옮긴다 — 판이 같을 때만 쓰므로(ifInState) 엔진의 새 내용과 같다.
  * 연락처의 고치기 · 만든 카드는 어댑터가 준 모양(칸 안의 남의 정보와 합친 결과)을, 그룹 고치기는 보낸 이름 · 구성원을 쓴다.
- * 만든 카드의 id 나 모양이 하나라도 없으면 null (옮길 수 없다 — 다시 읽는다)
+ * 엔진이 받지 않은 만들기(refusedKeys)는 건너뛴다. 그 밖의 만든 카드의 id 나 모양이 하나라도 없으면 null (옮길 수 없다 — 다시 읽는다)
  */
 export function applyAddressBookWrite(
   snapshot: AddressBookSnapshot,
@@ -352,6 +354,7 @@ export function applyAddressBookWrite(
     .map((card) => applyGroupUpdate(card, updates.get(card.id)));
 
   for (const card of changes.create) {
+    if (written.refusedKeys?.has(card.key)) continue;
     const id = written.createdIds.get(card.key);
     const read = id === undefined ? undefined : written.cards.get(id);
     if (read === undefined) return null;

backend/src/modules/contacts/contact-export.spec.ts

@@ -0,0 +1,291 @@
+import {
+  contactExportContentType,
+  contactExportFileName,
+  contactsToCsv,
+  contactsToVcard,
+  CSV_HEADER,
+  foldVcardLine,
+  type ExportedContact,
+} from './contact-export';
+
+const contact = (
+  overrides: Partial<ExportedContact> = {},
+): ExportedContact => ({
+  uid: 'urn:uuid:3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d',
+  name: '박지훈',
+  emails: [{ address: 'jihoon.park@hanbit.example', label: 'work' }],
+  phones: [{ number: '010-3192-5540', label: 'mobile' }],
+  company: '한빛상사',
+  department: '구매팀',
+  title: '과장',
+  note: '견적 담당',
+  groupNames: ['거래처'],
+  ...overrides,
+});
+
+/** 접힌 줄을 푼다 (CRLF + 공백 하나를 지운다 — RFC 2425 5.8.1) */
+const unfold = (text: string) => text.replace(/\r\n /g, '');
+
+describe('내보내기 — vCard 3.0', () => {
+  it('한 사람 — 줄 끝 CRLF, VERSION 은 BEGIN 바로 다음, 우리 칸만 (계약 3절 "내보내기")', () => {
+    expect(contactsToVcard([contact()])).toBe(
+      [
+        'BEGIN:VCARD',
+        'VERSION:3.0',
+        'UID:urn:uuid:3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d',
+        'FN:박지훈',
+        'N:박지훈;;;;',
+        'EMAIL;TYPE=INTERNET,WORK:jihoon.park@hanbit.example',
+        'TEL;TYPE=CELL:010-3192-5540',
+        'ORG:한빛상사;구매팀',
+        'TITLE:과장',
+        'NOTE:견적 담당',
+        'CATEGORIES:거래처',
+        'END:VCARD',
+        '',
+      ].join('\r\n'),
+    );
+  });
+
+  it('종류 — 이메일 WORK · HOME · INTERNET, 전화 CELL · WORK · HOME · VOICE', () => {
+    const text = contactsToVcard([
+      contact({
+        emails: [
+          { address: 'a@x.example', label: 'work' },
+          { address: 'b@x.example', label: 'personal' },
+          { address: 'c@x.example', label: 'other' },
+        ],
+        phones: [
+          { number: '1', label: 'mobile' },
+          { number: '2', label: 'work' },
+          { number: '3', label: 'home' },
+          { number: '4', label: 'other' },
+        ],
+      }),
+    ]);
+    expect(text).toContain('\r\nEMAIL;TYPE=INTERNET,WORK:a@x.example\r\n');
+    expect(text).toContain('\r\nEMAIL;TYPE=INTERNET,HOME:b@x.example\r\n');
+    expect(text).toContain('\r\nEMAIL;TYPE=INTERNET:c@x.example\r\n');
+    expect(text).toContain(
+      '\r\nTEL;TYPE=CELL:1\r\nTEL;TYPE=WORK:2\r\nTEL;TYPE=HOME:3\r\nTEL;TYPE=VOICE:4\r\n',
+    );
+  });
+
+  it('이스케이프 — \\ ; , 줄바꿈 (그룹 이름 안의 쉼표도)', () => {
+    const text = contactsToVcard([
+      contact({
+        name: '김; 아라, 팀장',
+        company: 'A;B',
+        department: null,
+        note: '첫 줄\n둘째 줄 C:\\temp',
+        groupNames: ['가,나', '다'],
+      }),
+    ]);
+    expect(text).toContain('\r\nFN:김\\; 아라\\, 팀장\r\n');
+    expect(text).toContain('\r\nN:김\\; 아라\\, 팀장;;;;\r\n');
+    expect(text).toContain('\r\nORG:A\\;B;\r\n');
+    expect(text).toContain('\r\nNOTE:첫 줄\\n둘째 줄 C:\\\\temp\r\n');
+    expect(text).toContain('\r\nCATEGORIES:가\\,나,다\r\n');
+  });
+
+  it('빈 칸 — 이름이 없으면 FN 은 첫 이메일(N 은 비운다), 없는 칸 · uid 는 줄을 넣지 않는다, 회사가 없고 부서만 있으면 ORG:;부서', () => {
+    const text = contactsToVcard([
+      contact({
+        uid: null,
+        name: null,
+        emails: [
+          { address: 'first@x.example', label: 'work' },
+          { address: 'second@x.example', label: 'other' },
+        ],
+        phones: [{ number: '010-3192-5540', label: 'mobile' }],
+        company: null,
+        department: '구매팀',
+        title: null,
+        note: null,
+        groupNames: [],
+      }),
+    ]);
+    expect(text).toBe(
+      [
+        'BEGIN:VCARD',
+        'VERSION:3.0',
+        'FN:first@x.example',
+        'N:;;;;',
+        'EMAIL;TYPE=INTERNET,WORK:first@x.example',
+        'EMAIL;TYPE=INTERNET:second@x.example',
+        'TEL;TYPE=CELL:010-3192-5540',
+        'ORG:;구매팀',
+        'END:VCARD',
+        '',
+      ].join('\r\n'),
+    );
+  });
+
+  it('이름 · 이메일이 없으면 FN 은 첫 전화번호, 그것도 없으면 빈 FN (N 은 늘 이름 칸 그대로)', () => {
+    const phoneOnly = contactsToVcard([
+      contact({
+        name: null,
+        emails: [],
+        phones: [
+          { number: '02-555-0100', label: 'work' },
+          { number: '010-3192-5540', label: 'mobile' },
+        ],
+      }),
+    ]);
+    expect(phoneOnly).toContain('\r\nFN:02-555-0100\r\nN:;;;;\r\n');
+
+    const nothing = contactsToVcard([
+      contact({ name: null, emails: [], phones: [] }),
+    ]);
+    expect(nothing).toContain('\r\nFN:\r\nN:;;;;\r\n');
+    // 이름이 있으면 이름 — 주소 · 번호로 채우지 않는다
+    expect(contactsToVcard([contact()])).toContain('\r\nFN:박지훈\r\n');
+  });
+
+  it('줄 접기 — 75바이트마다(이어지는 줄은 공백 하나로 시작해 74바이트), 한글(3바이트)을 가르지 않는다', () => {
+    const line = `NOTE:${'가'.repeat(60)}`;
+    const folded = foldVcardLine(line);
+    const lines = folded.split('\r\n');
+    expect(lines.length).toBeGreaterThan(1);
+    for (const [index, part] of lines.entries()) {
+      expect(Buffer.byteLength(part, 'utf8')).toBeLessThanOrEqual(75);
+      if (index > 0) expect(part.startsWith(' ')).toBe(true);
+      // 가른 곳이 글자 사이다 — 바이트로 바꿔도 깨진 글자(U+FFFD)가 없다
+      expect(Buffer.from(part, 'utf8').toString('utf8')).not.toContain(
+        '\uFFFD',
+      );
+    }
+    expect(unfold(folded)).toBe(line);
+    // 75바이트 이하는 그대로
+    expect(foldVcardLine('A'.repeat(75))).toBe('A'.repeat(75));
+    expect(foldVcardLine('A'.repeat(76))).toBe(`${'A'.repeat(75)}\r\n A`);
+    // 이모지(4바이트 · 서로게이트 쌍)도 가르지 않는다
+    const emoji = foldVcardLine(`FN:${'😀'.repeat(30)}`);
+    expect(unfold(emoji)).toBe(`FN:${'😀'.repeat(30)}`);
+    for (const part of emoji.split('\r\n')) {
+      expect(Buffer.byteLength(part, 'utf8')).toBeLessThanOrEqual(75);
+      expect(/[\uD800-\uDBFF]$/.test(part)).toBe(false);
+      expect(/^ ?[\uDC00-\uDFFF]/.test(part)).toBe(false);
+    }
+  });
+
+  it('여러 명은 한 파일에 이어 붙인다 · 연락처가 없으면 빈 파일', () => {
+    const text = contactsToVcard([contact(), contact({ name: '김아라' })]);
+    expect(text.match(/BEGIN:VCARD/g)).toHaveLength(2);
+    expect(text.endsWith('END:VCARD\r\n')).toBe(true);
+    expect(contactsToVcard([])).toBe('');
+  });
+});
+
+describe('내보내기 — CSV', () => {
+  it('UTF-8 BOM · CRLF · 한국어 머리 — 같은 칸 여럿은 "; ", 이메일은 종류 없이 모두', () => {
+    const text = contactsToCsv([
+      contact({
+        emails: [
+          { address: 'a@x.example', label: 'work' },
+          { address: 'b@x.example', label: 'personal' },
+        ],
+        phones: [
+          { number: '010-1111-2222', label: 'mobile' },
+          { number: '010-3333-4444', label: 'mobile' },
+          { number: '02-555-0100', label: 'work' },
+          { number: '031-000-0000', label: 'home' },
+          { number: '070-1234-5678', label: 'other' },
+        ],
+        groupNames: ['거래처', '협력사'],
+      }),
+    ]);
+    expect(text.startsWith('\uFEFF')).toBe(true);
+    expect(text).toBe(
+      '\uFEFF' +
+        '이름,이메일,휴대폰,회사 전화,집 전화,기타 전화,회사,부서,직함,메모,그룹\r\n' +
+        '박지훈,a@x.example; b@x.example,010-1111-2222; 010-3333-4444,02-555-0100,031-000-0000,070-1234-5678,한빛상사,구매팀,과장,견적 담당,거래처; 협력사\r\n',
+    );
+    expect(CSV_HEADER).toHaveLength(11);
+  });
+
+  it("= + - @ 로 시작하는 칸은 앞에 ' (엑셀 수식 막기) · 쉼표 · 따옴표 · 줄바꿈은 따옴표로 감싼다", () => {
+    const text = contactsToCsv([
+      contact({
+        name: '=HYPERLINK("http://x")',
+        emails: [],
+        phones: [{ number: '+82 10-1234-5678', label: 'mobile' }],
+        company: '-주식회사',
+        department: '@영업',
+        title: '과장, 팀장',
+        note: '첫 줄\n둘째 줄',
+        groupNames: [],
+      }),
+    ]);
+    const row = text.split('\r\n')[1];
+    expect(row).toBe(
+      `"'=HYPERLINK(""http://x"")",,'+82 10-1234-5678,,,,'-주식회사,'@영업,"과장, 팀장","첫 줄\n둘째 줄",`,
+    );
+  });
+
+  it("탭 · CR 로 시작하는 칸도 앞에 ' (OWASP CSV Injection) — CR 이 든 칸은 따옴표로 감싼다", () => {
+    const text = contactsToCsv([
+      contact({
+        name: '\t=1+1',
+        emails: [],
+        phones: [],
+        company: '\r=1+1',
+        department: null,
+        title: '가\t나',
+        note: null,
+        groupNames: [],
+      }),
+    ]);
+    // 가운데의 탭은 그대로 — 첫 글자만 본다
+    expect(text.slice(text.indexOf('\r\n') + 2)).toBe(
+      `'\t=1+1,,,,,,"'\r=1+1",,가\t나,,\r\n`,
+    );
+  });
+
+  it('빈 칸은 비운다 · 연락처가 없으면 머리 줄만', () => {
+    const text = contactsToCsv([
+      contact({
+        name: null,
+        phones: [],
+        company: null,
+        department: null,
+        title: null,
+        note: null,
+        groupNames: [],
+      }),
+    ]);
+    expect(text.split('\r\n')[1]).toBe(',jihoon.park@hanbit.example,,,,,,,,,');
+    expect(contactsToCsv([])).toBe(`\uFEFF${CSV_HEADER.join(',')}\r\n`);
+  });
+});
+
+describe('내보내기 — 파일 이름 · 형식', () => {
+  // 2026-11-10 15:30 UTC = 2026-11-11 00:30 KST
+  const at = new Date('2026-11-10T15:30:00.000Z');
+
+  it('주소록-YYYY-MM-DD(한국 날짜) · 그룹이면 주소록-<그룹 이름>-YYYY-MM-DD', () => {
+    expect(contactExportFileName('vcard', null, at)).toBe(
+      '주소록-2026-11-11.vcf',
+    );
+    expect(contactExportFileName('csv', '거래처', at)).toBe(
+      '주소록-거래처-2026-11-11.csv',
+    );
+  });
+
+  it('그룹 이름의 예약 글자는 _ · 앞뒤 공백과 점은 뗀다 · 남는 것이 없으면 그룹 칸을 빼고 · 50글자까지', () => {
+    expect(contactExportFileName('csv', ' 팀/파트:A* ', at)).toBe(
+      '주소록-팀_파트_A_-2026-11-11.csv',
+    );
+    expect(contactExportFileName('csv', ' .. ', at)).toBe(
+      '주소록-2026-11-11.csv',
+    );
+    expect(contactExportFileName('vcard', '가'.repeat(80), at)).toBe(
+      `주소록-${'가'.repeat(50)}-2026-11-11.vcf`,
+    );
+  });
+
+  it('Content-Type — text/vcard · text/csv (UTF-8)', () => {
+    expect(contactExportContentType('vcard')).toBe('text/vcard; charset=utf-8');
+    expect(contactExportContentType('csv')).toBe('text/csv; charset=utf-8');
+  });
+});

backend/src/modules/contacts/contact-export.ts

@@ -0,0 +1,267 @@
+import { kstDateString } from '@/shared/utils/kst-date';
+import { MAX_CONTACT_GROUP_NAME_LENGTH } from './contacts.constants';
+import type {
+  ContactEmailLabel,
+  ContactExportFormat,
+  ContactFields,
+  ContactPhoneLabel,
+} from './contacts.types';
+
+/**
+ * 주소록 내보내기 파일 (순수 함수) — 계약 3절 "내보내기" (16단계). 우리 칸만 쓴다(엔진 카드의 다른 칸은 읽지 않는다).
+ *
+ * vCard 3.0 (RFC 2426): 줄 끝 CRLF · 한 줄 75바이트에서 접는다(UTF-8 글자를 가르지 않게 — 이어지는 줄은 공백 하나로 시작) ·
+ * 글 값은 `\` `;` `,` 줄바꿈을 이스케이프. FN(이름 — 없으면 첫 이메일 → 첫 전화번호) · N(이름 전체를 성 칸에) · EMAIL · TEL · ORG(회사;부서) ·
+ * TITLE · NOTE · CATEGORIES(그룹 이름) · UID.
+ *
+ * CSV: UTF-8 BOM · CRLF · 한국어 머리(아래 CSV_HEADER) — 이메일은 종류 없이 모두, 같은 칸에 여럿이면 `; ` 로 잇는다.
+ * 칸이 `= + - @` · 탭 · CR 로 시작하면 앞에 `'` 를 붙인다(엑셀 수식 막기 — OWASP CSV Injection). 쉼표 · 따옴표 · 줄바꿈이 든 칸은 따옴표로 감싼다(RFC 4180).
+ * 우리 가져오기(화면)가 이 두 모양을 다시 받는다 — 머리 이름 · 차례를 바꾸면 frontend shared/utils/contact-import 도 함께
+ */
+
+/** 내보낼 연락처 하나 — 우리 칸 + 카드의 uid · 속한 그룹 이름(그룹 이름 차례) */
+export interface ExportedContact extends ContactFields {
+  readonly uid: string | null;
+  readonly groupNames: readonly string[];
+}
+
+export const VCARD_CONTENT_TYPE = 'text/vcard; charset=utf-8';
+export const CSV_CONTENT_TYPE = 'text/csv; charset=utf-8';
+
+const CRLF = '\r\n';
+/** vCard 한 줄의 바이트 상한 (줄 끝 제외 — 이어지는 줄은 앞의 공백까지 센다) */
+const VCARD_LINE_OCTETS = 75;
+
+const VCARD_EMAIL_TYPES: Record<ContactEmailLabel, string> = {
+  work: 'INTERNET,WORK',
+  personal: 'INTERNET,HOME',
+  other: 'INTERNET',
+};
+
+const VCARD_PHONE_TYPES: Record<ContactPhoneLabel, string> = {
+  mobile: 'CELL',
+  work: 'WORK',
+  home: 'HOME',
+  other: 'VOICE',
+};
+
+/** CSV 머리 — 칸 차례 (계약 3절 "내보내기") */
+export const CSV_HEADER = [
+  '이름',
+  '이메일',
+  '휴대폰',
+  '회사 전화',
+  '집 전화',
+  '기타 전화',
+  '회사',
+  '부서',
+  '직함',
+  '메모',
+  '그룹',
+] as const;
+
+/** 같은 칸에 여럿을 잇는 글 */
+const CSV_JOINER = '; ';
+/** 엑셀이 수식으로 읽는 첫 글자(OWASP CSV Injection — `= + - @` · 탭 · CR) — 앞에 `'` 를 붙인다 */
+const CSV_FORMULA_START = /^[=+\-@\t\r]/;
+/** 따옴표로 감쌀 칸 */
+const CSV_NEEDS_QUOTES = /[",\r\n]/;
+/** UTF-8 BOM(U+FEFF) — 엑셀이 한글을 UTF-8 로 읽게 (소스에 보이지 않는 글자를 두지 않는다) */
+const UTF8_BOM = String.fromCharCode(0xfeff);
+
+/** 파일 이름 앞머리 · 형식마다 확장자 */
+const FILE_NAME_PREFIX = '주소록';
+const FILE_EXTENSIONS: Record<ContactExportFormat, string> = {
+  vcard: '.vcf',
+  csv: '.csv',
+};
+/** 파일 이름에 쓸 수 없는 글자(경로 구분자 · Windows 예약 글자) — '_' 로 */
+const FILE_NAME_RESERVED = /[\\/:*?"<>|]/g;
+/** 그룹 이름 앞뒤에서 떼는 글자 — 공백과 점 (앞의 점은 숨김 파일, Windows 는 끝의 점을 지운다) */
+const FILE_NAME_EDGE = /^[\s.]$/u;
+
+/** vCard 글 값의 이스케이프 — `\` `;` `,` 줄바꿈(\n) (한 번 훑는다) */
+function escapeVcardText(value: string): string {
+  return value.replace(/[\\;,]|\r\n|\r|\n/g, (match) => {
+    if (match === '\\') return '\\\\';
+    if (match === ';') return '\\;';
+    if (match === ',') return '\\,';
+    return '\\n';
+  });
+}
+
+/** UTF-8 바이트 수 — 코드 포인트 하나 */
+function utf8Length(codePoint: number): number {
+  if (codePoint < 0x80) return 1;
+  if (codePoint < 0x800) return 2;
+  if (codePoint < 0x10000) return 3;
+  return 4;
+}
+
+/** 한 줄을 75바이트마다 접는다 — 글자(코드 포인트)를 가르지 않는다. 이어지는 줄은 공백 하나로 시작한다 */
+export function foldVcardLine(line: string): string {
+  const parts: string[] = [];
+  let current = '';
+  let bytes = 0;
+  let limit = VCARD_LINE_OCTETS;
+  for (const char of line) {
+    const size = utf8Length(char.codePointAt(0) ?? 0);
+    if (bytes + size > limit) {
+      parts.push(current);
+      current = '';
+      bytes = 0;
+      // 이어지는 줄 앞의 공백 하나도 75바이트에 든다
+      limit = VCARD_LINE_OCTETS - 1;
+    }
+    current += char;
+    bytes += size;
+  }
+  parts.push(current);
+  return parts.join(`${CRLF} `);
+}
+
+/**
+ * 보이는 이름(FN) — 이름, 없으면 첫 이메일, 그것도 없으면 첫 전화번호(vCard 3.0 은 FN 을 꼭 담는다 — 빈 FN 은 받는 쪽이 "이름 없음"으로 보인다).
+ * N 은 이름 칸 그대로 둔다(이름이 없으면 빈 칸 — 다시 가져올 때 주소를 이름으로 읽지 않게)
+ */
+function displayNameOf(contact: ExportedContact): string {
+  return (
+    contact.name ??
+    contact.emails[0]?.address ??
+    contact.phones[0]?.number ??
+    ''
+  );
+}
+
+/** 연락처 하나의 vCard 3.0 */
+function vcardOf(contact: ExportedContact): string {
+  const name = contact.name ?? '';
+  const lines = ['BEGIN:VCARD', 'VERSION:3.0'];
+  if (contact.uid !== null) lines.push(`UID:${escapeVcardText(contact.uid)}`);
+  lines.push(`FN:${escapeVcardText(displayNameOf(contact))}`);
+  lines.push(`N:${escapeVcardText(name)};;;;`);
+  for (const email of contact.emails) {
+    lines.push(
+      `EMAIL;TYPE=${VCARD_EMAIL_TYPES[email.label]}:${escapeVcardText(email.address)}`,
+    );
+  }
+  for (const phone of contact.phones) {
+    lines.push(
+      `TEL;TYPE=${VCARD_PHONE_TYPES[phone.label]}:${escapeVcardText(phone.number)}`,
+    );
+  }
+  if (contact.company !== null || contact.department !== null) {
+    lines.push(
+      `ORG:${escapeVcardText(contact.company ?? '')};${escapeVcardText(contact.department ?? '')}`,
+    );
+  }
+  if (contact.title !== null) {
+    lines.push(`TITLE:${escapeVcardText(contact.title)}`);
+  }
+  if (contact.note !== null) {
+    lines.push(`NOTE:${escapeVcardText(contact.note)}`);
+  }
+  if (contact.groupNames.length > 0) {
+    lines.push(
+      `CATEGORIES:${contact.groupNames.map(escapeVcardText).join(',')}`,
+    );
+  }
+  lines.push('END:VCARD');
+  return lines.map((line) => `${foldVcardLine(line)}${CRLF}`).join('');
+}
+
+/** vCard 3.0 파일 — 한 파일에 여러 장 (연락처가 없으면 빈 파일) */
+export function contactsToVcard(contacts: readonly ExportedContact[]): string {
+  return contacts.map(vcardOf).join('');
+}
+
+/** CSV 한 칸 — 수식 막기 · 필요하면 따옴표 */
+function csvCell(value: string): string {
+  const guarded = CSV_FORMULA_START.test(value) ? `'${value}` : value;
+  return CSV_NEEDS_QUOTES.test(guarded)
+    ? `"${guarded.replace(/"/g, '""')}"`
+    : guarded;
+}
+
+/** 그 종류의 전화번호들 — 한 칸 */
+function phonesOf(contact: ExportedContact, label: ContactPhoneLabel): string {
+  return contact.phones
+    .filter((phone) => phone.label === label)
+    .map((phone) => phone.number)
+    .join(CSV_JOINER);
+}
+
+function csvRow(contact: ExportedContact): string {
+  return [
+    contact.name ?? '',
+    contact.emails.map((email) => email.address).join(CSV_JOINER),
+    phonesOf(contact, 'mobile'),
+    phonesOf(contact, 'work'),
+    phonesOf(contact, 'home'),
+    phonesOf(contact, 'other'),
+    contact.company ?? '',
+    contact.department ?? '',
+    contact.title ?? '',
+    contact.note ?? '',
+    contact.groupNames.join(CSV_JOINER),
+  ]
+    .map(csvCell)
+    .join(',');
+}
+
+/** CSV 파일 — BOM + 머리 줄 + 연락처마다 한 줄 (연락처가 없으면 머리 줄만) */
+export function contactsToCsv(contacts: readonly ExportedContact[]): string {
+  const rows = [CSV_HEADER.join(','), ...contacts.map(csvRow)];
+  return `${UTF8_BOM}${rows.map((row) => `${row}${CRLF}`).join('')}`;
+}
+
+/** 앞뒤의 공백 · 점을 뗀다 — 반복 정규식 없이 한 번 훑는다(길이에 비례) */
+function trimEdges(chars: readonly string[]): string[] {
+  let start = 0;
+  let end = chars.length;
+  while (start < end && FILE_NAME_EDGE.test(chars[start])) start += 1;
+  while (end > start && FILE_NAME_EDGE.test(chars[end - 1])) end -= 1;
+  return chars.slice(start, end);
+}
+
+/** 파일 이름의 그룹 이름 — 예약 글자는 '_', 앞뒤 공백 · 점은 떼고 50글자(코드 포인트)까지. 남는 것이 없으면 null */
+function groupNamePart(name: string): string | null {
+  const chars = trimEdges(Array.from(name.replace(FILE_NAME_RESERVED, '_')));
+  const cleaned = trimEdges(chars.slice(0, MAX_CONTACT_GROUP_NAME_LENGTH)).join(
+    '',
+  );
+  return cleaned === '' ? null : cleaned;
+}
+
+/**
+ * 내려받을 파일 이름 — `주소록-YYYY-MM-DD.vcf` · `주소록-<그룹 이름>-YYYY-MM-DD.csv` (날짜는 한국 날짜).
+ * 헤더 인코딩은 shared/utils/content-disposition.ts 가 한다
+ */
+export function contactExportFileName(
+  format: ContactExportFormat,
+  groupName: string | null,
+  at: Date,
+): string {
+  const group = groupName === null ? null : groupNamePart(groupName);
+  const parts = [
+    FILE_NAME_PREFIX,
+    ...(group ? [group] : []),
+    kstDateString(at),
+  ];
+  return `${parts.join('-')}${FILE_EXTENSIONS[format]}`;
+}
+
+/** 형식마다 Content-Type */
+export function contactExportContentType(format: ContactExportFormat): string {
+  return format === 'vcard' ? VCARD_CONTENT_TYPE : CSV_CONTENT_TYPE;
+}
+
+/** 형식마다 파일 내용 */
+export function contactExportContent(
+  format: ContactExportFormat,
+  contacts: readonly ExportedContact[],
+): string {
+  return format === 'vcard'
+    ? contactsToVcard(contacts)
+    : contactsToCsv(contacts);
+}

backend/src/modules/contacts/contact-exports.controller.ts

@@ -0,0 +1,90 @@
+import {
+  Controller,
+  Get,
+  HttpStatus,
+  Query,
+  Res,
+  StreamableFile,
+  UseGuards,
+} from '@nestjs/common';
+import {
+  ApiCookieAuth,
+  ApiOperation,
+  ApiProduces,
+  ApiResponse,
+  ApiTags,
+} from '@nestjs/swagger';
+import type { Response } from 'express';
+
+import {
+  ApiErrorResponse,
+  ApiSessionErrors,
+} from '@/common/decorators/api-standard-response.decorator';
+import {
+  CurrentUser,
+  type AuthenticatedUser,
+} from '@/common/decorators/current-user.decorator';
+import { SkipTransform } from '@/common/decorators/skip-transform.decorator';
+import { JwtAuthGuard } from '@/common/guards/jwt-auth.guard';
+import { buildAttachmentDisposition } from '@/shared/utils/content-disposition';
+import {
+  DOWNLOAD_CACHE_CONTROL,
+  DOWNLOAD_CSP,
+} from '@/shared/utils/download-headers';
+import { CSV_CONTENT_TYPE, VCARD_CONTENT_TYPE } from './contact-export';
+import { CONTACT_EXPORTS_ROUTE } from './contacts.constants';
+import { ContactsService } from './contacts.service';
+import { ContactExportQueryDto } from './dto/contact-export.dto';
+
+// 내 주소록 — 내보내기 (계약 3절 "내보내기", 16단계). 파일 응답이라 표준 래퍼 없이 내려준다 (실패는 표준 실패 JSON)
+@ApiTags('Contacts')
+@ApiCookieAuth()
+@UseGuards(JwtAuthGuard)
+@ApiSessionErrors('로그인 필요 (쿠키 없음·만료)')
+@ApiErrorResponse('MAIL_001', '메일 엔진 장애')
+@Controller(CONTACT_EXPORTS_ROUTE)
+export class ContactExportsController {
+  constructor(private readonly contacts: ContactsService) {}
+
+  @Get()
+  @SkipTransform()
+  @ApiOperation({
+    summary: '주소록 내보내기 — vCard 3.0 · CSV 파일 (표준 래퍼 없음)',
+    description:
+      '내 주소록 전체 또는 그룹 하나(groupId)를 이름 차례로. 사내 목록은 넣지 않는다. 우리 칸만(엔진 카드의 다른 칸 — 주소 · 생일 · 사진 등은 넣지 않는다). ' +
+      'vcard: vCard 3.0 · CRLF · 75바이트 줄 접기 · FN(이름 — 없으면 첫 이메일 → 첫 전화번호) · N(이름 전체를 성 칸에) · EMAIL(TYPE=INTERNET,WORK / INTERNET,HOME / INTERNET) · TEL(CELL / WORK / HOME / VOICE) · ' +
+      'ORG(회사;부서) · TITLE · NOTE · CATEGORIES(그룹 이름) · UID. ' +
+      'csv: UTF-8 BOM · CRLF · 머리 「이름,이메일,휴대폰,회사 전화,집 전화,기타 전화,회사,부서,직함,메모,그룹」 — 같은 칸에 여럿이면 "; " 로 잇고, ' +
+      "= + - @ · 탭 · CR 로 시작하는 칸은 앞에 ' 를 붙인다(엑셀 수식 막기 — OWASP CSV Injection). " +
+      '파일 이름 「주소록-YYYY-MM-DD.vcf」 · 「주소록-<그룹 이름>-YYYY-MM-DD.csv」(한국 날짜) — Content-Disposition: attachment. Cache-Control: private, no-store. ' +
+      '화면은 첨부 받기처럼 이동 직전에 세션을 확인하고 <a href download> 로 받는다.',
+  })
+  @ApiProduces(VCARD_CONTENT_TYPE, CSV_CONTENT_TYPE)
+  @ApiResponse({
+    status: HttpStatus.OK,
+    description: '내보낸 파일 (.vcf · .csv)',
+    schema: { type: 'string', format: 'binary' },
+  })
+  @ApiErrorResponse('VAL_001', '모르는 형식 · 그룹 id 모양 · 모르는 쿼리')
+  @ApiErrorResponse('RES_001', '없는 groupId')
+  async export(
+    @CurrentUser() user: AuthenticatedUser,
+    @Query() query: ContactExportQueryDto,
+    @Res({ passthrough: true }) res: Response,
+  ): Promise<StreamableFile> {
+    const file = await this.contacts.exportContacts(
+      user,
+      query.format,
+      query.groupId,
+    );
+    // 개인 정보 — 남기지 않는다. 브라우저가 열지 않고 내려받게(형식 짐작 막기 · 열어도 스크립트가 돌지 않게)
+    res.setHeader('Cache-Control', DOWNLOAD_CACHE_CONTROL);
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Content-Security-Policy', DOWNLOAD_CSP);
+    return new StreamableFile(file.content, {
+      type: file.contentType,
+      disposition: buildAttachmentDisposition(file.fileName),
+      length: file.content.length,
+    });
+  }
+}

backend/src/modules/contacts/contact-import.spec.ts

@@ -0,0 +1,171 @@
+import {
+  deletionChunkSize,
+  importDuplicateIndex,
+  isExistingContact,
+  namePhonesKey,
+  phoneDigitsKey,
+  planGroupJoins,
+  type GroupRoom,
+} from './contact-import';
+import type { ContactFields, ContactPhone } from './contacts.types';
+
+const mobile = (number: string): ContactPhone => ({ number, label: 'mobile' });
+
+const person = (overrides: Partial<ContactFields> = {}) => ({
+  name: null,
+  emails: [],
+  phones: [],
+  ...overrides,
+});
+
+describe('가져오기 — 이미 있는 연락처 (계약 3절 "가져오기")', () => {
+  it('전화 숫자 모음 — 숫자만 남기고 겹침 · 차례를 무시한다, 숫자가 없는 번호는 뺀다', () => {
+    expect(
+      phoneDigitsKey([
+        mobile('010-1234-5678'),
+        { number: '(02) 555-0100', label: 'work' },
+        mobile('01012345678'),
+        mobile('#*'),
+      ]),
+    ).toBe('01012345678,025550100');
+    expect(phoneDigitsKey([])).toBe('');
+  });
+
+  it('이름 + 전화 열쇠 — 이름은 앞뒤 공백만 뺀다(가운데 공백 · 대소문자는 그대로), 이름이 없으면 null', () => {
+    expect(namePhonesKey({ name: ' 김아라 ', phones: [] })).toBe(
+      namePhonesKey({ name: '김아라', phones: [] }),
+    );
+    expect(namePhonesKey({ name: '김 아라', phones: [] })).not.toBe(
+      namePhonesKey({ name: '김아라', phones: [] }),
+    );
+    expect(namePhonesKey({ name: 'Ara', phones: [] })).not.toBe(
+      namePhonesKey({ name: 'ara', phones: [] }),
+    );
+    expect(namePhonesKey({ name: null, phones: [mobile('010')] })).toBeNull();
+    expect(namePhonesKey({ name: '  ', phones: [] })).toBeNull();
+  });
+
+  it('이메일이 있는 항목 — 그 가운데 하나라도 주소록에 있으면(앞뒤 공백 · 대소문자 무시) 이미 있음', () => {
+    const index = importDuplicateIndex([
+      person({
+        name: '박지훈',
+        emails: [{ address: 'Jihoon@Hanbit.example', label: 'work' }],
+      }),
+    ]);
+    expect(
+      isExistingContact(
+        index,
+        person({
+          emails: [
+            { address: 'new@x.example', label: 'work' },
+            { address: ' jihoon@hanbit.EXAMPLE ', label: 'other' },
+          ],
+        }),
+      ),
+    ).toBe(true);
+    // 이메일이 있으면 이름 · 전화는 보지 않는다
+    expect(
+      isExistingContact(
+        index,
+        person({
+          name: '박지훈',
+          emails: [{ address: 'other@x.example', label: 'work' }],
+        }),
+      ),
+    ).toBe(false);
+  });
+
+  it('이메일이 없는 항목 — 이름과 전화 숫자 모음이 모두 같은 연락처가 있으면 이미 있음 (주소록 쪽은 이메일이 있어도 된다)', () => {
+    const index = importDuplicateIndex([
+      person({
+        name: '김철수',
+        emails: [{ address: 'kim@x.example', label: 'work' }],
+        phones: [
+          mobile('010-1111-2222'),
+          { number: '02 555 0100', label: 'work' },
+        ],
+      }),
+      person({ name: '이영희' }),
+    ]);
+    expect(
+      isExistingContact(
+        index,
+        person({
+          name: '김철수 ',
+          phones: [
+            { number: '0255501 00', label: 'other' },
+            mobile('01011112222'),
+          ],
+        }),
+      ),
+    ).toBe(true);
+    // 번호 하나만 같으면 다른 사람으로 본다
+    expect(
+      isExistingContact(
+        index,
+        person({ name: '김철수', phones: [mobile('010-1111-2222')] }),
+      ),
+    ).toBe(false);
+    // 둘 다 전화가 없으면 이름만 같아도
+    expect(isExistingContact(index, person({ name: '이영희' }))).toBe(true);
+    expect(isExistingContact(index, person({ name: '이영희2' }))).toBe(false);
+  });
+});
+
+describe('가져오기 — 그룹 넣기 계획', () => {
+  const room = (members: string[], count = members.length): GroupRoom => ({
+    memberUids: new Set(members),
+    memberCount: count,
+  });
+
+  it('보낸 차례대로 넣고, 한도에 닿은 그룹은 그 뒤 사람만 빼고(skipped) 나머지 그룹에는 넣는다', () => {
+    const rooms = new Map([
+      ['g1', room(['u-old'], 2)],
+      ['g2', room([])],
+    ]);
+    const plan = planGroupJoins(
+      rooms,
+      [
+        { uid: 'a', groupIds: ['g1', 'g2'] },
+        { uid: 'b', groupIds: ['g1', 'g2'] },
+        { uid: 'c', groupIds: ['g2'] },
+      ],
+      3,
+    );
+    expect(plan.adds.get('g1')).toEqual(['a']);
+    expect(plan.adds.get('g2')).toEqual(['a', 'b', 'c']);
+    expect(plan.skipped.get('b')).toEqual(['g1']);
+    expect(plan.skipped.has('a')).toBe(false);
+  });
+
+  it('이미 구성원인 uid 는 세지도 넣지도 않는다 · 모르는 그룹은 건너뛴다', () => {
+    const plan = planGroupJoins(
+      new Map([['g1', room(['a'], 3)]]),
+      [
+        { uid: 'a', groupIds: ['g1', 'nope'] },
+        { uid: 'b', groupIds: ['g1'] },
+      ],
+      3,
+    );
+    expect(plan.adds.get('g1')).toBeUndefined();
+    expect(plan.skipped.get('b')).toEqual(['g1']);
+    expect(plan.skipped.has('a')).toBe(false);
+  });
+});
+
+describe('한꺼번에 지우기 — 한 번 몫', () => {
+  it('지울 연락처 수 + 고칠 그룹 수(겹침 없이)가 상한을 넘지 않게 앞에서부터', () => {
+    expect(deletionChunkSize([[], [], []], 500)).toBe(3);
+    expect(deletionChunkSize([['g1'], ['g1'], ['g2']], 4)).toBe(2);
+    expect(deletionChunkSize([['g1'], ['g1'], ['g1']], 4)).toBe(3);
+    expect(
+      deletionChunkSize(
+        Array.from({ length: 500 }, () => ['g1']),
+        500,
+      ),
+    ).toBe(499);
+    // 첫 사람이 홀로 넘어도 한 명은 지운다
+    expect(deletionChunkSize([['a', 'b', 'c']], 2)).toBe(1);
+    expect(deletionChunkSize([], 500)).toBe(0);
+  });
+});

backend/src/modules/contacts/contact-import.ts

@@ -0,0 +1,138 @@
+import { emailKey } from './address-book';
+import type { ContactFields, ContactPhone } from './contacts.types';
+
+/**
+ * 가져오기 · 한꺼번에 지우기의 순수 함수 (계약 3절 "가져오기 · 내보내기" — 16단계).
+ *
+ * "이미 있는 연락처" 규칙 — 화면이 같은 파일 안의 겹침을 **같은 규칙**으로 본다(frontend shared/utils/contact-import — 한쪽을 고치면 둘 다):
+ * - 이메일이 있는 항목: 그 이메일 가운데 하나라도(앞뒤 공백을 빼고 소문자 — emailKey) 내 주소록의 어느 연락처에 있으면 이미 있음
+ * - 이메일이 없는 항목: 이름(앞뒤 공백을 뺀 글)이 같고 전화번호의 숫자 모음(숫자만 남긴 번호들 — 차례 · 겹침 무시)이 같은 연락처가 있으면 이미 있음
+ *   (주소록 쪽 연락처는 이메일이 있어도 된다. 둘 다 전화가 없으면 이름만 같아도 이미 있음)
+ */
+
+const NON_DIGITS = /\D+/g;
+/** 이름과 전화 숫자 모음을 잇는 글 — 이름 칸에 올 수 없는 제어 문자 */
+const KEY_SEPARATOR = '\u0000';
+
+/** 전화번호들의 숫자 모음 — 숫자만 남긴 번호를 겹침 없이 차례로 (숫자가 없는 번호는 뺀다) */
+export function phoneDigitsKey(phones: readonly ContactPhone[]): string {
+  const digits = new Set<string>();
+  for (const phone of phones) {
+    const only = phone.number.replace(NON_DIGITS, '');
+    if (only !== '') digits.add(only);
+  }
+  return [...digits].sort().join(',');
+}
+
+/** 이메일이 없는 항목을 견주는 열쇠 — 이름(앞뒤 공백을 뺀 글) + 전화 숫자 모음. 이름이 없으면 null */
+export function namePhonesKey(
+  fields: Pick<ContactFields, 'name' | 'phones'>,
+): string | null {
+  const name = fields.name?.trim() ?? '';
+  return name === ''
+    ? null
+    : `${name}${KEY_SEPARATOR}${phoneDigitsKey(fields.phones)}`;
+}
+
+/** 내 주소록의 "이미 있음" 찾기 자료 — 이메일 모음 · 이름 + 전화 열쇠 모음 */
+export interface ImportDuplicateIndex {
+  readonly emails: ReadonlySet<string>;
+  readonly namePhones: ReadonlySet<string>;
+}
+
+/** 주소록의 연락처들로 찾기 자료를 만든다 — 연락처 수에 비례 */
+export function importDuplicateIndex(
+  contacts: readonly Pick<ContactFields, 'name' | 'emails' | 'phones'>[],
+): ImportDuplicateIndex {
+  const emails = new Set<string>();
+  const namePhones = new Set<string>();
+  for (const contact of contacts) {
+    for (const email of contact.emails) emails.add(emailKey(email.address));
+    const key = namePhonesKey(contact);
+    if (key !== null) namePhones.add(key);
+  }
+  return { emails, namePhones };
+}
+
+/** 이 항목이 내 주소록에 이미 있는가 (위 규칙) */
+export function isExistingContact(
+  index: ImportDuplicateIndex,
+  item: Pick<ContactFields, 'name' | 'emails' | 'phones'>,
+): boolean {
+  if (item.emails.length > 0) {
+    return item.emails.some((email) =>
+      index.emails.has(emailKey(email.address)),
+    );
+  }
+  const key = namePhonesKey(item);
+  return key !== null && index.namePhones.has(key);
+}
+
+/** 그룹 하나의 지금 자리 — 구성원 uid(이 주소록에 없는 카드를 가리키는 것 포함)와 센 구성원 수(이 주소록에 있는 연락처만) */
+export interface GroupRoom {
+  readonly memberUids: ReadonlySet<string>;
+  readonly memberCount: number;
+}
+
+/** 그룹에 넣을 사람 하나 — uid 와 넣을 그룹 */
+export interface GroupJoin {
+  readonly uid: string;
+  readonly groupIds: readonly string[];
+}
+
+export interface GroupJoinPlan {
+  /** 그룹 id → 새로 넣을 uid (넣는 차례) */
+  readonly adds: ReadonlyMap<string, readonly string[]>;
+  /** uid → 구성원 수 한도가 차서 넣지 못한 그룹 id (보낸 차례) */
+  readonly skipped: ReadonlyMap<string, readonly string[]>;
+}
+
+/**
+ * 가져온 사람들을 그룹에 넣는 계획 — 보낸 차례대로 넣고, 그룹이 max 명에 닿으면 그 뒤 사람은 그 그룹만 빼고(skipped) 나머지 그룹에는 넣는다.
+ * 이미 구성원인 uid 는 세지도 넣지도 않는다. 모르는 그룹 id 는 부르는 쪽이 먼저 막는다(여기서는 건너뛴다)
+ */
+export function planGroupJoins(
+  rooms: ReadonlyMap<string, GroupRoom>,
+  joins: readonly GroupJoin[],
+  max: number,
+): GroupJoinPlan {
+  const counts = new Map<string, number>();
+  const adds = new Map<string, string[]>();
+  const skipped = new Map<string, string[]>();
+  for (const join of joins) {
+    for (const groupId of join.groupIds) {
+      const room = rooms.get(groupId);
+      if (!room) continue;
+      const added = adds.get(groupId) ?? [];
+      if (room.memberUids.has(join.uid) || added.includes(join.uid)) continue;
+      const count = counts.get(groupId) ?? room.memberCount;
+      if (count >= max) {
+        skipped.set(join.uid, [...(skipped.get(join.uid) ?? []), groupId]);
+        continue;
+      }
+      counts.set(groupId, count + 1);
+      added.push(join.uid);
+      adds.set(groupId, added);
+    }
+  }
+  return { adds, skipped };
+}
+
+/**
+ * 한꺼번에 지우기의 한 번 몫 — 앞에서부터 몇 명을 지울지. 지울 연락처 수 + 고칠 그룹 수(그 연락처가 든 그룹 — 겹침 없이)가 max 를 넘지 않게
+ * (엔진 한 요청의 카드 수 상한). 첫 사람이 홀로 넘어도 한 명은 지운다(그런 주소록은 없다 — 그룹 100개)
+ */
+export function deletionChunkSize(
+  groupsOf: readonly (readonly string[])[],
+  max: number,
+): number {
+  const groups = new Set<string>();
+  let size = 0;
+  for (const ids of groupsOf) {
+    const fresh = ids.filter((id) => !groups.has(id));
+    if (size > 0 && size + 1 + groups.size + fresh.length > max) break;
+    for (const id of fresh) groups.add(id);
+    size += 1;
+  }
+  return size;
+}

backend/src/modules/contacts/contact-imports.controller.ts

@@ -0,0 +1,149 @@
+import {
+  Body,
+  Controller,
+  HttpCode,
+  HttpStatus,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { ApiCookieAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+
+import {
+  ApiErrorResponse,
+  ApiSessionErrors,
+  ApiStandardResponse,
+} from '@/common/decorators/api-standard-response.decorator';
+import {
+  CurrentUser,
+  type AuthenticatedUser,
+} from '@/common/decorators/current-user.decorator';
+import { JwtAuthGuard } from '@/common/guards/jwt-auth.guard';
+import {
+  CONTACT_DELETIONS_ROUTE,
+  CONTACT_IMPORT_CHECKS_ROUTE,
+  CONTACT_IMPORTS_ROUTE,
+  MAX_CONTACT_DELETIONS,
+  MAX_CONTACT_GROUP_MEMBERS,
+  MAX_CONTACT_IMPORT_BATCH,
+  MAX_CONTACTS,
+} from './contacts.constants';
+import { ContactsService } from './contacts.service';
+import {
+  ContactDeletionDto,
+  ContactImportBatchDto,
+  ContactImportCheckDto,
+  ContactImportResultDto,
+  ContactsDeletedDto,
+} from './dto/contact-import.dto';
+
+const ITEM_RULES =
+  `한 사람의 칸 규칙은 연락처 추가(POST /api/contacts)와 같고 uid(urn:uuid: + 소문자 UUID — 화면이 만든다)를 더한다. ` +
+  `${MAX_CONTACT_IMPORT_BATCH}명까지 · 한 묶음 안의 같은 uid · 이름도 이메일도 없는 사람 · 같은 연락처 안의 같은 주소는 400 VAL_001(하나라도 걸리면 묶음 전체).`;
+
+// 내 주소록 — 가져오기 확인 (계약 3절 "가져오기", 16단계). 파일은 화면이 읽는다 — 서버는 연락처 칸만 받는다
+@ApiTags('Contacts')
+@ApiCookieAuth()
+@UseGuards(JwtAuthGuard)
+@ApiSessionErrors('로그인 필요 (쿠키 없음·만료)')
+@ApiErrorResponse('MAIL_001', '메일 엔진 장애')
+@Controller(CONTACT_IMPORT_CHECKS_ROUTE)
+export class ContactImportChecksController {
+  constructor(private readonly contacts: ContactsService) {}
+
+  @Post()
+  @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: '가져올 연락처가 이미 있는지 확인 (만들지 않는다)',
+    description:
+      '사람마다 new · exists — 같은 이메일(앞뒤 공백 · 대소문자 무시)이 내 주소록에 있으면, 이메일이 없으면 이름(앞뒤 공백을 뺀 글)과 전화번호의 숫자 모음이 모두 같은 연락처가 있으면, ' +
+      `또는 같은 uid 의 연락처가 있으면 exists. remaining 은 더 넣을 수 있는 수(${MAX_CONTACTS.toLocaleString('en-US')} − 지금 연락처 수). ` +
+      `같은 파일 안의 겹침은 화면이 같은 규칙으로 본다. groupIds 는 보지 않는다. ${ITEM_RULES}`,
+  })
+  @ApiStandardResponse(ContactImportCheckDto, {
+    description: '사람마다 판정과 남은 자리',
+  })
+  @ApiErrorResponse(
+    'VAL_001',
+    '형식 · 길이 · 개수 · uid 모양 · 같은 uid 두 번 · 이름도 이메일도 없음 · 같은 주소 두 번 · 모르는 필드',
+  )
+  check(
+    @CurrentUser() user: AuthenticatedUser,
+    @Body() dto: ContactImportBatchDto,
+  ) {
+    return this.contacts.checkImport(user, dto.contacts);
+  }
+}
+
+// 내 주소록 — 가져오기 넣기 (계약 3절 "가져오기", 16단계). 엔진 요청 하나에 묶음을 만든다
+@ApiTags('Contacts')
+@ApiCookieAuth()
+@UseGuards(JwtAuthGuard)
+@ApiSessionErrors('로그인 필요 (쿠키 없음·만료)')
+@ApiErrorResponse('MAIL_001', '메일 엔진 장애')
+@Controller(CONTACT_IMPORTS_ROUTE)
+export class ContactImportsController {
+  constructor(private readonly contacts: ContactsService) {}
+
+  @Post()
+  @ApiOperation({
+    summary: '가져온 연락처 넣기 (100명씩)',
+    description:
+      '줄마다 보낸 uid 로 만든다 — 같은 uid 의 연락처가 이미 있으면(다시 보낸 묶음) 새로 만들지 않고 그 id 를 돌려준다(빠진 그룹만 마저 넣는다). ' +
+      `연락처 ${MAX_CONTACTS.toLocaleString('en-US')}개 · 크기 한도는 묶음 전체로 미리 본다 — 넘으면 409 CONTACT_002, 아무것도 만들지 않는다. ` +
+      `그룹 구성원 ${MAX_CONTACT_GROUP_MEMBERS}명을 넘기는 넣기는 그 그룹만 빼고 만들고 skippedGroupIds 에 적는다(실패가 아니다). ` +
+      '메일 서버가 일부만 받으면 받은 것만 items 에 — 빠진 uid 는 넣지 못한 것이다. 겹침(같은 이메일 등)은 보지 않는다(확인 경로의 몫). ' +
+      ITEM_RULES,
+  })
+  @ApiStandardResponse(ContactImportResultDto, {
+    status: 201,
+    description: '넣은 연락처(같은 uid 로 이미 있던 것 포함)',
+  })
+  @ApiErrorResponse(
+    'VAL_001',
+    '형식 · 길이 · 개수 · uid 모양 · 같은 uid 두 번 · 이름도 이메일도 없음 · 같은 주소 두 번 · 모르는 필드',
+  )
+  @ApiErrorResponse('RES_001', '없는 groupId')
+  @ApiErrorResponse(
+    'CONTACT_002',
+    `연락처 ${MAX_CONTACTS.toLocaleString('en-US')}개 · 크기 한도 — 묶음 전체로 보고 아무것도 만들지 않았다`,
+  )
+  importContacts(
+    @CurrentUser() user: AuthenticatedUser,
+    @Body() dto: ContactImportBatchDto,
+  ) {
+    return this.contacts.importContacts(user, dto.contacts);
+  }
+}
+
+// 내 주소록 — 연락처 한꺼번에 지우기 (가져오기 [되돌리기] — 계약 3절 "가져오기", 16단계)
+@ApiTags('Contacts')
+@ApiCookieAuth()
+@UseGuards(JwtAuthGuard)
+@ApiSessionErrors('로그인 필요 (쿠키 없음·만료)')
+@ApiErrorResponse('MAIL_001', '메일 엔진 장애')
+@Controller(CONTACT_DELETIONS_ROUTE)
+export class ContactDeletionsController {
+  constructor(private readonly contacts: ContactsService) {}
+
+  @Post()
+  @HttpCode(HttpStatus.OK)
+  @ApiOperation({
+    summary: '연락처 한꺼번에 지우기 (영구 삭제 · 되돌리기 표 없음)',
+    description:
+      `1~${MAX_CONTACT_DELETIONS}개. 지운 연락처를 가리키는 그룹 구성원도 함께 뺀다. 내 주소록에 없는 id(이미 지움 · 그룹 id)는 notFoundIds — 실패가 아니다. ` +
+      '메일 서버 한 요청의 상한을 넘으면 서버가 나눠 지운다 — 중간에 실패하면(503) 앞 몫은 지워진 채다(같은 목록을 다시 보내면 notFoundIds 로 나온다).',
+  })
+  @ApiStandardResponse(ContactsDeletedDto, {
+    description: '지운 id · 없던 id (보낸 차례)',
+  })
+  @ApiErrorResponse(
+    'VAL_001',
+    '형식 · 개수 · id 모양 · 같은 id 두 번 · 모르는 필드',
+  )
+  remove(
+    @CurrentUser() user: AuthenticatedUser,
+    @Body() dto: ContactDeletionDto,
+  ) {
+    return this.contacts.removeContacts(user, dto.ids);
+  }
+}

backend/src/modules/contacts/contacts.constants.ts

@@ -14,6 +14,28 @@ export const CONTACT_GROUPS_ROUTE = 'contact-groups';
 export const CONTACT_RESTORATIONS_ROUTE = 'contact-restorations';
 export const DIRECTORY_ENTRIES_ROUTE = 'directory-entries';
 
+/**
+ * 16단계 라우트 — 가져오기의 확인 · 넣기, 한꺼번에 지우기(가져오기 [되돌리기]), 내보내기 (계약 3절 "가져오기 · 내보내기")
+ * (`/api/contact-import-checks` · `/api/contact-imports` · `/api/contact-deletions` · `/api/contact-exports`)
+ */
+export const CONTACT_IMPORT_CHECKS_ROUTE = 'contact-import-checks';
+export const CONTACT_IMPORTS_ROUTE = 'contact-imports';
+export const CONTACT_DELETIONS_ROUTE = 'contact-deletions';
+export const CONTACT_EXPORTS_ROUTE = 'contact-exports';
+
+/** 가져오기 · 확인 한 요청의 연락처 수 — 1~100 (화면은 100명씩 차례로 보낸다) */
+export const MAX_CONTACT_IMPORT_BATCH = 100;
+/** 한꺼번에 지우기 한 요청의 id 수 — 1~500 */
+export const MAX_CONTACT_DELETIONS = 500;
+/**
+ * 엔진 한 번의 바꾸기(ContactCard/set)에 담는 카드 수 — 만들기 · 고치기 · 지우기를 모두 센다.
+ * 엔진의 maxObjectsInSet(500 — 2026-11-10 세션 능력 확인)과 같다. 한꺼번에 지우기는 그룹 고치기와 합쳐 이것을 넘으면 나눠 쓴다
+ */
+export const MAX_CARD_CHANGES_PER_WRITE = 500;
+/** 가져오기 항목의 uid — `urn:uuid:` + 소문자 UUID (화면이 만든다 — 다시 보낸 요청이 두 번 들어가지 않게) */
+export const CONTACT_IMPORT_UID_PATTERN =
+  /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
 /**
  * 주소록 한도 — 넘으면 409 CONTACT_002 (아무것도 바꾸지 않는다).
  * ⚠️ CONTACT_002 의 문구(common/errors/error-codes.ts)에 같은 숫자가 있다 — contacts.constants.spec.ts 가 맞는지 본다

backend/src/modules/contacts/contacts.module.ts

@@ -3,7 +3,13 @@ import { Module } from '@nestjs/common';
 import { JmapContactsProvider } from '@/modules/mail/jmap/jmap-contacts.provider';
 import { JmapDirectoryProvider } from '@/modules/mail/jmap/jmap-directory.provider';
 import { MailEngineModule } from '@/modules/mail/mail-engine.module';
+import { ContactExportsController } from './contact-exports.controller';
 import { ContactGroupsController } from './contact-groups.controller';
+import {
+  ContactDeletionsController,
+  ContactImportChecksController,
+  ContactImportsController,
+} from './contact-imports.controller';
 import { ContactRestorationsController } from './contact-restorations.controller';
 import { ContactsController } from './contacts.controller';
 import { CONTACTS_PROVIDER, DIRECTORY_PROVIDER } from './contacts.provider';
@@ -25,6 +31,11 @@ import { DirectoryService } from './directory.service';
     ContactGroupsController,
     ContactRestorationsController,
     DirectoryEntriesController,
+    // 16단계 — 가져오기 확인 · 넣기 · 한꺼번에 지우기 · 내보내기
+    ContactImportChecksController,
+    ContactImportsController,
+    ContactDeletionsController,
+    ContactExportsController,
   ],
   providers: [
     { provide: CONTACTS_PROVIDER, useClass: JmapContactsProvider },

backend/src/modules/contacts/contacts.provider.ts

@@ -103,16 +103,30 @@ export type AddressBookCardUpdate =
       readonly memberUids?: readonly string[];
     };
 
-/** 한 번에 하는 바꾸기 — 엔진 요청 하나 (만들기 → 고치기 → 지우기 차례로 한다) */
+/**
+ * 한 번에 하는 바꾸기 — 엔진 요청 하나 (만들기 → 고치기 → 지우기 차례로 한다).
+ * 카드 수(만들기 + 고치기 + 지우기)는 서비스가 MAX_CARD_CHANGES_PER_WRITE(엔진의 한 요청 상한) 안으로 맞춘다
+ */
 export interface AddressBookChanges {
   readonly create: readonly NewAddressBookCard[];
   readonly update: readonly AddressBookCardUpdate[];
   readonly destroy: readonly string[];
 }
 
+/** 바꾸기의 선택 (16단계 — 가져오기 · 한꺼번에 지우기) */
+export interface AddressBookWriteOptions {
+  /**
+   * 엔진이 받지 않은 **만들기**를 던지지 않고 결과(written 의 refusedKeys)에 적는다 — 가져오기.
+   * 받은 만들기 · 고치기는 들어간다. 고치기 · 지우기의 거절과 동시 고치기 거절(busy)은 이 선택과 상관없이 지금처럼 다룬다
+   */
+  readonly allowPartialCreate?: boolean;
+  /** 지울 카드의 원본(되돌리기 표)을 읽지 않는다 — 한꺼번에 지우기. 그 판에 카드가 있는지는 그대로 본다(없으면 conflict) */
+  readonly withoutOriginals?: boolean;
+}
+
 /**
  * 바꾸기의 결과
- * - written: 모두 했다 — 새 판(엔진이 알려 주지 않으면 null) · 만든 카드의 id(key → id, 만든 것은 모두 있다) ·
+ * - written: 모두 했다 — 새 판(엔진이 알려 주지 않으면 null) · 만든 카드의 id(key → id, 만든 것은 모두 있다 — allowPartialCreate 면 refusedKeys 를 뺀 것) ·
  *   만들거나 고친 연락처 · 만든 그룹의 지금 모양(id → 카드 — 엔진에 보낸 카드를 읽은 것, 그룹 고치기는 넣지 않는다) · 지운 카드의 원본(id → 원본)
  * - conflict: 받은 판과 엔진의 지금 판이 달라 아무것도 하지 않았다 (그사이 다른 곳에서 바뀌었다 — 다시 읽고 다시 한다)
  * - busy: 엔진이 같은 카드의 동시 고치기를 거절했다(serverUnavailable) — 일부가 들어갔을 수 있다. 다시 읽고 다시 한다
@@ -125,6 +139,8 @@ export type AddressBookWriteOutcome =
       readonly createdIds: ReadonlyMap<string, string>;
       readonly cards: ReadonlyMap<string, AddressBookCard>;
       readonly removed: ReadonlyMap<string, RemovedCardOriginal>;
+      /** 엔진이 받지 않은 만들기의 key — allowPartialCreate 로 쓸 때만 있다(없으면 모두 받았다) */
+      readonly refusedKeys?: ReadonlySet<string>;
     }
   | { readonly kind: 'conflict' }
   | {
@@ -143,12 +159,13 @@ export interface ContactsProvider {
    * 바꾸기를 한 번에 — 받은 판(version)이 엔진의 지금 판과 같을 때만 한다(아니면 conflict, 아무것도 하지 않음).
    * 고칠 연락처 · 지울 카드는 그 판 그대로 먼저 읽는다(칸 안의 남의 정보를 지키고 · 되돌리기 원본을 남기려고 — 그사이 바뀌었으면 conflict).
    * 엔진이 동시 고치기를 거절하면 busy. 엔진이 일부를 받지 않으면 그 코드로 던진다(엔진 오류 종류에 따라 VAL_001 · MAIL_001 등 —
-   * 받은 것은 이미 바뀌었을 수 있다). 주소록이 없는데 만들 카드가 있으면 MAIL_001
+   * 받은 것은 이미 바뀌었을 수 있다 — options.allowPartialCreate 면 받지 않은 만들기만은 던지지 않고 결과에 적는다). 주소록이 없는데 만들 카드가 있으면 MAIL_001
    */
   writeAddressBook(
     user: string,
     version: string,
     changes: AddressBookChanges,
+    options?: AddressBookWriteOptions,
   ): Promise<AddressBookWriteOutcome>;
 }
 

backend/src/modules/contacts/contacts.service.spec.ts

@@ -2,11 +2,14 @@ import { Logger } from '@nestjs/common';
 
 import type { AuthenticatedUser } from '@/common/decorators/current-user.decorator';
 import { BusinessException } from '@/common/errors/business.exception';
+import { kstDateString } from '@/shared/utils/kst-date';
 import { cardWeight } from './address-book';
 import {
   CONTACT_RESTORE_MAX_CARD_BYTES,
   CONTACT_RESTORE_TTL_MS,
   MAX_ADDRESS_BOOK_WEIGHT,
+  MAX_CARD_CHANGES_PER_WRITE,
+  MAX_CONTACT_DELETIONS,
   MAX_CONTACT_GROUP_MEMBERS,
   MAX_CONTACT_GROUPS,
   MAX_CONTACTS,
@@ -17,6 +20,7 @@ import type {
   AddressBookContactCard,
   AddressBookGroupCard,
   AddressBookSnapshot,
+  AddressBookWriteOptions,
   AddressBookWriteOutcome,
   ContactsProvider,
   RemovedCardOriginal,
@@ -24,6 +28,7 @@ import type {
 import { ContactsService } from './contacts.service';
 import type {
   ContactFields,
+  ContactImportItem,
   ContactInput,
   DirectoryEntry,
 } from './contacts.types';
@@ -61,6 +66,10 @@ class FakeAddressBook implements ContactsProvider {
   failure: BusinessException | null = null;
   /** 다음 쓰기들이 busy — lost 는 아무것도 들어가지 않음, applied 는 들어간 뒤 busy (서비스는 결과를 모른다) */
   readonly busy: ('lost' | 'applied')[] = [];
+  /** 엔진이 만들기를 받지 않을 uid (16단계 — 가져오기의 일부만 받기) */
+  readonly refuseUids = new Set<string>();
+  /** 쓰기마다 받은 선택 */
+  readonly writeOptions: (AddressBookWriteOptions | undefined)[] = [];
   private nextId = 1;
 
   readonly getAddressBookVersion = jest.fn(() =>
@@ -77,7 +86,9 @@ class FakeAddressBook implements ContactsProvider {
       _user: string,
       version: string,
       changes: AddressBookChanges,
+      options?: AddressBookWriteOptions,
     ): Promise<AddressBookWriteOutcome> => {
+      this.writeOptions.push(options);
       if (this.outsideChanges > 0) {
         this.outsideChanges -= 1;
         this.state += 1;
@@ -91,14 +102,30 @@ class FakeAddressBook implements ContactsProvider {
         this.state += 1;
         return Promise.reject(failure);
       }
+      const refusedKeys = new Set(
+        changes.create
+          .filter((card) => this.refuseUids.has(card.uid))
+          .map((card) => card.key),
+      );
+      if (refusedKeys.size > 0 && !options?.allowPartialCreate) {
+        // 엔진이 받지 않은 만들기 — 일부만 받기가 아니면 그 코드로 던진다(받은 것은 들어갔다)
+        this.apply(changes, refusedKeys);
+        return Promise.reject(
+          new BusinessException('VAL_001', {
+            context: { reason: 'address-book-change-refused' },
+          }),
+        );
+      }
       const removed = new Map<string, RemovedCardOriginal>();
-      for (const id of changes.destroy) {
-        const card = this.contacts.get(id) ?? this.groups.get(id);
-        if (card) removed.set(id, this.original(card));
+      if (!options?.withoutOriginals) {
+        for (const id of changes.destroy) {
+          const card = this.contacts.get(id) ?? this.groups.get(id);
+          if (card) removed.set(id, this.original(card));
+        }
       }
       const mode = this.busy.shift();
       if (mode === 'lost') return Promise.resolve({ kind: 'busy', removed });
-      const { createdIds, cards } = this.apply(changes);
+      const { createdIds, cards } = this.apply(changes, refusedKeys);
       if (mode === 'applied') {
         return Promise.resolve({ kind: 'busy', removed });
       }
@@ -108,6 +135,7 @@ class FakeAddressBook implements ContactsProvider {
         createdIds,
         cards,
         removed,
+        ...(options?.allowPartialCreate ? { refusedKeys } : {}),
       });
     },
   );
@@ -165,7 +193,10 @@ class FakeAddressBook implements ContactsProvider {
     return { source, bytes: Buffer.byteLength(source, 'utf8') };
   }
 
-  private apply(changes: AddressBookChanges): {
+  private apply(
+    changes: AddressBookChanges,
+    refusedKeys: ReadonlySet<string> = new Set(),
+  ): {
     createdIds: Map<string, string>;
     cards: Map<string, AddressBookCard>;
   } {
@@ -173,6 +204,7 @@ class FakeAddressBook implements ContactsProvider {
     const createdIds = new Map<string, string>();
     const cards = new Map<string, AddressBookCard>();
     for (const card of changes.create) {
+      if (refusedKeys.has(card.key)) continue;
       const id = `n${this.nextId++}`;
       createdIds.set(card.key, id);
       if (card.kind === 'contact') {
@@ -1364,4 +1396,413 @@ describe('ContactsService (주소록)', () => {
       expect(book.contacts.size).toBe(2);
     });
   });
+
+  describe('16단계 — 가져오기 · 한꺼번에 지우기 · 내보내기 (계약 3절 "가져오기 · 내보내기")', () => {
+    const uidOf = (n: number) =>
+      `urn:uuid:00000000-0000-4000-8000-${n.toString(16).padStart(12, '0')}`;
+    const item = (
+      n: number,
+      overrides: Partial<ContactImportItem> = {},
+    ): ContactImportItem => ({
+      ...emptyFields,
+      name: `사람${n}`,
+      emails: [{ address: `p${n}@import.example`, label: 'work' }],
+      groupIds: [],
+      uid: uidOf(n),
+      ...overrides,
+    });
+    const logged = () =>
+      logSpy.mock.calls.map(([message]) => String(message)).join('\n');
+
+    describe('가져오기 확인 (checkImport)', () => {
+      it('같은 이메일(대소문자 무시) · 이름 + 전화 숫자 · 같은 uid 는 exists, 나머지는 new — remaining 은 3,000 − 지금 수, 쓰지 않는다', async () => {
+        book.seedContact('c1', {
+          name: '박지훈',
+          emails: [{ address: 'Jihoon@Hanbit.example', label: 'work' }],
+        });
+        book.seedContact('c2', {
+          name: '김철수',
+          phones: [{ number: '010-1111-2222', label: 'mobile' }],
+        });
+
+        const result = await service.checkImport(ARA, [
+          item(1, {
+            emails: [{ address: ' jihoon@hanbit.EXAMPLE', label: 'personal' }],
+          }),
+          item(2, {
+            name: '김철수',
+            emails: [],
+            phones: [{ number: '01011112222', label: 'other' }],
+          }),
+          item(3, { uid: 'urn:uuid:c1' }),
+          item(4),
+          item(5, { name: '김철수', emails: [], phones: [] }),
+        ]);
+
+        expect(result).toEqual({
+          items: [
+            { uid: uidOf(1), status: 'exists' },
+            { uid: uidOf(2), status: 'exists' },
+            { uid: 'urn:uuid:c1', status: 'exists' },
+            { uid: uidOf(4), status: 'new' },
+            { uid: uidOf(5), status: 'new' },
+          ],
+          remaining: MAX_CONTACTS - 2,
+        });
+        expect(book.writeAddressBook).not.toHaveBeenCalled();
+      });
+
+      it('remaining 은 0 아래로 내려가지 않는다 (다른 프로그램이 3,000명 넘게 넣은 주소록)', async () => {
+        for (let index = 0; index < MAX_CONTACTS + 2; index += 1) {
+          book.seedContact(`s${index}`);
+        }
+        await expect(
+          service.checkImport(ARA, [item(1)]),
+        ).resolves.toMatchObject({ remaining: 0 });
+      });
+
+      it('묶음 검사 — 0명 · 101명 · 같은 uid · 이름도 이메일도 없음 · 같은 주소 두 번은 엔진에 묻기 전에 VAL_001', async () => {
+        const batches: ContactImportItem[][] = [
+          [],
+          Array.from({ length: 101 }, (_, n) => item(n)),
+          [item(1), item(2, { uid: uidOf(1) })],
+          [item(1, { name: null, emails: [] })],
+          [
+            item(1, {
+              emails: [
+                { address: 'a@x.example', label: 'work' },
+                { address: 'A@X.example', label: 'other' },
+              ],
+            }),
+          ],
+        ];
+        for (const batch of batches) {
+          expect((await failureOf(service.checkImport(ARA, batch))).code).toBe(
+            'VAL_001',
+          );
+          expect(
+            (await failureOf(service.importContacts(ARA, batch))).code,
+          ).toBe('VAL_001');
+        }
+        expect(book.getAddressBookVersion).not.toHaveBeenCalled();
+        expect(book.writeAddressBook).not.toHaveBeenCalled();
+      });
+    });
+
+    describe('가져오기 넣기 (importContacts)', () => {
+      it('보낸 uid 로 엔진 요청 하나에 만들고 고른 그룹에 넣는다 — 응답은 보낸 차례, 다시 읽지 않고 바로 목록에 보인다', async () => {
+        book.seedGroup('g1', '거래처');
+        book.seedGroup('g2', '협력사');
+
+        const result = await service.importContacts(ARA, [
+          item(2, { groupIds: ['g1', 'g2'] }),
+          item(1, { groupIds: ['g1'] }),
+        ]);
+
+        expect(book.writeAddressBook).toHaveBeenCalledTimes(1);
+        expect(book.writeOptions).toEqual([{ allowPartialCreate: true }]);
+        const [write] = book.writes;
+        expect(write.create.map((card) => card.uid)).toEqual([
+          uidOf(2),
+          uidOf(1),
+        ]);
+        expect(result.items).toEqual([
+          {
+            uid: uidOf(2),
+            id: expect.any(String) as unknown,
+            skippedGroupIds: [],
+          },
+          {
+            uid: uidOf(1),
+            id: expect.any(String) as unknown,
+            skippedGroupIds: [],
+          },
+        ]);
+        expect(book.groups.get('g1')?.memberUids).toEqual([uidOf(2), uidOf(1)]);
+        expect(book.groups.get('g2')?.memberUids).toEqual([uidOf(2)]);
+
+        const reads = book.reads;
+        const page = await service.list(ARA, listQuery());
+        expect(page.items.map((contact) => contact.name)).toEqual([
+          '사람1',
+          '사람2',
+        ]);
+        expect(page.items[1].groupIds).toEqual(['g1', 'g2']);
+        expect(book.reads).toBe(reads);
+      });
+
+      it('같은 묶음을 다시 보내면(응답을 잃음) 만들지 않고 같은 id 를 준다 — 빠진 그룹만 마저 넣는다', async () => {
+        book.seedGroup('g1', '거래처');
+        const first = await service.importContacts(ARA, [item(1), item(2)]);
+        const writes = book.writes.length;
+
+        const again = await service.importContacts(ARA, [
+          item(1),
+          item(2, { groupIds: ['g1'] }),
+        ]);
+
+        expect(again.items.map((entry) => entry.id)).toEqual(
+          first.items.map((entry) => entry.id),
+        );
+        expect(book.contacts.size).toBe(2);
+        // 다시 보낸 쓰기에는 만들기가 없고 그룹 넣기만 있다
+        expect(book.writes).toHaveLength(writes + 1);
+        expect(book.writes.at(-1)?.create).toEqual([]);
+        expect(book.groups.get('g1')?.memberUids).toEqual([uidOf(2)]);
+      });
+
+      it(`구성원 ${MAX_CONTACT_GROUP_MEMBERS}명이 찬 그룹은 그 그룹만 빼고(skippedGroupIds) 만들고 다른 그룹에는 넣는다`, async () => {
+        const members: string[] = [];
+        for (let index = 0; index < MAX_CONTACT_GROUP_MEMBERS - 1; index += 1) {
+          members.push(book.seedContact(`m${index}`).uid ?? '');
+        }
+        book.seedGroup('g1', '거의 참', members);
+        book.seedGroup('g2', '여유');
+
+        const result = await service.importContacts(ARA, [
+          item(1, { groupIds: ['g1', 'g2'] }),
+          item(2, { groupIds: ['g1', 'g2'] }),
+        ]);
+
+        expect(result.items.map((entry) => entry.skippedGroupIds)).toEqual([
+          [],
+          ['g1'],
+        ]);
+        expect(book.groups.get('g1')?.memberUids).toHaveLength(
+          MAX_CONTACT_GROUP_MEMBERS,
+        );
+        expect(book.groups.get('g2')?.memberUids).toEqual([uidOf(1), uidOf(2)]);
+        expect(logged()).toContain('구성원 한도로 그룹에 넣지 못함 1건');
+      });
+
+      it(`연락처가 ${MAX_CONTACTS}명을 넘게 되면 묶음 전체를 CONTACT_002 — 아무것도 만들지 않는다 · 없는 그룹은 RES_001`, async () => {
+        for (let index = 0; index < MAX_CONTACTS - 1; index += 1) {
+          book.seedContact(`s${index}`);
+        }
+        const failure = await failureOf(
+          service.importContacts(ARA, [item(1), item(2)]),
+        );
+        expect(failure.code).toBe('CONTACT_002');
+        expect(failure.context?.reason).toBe('contacts-limit');
+        expect(
+          (
+            await failureOf(
+              service.importContacts(ARA, [item(1, { groupIds: ['nope'] })]),
+            )
+          ).code,
+        ).toBe('RES_001');
+        expect(book.writeAddressBook).not.toHaveBeenCalled();
+
+        // 한 명은 들어간다
+        await expect(
+          service.importContacts(ARA, [item(1)]),
+        ).resolves.toMatchObject({ items: [{ uid: uidOf(1) }] });
+      });
+
+      it(`크기 ${MAX_ADDRESS_BOOK_WEIGHT.toLocaleString('en-US')} 를 넘게 하는 묶음은 CONTACT_002 — 아무것도 만들지 않는다`, async () => {
+        // 792만 남짓 — 한 명은 들어가고 100명 묶음(사람마다 1,100 남짓)은 넘는다
+        const note = 'x'.repeat(990_000);
+        for (let index = 0; index < 8; index += 1) {
+          book.seedContact(`big${index}`, { note });
+        }
+        const failure = await failureOf(
+          service.importContacts(
+            ARA,
+            Array.from({ length: 100 }, (_, n) =>
+              item(n, { note: 'y'.repeat(1_000) }),
+            ),
+          ),
+        );
+        expect(failure.code).toBe('CONTACT_002');
+        expect(failure.context?.reason).toBe('address-book-too-large');
+        expect(book.writeAddressBook).not.toHaveBeenCalled();
+      });
+
+      it('엔진이 일부만 받으면 받은 것만 돌려준다 — 던지지 않고, 기억한 주소록도 엔진과 같다(다시 읽지 않는다)', async () => {
+        book.refuseUids.add(uidOf(2));
+
+        const result = await service.importContacts(ARA, [
+          item(1),
+          item(2),
+          item(3),
+        ]);
+
+        expect(result.items.map((entry) => entry.uid)).toEqual([
+          uidOf(1),
+          uidOf(3),
+        ]);
+        expect(book.contacts.size).toBe(2);
+        const reads = book.reads;
+        const page = await service.list(ARA, listQuery());
+        expect(page.items.map((contact) => contact.name)).toEqual([
+          '사람1',
+          '사람3',
+        ]);
+        expect(book.reads).toBe(reads);
+        expect(logged()).toContain('넣지 못함 1명');
+      });
+
+      it('엔진이 바쁘다고 했지만 들어갔으면(applied) 다음 시도가 같은 uid 로 찾아 두 번 만들지 않는다', async () => {
+        book.busy.push('applied');
+        const result = await service.importContacts(ARA, [item(1), item(2)]);
+        expect(result.items.map((entry) => entry.uid)).toEqual([
+          uidOf(1),
+          uidOf(2),
+        ]);
+        expect(book.contacts.size).toBe(2);
+        expect(book.writeAddressBook).toHaveBeenCalledTimes(1);
+      });
+
+      it('그룹 카드가 쓰는 uid 는 만들지 않는다(엔진이 받지 않는다) — 응답에서 빠진다', async () => {
+        book.seedGroup('g1', '거래처');
+        const result = await service.importContacts(ARA, [
+          item(1, { uid: 'urn:uuid:g1' }),
+          item(2),
+        ]);
+        expect(result.items.map((entry) => entry.uid)).toEqual([uidOf(2)]);
+        expect(book.contacts.size).toBe(1);
+      });
+
+      it('로그에는 개수만 — 이름 · 주소 · uid 는 남기지 않는다', async () => {
+        await service.importContacts(ARA, [item(1, { note: '비밀 메모' })]);
+        expect(logged()).toContain('연락처를 가져왔습니다');
+        expect(logged()).not.toMatch(
+          /사람1|import\.example|비밀 메모|urn:uuid|ara\.kim@/i,
+        );
+      });
+    });
+
+    describe('한꺼번에 지우기 (removeContacts)', () => {
+      it('지우고 그룹 구성원에서도 뺀다 — 없는 id · 그룹 id 는 notFoundIds(보낸 차례), 되돌리기 원본은 읽지 않는다', async () => {
+        book.seedContact('c1');
+        book.seedContact('c2');
+        book.seedContact('c3');
+        book.seedGroup('g1', '거래처', ['urn:uuid:c1', 'urn:uuid:c3']);
+
+        const result = await service.removeContacts(ARA, [
+          'c3',
+          'gone',
+          'c1',
+          'g1',
+        ]);
+
+        expect(result).toEqual({
+          deletedIds: ['c3', 'c1'],
+          notFoundIds: ['gone', 'g1'],
+        });
+        expect(book.writeOptions).toEqual([{ withoutOriginals: true }]);
+        expect([...book.contacts.keys()]).toEqual(['c2']);
+        expect(book.groups.get('g1')?.memberUids).toEqual([]);
+        expect(logged()).toContain('연락처를 한꺼번에 지웠습니다: 2명');
+      });
+
+      it(`지울 연락처 + 고칠 그룹이 엔진 한 요청의 상한(${MAX_CARD_CHANGES_PER_WRITE})을 넘으면 앞에서부터 나눠 쓴다`, async () => {
+        const ids: string[] = [];
+        const uids: string[] = [];
+        for (let index = 0; index < MAX_CONTACT_DELETIONS; index += 1) {
+          const card = book.seedContact(`d${index}`);
+          ids.push(card.id);
+          uids.push(card.uid ?? '');
+        }
+        book.seedGroup('g1', '모두', uids);
+
+        const result = await service.removeContacts(ARA, ids);
+
+        expect(result.deletedIds).toHaveLength(MAX_CONTACT_DELETIONS);
+        expect(result.notFoundIds).toEqual([]);
+        expect(book.writes.map((write) => write.destroy.length)).toEqual([
+          MAX_CARD_CHANGES_PER_WRITE - 1,
+          1,
+        ]);
+        for (const write of book.writes) {
+          expect(
+            write.destroy.length + write.update.length,
+          ).toBeLessThanOrEqual(MAX_CARD_CHANGES_PER_WRITE);
+        }
+        expect(book.contacts.size).toBe(0);
+        expect(book.groups.get('g1')?.memberUids).toEqual([]);
+      });
+
+      it('같은 uid 의 다른 카드가 남으면 그 uid 는 그룹에 그대로 둔다', async () => {
+        book.seedContact('c1', { uid: 'urn:uuid:shared' });
+        book.seedContact('c2', { uid: 'urn:uuid:shared' });
+        book.seedGroup('g1', '거래처', ['urn:uuid:shared']);
+
+        await service.removeContacts(ARA, ['c1']);
+        expect(book.groups.get('g1')?.memberUids).toEqual(['urn:uuid:shared']);
+        expect(book.writes.at(-1)?.update).toEqual([]);
+      });
+
+      it('바쁘다고 했지만 들어갔으면 — 다음 시도에서 없어진 id 도 지운 것으로 센다(notFound 가 아니다)', async () => {
+        book.seedContact('c1');
+        book.seedContact('c2');
+        book.busy.push('applied');
+
+        await expect(
+          service.removeContacts(ARA, ['c1', 'c2']),
+        ).resolves.toEqual({ deletedIds: ['c1', 'c2'], notFoundIds: [] });
+      });
+
+      it('0개 · 501개 · 같은 id 두 번은 VAL_001 — 엔진에 묻지 않는다', async () => {
+        for (const ids of [
+          [],
+          Array.from({ length: MAX_CONTACT_DELETIONS + 1 }, (_, n) => `x${n}`),
+          ['c1', 'c1'],
+        ]) {
+          expect((await failureOf(service.removeContacts(ARA, ids))).code).toBe(
+            'VAL_001',
+          );
+        }
+        expect(book.getAddressBookVersion).not.toHaveBeenCalled();
+      });
+    });
+
+    describe('내보내기 (exportContacts)', () => {
+      beforeEach(() => {
+        book.seedContact('c-pa', {
+          name: '박지훈',
+          emails: [{ address: 'jihoon@hanbit.example', label: 'work' }],
+        });
+        book.seedContact('c-ga', {
+          name: '가나다',
+          phones: [{ number: '010-1234-5678', label: 'mobile' }],
+        });
+        book.seedGroup('g1', '거래처', ['urn:uuid:c-pa']);
+      });
+
+      it('vCard — 내 주소록 전체를 이름 차례로, 그룹 이름은 CATEGORIES · 파일 이름은 한국 날짜', async () => {
+        const file = await service.exportContacts(ARA, 'vcard');
+        const text = file.content.toString('utf8');
+
+        expect(file.fileName).toBe(
+          `주소록-${kstDateString(new Date(now))}.vcf`,
+        );
+        expect(file.contentType).toBe('text/vcard; charset=utf-8');
+        expect(file.count).toBe(2);
+        expect(text.indexOf('FN:가나다')).toBeLessThan(
+          text.indexOf('FN:박지훈'),
+        );
+        expect(text).toContain('UID:urn:uuid:c-pa\r\n');
+        expect(text).toContain('CATEGORIES:거래처\r\n');
+        expect(logged()).toContain(
+          '주소록을 내보냈습니다: 형식=vcard, 연락처 2명',
+        );
+        expect(logged()).not.toMatch(/박지훈|가나다|hanbit|ara\.kim@/);
+      });
+
+      it('CSV — 그룹 하나만(groupId), 파일 이름에 그룹 이름 · 없는 그룹은 RES_001', async () => {
+        const file = await service.exportContacts(ARA, 'csv', 'g1');
+        const rows = file.content.toString('utf8').split('\r\n');
+
+        expect(file.fileName).toBe(
+          `주소록-거래처-${kstDateString(new Date(now))}.csv`,
+        );
+        expect(rows).toHaveLength(3);
+        expect(rows[1]).toBe('박지훈,jihoon@hanbit.example,,,,,,,,,거래처');
+        expect(
+          (await failureOf(service.exportContacts(ARA, 'csv', 'nope'))).code,
+        ).toBe('RES_001');
+      });
+    });
+  });
 });

backend/src/modules/contacts/contacts.service.ts

@@ -20,6 +20,19 @@ import {
   type WrittenChanges,
 } from './address-book';
 import { ContactBookCache } from './contact-book-cache';
+import {
+  contactExportContent,
+  contactExportContentType,
+  contactExportFileName,
+  type ExportedContact,
+} from './contact-export';
+import {
+  deletionChunkSize,
+  importDuplicateIndex,
+  isExistingContact,
+  planGroupJoins,
+  type GroupRoom,
+} from './contact-import';
 import { cursorOffset, listScope, pageOf } from './contact-paging';
 import {
   ContactRestoreStore,
@@ -38,8 +51,11 @@ import {
   CONTACT_RESTORE_TTL_MS,
   CONTACT_WRITE_ATTEMPTS,
   MAX_ADDRESS_BOOK_WEIGHT,
+  MAX_CARD_CHANGES_PER_WRITE,
+  MAX_CONTACT_DELETIONS,
   MAX_CONTACT_GROUP_MEMBERS,
   MAX_CONTACT_GROUPS,
+  MAX_CONTACT_IMPORT_BATCH,
   MAX_CONTACTS,
   MAX_GROUP_MEMBERS_PER_REQUEST,
 } from './contacts.constants';
@@ -48,6 +64,7 @@ import {
   type AddressBookCardUpdate,
   type AddressBookChanges,
   type AddressBookContactCard,
+  type AddressBookWriteOptions,
   type ContactsProvider,
   type NewAddressBookCard,
   type RemovedCardOriginal,
@@ -56,14 +73,20 @@ import type {
   Contact,
   ContactDeleted,
   ContactEmail,
+  ContactExportFile,
+  ContactExportFormat,
   ContactFields,
   ContactGroup,
   ContactGroupDeleted,
   ContactGroupMembersAdded,
+  ContactImportCheck,
+  ContactImportItem,
+  ContactImportResult,
   ContactInput,
   ContactPatch,
   ContactPhone,
   ContactRestored,
+  ContactsDeleted,
   ContactSuggestionLine,
   DirectoryEntry,
 } from './contacts.types';
@@ -79,6 +102,8 @@ const NEW_CONTACT_KEY = 'contact';
 const NEW_GROUP_KEY = 'group';
 const NEW_MEMBER_KEY_PREFIX = 'member-';
 const RESTORED_KEY = 'restored';
+/** 가져오기의 한 사람 — 보낸 차례 번호를 붙인다 (import-0 …) */
+const IMPORT_KEY_PREFIX = 'import-';
 
 const NO_CHANGES: AddressBookChanges = { create: [], update: [], destroy: [] };
 
@@ -105,6 +130,8 @@ interface ChangePlan<T> {
   readonly result: (after: BookView, written: WriteResult) => T;
   /** 바꾼 뒤 남기는 info 로그 (개수 · id 만 — 연락처의 내용은 남기지 않는다) */
   readonly log?: string;
+  /** 엔진에 쓰는 선택 — 가져오기(일부만 받기) · 한꺼번에 지우기(원본 읽지 않기) (16단계) */
+  readonly write?: AddressBookWriteOptions;
 }
 
 /** 읽는 중인 주소록 — token 은 이 읽기의 표 (그사이 바꾸기가 끝나면 빠져서 옛 결과를 기억하지 않는다) */
@@ -269,7 +296,9 @@ function joinGroups(groups: readonly BookGroup[], uid: string) {
  *   거절하면(busy) 다시 읽어 다시 정한다 (CONTACT_WRITE_ATTEMPTS 번 — 넘으면 MAIL_001). 한도(연락처 3,000 · 그룹 100 · 구성원 500 · 크기 800만 —
  *   CONTACT_002) · 같은 이름의 그룹(CONTACT_001)도 그 판으로 본다. 쓴 뒤에는 같은 바꾸기를 기억한 주소록에 옮겨 다시 읽지 않는다 (address-book.ts)
  * - 지우기는 되돌리기 표를 준다 — 엔진 카드 전체를 5분 기억한다 (contact-restore-store.ts)
- * - 로그에는 개수 · id 만 — 이름 · 주소 · 전화번호 · 메모 · 되돌리기 표는 남기지 않는다
+ * - 16단계 — 가져오기(확인 · 100명씩 넣기 — 화면이 준 uid 로 두 번 들어가지 않게, 엔진이 일부만 받아도 던지지 않는다 · contact-import.ts),
+ *   한꺼번에 지우기(가져오기 [되돌리기] — 되돌리기 표 없음), 내보내기(vCard · CSV — contact-export.ts)
+ * - 로그에는 개수 · id 만 — 이름 · 주소 · 전화번호 · 메모 · 되돌리기 표 · 파일 내용은 남기지 않는다
  *
  * ⚠️ 프로세스 메모리다(기억한 주소록 · 바꾸기 차례 · 되돌리기 표). 인스턴스를 늘려도 주소록은 틀리지 않는다 — 판이 그대로일 때만 쓴다.
  * 되돌리기 표는 공유 저장소로 옮겨야 한다(다른 인스턴스로 간 되돌리기는 404).
@@ -288,12 +317,15 @@ export class ContactsService {
   private readonly loading = new Map<string, Loading>();
   /** 같은 직원의 바꾸기 차례 — 끝나면 빠진다 */
   private readonly writeQueues = new Map<string, Promise<void>>();
+  /** 되돌리기 표의 시계 · 내보낸 파일 이름의 날짜 */
+  private readonly now: () => number;
 
   constructor(
     @Inject(CONTACTS_PROVIDER) private readonly provider: ContactsProvider,
     private readonly directory: DirectoryService,
     @Optional() @Inject(CONTACTS_CLOCK) clock?: () => number,
   ) {
+    this.now = clock ?? (() => Date.now());
     this.restorations = new ContactRestoreStore(
       {
         ttlMs: CONTACT_RESTORE_TTL_MS,
@@ -302,7 +334,7 @@ export class ContactsService {
         maxTotalBytes: CONTACT_RESTORE_MAX_TOTAL_BYTES,
         tokenBytes: CONTACT_RESTORE_TOKEN_BYTES,
       },
-      clock ?? (() => Date.now()),
+      this.now,
     );
   }
 
@@ -840,6 +872,261 @@ export class ContactsService {
     });
   }
 
+  /**
+   * POST /api/contact-import-checks — 가져올 연락처가 내 주소록에 이미 있는지 · 더 넣을 수 있는 수 (계약 3절 "가져오기" — 16단계). 만들지 않는다.
+   * 이미 있음: 같은 uid 의 연락처(다시 보낸 묶음) 또는 contact-import.ts 의 규칙(이메일 · 이름 + 전화). 항목 검사(이름이나 이메일 · 같은 주소 · 같은 uid)는
+   * 넣기와 같다 — 하나라도 걸리면 VAL_001. groupIds 는 보지 않는다(새 그룹은 넣기 직전에 만든다)
+   */
+  async checkImport(
+    user: AuthenticatedUser,
+    items: readonly ContactImportItem[],
+  ): Promise<ContactImportCheck> {
+    this.assertImportItems(items);
+    const book = await this.freshBook(user.email);
+    const index = importDuplicateIndex(
+      book.contacts.map((entry) => entry.contact),
+    );
+    return {
+      items: items.map((item) => ({
+        uid: item.uid,
+        status:
+          book.contactsByUid.has(item.uid) || isExistingContact(index, item)
+            ? 'exists'
+            : 'new',
+      })),
+      remaining: Math.max(0, MAX_CONTACTS - book.contacts.length),
+    };
+  }
+
+  /**
+   * POST /api/contact-imports — 가져온 연락처를 엔진 요청 하나로 만든다 (계약 3절 "가져오기" — 16단계).
+   * - 줄마다 화면이 준 uid 로 만든다. 같은 uid 의 연락처가 이미 있으면(다시 보낸 묶음 · 앞 시도가 들어감) 만들지 않고 그 연락처를 돌려준다 — 빠진 그룹만 마저 넣는다
+   * - 연락처 수 · 크기 한도는 묶음 전체로 본다 — 넘으면 CONTACT_002, 아무것도 만들지 않는다. 없는 그룹은 RES_001
+   * - 그룹 구성원 500명을 넘기는 넣기는 그 그룹만 빼고(skippedGroupIds) 만든다 — 실패가 아니다
+   * - 엔진이 일부만 받으면 받은 것만 돌려준다(빠진 uid 는 화면이 "넣지 못함"으로) — 던지지 않는다. 그룹 카드가 쓰는 uid 도 만들지 않는다(엔진이 받지 않는다)
+   * - 겹침(같은 이메일 등)은 보지 않는다 — 확인(checkImport)의 몫
+   */
+  async importContacts(
+    actor: AuthenticatedUser,
+    items: readonly ContactImportItem[],
+  ): Promise<ContactImportResult> {
+    this.assertImportItems(items);
+    const result = await this.change(actor, (book) => {
+      const groups = new Map<string, BookGroup>();
+      for (const item of items) {
+        for (const groupId of item.groupIds) {
+          if (!groups.has(groupId)) {
+            groups.set(groupId, this.requireGroup(book, groupId));
+          }
+        }
+      }
+
+      /** 이미 있는 같은 uid 의 연락처 */
+      const landed = new Map<string, BookContact>();
+      /** uid → 이 바꾸기 안의 key */
+      const keys = new Map<string, string>();
+      items.forEach((item, index) => {
+        const existing = book.contactsByUid.get(item.uid)?.[0];
+        if (existing) landed.set(item.uid, existing);
+        else if (!book.uidsInUse.has(item.uid)) {
+          keys.set(item.uid, `${IMPORT_KEY_PREFIX}${index}`);
+        }
+      });
+      if (book.contacts.length + keys.size > MAX_CONTACTS) {
+        throw overLimit('contacts-limit', {
+          contacts: book.contacts.length,
+          creating: keys.size,
+        });
+      }
+
+      const rooms = new Map<string, GroupRoom>(
+        [...groups].map(([id, group]) => [
+          id,
+          {
+            memberUids: new Set(group.card.memberUids),
+            memberCount: group.group.memberCount,
+          },
+        ]),
+      );
+      const joins = planGroupJoins(
+        rooms,
+        items.filter((item) => landed.has(item.uid) || keys.has(item.uid)),
+        MAX_CONTACT_GROUP_MEMBERS,
+      );
+      const update: AddressBookCardUpdate[] = [];
+      for (const [groupId, group] of groups) {
+        const adding = joins.adds.get(groupId);
+        if (adding && adding.length > 0) {
+          update.push({
+            kind: 'group',
+            id: groupId,
+            memberUids: withMembers(group, adding),
+          });
+        }
+      }
+      return {
+        changes: {
+          create: items.flatMap((item): NewAddressBookCard[] => {
+            const key = keys.get(item.uid);
+            return key === undefined
+              ? []
+              : [
+                  {
+                    kind: 'contact',
+                    key,
+                    uid: item.uid,
+                    fields: fieldsOf(item),
+                  },
+                ];
+          }),
+          update,
+          destroy: [],
+        },
+        write: { allowPartialCreate: true },
+        result: (_after, written) => ({
+          items: items.flatMap((item) => {
+            const key = keys.get(item.uid);
+            const id =
+              landed.get(item.uid)?.card.id ??
+              (key === undefined ? undefined : written.createdIds.get(key));
+            return id === undefined
+              ? []
+              : [
+                  {
+                    uid: item.uid,
+                    id,
+                    skippedGroupIds: [...(joins.skipped.get(item.uid) ?? [])],
+                  },
+                ];
+          }),
+        }),
+      };
+    });
+    const skipped = result.items.reduce(
+      (sum, item) => sum + item.skippedGroupIds.length,
+      0,
+    );
+    this.logger.log(
+      `${traceTag()} 연락처를 가져왔습니다: 보낸 ${items.length}명 가운데 ${result.items.length}명(이미 있던 같은 uid 포함), 넣지 못함 ${items.length - result.items.length}명, 구성원 한도로 그룹에 넣지 못함 ${skipped}건 (user=${maskEmail(normalizeUser(actor.email))})`,
+    );
+    return result;
+  }
+
+  /**
+   * POST /api/contact-deletions — 연락처 여러 개를 영구 삭제한다 (가져오기 [되돌리기] — 계약 3절 "가져오기" — 16단계). 되돌리기 표는 주지 않는다.
+   * 지운 연락처를 가리키는 그룹 구성원도 함께 뺀다(같은 uid 의 다른 카드가 남으면 그대로). 내 주소록에 없는 id(그룹 id 포함)는 notFoundIds.
+   * 엔진 한 요청에 담는 카드 수(지울 연락처 + 고칠 그룹)가 상한을 넘으면 앞에서부터 나눠 쓴다 — 중간에 실패하면 앞 몫은 지워진 채다(다시 보내면 notFoundIds)
+   */
+  async removeContacts(
+    actor: AuthenticatedUser,
+    ids: readonly string[],
+  ): Promise<ContactsDeleted> {
+    if (ids.length < 1 || ids.length > MAX_CONTACT_DELETIONS) {
+      throw new BusinessException('VAL_001', {
+        context: { reason: 'contact-deletions-count', requested: ids.length },
+      });
+    }
+    if (new Set(ids).size !== ids.length) {
+      throw new BusinessException('VAL_001', {
+        context: { reason: 'contact-deletions-duplicate' },
+      });
+    }
+    const deleted = new Set<string>();
+    let pending: readonly string[] = ids;
+    while (pending.length > 0) {
+      const batch = pending;
+      /** 이 몫에서 지우려 했던 id — 엔진이 바쁘다고 했는데 들어갔으면 다음 시도에서 없어진 것을 지운 것으로 센다 */
+      const tried = new Set<string>();
+      const step = await this.change(actor, (book, attempt) => {
+        const present = batch.filter((id) => book.contactsById.has(id));
+        const landed = attempt.uncertain
+          ? batch.filter((id) => tried.has(id) && !book.contactsById.has(id))
+          : [];
+        const groupIdsByUid = new Map<string, string[]>();
+        for (const group of book.groups) {
+          for (const uid of group.card.memberUids) {
+            const groupIds = groupIdsByUid.get(uid) ?? [];
+            groupIds.push(group.card.id);
+            groupIdsByUid.set(uid, groupIds);
+          }
+        }
+        const size = deletionChunkSize(
+          present.map((id) => {
+            const uid = book.contactsById.get(id)?.card.uid ?? null;
+            return uid === null ? [] : (groupIdsByUid.get(uid) ?? []);
+          }),
+          MAX_CARD_CHANGES_PER_WRITE,
+        );
+        const now = present.slice(0, size);
+        for (const id of now) tried.add(id);
+        const update = this.leavingGroups(book, now);
+        return {
+          changes: { create: [], update, destroy: now },
+          write: { withoutOriginals: true },
+          result: () => ({
+            deleted: [...landed, ...now],
+            rest: present.slice(size),
+          }),
+          log: `연락처를 한꺼번에 지웠습니다: ${now.length}명, 그룹에서 뺌 ${update.length}개`,
+        };
+      });
+      for (const id of step.deleted) deleted.add(id);
+      pending = step.rest;
+    }
+    return {
+      deletedIds: ids.filter((id) => deleted.has(id)),
+      notFoundIds: ids.filter((id) => !deleted.has(id)),
+    };
+  }
+
+  /**
+   * GET /api/contact-exports — 내 주소록 전체 또는 그룹 하나를 vCard 3.0 · CSV 로 (계약 3절 "내보내기" — 16단계).
+   * 이름 차례, 우리 칸만(contact-export.ts). 사내 목록은 넣지 않는다. 없는 그룹은 RES_001. 로그에는 형식 · 개수 · 그룹 id 만
+   */
+  async exportContacts(
+    user: AuthenticatedUser,
+    format: ContactExportFormat,
+    groupId?: string,
+  ): Promise<ContactExportFile> {
+    const book = await this.freshBook(user.email);
+    const group =
+      groupId === undefined ? null : this.requireGroup(book, groupId);
+    const entries =
+      group === null
+        ? book.contacts
+        : group.memberIds.flatMap((id) => {
+            const entry = book.contactsById.get(id);
+            return entry ? [entry] : [];
+          });
+    const groupNames = new Map(
+      book.groups.map((entry) => [entry.card.id, entry.card.name]),
+    );
+    const contacts = entries.map(
+      (entry): ExportedContact => ({
+        ...fieldsOf(entry.contact),
+        uid: entry.card.uid,
+        groupNames: entry.contact.groupIds.flatMap((id) => {
+          const name = groupNames.get(id);
+          return name ? [name] : [];
+        }),
+      }),
+    );
+    const content = Buffer.from(contactExportContent(format, contacts), 'utf8');
+    this.logger.log(
+      `${traceTag()} 주소록을 내보냈습니다: 형식=${format}, 연락처 ${contacts.length}명, 범위=${group === null ? '전체' : `그룹 ${group.card.id}`} (user=${maskEmail(normalizeUser(user.email))})`,
+    );
+    return {
+      fileName: contactExportFileName(
+        format,
+        group?.card.name ?? null,
+        new Date(this.now()),
+      ),
+      contentType: contactExportContentType(format),
+      content,
+      count: contacts.length,
+    };
+  }
+
   /**
    * GET /api/directory-entries — 사내 목록(directory.service.ts)에서 excludeGroupId 면 그 그룹(이 직원의 주소록) 구성원이 가진 주소를 뺀다.
    * 그룹은 커서를 확인한 뒤에 찾는다 — 없는 그룹이면 404 RES_001
@@ -1071,6 +1358,7 @@ export class ContactsService {
             user,
             book.version,
             planned.changes,
+            planned.write,
           );
         } catch (error) {
           // 일부만 바뀌었을 수 있다 — 기억한 것을 버리고 다음 요청은 다시 읽는다
@@ -1175,6 +1463,57 @@ export class ContactsService {
     }
   }
 
+  /**
+   * 가져오기 · 확인의 묶음 — 1~100명, 사람마다 연락처 추가와 같은 검사(이름이나 이메일 · 같은 주소), 묶음 안의 같은 uid 는 안 된다.
+   * 하나라도 걸리면 엔진에 묻기 전에 VAL_001 (화면이 같은 규칙으로 미리 거른다)
+   */
+  private assertImportItems(items: readonly ContactImportItem[]): void {
+    if (items.length < 1 || items.length > MAX_CONTACT_IMPORT_BATCH) {
+      throw new BusinessException('VAL_001', {
+        context: { reason: 'contact-import-count', requested: items.length },
+      });
+    }
+    const uids = new Set<string>();
+    for (const item of items) {
+      this.assertNameOrEmail(item);
+      this.assertDistinctEmails(item.emails);
+      if (uids.has(item.uid)) {
+        throw new BusinessException('VAL_001', {
+          context: { reason: 'contact-import-duplicate-uid' },
+        });
+      }
+      uids.add(item.uid);
+    }
+  }
+
+  /**
+   * 연락처들을 지울 때 고칠 그룹 — 지우는 카드의 uid 를 구성원에서 뺀다. 같은 uid 의 다른 카드가 남으면(이번에 지우지 않는 카드) 그 uid 는 그대로 둔다.
+   * 그룹 구성원을 한 번 훑는다
+   */
+  private leavingGroups(
+    book: BookView,
+    ids: readonly string[],
+  ): AddressBookCardUpdate[] {
+    const removing = new Set(ids);
+    const uids = new Set<string>();
+    for (const id of ids) {
+      const uid = book.contactsById.get(id)?.card.uid ?? null;
+      if (uid === null) continue;
+      const owners = book.contactsByUid.get(uid) ?? [];
+      if (owners.every((owner) => removing.has(owner.card.id))) uids.add(uid);
+    }
+    if (uids.size === 0) return [];
+    return book.groups
+      .filter((group) => group.card.memberUids.some((uid) => uids.has(uid)))
+      .map(
+        (group): AddressBookCardUpdate => ({
+          kind: 'group',
+          id: group.card.id,
+          memberUids: withMembers(group, [], uids),
+        }),
+      );
+  }
+
   /** 크기 한도 — 이 바꾸기로 주소록이 800만을 넘게 커지면 CONTACT_002 (줄이는 쓰기 · 지우기는 늘 된다) */
   private assertWeight(book: BookView, changes: AddressBookChanges): void {
     const after = weightAfterChanges(book, changes);

backend/src/modules/contacts/contacts.types.ts

@@ -104,6 +104,70 @@ export interface ContactGroupMembersAdded {
   readonly createdCount: number;
 }
 
+/**
+ * 가져오기의 한 사람 (계약 3절 ContactImportItem — 16단계) — 연락처 추가 본문(ContactInput)과 같은 칸 + 화면이 만든 uid.
+ * 같은 uid 가 이미 주소록에 있으면(다시 보낸 요청) 새로 만들지 않고 그 연락처를 돌려준다
+ */
+export interface ContactImportItem extends ContactInput {
+  /** `urn:uuid:` + 소문자 UUID */
+  readonly uid: string;
+}
+
+/** 가져오기 확인의 판정 — new 넣을 연락처 · exists 이미 있는 연락처(계약 3절 "가져오기") */
+export type ContactImportStatus = 'new' | 'exists';
+
+export const CONTACT_IMPORT_STATUSES: readonly ContactImportStatus[] = [
+  'new',
+  'exists',
+];
+
+/** POST /api/contact-import-checks 의 응답 */
+export interface ContactImportCheck {
+  /** 보낸 차례 그대로 한 줄씩 */
+  readonly items: readonly {
+    readonly uid: string;
+    readonly status: ContactImportStatus;
+  }[];
+  /** 더 넣을 수 있는 연락처 수 — 3,000 − 지금 연락처 수 (0 아래로는 내려가지 않는다) */
+  readonly remaining: number;
+}
+
+/** 가져온 연락처 하나 — 화면이 준 uid · 엔진의 카드 id · 구성원 500명이 차서 넣지 못한 그룹 */
+export interface ContactImported {
+  readonly uid: string;
+  readonly id: string;
+  readonly skippedGroupIds: readonly string[];
+}
+
+/** POST /api/contact-imports 의 응답 — 넣은(또는 이미 있던 같은 uid 의) 연락처만, 보낸 차례 그대로. 빠진 uid 는 엔진이 받지 않은 것 */
+export interface ContactImportResult {
+  readonly items: readonly ContactImported[];
+}
+
+/** POST /api/contact-deletions 의 응답 — 보낸 차례 그대로 */
+export interface ContactsDeleted {
+  readonly deletedIds: readonly string[];
+  /** 내 주소록에 없는 id (이미 지움 · 그룹 id 포함) */
+  readonly notFoundIds: readonly string[];
+}
+
+/** 내보내기 형식 — vCard 3.0 · CSV(UTF-8 BOM) */
+export type ContactExportFormat = 'vcard' | 'csv';
+
+export const CONTACT_EXPORT_FORMATS: readonly ContactExportFormat[] = [
+  'vcard',
+  'csv',
+];
+
+/** 내보낼 파일 — 이름 · 형식 · 내용 */
+export interface ContactExportFile {
+  readonly fileName: string;
+  readonly contentType: string;
+  readonly content: Buffer;
+  /** 담은 연락처 수 (로그) */
+  readonly count: number;
+}
+
 /** 사내 목록의 종류 — 직원(개인 계정) · 공용 주소(그룹 계정) */
 export type DirectoryEntryKind = 'person' | 'shared';
 

backend/src/modules/contacts/dto/contact-export.dto.ts

@@ -0,0 +1,30 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsIn } from 'class-validator';
+
+import {
+  CONTACT_EXPORT_FORMATS,
+  type ContactExportFormat,
+} from '@/modules/contacts/contacts.types';
+import { ContactGroupIdQuery } from './contact.dto';
+
+/** GET /api/contact-exports 의 쿼리 (계약 3절 "내보내기" — 16단계) — 모르는 형식 · 쿼리는 400 VAL_001 */
+export class ContactExportQueryDto {
+  @ApiProperty({
+    description:
+      'vcard — vCard 3.0(.vcf, 다른 메일 · 휴대폰으로 옮길 때) · csv — CSV(UTF-8 BOM, 엑셀에서 볼 때)',
+    enum: [...CONTACT_EXPORT_FORMATS],
+    example: 'vcard',
+  })
+  @IsIn(CONTACT_EXPORT_FORMATS, {
+    message: '내보낼 형식을 다시 골라 주세요.',
+  })
+  format!: ContactExportFormat;
+
+  @ApiPropertyOptional({
+    description:
+      '이 그룹의 구성원만 — 없으면 내 주소록 전체. 없는 그룹이면 404 RES_001',
+    example: 'jy',
+  })
+  @ContactGroupIdQuery()
+  groupId?: string;
+}

backend/src/modules/contacts/dto/contact-import.dto.spec.ts

@@ -0,0 +1,175 @@
+import { BadRequestException } from '@nestjs/common';
+import { plainToInstance } from 'class-transformer';
+import { validate, type ValidationError } from 'class-validator';
+
+import { createValidationPipe } from '@/app.setup';
+import {
+  MAX_CONTACT_DELETIONS,
+  MAX_CONTACT_IMPORT_BATCH,
+} from '@/modules/contacts/contacts.constants';
+import { ContactExportQueryDto } from './contact-export.dto';
+import {
+  ContactDeletionDto,
+  ContactImportBatchDto,
+} from './contact-import.dto';
+
+/** 걸린 규칙 이름 — 중첩된 칸까지 */
+function constraintNames(errors: ValidationError[]): string[] {
+  return errors.flatMap((error) => [
+    ...Object.keys(error.constraints ?? {}),
+    ...constraintNames(error.children ?? []),
+  ]);
+}
+
+/** 전역 ValidationPipe 와 같은 옵션으로 (stopAtFirstError 는 고른다 — 빼면 걸린 규칙을 모두 본다) */
+async function namesOf<T extends object>(
+  type: new () => T,
+  body: object,
+  stopAtFirstError = false,
+): Promise<string[]> {
+  const dto = plainToInstance(type, body);
+  return constraintNames(
+    await validate(dto, {
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      stopAtFirstError,
+    }),
+  );
+}
+
+const UID = 'urn:uuid:3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d';
+
+const person = (overrides: object = {}) => ({
+  name: '박지훈',
+  emails: [{ address: 'jihoon.park@hanbit.example', label: 'work' }],
+  phones: [{ number: '010-3192-5540', label: 'mobile' }],
+  company: '한빛상사',
+  department: '구매팀',
+  title: '과장',
+  note: null,
+  groupIds: [],
+  uid: UID,
+  ...overrides,
+});
+
+describe('가져오기 본문 (POST /api/contact-import-checks · /api/contact-imports — 16단계)', () => {
+  it('맞는 묶음 — 사람마다 연락처 추가 본문 + uid, 글은 앞뒤 공백을 지운다', async () => {
+    expect(
+      await namesOf(ContactImportBatchDto, { contacts: [person()] }),
+    ).toEqual([]);
+    const dto = plainToInstance(ContactImportBatchDto, {
+      contacts: [person({ name: '  김아라 ', company: '   ' })],
+    });
+    expect(await validate(dto)).toEqual([]);
+    expect(dto.contacts[0].name).toBe('김아라');
+    expect(dto.contacts[0].company).toBeNull();
+  });
+
+  it('uid — urn:uuid: + 소문자 UUID 만', async () => {
+    for (const uid of [
+      UID.toUpperCase(),
+      UID.replace('urn:uuid:', ''),
+      `${UID}0`,
+      'urn:uuid:not-a-uuid',
+      7,
+      null,
+    ]) {
+      expect(
+        await namesOf(ContactImportBatchDto, { contacts: [person({ uid })] }),
+      ).not.toEqual([]);
+    }
+    const missing: Record<string, unknown> = person();
+    delete missing.uid;
+    expect(
+      await namesOf(ContactImportBatchDto, { contacts: [missing] }),
+    ).not.toEqual([]);
+  });
+
+  it(`묶음 — 배열 · 1~${MAX_CONTACT_IMPORT_BATCH}명, 사람마다 연락처 추가와 같은 칸 검사 · 모르는 칸은 안 된다`, async () => {
+    for (const contacts of [
+      null,
+      'x',
+      [],
+      Array.from({ length: MAX_CONTACT_IMPORT_BATCH + 1 }, () => person()),
+      [person({ emails: [{ address: 'not-an-email', label: 'work' }] })],
+      [person({ phones: [{ number: '내선 12', label: 'work' }] })],
+      [person({ note: '가'.repeat(1_001) })],
+      [person({ extra: true })],
+    ]) {
+      expect(await namesOf(ContactImportBatchDto, { contacts })).not.toEqual(
+        [],
+      );
+    }
+    expect(
+      await namesOf(ContactImportBatchDto, {
+        contacts: Array.from({ length: MAX_CONTACT_IMPORT_BATCH }, () =>
+          person(),
+        ),
+      }),
+    ).toEqual([]);
+  });
+
+  it('개수가 넘으면 사람마다의 검사를 하지 않는다 — 형식 → 개수 → 중첩 차례 (stopAtFirstError)', async () => {
+    const names = await namesOf(
+      ContactImportBatchDto,
+      {
+        contacts: Array.from({ length: MAX_CONTACT_IMPORT_BATCH + 1 }, () =>
+          person({ emails: [{ address: 'bad', label: 'work' }] }),
+        ),
+      },
+      true,
+    );
+    expect(names).toEqual(['arrayMaxSize']);
+    const pipe = createValidationPipe();
+    await expect(
+      pipe.transform(
+        { contacts: [] },
+        { type: 'body', metatype: ContactImportBatchDto },
+      ),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+});
+
+describe('한꺼번에 지우기 본문 (POST /api/contact-deletions — 16단계)', () => {
+  it(`id 1~${MAX_CONTACT_DELETIONS}개 · id 모양 · 겹치지 않게`, async () => {
+    expect(await namesOf(ContactDeletionDto, { ids: ['jw', 'jx'] })).toEqual(
+      [],
+    );
+    for (const ids of [
+      null,
+      [],
+      Array.from({ length: MAX_CONTACT_DELETIONS + 1 }, (_, n) => `c${n}`),
+      ['jw', 'jw'],
+      ['../x'],
+      [7],
+    ]) {
+      expect(await namesOf(ContactDeletionDto, { ids })).not.toEqual([]);
+    }
+    expect(
+      await namesOf(ContactDeletionDto, {
+        ids: Array.from({ length: MAX_CONTACT_DELETIONS }, (_, n) => `c${n}`),
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe('내보내기 쿼리 (GET /api/contact-exports — 16단계)', () => {
+  it('format 은 vcard · csv 만(없으면 안 된다) · groupId 는 id 모양 · 모르는 쿼리는 안 된다', async () => {
+    expect(await namesOf(ContactExportQueryDto, { format: 'vcard' })).toEqual(
+      [],
+    );
+    expect(
+      await namesOf(ContactExportQueryDto, { format: 'csv', groupId: 'jy' }),
+    ).toEqual([]);
+    for (const query of [
+      {},
+      { format: 'xlsx' },
+      { format: 'VCARD' },
+      { format: ['vcard', 'csv'] },
+      { format: 'csv', groupId: '../x' },
+      { format: 'csv', limit: '10' },
+    ]) {
+      expect(await namesOf(ContactExportQueryDto, query)).not.toEqual([]);
+    }
+  });
+});

backend/src/modules/contacts/dto/contact-import.dto.ts

@@ -0,0 +1,202 @@
+import { applyDecorators } from '@nestjs/common';
+import { ApiProperty } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  ArrayMaxSize,
+  ArrayMinSize,
+  IsArray,
+  IsString,
+  Matches,
+  ValidateNested,
+} from 'class-validator';
+
+import { ArrayDistinct } from '@/common/decorators/array-distinct.decorator';
+import { MaxCodeUnits } from '@/common/decorators/code-units.decorator';
+import {
+  CONTACT_ID_PATTERN,
+  CONTACT_IMPORT_UID_PATTERN,
+  MAX_CONTACT_DELETIONS,
+  MAX_CONTACT_IMPORT_BATCH,
+} from '@/modules/contacts/contacts.constants';
+import {
+  CONTACT_IMPORT_STATUSES,
+  type ContactImportCheck,
+  type ContactImported,
+  type ContactImportItem,
+  type ContactImportResult,
+  type ContactImportStatus,
+  type ContactsDeleted,
+} from '@/modules/contacts/contacts.types';
+import { ContactInputDto } from './contact.dto';
+
+/**
+ * 가져오기 · 한꺼번에 지우기 — 본문과 응답 (계약 3절 "가져오기 · 내보내기" — 16단계).
+ * 한 사람(ContactImportItem)은 연락처 추가 본문(ContactInputDto)과 같은 검사에 uid 를 더한 것이다. 이름이나 이메일 · 같은 연락처 안의 같은 주소 ·
+ * 묶음 안의 같은 uid 는 서비스가 본다(모두 400 VAL_001). 칸의 검사는 적은 차례대로 돈다(contact.dto.ts 머리말 — 형식 → 길이 · 개수 → 모양)
+ */
+
+/** `urn:uuid:` + 소문자 UUID 의 길이 */
+const IMPORT_UID_LENGTH = 45;
+
+function ImportUid(): PropertyDecorator {
+  return applyDecorators(
+    IsString({ message: '가져올 연락처의 표시가 올바르지 않습니다.' }),
+    MaxCodeUnits(IMPORT_UID_LENGTH, {
+      message: '가져올 연락처의 표시가 올바르지 않습니다.',
+    }),
+    Matches(CONTACT_IMPORT_UID_PATTERN, {
+      message: '가져올 연락처의 표시가 올바르지 않습니다.',
+    }),
+  );
+}
+
+/** 가져올 연락처 목록 — 형식 → 개수(1~100) → 사람마다(중첩) 차례로 (개수가 넘으면 중첩 검사를 하지 않는다 — stopAtFirstError) */
+function ImportList(): PropertyDecorator {
+  return applyDecorators(
+    IsArray({ message: '가져올 연락처 목록 형식이 올바르지 않습니다.' }),
+    ArrayMinSize(1, { message: '가져올 연락처를 하나 이상 보내 주세요.' }),
+    ArrayMaxSize(MAX_CONTACT_IMPORT_BATCH, {
+      message: `한 번에 ${MAX_CONTACT_IMPORT_BATCH}명까지 보낼 수 있습니다.`,
+    }),
+    ValidateNested({ each: true }),
+    Type(() => ContactImportItemDto),
+  );
+}
+
+/** 지울 연락처 id 목록 — 형식 → 개수(1~500) → id 모양 → 겹침 */
+function DeletionIdList(): PropertyDecorator {
+  return applyDecorators(
+    IsArray({ message: '지울 연락처 목록 형식이 올바르지 않습니다.' }),
+    ArrayMinSize(1, { message: '지울 연락처를 하나 이상 보내 주세요.' }),
+    ArrayMaxSize(MAX_CONTACT_DELETIONS, {
+      message: `한 번에 ${MAX_CONTACT_DELETIONS}명까지 지울 수 있습니다.`,
+    }),
+    Matches(CONTACT_ID_PATTERN, {
+      each: true,
+      message: '지울 연락처를 다시 골라 주세요.',
+    }),
+    ArrayDistinct({ message: '같은 연락처를 두 번 보낼 수 없습니다.' }),
+  );
+}
+
+export class ContactImportItemDto
+  extends ContactInputDto
+  implements ContactImportItem
+{
+  @ApiProperty({
+    description:
+      '화면이 사람마다 만든 uid — `urn:uuid:` + 소문자 UUID. 엔진 카드의 uid 가 된다. 같은 uid 의 연락처가 이미 있으면(다시 보낸 묶음) 새로 만들지 않는다. 한 묶음 안에서 겹치면 400 VAL_001',
+    example: 'urn:uuid:3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d',
+    maxLength: IMPORT_UID_LENGTH,
+  })
+  @ImportUid()
+  uid!: string;
+}
+
+/** 가져오기 · 확인의 본문 — 1~100명 */
+export class ContactImportBatchDto {
+  @ApiProperty({
+    type: [ContactImportItemDto],
+    minItems: 1,
+    maxItems: MAX_CONTACT_IMPORT_BATCH,
+    description: `가져올 연락처 — 1~${MAX_CONTACT_IMPORT_BATCH}명. 칸 규칙은 연락처 추가(POST /api/contacts)와 같다`,
+  })
+  @ImportList()
+  contacts!: ContactImportItemDto[];
+}
+
+export class ContactImportCheckItemDto {
+  @ApiProperty({
+    description: '보낸 uid',
+    example: 'urn:uuid:3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d',
+  })
+  uid!: string;
+
+  @ApiProperty({
+    description:
+      'new 넣을 연락처 · exists 이미 있는 연락처 — 같은 이메일(앞뒤 공백 · 대소문자 무시)이 내 주소록에 있음, 이메일이 없으면 이름(앞뒤 공백을 뺀 글)과 전화번호의 숫자 모음이 모두 같은 연락처가 있음, 또는 같은 uid 의 연락처가 있음',
+    enum: [...CONTACT_IMPORT_STATUSES],
+    example: 'new',
+  })
+  status!: ContactImportStatus;
+}
+
+/** POST /api/contact-import-checks → 200 */
+export class ContactImportCheckDto implements ContactImportCheck {
+  @ApiProperty({
+    type: [ContactImportCheckItemDto],
+    description: '보낸 차례 그대로 한 줄씩',
+  })
+  items!: ContactImportCheckItemDto[];
+
+  @ApiProperty({
+    description:
+      '더 넣을 수 있는 연락처 수 — 3,000 − 지금 연락처 수 (0 아래로 내려가지 않는다). 화면은 이것으로 넣을 수를 미리 줄인다',
+    example: 2_660,
+  })
+  remaining!: number;
+}
+
+export class ContactImportedDto implements ContactImported {
+  @ApiProperty({
+    description: '보낸 uid',
+    example: 'urn:uuid:3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d',
+  })
+  uid!: string;
+
+  @ApiProperty({
+    description:
+      '연락처 id — 새로 만든 카드, 또는 같은 uid 로 이미 있던 카드(다시 보낸 묶음)',
+    example: 'jw',
+  })
+  id!: string;
+
+  @ApiProperty({
+    type: [String],
+    description:
+      '구성원 500명이 차서 넣지 못한 그룹 id (보낸 groupIds 차례) — 실패가 아니다. 연락처는 만들었고 나머지 그룹에는 넣었다',
+    example: [],
+  })
+  skippedGroupIds!: string[];
+}
+
+/** POST /api/contact-imports → 201 */
+export class ContactImportResultDto implements ContactImportResult {
+  @ApiProperty({
+    type: [ContactImportedDto],
+    description:
+      '넣은 연락처(같은 uid 로 이미 있던 것 포함) — 보낸 차례 그대로. 보낸 uid 가 빠져 있으면 메일 서버가 받지 않은 것이다(화면은 "넣지 못함"으로)',
+  })
+  items!: ContactImportedDto[];
+}
+
+/** POST /api/contact-deletions 의 본문 — 1~500개 · 겹치지 않게 */
+export class ContactDeletionDto {
+  @ApiProperty({
+    type: [String],
+    minItems: 1,
+    maxItems: MAX_CONTACT_DELETIONS,
+    description: `지울 연락처 id — 1~${MAX_CONTACT_DELETIONS}개, 겹치지 않게(겹치면 400 VAL_001)`,
+    example: ['jw', 'jx'],
+  })
+  @DeletionIdList()
+  ids!: string[];
+}
+
+/** POST /api/contact-deletions → 200 */
+export class ContactsDeletedDto implements ContactsDeleted {
+  @ApiProperty({
+    type: [String],
+    description: '지운 연락처 id — 보낸 차례 그대로',
+    example: ['jw'],
+  })
+  deletedIds!: string[];
+
+  @ApiProperty({
+    type: [String],
+    description:
+      '내 주소록에 없는 id — 이미 지움 · 그룹 id 등 (보낸 차례 그대로)',
+    example: ['jx'],
+  })
+  notFoundIds!: string[];
+}

backend/src/modules/file-sharing/file-sharing.repository.ts

@@ -97,6 +97,19 @@ export class FileSharingRepository {
     await this.links.update({ id }, { sentEmailId });
   }
 
+  /** 보낸 때를 앞당긴다 — 취소하지 않았고 지금 보낸 때가 더 늦을 때만, 한 문장으로 (true = 바꿨다) */
+  async moveSentAtEarlier(id: string, sentAt: Date): Promise<boolean> {
+    const result = await this.links
+      .createQueryBuilder()
+      .update(ShareLinkEntity)
+      .set({ sentAt })
+      .where('id = :id', { id })
+      .andWhere('canceled_at IS NULL')
+      .andWhere('sent_at > :sentAt', { sentAt })
+      .execute();
+    return (result.affected ?? 0) > 0;
+  }
+
   /** 취소한 링크로 — 이미 취소했으면 그대로 (true = 이번에 바꿨다) */
   async cancel(
     id: string,

backend/src/modules/file-sharing/file-sharing.service.spec.ts

@@ -91,6 +91,16 @@ class FakeRepository {
     return Promise.resolve();
   }
 
+  /** 실제 표처럼 — 취소하지 않았고 지금 보낸 때가 더 늦을 때만 (조건부 UPDATE 한 문장) */
+  moveSentAtEarlier(id: string, sentAt: Date) {
+    const link = this.records.find((item) => item.link.id === id)?.link;
+    if (!link || link.canceledAt !== null || link.sentAt <= sentAt) {
+      return Promise.resolve(false);
+    }
+    link.sentAt = sentAt;
+    return Promise.resolve(true);
+  }
+
   cancel(id: string, reason: 'send-failed' | 'send-canceled', now: Date) {
     const link = this.records.find((item) => item.link.id === id)?.link;
     if (!link || link.canceledAt !== null) return Promise.resolve(false);
@@ -314,6 +324,34 @@ describe('FileSharingService — 공유 링크 · 공개 내려받기 (11단계)
     expect(await codeOf(() => service.publicLink(token))).toBe('RES_001');
   });
 
+  it('예약 메일을 지금 보냈으면(메일 15단계) 보낸 때를 앞당긴다 — 끝나는 때는 그대로(덩이가 적은 날짜), 취소한 링크 · 더 늦은 시각은 바꾸지 않는다', async () => {
+    const { service, repository } = setup();
+    const scheduled = new Date(Date.now() + 5 * 24 * 60 * 60_000);
+    const created = await service.createMailLink({
+      ownerEmail: ARA,
+      senderName: '김아라',
+      files: [{ id: FILE_A, name: '설계도.dwg', size: CONTENT.length }],
+      sentAt: scheduled,
+      messageId: 'ara.release@arasystem.test',
+    });
+    const { link } = created.record;
+    const expiresAt = link.expiresAt.getTime();
+    const now = new Date();
+
+    await expect(service.markReleased(link.id, now)).resolves.toBe(true);
+    expect(link.sentAt).toEqual(now);
+    expect(link.expiresAt.getTime()).toBe(expiresAt);
+    // 다시 와도(응답을 받지 못한 재시도) 더 늦은 시각으로 되돌리지 않는다
+    await expect(service.markReleased(link.id, scheduled)).resolves.toBe(false);
+    expect(link.sentAt).toEqual(now);
+
+    await service.cancel(created.record, 'send-canceled');
+    await expect(
+      service.markReleased(link.id, new Date(now.getTime() - 1_000)),
+    ).resolves.toBe(false);
+    expect(repository.records).toHaveLength(1);
+  });
+
   describe('파일 응답 (Range · HEAD · 횟수)', () => {
     it('전체 200 — 내려받기 머리글(형식 · 이름 · nosniff · sandbox · no-store · ETag · Accept-Ranges · X-Accel-Buffering)', async () => {
       const { service } = setup();

backend/src/modules/file-sharing/file-sharing.service.ts

@@ -21,6 +21,7 @@ import {
 import type { StoredFileView } from '@/modules/file-storage/file-storage.types';
 import { currentRequestId, traceTag } from '@/shared/logger/request-context';
 import { buildAttachmentDisposition } from '@/shared/utils/content-disposition';
+import { downloadHeaders } from '@/shared/utils/download-headers';
 import { decideRange } from '@/shared/utils/http-range';
 import { kstEndOfDayAfter } from '@/shared/utils/kst-date';
 import { maskEmail } from '@/shared/utils/mask';
@@ -67,10 +68,8 @@ import {
 /** 보낸 링크 목록의 커서 범위 (shared/utils/offset-cursor.ts) */
 const SHARE_LINKS_SCOPE = 'share-links';
 
-/** 파일 응답의 머리글 (계약 4절 "파일 응답") — 형식은 서버가 정한다(늘 내려받기) */
+/** 파일 응답의 형식 (계약 4절 "파일 응답") — 서버가 정한다(늘 내려받기). 나머지 머리글은 shared/utils/download-headers.ts */
 const FILE_CONTENT_TYPE = 'application/octet-stream';
-const FILE_CSP = "default-src 'none'; sandbox";
-const FILE_CACHE_CONTROL = 'private, no-store';
 
 /** 내려받기 — 누가 받나 */
 export interface DownloadOptions {
@@ -200,6 +199,15 @@ export class FileSharingService implements BeforeApplicationShutdown {
     await this.repository.markSent(linkId, sentEmailId);
   }
 
+  /**
+   * 예약한 메일을 지금 보냈다(메일 15단계 — 계약 2절 "보내기 취소 · 예약 발송") — 보낸 때를 실제로 보낸 때로 앞당긴다(보낸 링크 목록 · 공개 화면의 보낸 때).
+   * **끝나는 때는 그대로 둔다** — 보낸 메일의 덩이가 예약 시각으로 센 그 날짜를 이미 적었다. 앞당기면 받는 사람이 본 날짜보다 먼저 끝난다(파일 기간도 그대로라 다시 세지 않는다).
+   * 취소한 링크 · 이미 그보다 앞선 보낸 때는 바꾸지 않는다 (true = 바꿨다)
+   */
+  async markReleased(linkId: string, sentAt: Date): Promise<boolean> {
+    return this.repository.moveSentAtEarlier(linkId, sentAt);
+  }
+
   /**
    * 같은 Idempotency-Key 의 재시도가 처음 메일을 찾았다 — 그 발송이 만든 링크(보낸 메일을 모르는 것)에 보낸 사본을 잇는다.
    * 결과를 모르게 끝난 첫 시도의 링크가 이렇게 제자리를 찾는다 (계약 4절 "링크를 만드는 때")
@@ -634,25 +642,24 @@ export class FileSharingService implements BeforeApplicationShutdown {
     });
   }
 
-  /** 파일 응답의 머리글 (계약 4절 "파일 응답") — 형식 · 이름 · 검증자 · 캐시 · 버퍼링 */
+  /**
+   * 파일 응답의 머리글 (계약 4절 "파일 응답") — 형식 · 이름 · 검증자 · 캐시 · 버퍼링.
+   * 휴대폰 앱 받기와 같은 꼴이다(shared/utils/download-headers.ts — 형식만 다르다)
+   */
   private writeFileHeaders(
     res: Response,
     name: string,
     etag: string,
     lastModified: Date,
   ): void {
-    res.setHeader('Content-Type', FILE_CONTENT_TYPE);
-    res.setHeader('Content-Disposition', buildAttachmentDisposition(name));
-    res.setHeader('X-Content-Type-Options', 'nosniff');
-    res.setHeader('Content-Security-Policy', FILE_CSP);
-    res.setHeader('Cache-Control', FILE_CACHE_CONTROL);
-    res.setHeader('Referrer-Policy', 'no-referrer');
-    res.setHeader('X-Robots-Tag', 'noindex');
-    res.setHeader('Accept-Ranges', 'bytes');
-    res.setHeader('ETag', etag);
-    res.setHeader('Last-Modified', lastModified.toUTCString());
-    // 앞단 nginx · 외부 프록시가 이 응답을 임시 파일에 받아 두지 않게 (느린 받는 사람마다 1GB 까지)
-    res.setHeader('X-Accel-Buffering', 'no');
+    for (const [header, value] of downloadHeaders({
+      contentType: FILE_CONTENT_TYPE,
+      contentDisposition: buildAttachmentDisposition(name),
+      etag,
+      lastModified,
+    })) {
+      res.setHeader(header, value);
+    }
   }
 
   private writeLength(

backend/src/modules/mail-signature/dto/mail-signature.dto.spec.ts

@@ -0,0 +1,121 @@
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+
+import { SIGNATURE_NAME_MAX_LENGTH } from '@/modules/mail-signature/mail-signature.constants';
+import {
+  MailSignatureDefaultsDto,
+  SaveMailSignatureDto,
+  UpdateLegacyMailSignatureDto,
+} from './mail-signature.dto';
+
+/** 전역 ValidationPipe 와 같은 옵션으로 검증한다 (app.setup.ts — stopAtFirstError 만 빼고 — 걸린 규칙을 모두 본다) — 걸린 규칙 이름만 */
+async function constraintsOf(
+  type: new () => object,
+  body: object,
+): Promise<string[]> {
+  const errors = await validate(plainToInstance(type, body), {
+    whitelist: true,
+    forbidNonWhitelisted: true,
+  });
+  return errors.flatMap((error) => Object.keys(error.constraints ?? {}));
+}
+
+describe('서명 만들기 · 고치기 본문 (POST /api/mail-signatures · PUT /api/mail-signatures/{id} — 16단계)', () => {
+  const save = (body: object) => constraintsOf(SaveMailSignatureDto, body);
+
+  it('이름은 앞뒤 공백을 지운 값으로 1~30자(JS 문자열 길이) — 본문 칸은 보내지 않거나 null 이어도 된다', async () => {
+    expect(await save({ name: '대외' })).toEqual([]);
+    expect(
+      await save({ name: '대외', bodyHtml: '<p>김아라</p>', body: '김아라' }),
+    ).toEqual([]);
+    expect(await save({ name: '대외', bodyHtml: null, body: null })).toEqual(
+      [],
+    );
+    expect(await save({ name: 'x'.repeat(SIGNATURE_NAME_MAX_LENGTH) })).toEqual(
+      [],
+    );
+    expect(
+      plainToInstance(SaveMailSignatureDto, { name: '  대외  ' }).name,
+    ).toBe('대외');
+    // 이모지 하나는 2자로 센다 — 화면의 .length 와 같다
+    expect(
+      await save({ name: '🌴'.repeat(SIGNATURE_NAME_MAX_LENGTH / 2) }),
+    ).toEqual([]);
+  });
+
+  it('이름이 비거나(공백뿐 포함) · 30자를 넘거나 · 제어 문자 · 글이 아니면 VAL_001', async () => {
+    expect(await save({ name: '' })).toEqual(['minCodeUnits']);
+    expect(await save({ name: '   ' })).toEqual(['minCodeUnits']);
+    expect(
+      await save({ name: 'x'.repeat(SIGNATURE_NAME_MAX_LENGTH + 1) }),
+    ).toEqual(['maxCodeUnits']);
+    expect(
+      await save({ name: `${'🌴'.repeat(SIGNATURE_NAME_MAX_LENGTH / 2)}x` }),
+    ).toEqual(['maxCodeUnits']);
+    for (const name of ['사내\n영문', '사내\t영문', 'a\u0000']) {
+      expect(await save({ name })).toEqual(['matches']);
+    }
+    // 앞뒤의 공백 · 줄바꿈은 지운 값으로 본다(trim)
+    expect(await save({ name: '\t사내\n' })).toEqual([]);
+    expect(await save({})).toEqual(expect.arrayContaining(['isString']));
+    expect(await save({ name: 1 })).toEqual(
+      expect.arrayContaining(['isString']),
+    );
+  });
+
+  it('본문 칸이 글이 아니거나 모르는 칸(옛 두 표시 포함)이면 VAL_001', async () => {
+    expect(await save({ name: '대외', bodyHtml: 1 })).toEqual(['isString']);
+    expect(await save({ name: '대외', body: [] })).toEqual(['isString']);
+    expect(await save({ name: '대외', isForNew: true })).toEqual([
+      'whitelistValidation',
+    ]);
+  });
+});
+
+describe('메일에 넣을 서명 (PUT /api/mail-signature-defaults — 16단계)', () => {
+  const defaults = (body: object) =>
+    constraintsOf(MailSignatureDefaultsDto, body);
+
+  it('두 키를 모두 보낸다 — 서명 id 또는 null(넣지 않음). 모양은 서비스가 본다(내 서명이 아니면 404)', async () => {
+    const id = '0b6f7c1e-3a52-4c4e-9f0e-2d1f5a7b8c9d';
+    expect(await defaults({ newMessageId: id, replyId: null })).toEqual([]);
+    expect(await defaults({ newMessageId: null, replyId: null })).toEqual([]);
+    expect(await defaults({ newMessageId: 'not-a-uuid', replyId: id })).toEqual(
+      [],
+    );
+  });
+
+  it('빠진 키 · 글이 아닌 값 · 너무 긴 값 · 모르는 칸은 VAL_001', async () => {
+    expect(await defaults({ newMessageId: null })).toEqual(
+      expect.arrayContaining(['isString']),
+    );
+    expect(await defaults({ newMessageId: 1, replyId: null })).toEqual(
+      expect.arrayContaining(['isString']),
+    );
+    expect(
+      await defaults({ newMessageId: 'x'.repeat(65), replyId: null }),
+    ).toEqual(['maxCodeUnits']);
+    expect(
+      await defaults({ newMessageId: null, replyId: null, forwardId: null }),
+    ).toEqual(['whitelistValidation']);
+  });
+});
+
+describe('옛 경로 저장 본문 (PUT /api/mail-signature — 16단계 전의 웹 탭)', () => {
+  it('지금과 같은 네 칸 — 두 표시는 boolean 이어야 한다', async () => {
+    expect(
+      await constraintsOf(UpdateLegacyMailSignatureDto, {
+        bodyHtml: '<p>김아라</p>',
+        body: '김아라',
+        isForNew: true,
+        isForReply: false,
+      }),
+    ).toEqual([]);
+    expect(
+      await constraintsOf(UpdateLegacyMailSignatureDto, {
+        isForNew: 'true',
+        isForReply: true,
+      }),
+    ).toEqual(['isBoolean']);
+  });
+});

backend/src/modules/mail-signature/dto/mail-signature.dto.ts

@@ -1,17 +1,35 @@
+import { applyDecorators } from '@nestjs/common';
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsBoolean, IsOptional, IsString } from 'class-validator';
+import {
+  IsBoolean,
+  IsOptional,
+  IsString,
+  Matches,
+  ValidateIf,
+} from 'class-validator';
 
 import {
+  MaxCodeUnits,
+  MinCodeUnits,
+} from '@/common/decorators/code-units.decorator';
+import { TrimString } from '@/common/decorators/trim-string.decorator';
+import { PageInfoDto } from '@/common/dto/pagination.dto';
+import {
+  SIGNATURES_MAX,
   SIGNATURE_HTML_MAX_LENGTH,
   SIGNATURE_IMAGES_PER_SIGNATURE,
   SIGNATURE_IMAGE_MAX_BYTES,
+  SIGNATURE_NAME_MAX_LENGTH,
   SIGNATURE_TEXT_MAX_LENGTH,
 } from '@/modules/mail-signature/mail-signature.constants';
 import type {
+  LegacyMailSignature,
   MailSignature,
+  MailSignatureDefaults,
   SignatureImage,
 } from '@/modules/mail-signature/mail-signature.types';
 import type { SignatureImageType } from '@/modules/mail-signature/signature-image-format';
+import { SINGLE_LINE_TEXT_PATTERN } from '@/modules/mail/mail.constants';
 
 const IMAGE_TYPES: SignatureImageType[] = [
   'image/png',
@@ -19,24 +37,109 @@ const IMAGE_TYPES: SignatureImageType[] = [
   'image/gif',
 ];
 
-/** PUT /api/mail-signature — 계약 2절 "서명" */
-export class UpdateMailSignatureDto {
+/** 서명 id 칸의 길이 상한 — 서버가 만든 UUID(36자)라 넉넉히. 넘거나 형식이 틀린 id 는 없는 서명과 같다(404 RES_001) */
+const SIGNATURE_ID_MAX_LENGTH = 64;
+
+/** null 은 "넣지 않음"으로 받는다 — 키가 없으면(undefined) 형식 오류다 (전체 교체라 두 키를 모두 보낸다) */
+const unlessNull = (_object: object, value: unknown) => value !== null;
+
+const BODY_HTML_DESCRIPTION =
+  `서명 서식 HTML — 서식 본문과 같은 허용 목록 + 내 서명 그림(<img src="/api/mail-signature/images/{id}" width="1~600" alt="">). ` +
+  `정화한 뒤 ${SIGNATURE_HTML_MAX_LENGTH.toLocaleString('ko-KR')}자 이하, 서로 다른 그림 ${SIGNATURE_IMAGES_PER_SIGNATURE}장까지(넘으면 400 VAL_001). null·빈 문자열이면 서식 서명 없음. ` +
+  '어느 서명도 더는 가리키지 않는 그림은 저장할 때 지운다';
+const BODY_HTML_EXAMPLE =
+  '<p style="margin:0"><strong>김아라</strong> · 아라시스템</p><img src="/api/mail-signature/images/3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d" width="144" alt="">';
+const BODY_DESCRIPTION = `텍스트 서명 — 텍스트 대체 본문에 넣는다. ${SIGNATURE_TEXT_MAX_LENGTH.toLocaleString('ko-KR')}자 이하(JS 문자열 길이, 넘으면 400 VAL_001)`;
+
+/** 서명 이름 — 앞뒤 공백을 뺀 1~30자(JS 문자열 길이), 제어 문자 없음. 검사는 적은 차례대로(형식 → 길이 → 모양) */
+function SignatureName() {
+  return applyDecorators(
+    ApiProperty({
+      description:
+        `서명 이름 — 앞뒤 공백을 뺀 1~${SIGNATURE_NAME_MAX_LENGTH}자(JS 문자열 길이), 제어 문자(줄바꿈 · 탭 등)는 쓸 수 없다. ` +
+        '내 다른 서명과 같은 이름(영문 대소문자 무시)이면 400 VAL_001',
+      example: '대외',
+      minLength: 1,
+      maxLength: SIGNATURE_NAME_MAX_LENGTH,
+    }),
+    TrimString(),
+    IsString({ message: '서명 이름 형식이 올바르지 않습니다.' }),
+    MinCodeUnits(1, { message: '서명 이름을 입력해 주세요.' }),
+    MaxCodeUnits(SIGNATURE_NAME_MAX_LENGTH, {
+      message: `서명 이름은 ${SIGNATURE_NAME_MAX_LENGTH}자 이하로 입력해 주세요.`,
+    }),
+    Matches(SINGLE_LINE_TEXT_PATTERN, {
+      message: '서명 이름에는 줄바꿈 같은 제어 문자를 쓸 수 없습니다.',
+    }),
+  );
+}
+
+/** 「메일에 넣을 서명」 칸 하나 — 내 서명 id 또는 null(넣지 않음). 키는 늘 보낸다 */
+function DefaultSignatureId(description: string) {
+  return applyDecorators(
+    ApiProperty({
+      description: `${description} — 내 서명 id, null 이면 넣지 않음. 내 서명이 아닌 id(없음 · 남의 것 · 형식이 틀림)는 404 RES_001`,
+      nullable: true,
+      type: String,
+      example: '3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d',
+    }),
+    ValidateIf(unlessNull),
+    IsString({ message: '서명을 다시 골라 주세요.' }),
+    MaxCodeUnits(SIGNATURE_ID_MAX_LENGTH, {
+      message: '서명을 다시 골라 주세요.',
+    }),
+  );
+}
+
+/** POST /api/mail-signatures · PUT /api/mail-signatures/{id} — 계약 2절 "서명" (16단계, 전체 교체) */
+export class SaveMailSignatureDto {
+  @SignatureName()
+  name!: string;
+
   @ApiPropertyOptional({
-    description:
-      `서명 서식 HTML — 서식 본문과 같은 허용 목록 + 내 서명 그림(<img src="/api/mail-signature/images/{id}" width="1~600" alt="">). ` +
-      `정화한 뒤 ${SIGNATURE_HTML_MAX_LENGTH.toLocaleString('ko-KR')}자 이하, 서로 다른 그림 ${SIGNATURE_IMAGES_PER_SIGNATURE}장까지(넘으면 400 VAL_001). null·빈 문자열이면 서식 서명 없음. ` +
-      '서명 HTML 이 더는 가리키지 않는 그림은 저장할 때 지운다',
+    description: BODY_HTML_DESCRIPTION,
     nullable: true,
     type: String,
-    example:
-      '<p style="margin:0"><strong>김아라</strong> · 아라시스템</p><img src="/api/mail-signature/images/3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d" width="144" alt="">',
+    example: BODY_HTML_EXAMPLE,
   })
   @IsOptional()
   @IsString({ message: '서명 형식이 올바르지 않습니다.' })
   bodyHtml?: string | null;
 
   @ApiPropertyOptional({
-    description: `텍스트 서명 — 텍스트 대체 본문에 넣는다. ${SIGNATURE_TEXT_MAX_LENGTH.toLocaleString('ko-KR')}자 이하(JS 문자열 길이, 넘으면 400 VAL_001)`,
+    description: BODY_DESCRIPTION,
+    nullable: true,
+    type: String,
+    example: '김아라 · 아라시스템',
+  })
+  @IsOptional()
+  @IsString({ message: '텍스트 서명 형식이 올바르지 않습니다.' })
+  body?: string | null;
+}
+
+/** GET · PUT /api/mail-signature-defaults — 계약 2절 "서명"의 「메일에 넣을 서명」 (16단계) */
+export class MailSignatureDefaultsDto implements MailSignatureDefaults {
+  @DefaultSignatureId('새 메일에 넣는 서명')
+  newMessageId!: string | null;
+
+  @DefaultSignatureId('답장 · 전달에 넣는 서명(인용 위)')
+  replyId!: string | null;
+}
+
+/** PUT /api/mail-signature — 옛 경로(16단계 전의 웹 탭). 「새 메일」 기본 서명의 본문을 바꾸고 두 표시를 기본 둘로 옮긴다 */
+export class UpdateLegacyMailSignatureDto {
+  @ApiPropertyOptional({
+    description: BODY_HTML_DESCRIPTION,
+    nullable: true,
+    type: String,
+    example: BODY_HTML_EXAMPLE,
+  })
+  @IsOptional()
+  @IsString({ message: '서명 형식이 올바르지 않습니다.' })
+  bodyHtml?: string | null;
+
+  @ApiPropertyOptional({
+    description: BODY_DESCRIPTION,
     nullable: true,
     type: String,
     example: '김아라 · 아라시스템',
@@ -45,11 +148,19 @@ export class UpdateMailSignatureDto {
   @IsString({ message: '텍스트 서명 형식이 올바르지 않습니다.' })
   body?: string | null;
 
-  @ApiProperty({ description: '새 메일에 넣는다', example: true })
+  @ApiProperty({
+    description:
+      'true = 이 서명을 새 메일의 기본으로, false = 새 메일에 넣지 않음',
+    example: true,
+  })
   @IsBoolean({ message: '새 메일에 넣을지 여부를 다시 선택해 주세요.' })
   isForNew!: boolean;
 
-  @ApiProperty({ description: '답장·전달에 넣는다 (인용 위)', example: true })
+  @ApiProperty({
+    description:
+      'true = 이 서명을 답장·전달의 기본으로, false = 이 서명이 기본이었으면 넣지 않음(다른 서명이 기본이면 그대로)',
+    example: true,
+  })
   @IsBoolean({ message: '답장·전달에 넣을지 여부를 다시 선택해 주세요.' })
   isForReply!: boolean;
 }
@@ -82,26 +193,86 @@ export class SignatureImageDto implements SignatureImage {
   height!: number;
 }
 
+/** 서명 하나 (16단계) */
 export class MailSignatureDto implements MailSignature {
   @ApiProperty({
-    description: `서명 서식 HTML (정화한 값, ${SIGNATURE_HTML_MAX_LENGTH.toLocaleString('ko-KR')}자 이하) — 저장한 적 없거나 비었으면 null`,
+    description: '서명 id (서버가 만든 UUID)',
+    example: '0b6f7c1e-3a52-4c4e-9f0e-2d1f5a7b8c9d',
+  })
+  id!: string;
+
+  @ApiProperty({ description: '서명 이름 (1~30자)', example: '대외' })
+  name!: string;
+
+  @ApiProperty({
+    description: `서명 서식 HTML (정화한 값, ${SIGNATURE_HTML_MAX_LENGTH.toLocaleString('ko-KR')}자 이하) — 없으면 null`,
     nullable: true,
     type: String,
   })
   bodyHtml!: string | null;
 
   @ApiProperty({
-    description: '텍스트 서명 — 저장한 적 없거나 비었으면 null',
+    description: '텍스트 서명 — 없으면 null',
     nullable: true,
     type: String,
   })
   body!: string | null;
 
-  @ApiProperty({ description: '새 메일에 넣는다 (기본 true)', example: true })
+  @ApiProperty({
+    description: `서명 HTML 이 쓰는 그림 — HTML 에 나온 순서 (${SIGNATURE_IMAGES_PER_SIGNATURE}장까지)`,
+    type: [SignatureImageDto],
+  })
+  images!: SignatureImageDto[];
+
+  @ApiProperty({
+    description: '마지막으로 저장한 시각 (ISO 8601 UTC)',
+    example: '2026-11-10T05:12:00.000Z',
+  })
+  updatedAt!: string;
+}
+
+/** GET /api/mail-signatures — 내 서명 목록 */
+export class MailSignaturePageDto {
+  @ApiProperty({
+    type: [MailSignatureDto],
+    description: `만든 차례 — ${SIGNATURES_MAX}개까지`,
+  })
+  items!: MailSignatureDto[];
+
+  @ApiProperty({
+    type: PageInfoDto,
+    description: '한 번에 모두 내려준다 (hasNext=false, total = 서명 수)',
+  })
+  pageInfo!: PageInfoDto;
+}
+
+/** GET · PUT /api/mail-signature — 옛 경로의 서명 (앱 첫 판 · 16단계 전의 웹 탭) */
+export class LegacyMailSignatureDto implements LegacyMailSignature {
+  @ApiProperty({
+    description: `옛 경로가 보이는 서명(「새 메일」 기본, 없으면 「답장 · 전달」 기본)의 서식 HTML (정화한 값, ${SIGNATURE_HTML_MAX_LENGTH.toLocaleString('ko-KR')}자 이하) — 기본 서명이 둘 다 없거나 비었으면 null`,
+    nullable: true,
+    type: String,
+  })
+  bodyHtml!: string | null;
+
+  @ApiProperty({
+    description:
+      '옛 경로가 보이는 서명(「새 메일」 기본, 없으면 「답장 · 전달」 기본)의 텍스트 — 기본 서명이 둘 다 없거나 비었으면 null',
+    nullable: true,
+    type: String,
+  })
+  body!: string | null;
+
+  @ApiProperty({
+    description:
+      '「새 메일」 기본 서명이 있다 — 없으면 false (그때 본문이 있으면 「답장 · 전달」 기본 서명이다)',
+    example: true,
+  })
   isForNew!: boolean;
 
   @ApiProperty({
-    description: '답장·전달에 넣는다 — 인용 위 (기본 true)',
+    description:
+      '「답장 · 전달」 기본이 이 서명이다 — 「새 메일」 기본과 다른 서명이면 false (앱 첫 판은 그때 답장에 서명을 넣지 않는다)',
     example: true,
   })
   isForReply!: boolean;
@@ -113,7 +284,7 @@ export class MailSignatureDto implements MailSignature {
   images!: SignatureImageDto[];
 
   @ApiProperty({
-    description: '저장한 시각 (ISO 8601 UTC) — 저장한 적 없으면 null',
+    description: '저장한 시각 (ISO 8601 UTC) — 기본 서명이 둘 다 없으면 null',
     nullable: true,
     type: String,
     example: '2026-10-27T05:12:00.000Z',

backend/src/modules/mail-signature/mail-signature.constants.ts

@@ -20,15 +20,28 @@ export const SIGNATURE_IMAGE_MAX_BYTES = INLINE_IMAGE_MAX_BYTES;
  */
 export const SIGNATURE_IMAGE_MAX_DIMENSION = 4096;
 
-/** 서명 하나에 넣을 수 있는 서로 다른 그림 수 — 넘으면 서명 저장(PUT)이 400 VAL_001 */
+/** 서명 하나에 넣을 수 있는 서로 다른 그림 수 — 넘으면 서명 저장(POST · PUT)이 400 VAL_001 */
 export const SIGNATURE_IMAGES_PER_SIGNATURE = 3;
 
 /**
- * 한 사람이 둘 수 있는 서명 그림 수 — 서명에 붙은 것 + 올리고 아직 저장하지 않은 것. 넘으면 올리기가 400 VAL_001.
- * 편집기에서 그림을 넣었다 빼기를 되풀이해도(빼도 저장 전·10분 유예 동안은 남는다) 막히지 않게 서명 한도보다 넉넉히 둔다.
- * 저장하지 않은 그림은 하루 뒤 정리 작업이, 서명이 더는 가리키지 않는 그림은 다음 저장이 지운다.
+ * 한 사람이 둘 수 있는 서명 그림 수 — 모든 서명에 붙은 것 + 올리고 아직 저장하지 않은 것. 넘으면 올리기가 400 VAL_001.
+ * 서명 여럿(16단계 — 10개 × 3장)이 함께 쓰는 칸이라 10 → 20 으로 늘렸다. 편집기에서 그림을 넣었다 빼기를 되풀이해도
+ * (빼도 저장 전·10분 유예 동안은 남는다) 막히지 않게 서명 하나의 한도보다 넉넉히 둔다.
+ * 저장하지 않은 그림은 하루 뒤 정리 작업이, 어느 서명도 더는 가리키지 않는 그림은 다음 저장이 지운다.
  */
-export const SIGNATURE_IMAGES_STORED_MAX = 10;
+export const SIGNATURE_IMAGES_STORED_MAX = 20;
+
+/** 한 사람이 둘 수 있는 서명 수 (16단계) — 11번째 만들기는 400 VAL_001 */
+export const SIGNATURES_MAX = 10;
+
+/** 서명 이름의 길이 — 앞뒤 공백을 뺀 JS 문자열 길이 (16단계). 같은 이름(ASCII 대소문자 무시)은 400 VAL_001 */
+export const SIGNATURE_NAME_MAX_LENGTH = 30;
+
+/**
+ * 옛 서명(한 사람에 하나)을 옮긴 이름 — 마이그레이션 `MultipleMailSignatures` 와 옛 경로 `PUT /api/mail-signature` 가
+ * 기본 서명(「새 메일」 · 「답장 · 전달」)이 둘 다 없을 때 만드는 서명의 이름이다 (계약 2절 "서명" — 16단계)
+ */
+export const LEGACY_SIGNATURE_NAME = '기본 서명';
 
 /** 서명 서식(HTML) 최대 길이 — 정화한 뒤 JS 문자열 길이 */
 export const SIGNATURE_HTML_MAX_LENGTH = 10_000;

backend/src/modules/mail-signature/mail-signature.controller.ts

@@ -37,9 +37,9 @@ import { SkipTransform } from '@/common/decorators/skip-transform.decorator';
 import { BusinessException } from '@/common/errors/business.exception';
 import { JwtAuthGuard } from '@/common/guards/jwt-auth.guard';
 import {
-  MailSignatureDto,
+  LegacyMailSignatureDto,
   SignatureImageDto,
-  UpdateMailSignatureDto,
+  UpdateLegacyMailSignatureDto,
 } from './dto/mail-signature.dto';
 import {
   SIGNATURE_HTML_MAX_LENGTH,
@@ -57,7 +57,8 @@ import { SignatureImageIdPipe } from './signature-image-id.pipe';
 const IMAGE_CONTENT_TYPES = ['image/png', 'image/jpeg', 'image/gif'];
 
 // 메일 서명 (계약 2절 "서명") — 로그인한 직원 자신의 서명·그림만 다룬다.
-// 그림 업로드는 modules/upload 패턴을 따른다 (가드가 multer 보다 먼저 돌아 미인증 요청은 파일을 읽기 전에 막힌다).
+// 16단계부터 서명은 여럿이다(mail-signatures.controller.ts) — 여기의 GET · PUT 은 「새 메일」 기본 서명(없으면 「답장 · 전달」 기본)을 다루는 옛 경로(앱 첫 판 · 옛 웹 탭)이고,
+// 그림 경로는 모든 서명이 함께 쓴다. 그림 업로드는 modules/upload 패턴을 따른다 (가드가 multer 보다 먼저 돌아 미인증 요청은 파일을 읽기 전에 막힌다).
 @ApiTags('Mail')
 @ApiCookieAuth()
 @UseGuards(JwtAuthGuard)
@@ -68,33 +69,37 @@ export class MailSignatureController {
 
   @Get()
   @ApiOperation({
-    summary: '내 서명',
+    summary: '「새 메일」 기본 서명 — 옛 경로 (앱 첫 판)',
     description:
-      '저장한 적 없으면 기본값(bodyHtml·body null, isForNew·isForReply true, images [])을 돌려준다.',
+      '16단계부터 서명은 여럿이다(/api/mail-signatures). 이 경로는 「새 메일」 기본 서명을 15단계까지의 모양으로 준다 — ' +
+      'isForNew = 「새 메일」 기본 서명이 있음, isForReply = 「답장 · 전달」 기본이 같은 서명. ' +
+      '「새 메일」 기본이 없으면 「답장 · 전달」 기본 서명을 isForNew false · isForReply true 로 준다. ' +
+      '둘 다 없으면 { bodyHtml: null, body: null, isForNew: false, isForReply: false, images: [], updatedAt: null }.',
   })
-  @ApiStandardResponse(MailSignatureDto, { description: '서명' })
+  @ApiStandardResponse(LegacyMailSignatureDto, { description: '서명' })
   getSignature(@CurrentUser() user: AuthenticatedUser) {
-    return this.signatures.getSignature(user.email);
+    return this.signatures.getLegacySignature(user.email);
   }
 
   @Put()
   @ApiOperation({
-    summary: '서명 저장 (전체 교체)',
+    summary: '「새 메일」 기본 서명 저장 — 옛 경로 (16단계 전의 웹 탭)',
     description:
+      '옛 GET 이 보이는 서명(「새 메일」 기본, 없으면 「답장 · 전달」 기본, 둘 다 없으면 "기본 서명"이라는 이름의 서명 — 없으면 만든다)의 본문을 바꾸고, isForNew · isForReply 를 「메일에 넣을 서명」 둘로 옮긴다. ' +
       `bodyHtml 은 서식 본문 허용 목록 + 내 서명 그림으로 정화해 저장한다(정화 뒤 ${SIGNATURE_HTML_MAX_LENGTH.toLocaleString('ko-KR')}자 이하), ` +
       `body 는 ${SIGNATURE_TEXT_MAX_LENGTH.toLocaleString('ko-KR')}자 이하, 서로 다른 그림은 ${SIGNATURE_IMAGES_PER_SIGNATURE}장까지(같은 그림 두 번은 한 장). ` +
-      '서명 HTML 이 더는 가리키지 않는 그림은 지운다 — 막 올리고(10분 안) 아직 넣지 않은 그림은 남긴다.',
+      '어느 서명도 더는 가리키지 않는 그림은 지운다 — 막 올리고(10분 안) 아직 넣지 않은 그림은 남긴다.',
   })
-  @ApiStandardResponse(MailSignatureDto, { description: '저장한 서명' })
+  @ApiStandardResponse(LegacyMailSignatureDto, { description: '저장한 서명' })
   @ApiErrorResponse(
     'VAL_001',
-    `형식 오류 · 텍스트 서명 2,000자 초과 · 정화한 서식 서명 10,000자 초과 · 서식 서명이 너무 깊게 중첩됨 · 그림 ${SIGNATURE_IMAGES_PER_SIGNATURE}장 초과`,
+    `형식 오류 · 텍스트 서명 2,000자 초과 · 정화한 서식 서명 10,000자 초과 · 서식 서명이 너무 깊게 중첩됨 · 그림 ${SIGNATURE_IMAGES_PER_SIGNATURE}장 초과 · 서명을 새로 만들어야 하는데 이미 10개`,
   )
   saveSignature(
     @CurrentUser() user: AuthenticatedUser,
-    @Body() dto: UpdateMailSignatureDto,
+    @Body() dto: UpdateLegacyMailSignatureDto,
   ) {
-    return this.signatures.saveSignature(user.email, dto);
+    return this.signatures.saveLegacySignature(user.email, dto);
   }
 
   @Post('images')
@@ -103,8 +108,8 @@ export class MailSignatureController {
     summary: '서명 그림 올리기 (파일 1개)',
     description:
       `PNG·JPEG·GIF 만 — 확장자·MIME·파일 앞부분(내용)을 모두 본다(WebP·SVG 는 받지 않는다). ` +
-      `한 장 ${SIGNATURE_IMAGE_MAX_BYTES.toLocaleString('ko-KR')}바이트 이하. 한 사람이 둘 수 있는 그림은 ${SIGNATURE_IMAGES_STORED_MAX}장까지 — 서명에 붙은 것 + 올리고 아직 저장하지 않은 것 ` +
-      `(서명 하나에는 ${SIGNATURE_IMAGES_PER_SIGNATURE}장 — PUT 이 본다). ` +
+      `한 장 ${SIGNATURE_IMAGE_MAX_BYTES.toLocaleString('ko-KR')}바이트 이하. 한 사람이 둘 수 있는 그림은 ${SIGNATURE_IMAGES_STORED_MAX}장까지 — 모든 서명에 붙은 것 + 올리고 아직 저장하지 않은 것 ` +
+      `(서명 하나에는 ${SIGNATURE_IMAGES_PER_SIGNATURE}장 — 서명 저장이 본다). ` +
       '서명을 저장하지 않으면 하루 뒤 지운다.',
   })
   @ApiConsumes('multipart/form-data')

backend/src/modules/mail-signature/mail-signature.entity.ts

@@ -1,35 +1,63 @@
-import { Column, Entity, PrimaryColumn } from 'typeorm';
+import { Column, Entity, Index, PrimaryColumn } from 'typeorm';
 
 /** 메일 주소 최대 길이 (RFC 5321 경로 한도) — mail.constants 의 MAX_EMAIL_LENGTH 와 같다 */
 const EMAIL_COLUMN_LENGTH = 254;
+/**
+ * 서명 이름 칸 — 이름은 30자(JS 문자열 길이 — SIGNATURE_NAME_MAX_LENGTH)까지라 넉넉히 둔다.
+ * varchar 는 코드 포인트로 세어 JS 길이 30 이면 늘 들어간다 (서로게이트 쌍 하나가 JS 로는 2자 · 여기서는 1자)
+ */
+const NAME_COLUMN_LENGTH = 64;
 
 /**
- * 메일 서명 (계약 2절 "서명") — 사용자마다 하나. 메일 엔진(JMAP Identity)이 아니라 우리 DB 에 둔다 —
- * 엔진을 바꿔도 남고, DB 백업에 함께 들어간다.
- * HTML 은 저장하기 전에 보내는 정화(서명 그림 포함)를 거친 값이다.
+ * 메일 서명 (계약 2절 "서명") — 16단계부터 한 사람에 여러 개(10개까지)다. 메일 엔진(JMAP Identity)이 아니라 우리 DB 에 둔다 —
+ * 엔진을 바꿔도 남고, DB 백업에 함께 들어간다. HTML 은 저장하기 전에 보내는 정화(서명 그림 포함)를 거친 값이다.
+ *
+ * 「메일에 넣을 서명」 둘(새 메일 · 답장과 전달)은 서명 줄의 표시로 둔다 — 한 사람에 하나씩만(부분 유일 인덱스).
+ * 서명을 지우면 표시도 함께 없어져 그 자리는 "넣지 않음"이 된다. 퇴사 마무리는 주소로 이 표의 줄을 지운다(modules/ops/ops-data.service.ts).
+ * 목록은 만든 차례(created_at, 같으면 id)다.
  */
 @Entity({ name: 'mail_signatures' })
+@Index('IDX_mail_signatures_user_email_created_at', ['userEmail', 'createdAt'])
+@Index('UQ_mail_signatures_new_message_default', ['userEmail'], {
+  unique: true,
+  where: '"is_new_message_default"',
+})
+@Index('UQ_mail_signatures_reply_default', ['userEmail'], {
+  unique: true,
+  where: '"is_reply_default"',
+})
 export class MailSignatureEntity {
-  @PrimaryColumn({
+  /** 서버가 만든 UUID (소문자) */
+  @PrimaryColumn({ type: 'uuid' })
+  id!: string;
+
+  @Column({
     name: 'user_email',
     type: 'varchar',
     length: EMAIL_COLUMN_LENGTH,
   })
   userEmail!: string;
 
+  /** 앞뒤 공백을 뺀 1~30자 — 같은 사람 안에서 겹치지 않는다(ASCII 대소문자 무시 — 서비스가 사용자 잠금 안에서 본다) */
+  @Column({ type: 'varchar', length: NAME_COLUMN_LENGTH })
+  name!: string;
+
   @Column({ name: 'body_html', type: 'text', nullable: true })
   bodyHtml!: string | null;
 
   @Column({ name: 'body_text', type: 'text', nullable: true })
   bodyText!: string | null;
 
-  /** 새 메일에 넣는다 */
-  @Column({ name: 'is_for_new', type: 'boolean', default: true })
-  isForNew!: boolean;
+  /** 「새 메일」에 넣는 서명 — 한 사람에 하나까지 */
+  @Column({ name: 'is_new_message_default', type: 'boolean', default: false })
+  isNewMessageDefault!: boolean;
 
-  /** 답장·전달에 넣는다 (인용 위) */
-  @Column({ name: 'is_for_reply', type: 'boolean', default: true })
-  isForReply!: boolean;
+  /** 「답장 · 전달」에 넣는 서명(인용 위) — 한 사람에 하나까지 */
+  @Column({ name: 'is_reply_default', type: 'boolean', default: false })
+  isReplyDefault!: boolean;
+
+  @Column({ name: 'created_at', type: 'timestamptz' })
+  createdAt!: Date;
 
   @Column({ name: 'updated_at', type: 'timestamptz' })
   updatedAt!: Date;

backend/src/modules/mail-signature/mail-signature.module.ts

@@ -12,11 +12,15 @@ import { MailSignatureController } from './mail-signature.controller';
 import { MailSignatureEntity } from './mail-signature.entity';
 import { MailSignatureRepository } from './mail-signature.repository';
 import { MailSignatureService } from './mail-signature.service';
+import {
+  MailSignatureDefaultsController,
+  MailSignaturesController,
+} from './mail-signatures.controller';
 import { SIGNATURE_IMAGE_TYPES_BY_EXTENSION } from './signature-image-format';
 import { SignatureImageStorage } from './signature-image-storage';
 
 /**
- * 메일 서명 모듈 (계약 2절 "서명") — 서명·그림은 서버 DB 와 업로드 볼륨에 둔다.
+ * 메일 서명 모듈 (계약 2절 "서명") — 서명·그림은 서버 DB 와 업로드 볼륨에 둔다. 16단계부터 한 사람에 서명 여러 개(10개까지).
  * 메일 모듈이 발송·임시 저장 때 그림을 쓰도록 서비스를 내보낸다 (이 모듈은 메일 모듈을 가져오지 않는다).
  *
  * 그림 업로드: 한 장 300KB 이하라 메모리에 받는다 — 파일 내용(앞부분)을 본 뒤에만 디스크에 서버가 만든 이름으로 쓴다.
@@ -47,7 +51,13 @@ import { SignatureImageStorage } from './signature-image-storage';
       },
     }),
   ],
-  controllers: [MailSignatureController],
+  controllers: [
+    // 여러 서명 · 「메일에 넣을 서명」 둘 (16단계)
+    MailSignaturesController,
+    MailSignatureDefaultsController,
+    // 옛 경로(「새 메일」 기본 서명 — 앱 첫 판) · 서명 그림
+    MailSignatureController,
+  ],
   providers: [
     MailSignatureRepository,
     {

backend/src/modules/mail-signature/mail-signature.repository.ts

@@ -1,36 +1,75 @@
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { DataSource, In, IsNull, LessThan, type Repository } from 'typeorm';
+import {
+  DataSource,
+  In,
+  IsNull,
+  LessThan,
+  type EntityManager,
+  type Repository,
+} from 'typeorm';
 
 import { MailSignatureImageEntity } from './mail-signature-image.entity';
 import { MailSignatureEntity } from './mail-signature.entity';
+import type { MailSignatureDefaults } from './mail-signature.types';
 
 /**
  * 서명 저장을 사용자별로 차례대로 — `pg_advisory_xact_lock(이 값, hashtext(주소))` (트랜잭션이 끝나면 풀린다).
- * 서명 행이 아직 없을 때도 잠긴다 (행 잠금 FOR UPDATE 는 없는 행을 잠그지 못한다). 첫 인자는 다른 잠금과 섞이지 않게 붙인 이름표 — 'SIG1' 의 ASCII.
+ * 서명 줄이 아직 없을 때도 잠긴다 (행 잠금 FOR UPDATE 는 없는 행을 잠그지 못한다). 첫 인자는 다른 잠금과 섞이지 않게 붙인 이름표 — 'SIG1' 의 ASCII.
  */
 const SIGNATURE_SAVE_LOCK = 0x53494731;
 
-/** 서명 저장 — 잠근 뒤 본 그림으로 저장할 서명을 정한다 (서비스가 그사이 없어진 그림을 서명에서 뺀다) */
-export type PrepareSignature = (
-  images: readonly MailSignatureImageEntity[],
-) => {
-  readonly signature: MailSignatureEntity;
-  readonly referencedImageIds: readonly string[];
-};
+/** 목록 차례 — 만든 차례, 같은 시각이면 id */
+const SIGNATURE_ORDER = { createdAt: 'ASC', id: 'ASC' } as const;
 
-/** 서명 저장 결과 */
-export interface SavedSignature {
-  readonly signature: MailSignatureEntity;
-  /** 저장한 뒤 남은 그 사람의 그림 (올린 순서) */
+/** 잠근 뒤 본 그 사람의 서명 · 그림 */
+export interface SignatureSnapshot {
+  /** 만든 차례 */
+  readonly signatures: readonly MailSignatureEntity[];
+  /** 올린 차례 */
+  readonly images: readonly MailSignatureImageEntity[];
+}
+
+/** 새로 넣을 서명 — 기본 표시는 plan 의 defaults 로만 바꾼다(넣을 때는 늘 꺼짐) */
+export type NewSignatureRow = Omit<
+  MailSignatureEntity,
+  'isNewMessageDefault' | 'isReplyDefault'
+>;
+
+/** 고칠 서명 — 이름 · 본문 · 저장 시각만 */
+export type SignatureRowUpdate = Pick<
+  MailSignatureEntity,
+  'id' | 'name' | 'bodyHtml' | 'bodyText' | 'updatedAt'
+>;
+
+/** 잠근 뒤 정한 바꿀 것 — 서비스가 스냅숏을 보고 정한다(한도 · 이름 겹침은 서비스가 던진다 — 그러면 아무것도 바꾸지 않는다) */
+export interface SignaturePlan {
+  readonly insert?: NewSignatureRow;
+  readonly update?: SignatureRowUpdate;
+  readonly removeId?: string;
+  /** 「메일에 넣을 서명」 둘을 이 값으로 — 없으면 그대로 (지운 서명의 표시는 줄과 함께 없어진다) */
+  readonly defaults?: MailSignatureDefaults;
+  /** 바꾼 뒤 모든 서명 HTML 이 가리키는 그림 (합집합) — 이 밖의 그림은 지운다(막 올린 것은 남긴다) */
+  readonly referencedImageIds: readonly string[];
+}
+
+export type PlanSignatureChange = (
+  snapshot: SignatureSnapshot,
+) => SignaturePlan;
+
+/** 서명 바꾸기 결과 */
+export interface SignatureChangeResult {
+  /** 바꾼 뒤 그 사람의 서명 — 만든 차례, 기본 표시 포함 */
+  readonly signatures: MailSignatureEntity[];
+  /** 바꾼 뒤 남은 그 사람의 그림 (올린 차례) */
   readonly images: MailSignatureImageEntity[];
   /** 지운 그림 — 파일은 부르는 쪽이 커밋 뒤에 지운다 */
   readonly removed: MailSignatureImageEntity[];
 }
 
 /**
- * 서명·서명 그림 표 접근 — 판단(정화·한도·누가 볼 수 있나)은 MailSignatureService 가 한다.
- * 그림을 찾을 때는 늘 주인(user_email)을 함께 조건에 넣는다 — 남의 그림 id 로는 아무것도 나오지 않는다.
+ * 서명·서명 그림 표 접근 — 판단(정화·한도·이름 겹침·누가 볼 수 있나)은 MailSignatureService 가 한다.
+ * 서명 · 그림을 찾을 때는 늘 주인(user_email)을 함께 조건에 넣는다 — 남의 id 로는 아무것도 나오지 않는다.
  */
 @Injectable()
 export class MailSignatureRepository {
@@ -42,8 +81,12 @@ export class MailSignatureRepository {
     private readonly dataSource: DataSource,
   ) {}
 
-  findSignature(userEmail: string): Promise<MailSignatureEntity | null> {
-    return this.signatures.findOneBy({ userEmail });
+  /** 그 사람의 서명 — 만든 차례 */
+  listSignatures(userEmail: string): Promise<MailSignatureEntity[]> {
+    return this.signatures.find({
+      where: { userEmail },
+      order: SIGNATURE_ORDER,
+    });
   }
 
   /** 그 사람의 그림 — 올린 순서대로 */
@@ -70,31 +113,62 @@ export class MailSignatureRepository {
   }
 
   /**
-   * 서명을 저장한다 — 한 트랜잭션에서, 사용자별로 차례대로 (두 탭이 동시에 저장해도 서로의 그림을 엉뚱하게 지우지 않게).
-   * 1) 사용자 잠금 2) 그 사람의 그림을 잠가 읽는다(FOR UPDATE — 정리 작업이 그사이 지우지 못한다) 3) `prepare` 가 저장할 서명을 정한다
-   * 4) 서명을 넣거나 고치고, 서명이 가리키는 그림은 붙은 것으로 표시하고, 가리키지 않는 그림은 지운다 —
-   *    다만 한 번도 저장하지 않은 그림 중 `keepUploadedAfter` 뒤에 올린 것은 남긴다 (막 올린 그림 — SIGNATURE_IMAGE_UPLOAD_GRACE_MS).
+   * 서명을 바꾼다(만들기 · 고치기 · 지우기 · 기본 바꾸기) — 한 트랜잭션에서, 사용자별로 차례대로 (두 탭이 동시에 저장해도 서로의 그림을 엉뚱하게 지우지 않게).
+   * 1) 사용자 잠금 2) 그 사람의 서명과 그림을 읽는다(그림은 FOR UPDATE — 정리 작업이 그사이 지우지 못한다) 3) `plan` 이 바꿀 것을 정한다
+   * 4) 넣기 · 고치기 · 지우기 → 기본 표시(끄고 나서 켠다 — 부분 유일 인덱스는 줄마다 바로 보므로) →
+   *    모든 서명이 가리키는 그림은 붙은 것으로 표시하고, 어느 서명도 가리키지 않는 그림은 지운다 —
+   *    다만 한 번도 저장하지 않은 그림 중 `keepUploadedAfter` 뒤에 올린 것은 남긴다 (막 올린 그림 — SIGNATURE_IMAGE_UPLOAD_GRACE_MS)
+   * 5) 바꾼 뒤의 서명을 다시 읽어 돌려준다
    */
-  saveSignature(
+  change(
     userEmail: string,
-    prepare: PrepareSignature,
+    plan: PlanSignatureChange,
     now: Date,
     keepUploadedAfter: Date,
-  ): Promise<SavedSignature> {
+  ): Promise<SignatureChangeResult> {
     return this.dataSource.transaction(async (manager) => {
       await manager.query('SELECT pg_advisory_xact_lock($1, hashtext($2))', [
         SIGNATURE_SAVE_LOCK,
         userEmail,
       ]);
+      const signatures = await manager.find(MailSignatureEntity, {
+        where: { userEmail },
+        order: SIGNATURE_ORDER,
+      });
       const images = await manager.find(MailSignatureImageEntity, {
         where: { userEmail },
         order: { createdAt: 'ASC' },
         lock: { mode: 'pessimistic_write' },
       });
-      const { signature, referencedImageIds } = prepare(images);
-      await manager.upsert(MailSignatureEntity, signature, ['userEmail']);
+      const next = plan({ signatures, images });
 
-      const referenced = new Set(referencedImageIds);
+      if (next.insert) {
+        await manager.insert(MailSignatureEntity, {
+          ...next.insert,
+          userEmail,
+          isNewMessageDefault: false,
+          isReplyDefault: false,
+        });
+      }
+      if (next.update) {
+        const { id, name, bodyHtml, bodyText, updatedAt } = next.update;
+        await manager.update(
+          MailSignatureEntity,
+          { id, userEmail },
+          { name, bodyHtml, bodyText, updatedAt },
+        );
+      }
+      if (next.removeId) {
+        await manager.delete(MailSignatureEntity, {
+          id: next.removeId,
+          userEmail,
+        });
+      }
+      if (next.defaults) {
+        await this.applyDefaults(manager, userEmail, next.defaults);
+      }
+
+      const referenced = new Set(next.referencedImageIds);
       const attach = images
         .filter(
           (image) => referenced.has(image.id) && image.attachedAt === null,
@@ -105,7 +179,6 @@ export class MailSignatureRepository {
           !referenced.has(image.id) &&
           (image.attachedAt !== null || image.createdAt <= keepUploadedAfter),
       );
-
       if (attach.length > 0) {
         await manager.update(
           MailSignatureImageEntity,
@@ -118,9 +191,13 @@ export class MailSignatureRepository {
           id: In(stale.map((image) => image.id)),
         });
       }
+
       const attached = new Set(attach);
       return {
-        signature,
+        signatures: await manager.find(MailSignatureEntity, {
+          where: { userEmail },
+          order: SIGNATURE_ORDER,
+        }),
         images: images
           .filter((image) => !stale.includes(image))
           .map((image) =>
@@ -131,6 +208,33 @@ export class MailSignatureRepository {
     });
   }
 
+  /**
+   * 기본 표시를 그 값으로 — 칸마다 먼저 다른 줄의 표시를 끄고 그 줄을 켠다(한 문장으로 바꾸면 줄마다 보는 유일 인덱스에 걸릴 수 있다).
+   * id 는 서비스가 그 사람의 서명인지 본 값이다 (주인 조건도 함께 건다)
+   */
+  private async applyDefaults(
+    manager: EntityManager,
+    userEmail: string,
+    defaults: MailSignatureDefaults,
+  ): Promise<void> {
+    const columns = [
+      ['is_new_message_default', defaults.newMessageId],
+      ['is_reply_default', defaults.replyId],
+    ] as const;
+    for (const [column, id] of columns) {
+      await manager.query(
+        `UPDATE "mail_signatures" SET "${column}" = false WHERE "user_email" = $1 AND "${column}" AND "id" IS DISTINCT FROM $2::uuid`,
+        [userEmail, id],
+      );
+      if (id !== null) {
+        await manager.query(
+          `UPDATE "mail_signatures" SET "${column}" = true WHERE "user_email" = $1 AND "id" = $2::uuid AND NOT "${column}"`,
+          [userEmail, id],
+        );
+      }
+    }
+  }
+
   /** 서명에 붙지 않은 채 `before` 전에 올린 그림 (정리 작업용 — 부분 인덱스를 탄다) */
   findUnattachedBefore(before: Date): Promise<MailSignatureImageEntity[]> {
     return this.images.find({

backend/src/modules/mail-signature/mail-signature.service.spec.ts

@@ -8,6 +8,8 @@ import { BusinessException } from '@/common/errors/business.exception';
 import { MAX_BODY_HTML_LENGTH } from '@/modules/mail/mail.constants';
 import { MailSignatureImageEntity } from './mail-signature-image.entity';
 import {
+  LEGACY_SIGNATURE_NAME,
+  SIGNATURES_MAX,
   SIGNATURE_IMAGES_PER_SIGNATURE,
   SIGNATURE_IMAGES_STORED_MAX,
   SIGNATURE_IMAGE_MAX_BYTES,
@@ -17,34 +19,37 @@ import {
 import { MailSignatureEntity } from './mail-signature.entity';
 import type {
   MailSignatureRepository,
-  PrepareSignature,
-  SavedSignature,
+  PlanSignatureChange,
+  SignatureChangeResult,
+  SignaturePlan,
 } from './mail-signature.repository';
 import { MailSignatureService } from './mail-signature.service';
+import type { MailSignatureDefaults } from './mail-signature.types';
 import { SignatureImageStorage } from './signature-image-storage';
 
 const ARA = 'ara.kim@arasystem.test';
 const DOYUN = 'doyun.lee@arasystem.test';
 const src = (id: string) => `/api/mail-signature/images/${id}`;
+const NOT_MINE = '11111111-1111-4111-8111-111111111111';
 
 /**
- * 표 대역 — MailSignatureRepository 와 같은 판단(주인 조건·저장 때 지울 그림)을 메모리에서 한다.
- * 실제 SQL(트랜잭션·부분 인덱스)은 e2e 가 본다.
+ * 표 대역 — MailSignatureRepository 와 같은 판단(주인 조건 · 기본 표시 · 바꾼 뒤 지울 그림)을 메모리에서 한다.
+ * 실제 SQL(트랜잭션 · 사용자 잠금 · 부분 유일 인덱스)은 e2e 가 본다.
  */
 class FakeRepository {
-  readonly signatures = new Map<string, MailSignatureEntity>();
+  signatures: MailSignatureEntity[] = [];
   images: MailSignatureImageEntity[] = [];
   /** 다음 insertImage 를 실패시킨다 */
   failNextInsert = false;
-  /** 다음 저장이 잠그기 직전에 이 그림이 지워진다 (다른 탭의 저장·정리 작업이 먼저 끝난 경우) */
-  deletedBeforeNextSave: string | null = null;
-  readonly saveCalls: {
-    referenced: readonly string[];
+  /** 다음 바꾸기가 잠그기 직전에 이 그림이 지워진다 (다른 탭의 저장·정리 작업이 먼저 끝난 경우) */
+  deletedBeforeNextChange: string | null = null;
+  readonly changeCalls: {
+    plan: SignaturePlan;
     keepUploadedAfter: Date;
   }[] = [];
 
-  findSignature(user: string): Promise<MailSignatureEntity | null> {
-    return Promise.resolve(this.signatures.get(user) ?? null);
+  listSignatures(user: string): Promise<MailSignatureEntity[]> {
+    return Promise.resolve(this.mine(user).map((row) => ({ ...row })));
   }
 
   listImages(user: string): Promise<MailSignatureImageEntity[]> {
@@ -76,38 +81,91 @@ class FakeRepository {
     return Promise.resolve();
   }
 
-  saveSignature(
+  change(
     user: string,
-    prepare: PrepareSignature,
+    plan: PlanSignatureChange,
     now: Date,
     keepUploadedAfter: Date,
-  ): Promise<SavedSignature> {
-    if (this.deletedBeforeNextSave) {
-      const gone = this.deletedBeforeNextSave;
-      this.deletedBeforeNextSave = null;
+  ): Promise<SignatureChangeResult> {
+    if (this.deletedBeforeNextChange) {
+      const gone = this.deletedBeforeNextChange;
+      this.deletedBeforeNextChange = null;
       this.images = this.images.filter((row) => row.id !== gone);
     }
-    const mine = this.images.filter((row) => row.userEmail === user);
-    const { signature, referencedImageIds: referenced } = prepare(mine);
-    this.saveCalls.push({ referenced, keepUploadedAfter });
-    this.signatures.set(signature.userEmail, signature);
-    for (const row of mine) {
-      if (referenced.includes(row.id) && row.attachedAt === null) {
+    const images = this.images.filter((row) => row.userEmail === user);
+    let next: SignaturePlan;
+    try {
+      next = plan({
+        signatures: this.mine(user).map((row) => ({ ...row })),
+        images,
+      });
+    } catch (error) {
+      // 정한 것을 던지면(한도 · 이름 겹침) 아무것도 바꾸지 않는다 — 실제 표는 트랜잭션을 되돌린다
+      return Promise.reject(
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    }
+    this.changeCalls.push({ plan: next, keepUploadedAfter });
+
+    if (next.insert) {
+      this.signatures.push({
+        ...next.insert,
+        isNewMessageDefault: false,
+        isReplyDefault: false,
+      });
+    }
+    if (next.update) {
+      const { id, name, bodyHtml, bodyText, updatedAt } = next.update;
+      this.signatures = this.signatures.map((row) =>
+        row.id === id && row.userEmail === user
+          ? { ...row, name, bodyHtml, bodyText, updatedAt }
+          : row,
+      );
+    }
+    if (next.removeId) {
+      this.signatures = this.signatures.filter(
+        (row) => !(row.id === next.removeId && row.userEmail === user),
+      );
+    }
+    if (next.defaults) this.applyDefaults(user, next.defaults);
+
+    const referenced = new Set(next.referencedImageIds);
+    for (const row of images) {
+      if (referenced.has(row.id) && row.attachedAt === null) {
         row.attachedAt = now;
       }
     }
-    const stale = mine.filter(
+    const stale = images.filter(
       (row) =>
-        !referenced.includes(row.id) &&
+        !referenced.has(row.id) &&
         (row.attachedAt !== null || row.createdAt <= keepUploadedAfter),
     );
     this.images = this.images.filter((row) => !stale.includes(row));
     return Promise.resolve({
-      signature,
-      images: mine.filter((row) => !stale.includes(row)),
+      signatures: this.mine(user).map((row) => ({ ...row })),
+      images: images.filter((row) => !stale.includes(row)),
       removed: stale,
     });
   }
+
+  /** 만든 차례 (서비스가 사람마다 만든 시각을 늘 늘려 준다) */
+  private mine(user: string): MailSignatureEntity[] {
+    return this.signatures
+      .filter((row) => row.userEmail === user)
+      .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+  }
+
+  private applyDefaults(user: string, defaults: MailSignatureDefaults): void {
+    this.signatures = this.signatures.map((row) =>
+      row.userEmail === user
+        ? {
+            ...row,
+            isNewMessageDefault: row.id === defaults.newMessageId,
+            isReplyDefault: row.id === defaults.replyId,
+          }
+        : row,
+    );
+  }
 }
 
 describe('MailSignatureService', () => {
@@ -139,7 +197,7 @@ describe('MailSignatureService', () => {
   ): Promise<MailSignatureImageEntity> {
     const id =
       overrides.id ??
-      `0000000${repository.images.length}-0000-4000-8000-000000000000`;
+      `${String(repository.images.length).padStart(8, '0')}-0000-4000-8000-000000000000`;
     const row: MailSignatureImageEntity = {
       id,
       userEmail: ARA,
@@ -157,6 +215,10 @@ describe('MailSignatureService', () => {
     return row;
   }
 
+  /** 서명 하나를 만든다 (이름 · 텍스트만) */
+  const create = (name: string, extra: { bodyHtml?: string | null } = {}) =>
+    service.createSignature(ARA, { name, body: `${name} 서명`, ...extra });
+
   beforeEach(() => {
     dir = mkdtempSync(join(tmpdir(), 'signature-images-'));
     repository = new FakeRepository();
@@ -175,110 +237,269 @@ describe('MailSignatureService', () => {
     rmSync(dir, { recursive: true, force: true });
   });
 
-  it('저장한 적 없으면 기본값을 돌려준다', async () => {
-    await expect(service.getSignature(ARA)).resolves.toEqual({
-      bodyHtml: null,
-      body: null,
-      isForNew: true,
-      isForReply: true,
-      images: [],
-      updatedAt: null,
+  describe('여러 서명 (16단계)', () => {
+    it('서명이 없으면 빈 목록 · 기본 둘 null — 첫 서명은 두 곳의 기본이 되고, 다음 서명은 기본을 바꾸지 않는다', async () => {
+      await expect(service.listSignatures(ARA)).resolves.toEqual({
+        items: [],
+        pageInfo: { hasNext: false, nextCursor: null, total: 0 },
+      });
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: null,
+        replyId: null,
+      });
+
+      const first = await create('사내');
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: first.id,
+        replyId: first.id,
+      });
+
+      const second = await create('대외');
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: first.id,
+        replyId: first.id,
+      });
+      const list = await service.listSignatures(` ${ARA.toUpperCase()} `);
+      expect(list.items.map((item) => [item.id, item.name])).toEqual([
+        [first.id, '사내'],
+        [second.id, '대외'],
+      ]);
+      expect(list.pageInfo).toEqual({
+        hasNext: false,
+        nextCursor: null,
+        total: 2,
+      });
+      // 다른 사람의 서명은 따로다 — 그 사람의 첫 서명도 그 사람의 기본이 된다
+      const doyun = await service.createSignature(DOYUN, { name: '사내' });
+      await expect(service.getDefaults(DOYUN)).resolves.toEqual({
+        newMessageId: doyun.id,
+        replyId: doyun.id,
+      });
     });
-  });
 
-  describe('저장', () => {
-    it('서식 서명은 보내는 정화를 거쳐 저장한다 — 내 그림만 남고, 서명이 쓰는 그림을 함께 돌려준다', async () => {
+    it('서식은 보내는 정화를 거쳐 저장한다 — 내 그림만 남고, 서명이 쓰는 그림 · 저장 시각을 함께 돌려준다', async () => {
       const mine = await storedImage();
-      const html = `<p onclick="x()"><strong>김아라</strong><script>alert(1)</script></p><img src="${src(mine.id)}" width="144" alt="" style="border:0"><img src="${src('11111111-1111-4111-8111-111111111111')}">`;
+      const html = `<p onclick="x()"><strong>김아라</strong><script>alert(1)</script></p><img src="${src(mine.id)}" width="144" alt="" style="border:0"><img src="${src(NOT_MINE)}">`;
 
-      const saved = await service.saveSignature(` ${ARA.toUpperCase()} `, {
+      const saved = await service.createSignature(ARA, {
+        name: '대외',
         bodyHtml: html,
         body: '김아라 · 아라시스템',
-        isForNew: true,
-        isForReply: false,
       });
 
       expect(saved).toEqual({
+        id: expect.stringMatching(/^[0-9a-f-]{36}$/) as string,
+        name: '대외',
         bodyHtml: `<p><strong>김아라</strong></p><img src="${src(mine.id)}" width="144" alt="" />`,
         body: '김아라 · 아라시스템',
-        isForNew: true,
-        isForReply: false,
         images: [
           { id: mine.id, type: 'image/png', size: 33, width: 10, height: 10 },
         ],
         updatedAt: expect.any(String) as string,
       });
-      // 주소는 소문자로 모은다 — 같은 사람의 서명이 둘로 나뉘지 않게
-      expect(repository.signatures.has(ARA)).toBe(true);
-      expect(repository.saveCalls[0].referenced).toEqual([mine.id]);
-      await expect(service.getSignature(ARA)).resolves.toEqual(saved);
+      expect(repository.changeCalls[0].plan.referencedImageIds).toEqual([
+        mine.id,
+      ]);
+      expect((await service.listSignatures(ARA)).items).toEqual([saved]);
     });
 
-    it('막 올린 그림(10분 안)은 서명에 없어도 남기도록 기준 시각을 넘긴다 — 올리기와 저장이 엇갈려도 편집기의 그림이 사라지지 않게', async () => {
-      const before = Date.now();
+    it(`${SIGNATURES_MAX}개까지 — 11번째는 400 VAL_001, 같은 이름(영문 대소문자 무시)도 VAL_001 — 아무것도 저장하지 않는다`, async () => {
+      await create('Office');
+      expect(await failureOf(() => create('office'))).toEqual({
+        code: 'VAL_001',
+        reason: 'signature-name-taken',
+      });
+      // 영문 밖의 글자는 대소문자를 가리지 않고 그대로 견준다
+      await expect(create('ÖFFICE')).resolves.toMatchObject({ name: 'ÖFFICE' });
+      for (let index = 3; index <= SIGNATURES_MAX; index += 1) {
+        await create(`서명 ${index}`);
+      }
+      const before = repository.signatures.length;
+      expect(await failureOf(() => create('열한 번째'))).toEqual({
+        code: 'VAL_001',
+        reason: 'too-many-signatures',
+      });
+      expect(repository.signatures).toHaveLength(before);
+    });
 
-      await service.saveSignature(ARA, {
-        bodyHtml: null,
-        body: null,
-        isForNew: true,
-        isForReply: true,
+    it('고치기는 이름 · 본문을 바꾸고 기본 표시는 그대로 — 다른 서명과 같은 이름은 VAL_001, 자기 이름(대소문자만 바꿈)은 된다', async () => {
+      const a = await create('사내');
+      const b = await create('대외');
+
+      const updated = await service.updateSignature(ARA, a.id.toUpperCase(), {
+        name: '사내 (새)',
+        body: '바꾼 서명',
+        bodyHtml: '<p>바꾼 서명</p>',
+      });
+      expect(updated).toMatchObject({
+        id: a.id,
+        name: '사내 (새)',
+        body: '바꾼 서명',
+        bodyHtml: '<p>바꾼 서명</p>',
+      });
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: a.id,
+        replyId: a.id,
       });
 
-      const { keepUploadedAfter } = repository.saveCalls[0];
+      expect(
+        await failureOf(() =>
+          service.updateSignature(ARA, b.id, { name: '사내 (새)' }),
+        ),
+      ).toEqual({ code: 'VAL_001', reason: 'signature-name-taken' });
+      await expect(
+        service.updateSignature(ARA, b.id, { name: '대외' }),
+      ).resolves.toMatchObject({ name: '대외', body: null, bodyHtml: null });
+    });
+
+    it('없는 서명 · 남의 서명은 RES_001 — 고치기 · 지우기 · 기본 고르기 모두, 아무것도 바꾸지 않는다', async () => {
+      const mine = await create('사내');
+      const doyuns = await service.createSignature(DOYUN, { name: '대외' });
+
+      for (const id of [doyuns.id, NOT_MINE, 'not-a-uuid']) {
+        expect(
+          await failureOf(() =>
+            service.updateSignature(ARA, id, { name: '바꿈' }),
+          ),
+        ).toEqual({ code: 'RES_001', reason: 'signature-not-found' });
+        expect(await failureOf(() => service.deleteSignature(ARA, id))).toEqual(
+          { code: 'RES_001', reason: 'signature-not-found' },
+        );
+        expect(
+          await failureOf(() =>
+            service.setDefaults(ARA, { newMessageId: mine.id, replyId: id }),
+          ),
+        ).toEqual({ code: 'RES_001', reason: 'signature-not-found' });
+      }
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: mine.id,
+        replyId: mine.id,
+      });
+      expect(repository.signatures).toHaveLength(2);
+    });
+
+    it('기본 고르기 — 두 곳을 따로 · 같은 서명 · 넣지 않음(null)으로, 한 사람에 하나씩', async () => {
+      const a = await create('사내');
+      const b = await create('대외');
+
+      await expect(
+        service.setDefaults(ARA, { newMessageId: b.id, replyId: a.id }),
+      ).resolves.toEqual({ newMessageId: b.id, replyId: a.id });
+      await expect(
+        service.setDefaults(ARA, {
+          newMessageId: null,
+          replyId: b.id.toUpperCase(),
+        }),
+      ).resolves.toEqual({ newMessageId: null, replyId: b.id });
+      expect(
+        repository.signatures.filter((row) => row.isReplyDefault),
+      ).toHaveLength(1);
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: null,
+        replyId: b.id,
+      });
+    });
+
+    it('지우면 그 서명을 기본으로 쓰던 곳은 넣지 않음 — 다른 서명이 저절로 기본이 되지 않는다', async () => {
+      const a = await create('사내');
+      const b = await create('대외');
+      await service.setDefaults(ARA, { newMessageId: a.id, replyId: b.id });
+
+      await service.deleteSignature(ARA, a.id);
+
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: null,
+        replyId: b.id,
+      });
+      expect(
+        (await service.listSignatures(ARA)).items.map((item) => item.id),
+      ).toEqual([b.id]);
+    });
+
+    it('그림 정리는 모든 서명 HTML 의 합집합 — 다른 서명이 쓰는 그림은 남기고, 지운 서명에만 쓰던 그림은 표 · 파일에서 지운다', async () => {
+      const shared = await storedImage();
+      const onlyA = await storedImage();
+      // 막 올린 그림 — 사내를 저장할 때는 아직 어느 서명에도 없지만 남는다(10분 안)
+      const onlyB = await storedImage({ createdAt: new Date() });
+      const img = (id: string) => `<img src="${src(id)}" width="96">`;
+      const a = await create('사내', {
+        bodyHtml: `${img(shared.id)}${img(onlyA.id)}`,
+      });
+      const b = await create('대외', {
+        bodyHtml: `${img(shared.id)}${img(onlyB.id)}`,
+      });
+      expect(repository.images.map((row) => row.id)).toEqual([
+        shared.id,
+        onlyA.id,
+        onlyB.id,
+      ]);
+
+      // a 에서 shared 를 빼도 b 가 쓰므로 남는다
+      await service.updateSignature(ARA, a.id, {
+        name: '사내',
+        bodyHtml: img(onlyA.id),
+      });
+      expect(repository.images.map((row) => row.id)).toEqual([
+        shared.id,
+        onlyA.id,
+        onlyB.id,
+      ]);
+
+      // a 를 지우면 a 에만 있던 그림이 사라진다
+      await service.deleteSignature(ARA, a.id);
+      expect(repository.images.map((row) => row.id)).toEqual([
+        shared.id,
+        onlyB.id,
+      ]);
+      expect(existsSync(join(dir, onlyA.fileName))).toBe(false);
+      expect(existsSync(join(dir, shared.fileName))).toBe(true);
+
+      // 남은 서명이 그림을 모두 빼면 둘 다 지운다
+      await service.updateSignature(ARA, b.id, { name: '대외', body: '글만' });
+      expect(repository.images).toEqual([]);
+    });
+
+    it('막 올린 그림(10분 안)은 어느 서명에도 없어도 남기도록 기준 시각을 넘긴다 — 올리기와 저장이 엇갈려도 편집기의 그림이 사라지지 않게', async () => {
+      const before = Date.now();
+      const fresh = await storedImage({ createdAt: new Date() });
+
+      await create('사내');
+
+      const { keepUploadedAfter } = repository.changeCalls[0];
       expect(keepUploadedAfter.getTime()).toBeGreaterThanOrEqual(
         before - SIGNATURE_IMAGE_UPLOAD_GRACE_MS,
       );
       expect(keepUploadedAfter.getTime()).toBeLessThanOrEqual(
         Date.now() - SIGNATURE_IMAGE_UPLOAD_GRACE_MS,
       );
+      expect(repository.images.map((row) => row.id)).toEqual([fresh.id]);
     });
 
     it('잠그기 전에 다른 저장·정리 작업이 지운 그림은 서명에서 뺀다 — 없는 그림을 가리키는 서명을 남기지 않는다', async () => {
       const kept = await storedImage();
       const gone = await storedImage();
-      repository.deletedBeforeNextSave = gone.id;
+      repository.deletedBeforeNextChange = gone.id;
 
-      const saved = await service.saveSignature(ARA, {
+      const saved = await create('사내', {
         bodyHtml: `<p>서명</p><img src="${src(kept.id)}" width="96"><img src="${src(gone.id)}" width="96">`,
-        body: null,
-        isForNew: true,
-        isForReply: true,
       });
 
       expect(saved.bodyHtml).toBe(
         `<p>서명</p><img src="${src(kept.id)}" width="96" />`,
       );
       expect(saved.images.map((image) => image.id)).toEqual([kept.id]);
-      expect(repository.saveCalls[0].referenced).toEqual([kept.id]);
 
       // 그림만 있던 서명에서 그림이 모두 사라지면 서식 서명이 없다
-      repository.deletedBeforeNextSave = kept.id;
-      const empty = await service.saveSignature(ARA, {
+      repository.deletedBeforeNextChange = kept.id;
+      const empty = await service.updateSignature(ARA, saved.id, {
+        name: '사내',
         bodyHtml: `<img src="${src(kept.id)}">`,
         body: '텍스트 서명',
-        isForNew: true,
-        isForReply: true,
       });
       expect(empty.bodyHtml).toBeNull();
       expect(empty.body).toBe('텍스트 서명');
     });
 
-    it('서명이 더는 가리키지 않는 그림은 표와 파일에서 지운다', async () => {
-      const kept = await storedImage({ attachedAt: new Date() });
-      const dropped = await storedImage({ attachedAt: new Date() });
-
-      await service.saveSignature(ARA, {
-        bodyHtml: `<img src="${src(kept.id)}">`,
-        body: null,
-        isForNew: true,
-        isForReply: true,
-      });
-
-      expect(repository.images.map((row) => row.id)).toEqual([kept.id]);
-      expect(existsSync(join(dir, kept.fileName))).toBe(true);
-      expect(existsSync(join(dir, dropped.fileName))).toBe(false);
-    });
-
     it('지운 그림의 파일을 지우지 못해도 저장은 끝난다 — 경고만 (남은 파일은 정리 작업이 지운다)', async () => {
       const dropped = await storedImage({ attachedAt: new Date() });
       jest
@@ -286,12 +507,7 @@ describe('MailSignatureService', () => {
         .mockRejectedValue(new Error('EACCES: permission denied'));
 
       await expect(
-        service.saveSignature(ARA, {
-          bodyHtml: '<p>그림 없음</p>',
-          body: null,
-          isForNew: true,
-          isForReply: true,
-        }),
+        create('사내', { bodyHtml: '<p>그림 없음</p>' }),
       ).resolves.toMatchObject({ bodyHtml: '<p>그림 없음</p>', images: [] });
       expect(repository.images).not.toContainEqual(dropped);
       expect(warnSpy).toHaveBeenCalledWith(
@@ -300,12 +516,12 @@ describe('MailSignatureService', () => {
     });
 
     it('빈 서식·텍스트, 정화해서 비는 서식은 null 로 저장한다', async () => {
+      const row = await create('사내');
       for (const bodyHtml of ['', '<script>x()</script>', null, undefined]) {
-        const saved = await service.saveSignature(ARA, {
+        const saved = await service.updateSignature(ARA, row.id, {
+          name: '사내',
           bodyHtml,
           body: '',
-          isForNew: false,
-          isForReply: true,
         });
         expect(saved.bodyHtml).toBeNull();
         expect(saved.body).toBeNull();
@@ -322,27 +538,22 @@ describe('MailSignatureService', () => {
         images.push(await storedImage());
       }
       const img = (id: string) => `<img src="${src(id)}" width="96">`;
-      const save = (bodyHtml: string) =>
-        service.saveSignature(ARA, {
-          bodyHtml,
-          body: null,
-          isForNew: true,
-          isForReply: true,
-        });
 
       expect(
         await failureOf(() =>
-          save(images.map((image) => img(image.id)).join('')),
+          create('사내', {
+            bodyHtml: images.map((image) => img(image.id)).join(''),
+          }),
         ),
       ).toEqual({ code: 'VAL_001', reason: 'signature-too-many-images' });
-      expect(repository.saveCalls).toHaveLength(0);
+      expect(repository.changeCalls).toHaveLength(0);
 
       // 세 장 + 같은 그림 한 번 더 + 남의 그림 — 서로 다른 내 그림은 세 장이다
       const [a, b, c] = images;
-      const saved = await save(
-        [a, b, c, a].map((image) => img(image.id)).join('') +
-          img('11111111-1111-4111-8111-111111111111'),
-      );
+      const saved = await create('사내', {
+        bodyHtml:
+          [a, b, c, a].map((image) => img(image.id)).join('') + img(NOT_MINE),
+      });
       expect(saved.images.map((image) => image.id)).toEqual([a.id, b.id, c.id]);
     });
 
@@ -363,24 +574,207 @@ describe('MailSignatureService', () => {
       for (const [input, reason] of cases) {
         expect(
           await failureOf(() =>
-            service.saveSignature(ARA, {
-              isForNew: true,
-              isForReply: true,
-              ...input,
-            }),
+            service.createSignature(ARA, { name: '사내', ...input }),
           ),
         ).toEqual({ code: 'VAL_001', reason });
       }
-      expect(repository.saveCalls).toHaveLength(0);
+      expect(repository.changeCalls).toHaveLength(0);
 
       // 경계 — 정확히 2,000자 · 정화한 결과 10,000자는 저장한다
-      const saved = await service.saveSignature(ARA, {
+      const saved = await service.createSignature(ARA, {
+        name: '사내',
         body: '가'.repeat(2_000),
         bodyHtml: `<p>${'가'.repeat(10_000 - 7)}</p>`,
+      });
+      expect(saved.bodyHtml).toHaveLength(10_000);
+    });
+  });
+
+  describe('옛 경로 — 「새 메일」 기본 서명 (앱 첫 판 · 옛 웹 탭)', () => {
+    it('「새 메일」 기본 서명을 네 칸으로(isForReply 는 답장 기본이 같은 서명일 때만) — 없으면 답장 기본 서명, 둘 다 없으면 본문 없음 · 두 표시 false', async () => {
+      await expect(service.getLegacySignature(ARA)).resolves.toEqual({
+        bodyHtml: null,
+        body: null,
+        isForNew: false,
+        isForReply: false,
+        images: [],
+        updatedAt: null,
+      });
+
+      const image = await storedImage();
+      const a = await create('사내', {
+        bodyHtml: `<p>사내</p><img src="${src(image.id)}" width="96">`,
+      });
+      const b = await create('대외');
+      await expect(service.getLegacySignature(ARA)).resolves.toEqual({
+        bodyHtml: a.bodyHtml,
+        body: '사내 서명',
+        isForNew: true,
+        isForReply: true,
+        images: a.images,
+        updatedAt: a.updatedAt,
+      });
+
+      await service.setDefaults(ARA, { newMessageId: a.id, replyId: b.id });
+      await expect(service.getLegacySignature(ARA)).resolves.toMatchObject({
+        body: '사내 서명',
+        isForNew: true,
+        isForReply: false,
+      });
+      // 「새 메일」 기본이 없으면 답장 기본 서명을 isForNew false 로 — 옛 두 체크가 새 메일 끔 · 답장 켬이던 직원이
+      // 앱 첫 판의 답장에서 서명을 잃지 않게 (리뷰 L4)
+      await service.setDefaults(ARA, { newMessageId: null, replyId: b.id });
+      await expect(service.getLegacySignature(ARA)).resolves.toEqual({
+        bodyHtml: null,
+        body: '대외 서명',
+        isForNew: false,
+        isForReply: true,
+        images: [],
+        updatedAt: b.updatedAt,
+      });
+      // 둘 다 없으면 다시 본문 없음
+      await service.setDefaults(ARA, { newMessageId: null, replyId: null });
+      await expect(service.getLegacySignature(ARA)).resolves.toEqual({
+        bodyHtml: null,
+        body: null,
+        isForNew: false,
+        isForReply: false,
+        images: [],
+        updatedAt: null,
+      });
+    });
+
+    it('저장 — 서명이 없으면 "기본 서명"을 만들고, 두 표시를 기본 둘로 옮긴다', async () => {
+      const saved = await service.saveLegacySignature(ARA, {
+        bodyHtml: '<p>김아라</p>',
+        body: '김아라',
+        isForNew: true,
+        isForReply: false,
+      });
+
+      expect(saved).toMatchObject({
+        bodyHtml: '<p>김아라</p>',
+        body: '김아라',
+        isForNew: true,
+        isForReply: false,
+      });
+      const [row] = (await service.listSignatures(ARA)).items;
+      expect(row.name).toBe(LEGACY_SIGNATURE_NAME);
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: row.id,
+        replyId: null,
+      });
+    });
+
+    it('저장 — 「새 메일」 기본 서명의 본문만 바꾸고(이름 그대로), 답장 기본이 다른 서명이면 isForReply false 로는 그대로 둔다', async () => {
+      const a = await create('사내');
+      const b = await create('대외');
+      await service.setDefaults(ARA, { newMessageId: a.id, replyId: b.id });
+
+      await service.saveLegacySignature(ARA, {
+        body: '바꾼 글',
+        isForNew: true,
+        isForReply: false,
+      });
+      const items = (await service.listSignatures(ARA)).items;
+      expect(items.map((item) => [item.name, item.body])).toEqual([
+        ['사내', '바꾼 글'],
+        ['대외', '대외 서명'],
+      ]);
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: a.id,
+        replyId: b.id,
+      });
+
+      // isForReply true → 답장 기본도 이 서명으로
+      await service.saveLegacySignature(ARA, {
+        body: '바꾼 글',
         isForNew: true,
         isForReply: true,
       });
-      expect(saved.bodyHtml).toHaveLength(10_000);
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: a.id,
+        replyId: a.id,
+      });
+    });
+
+    it('저장 — 「새 메일」 기본이 없으면 옛 GET 이 보인 답장 기본 서명을 고친다 (새로 만들지 않는다)', async () => {
+      await create('사내');
+      const b = await create('대외');
+      await service.setDefaults(ARA, { newMessageId: null, replyId: b.id });
+
+      const saved = await service.saveLegacySignature(ARA, {
+        body: '바꾼 글',
+        isForNew: false,
+        isForReply: true,
+      });
+
+      expect(saved).toMatchObject({
+        body: '바꾼 글',
+        isForNew: false,
+        isForReply: true,
+      });
+      const items = (await service.listSignatures(ARA)).items;
+      expect(items.map((item) => [item.name, item.body])).toEqual([
+        ['사내', '사내 서명'],
+        ['대외', '바꾼 글'],
+      ]);
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: null,
+        replyId: b.id,
+      });
+    });
+
+    it('저장 — 「새 메일」을 끈 채로 거듭 저장해도 "기본 서명"이 늘지 않는다 (답장 기본으로 · 두 표시를 끄면 이름으로 다시 찾는다)', async () => {
+      for (let index = 0; index < 3; index += 1) {
+        await service.saveLegacySignature(ARA, {
+          body: `글 ${index}`,
+          isForNew: false,
+          isForReply: true,
+        });
+      }
+      const items = (await service.listSignatures(ARA)).items;
+      expect(items.map((item) => [item.name, item.body])).toEqual([
+        [LEGACY_SIGNATURE_NAME, '글 2'],
+      ]);
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: null,
+        replyId: items[0].id,
+      });
+
+      // 두 표시를 모두 끄면 기본 서명이 없어진다 — 그 뒤 저장은 이름으로 같은 서명을 다시 찾는다
+      for (let index = 3; index < 5; index += 1) {
+        await service.saveLegacySignature(ARA, {
+          body: `글 ${index}`,
+          isForNew: false,
+          isForReply: false,
+        });
+      }
+      const after = (await service.listSignatures(ARA)).items;
+      expect(after.map((item) => [item.name, item.body])).toEqual([
+        [LEGACY_SIGNATURE_NAME, '글 4'],
+      ]);
+      await expect(service.getDefaults(ARA)).resolves.toEqual({
+        newMessageId: null,
+        replyId: null,
+      });
+    });
+
+    it(`저장 — 서명을 새로 만들어야 하는데 이미 ${SIGNATURES_MAX}개면 400 VAL_001`, async () => {
+      for (let index = 1; index <= SIGNATURES_MAX; index += 1) {
+        await create(`서명 ${index}`);
+      }
+      await service.setDefaults(ARA, { newMessageId: null, replyId: null });
+
+      expect(
+        await failureOf(() =>
+          service.saveLegacySignature(ARA, {
+            body: '글',
+            isForNew: true,
+            isForReply: true,
+          }),
+        ),
+      ).toEqual({ code: 'VAL_001', reason: 'too-many-signatures' });
     });
   });
 
@@ -467,7 +861,8 @@ describe('MailSignatureService', () => {
       ).resolves.toMatchObject({ size: SIGNATURE_IMAGE_MAX_BYTES });
     });
 
-    it(`한 사람이 둘 수 있는 그림은 ${SIGNATURE_IMAGES_STORED_MAX}장까지 — 넘으면 400 VAL_001. 동시에 올려도 넘지 않는다`, async () => {
+    it(`한 사람이 둘 수 있는 그림은 ${SIGNATURE_IMAGES_STORED_MAX}장까지(서명 여럿이 함께 쓰는 칸) — 넘으면 400 VAL_001. 동시에 올려도 넘지 않는다`, async () => {
+      expect(SIGNATURE_IMAGES_STORED_MAX).toBe(20);
       const results = await Promise.allSettled(
         Array.from({ length: SIGNATURE_IMAGES_STORED_MAX + 2 }, () =>
           upload(pngBytes(10, 10)),
@@ -525,7 +920,7 @@ describe('MailSignatureService', () => {
       });
       for (const [user, id] of [
         [DOYUN, mine.id],
-        [ARA, '11111111-1111-4111-8111-111111111111'],
+        [ARA, NOT_MINE],
       ]) {
         expect(await failureOf(() => service.openImage(user, id))).toEqual({
           code: 'RES_001',

backend/src/modules/mail-signature/mail-signature.service.ts

@@ -1,10 +1,12 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { randomUUID } from 'crypto';
 
+import {
+  type PaginatedResult,
+  toPaginatedResult,
+} from '@/common/dto/pagination.dto';
 import { BusinessException } from '@/common/errors/business.exception';
-import { checkHtmlParseBudget } from '@/modules/mail/html/html-parse-budget';
-import { MAX_BODY_HTML_LENGTH } from '@/modules/mail/mail.constants';
-import { sanitizeOutgoingHtml } from '@/modules/mail/html/sanitize-outgoing-html';
+import { sanitizeStoredHtml } from '@/modules/mail/html/sanitize-stored-html';
 import {
   findSignatureImageIds,
   rewriteSignatureImages,
@@ -14,6 +16,8 @@ import { traceTag } from '@/shared/logger/request-context';
 import { maskEmail } from '@/shared/utils/mask';
 import { MailSignatureImageEntity } from './mail-signature-image.entity';
 import {
+  LEGACY_SIGNATURE_NAME,
+  SIGNATURES_MAX,
   SIGNATURE_HTML_MAX_LENGTH,
   SIGNATURE_IMAGES_PER_SIGNATURE,
   SIGNATURE_IMAGES_STORED_MAX,
@@ -22,9 +26,16 @@ import {
   SIGNATURE_TEXT_MAX_LENGTH,
 } from './mail-signature.constants';
 import { MailSignatureEntity } from './mail-signature.entity';
-import { MailSignatureRepository } from './mail-signature.repository';
+import {
+  MailSignatureRepository,
+  type SignaturePlan,
+  type SignatureSnapshot,
+} from './mail-signature.repository';
 import type {
+  LegacyMailSignature,
+  LegacyMailSignatureInput,
   MailSignature,
+  MailSignatureDefaults,
   MailSignatureInput,
   SignatureImage,
   SignatureImageUpload,
@@ -39,18 +50,36 @@ import {
 } from './signature-image-format';
 import { SignatureImageStorage } from './signature-image-storage';
 
-const DEFAULT_SIGNATURE: Omit<MailSignature, 'images'> = {
+/** 옛 경로 — 「새 메일」 · 「답장 · 전달」 기본 서명이 모두 없을 때 (앱 첫 판은 본문이 없으면 서명을 넣지 않는다) */
+const NO_LEGACY_SIGNATURE: LegacyMailSignature = {
   bodyHtml: null,
   body: null,
-  isForNew: true,
-  isForReply: true,
+  isForNew: false,
+  isForReply: false,
+  images: [],
   updatedAt: null,
 };
 
+/** 정화 · 길이를 지난 서명 본문 — 그림은 잠근 뒤 다시 맞춘다 */
+interface PreparedSignatureBody {
+  readonly bodyHtml: string | null;
+  readonly body: string | null;
+}
+
 function normalizeUser(email: string): string {
   return email.trim().toLowerCase();
 }
 
+/** 서명 id · 그림 id — 서버가 만든 UUID(소문자). 경로 파이프가 소문자로 바꾸지만 본문에서 온 id(기본 고르기)도 같게 */
+function normalizeId(id: string): string {
+  return id.trim().toLowerCase();
+}
+
+/** 이름 견주기 — ASCII 대소문자만 무시한다 (화면과 같다 — 한글 · 그 밖의 글자는 그대로 견준다) */
+function nameKey(name: string): string {
+  return name.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+}
+
 function toImage(row: MailSignatureImageEntity): SignatureImage {
   return {
     id: row.id,
@@ -61,6 +90,67 @@ function toImage(row: MailSignatureImageEntity): SignatureImage {
   };
 }
 
+/** 서명 HTML 이 쓰는 그림 — HTML 에 나온 순서 (표에 없는 그림은 뺀다) */
+function imagesOf(
+  html: string | null,
+  images: readonly MailSignatureImageEntity[],
+): SignatureImage[] {
+  if (!html) return [];
+  const byId = new Map(images.map((image) => [image.id, image]));
+  return findSignatureImageIds(html).flatMap((id) => {
+    const image = byId.get(id);
+    return image ? [toImage(image)] : [];
+  });
+}
+
+function toSignature(
+  row: MailSignatureEntity,
+  images: readonly MailSignatureImageEntity[],
+): MailSignature {
+  return {
+    id: row.id,
+    name: row.name,
+    bodyHtml: row.bodyHtml,
+    body: row.bodyText,
+    images: imagesOf(row.bodyHtml, images),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+function defaultsOf(
+  signatures: readonly MailSignatureEntity[],
+): MailSignatureDefaults {
+  return {
+    newMessageId: signatures.find((row) => row.isNewMessageDefault)?.id ?? null,
+    replyId: signatures.find((row) => row.isReplyDefault)?.id ?? null,
+  };
+}
+
+/**
+ * 새 서명의 만든 시각 — 그 사람의 마지막 서명보다 늦게(같은 밀리초면 1ms 뒤로). 목록은 만든 차례라
+ * 잠근 차례대로 늘 뒤에 붙는다 (같은 시각이면 id 차례가 되어 들쭉날쭉하지 않게)
+ */
+function createdAfter(
+  signatures: readonly MailSignatureEntity[],
+  now: Date,
+): Date {
+  const last = Math.max(0, ...signatures.map((row) => row.createdAt.getTime()));
+  return new Date(Math.max(now.getTime(), last + 1));
+}
+
+/** 모든 서명 HTML 이 가리키는 그림 — 합집합 (지울 그림을 정하는 기준) */
+function referencedImageIdsOf(
+  signatures: readonly Pick<MailSignatureEntity, 'bodyHtml'>[],
+): string[] {
+  return [
+    ...new Set(
+      signatures.flatMap((row) =>
+        row.bodyHtml ? findSignatureImageIds(row.bodyHtml) : [],
+      ),
+    ),
+  ];
+}
+
 /** 올린 이름의 확장자 (소문자, 점 포함) */
 function extensionOf(name: string): string {
   const dot = name.lastIndexOf('.');
@@ -68,15 +158,19 @@ function extensionOf(name: string): string {
 }
 
 /**
- * 메일 서명 (계약 2절 "서명") — 사용자마다 하나, 서버 DB 에 둔다.
+ * 메일 서명 (계약 2절 "서명") — 16단계부터 한 사람에 여러 개(10개까지), 서버 DB 에 둔다.
  * - 서명 HTML 은 보내는 정화(서명 그림 포함)를 거친 뒤 저장한다 — 서명은 쓰기 화면이 본문에 넣어 그대로 보내므로 같은 규칙이다
+ * - 「메일에 넣을 서명」 둘(새 메일 · 답장과 전달)은 서명 줄의 표시다 — 서명이 하나도 없던 사람의 첫 서명이 두 곳의 기본이 된다
+ * - 서명 그림은 모든 서명이 함께 쓰는 칸(한 사람 20장)이다 — 저장 · 지우기 때 **어느 서명도 가리키지 않는** 그림을 지운다(막 올린 것은 남긴다)
  * - 그림은 PNG·JPEG·GIF 만 — 확장자·MIME 은 multer 가, 파일 내용(앞부분)·크기는 여기서 본다
- * - 그림은 주인만 본다 — 남의 그림 id 는 없는 것과 같다 (RES_001)
+ * - 서명 · 그림은 주인만 본다 — 남의 id 는 없는 것과 같다 (RES_001)
+ * - 옛 경로(`GET · PUT /api/mail-signature` — 앱 첫 판 · 16단계 전의 웹 탭)는 「새 메일」 기본 서명을 15단계까지의 모양으로 다룬다
+ * 서명 · 이름 · 글은 로그에 남기지 않는다 (사유 · 수 · 가린 주소만)
  */
 @Injectable()
 export class MailSignatureService {
   private readonly logger = new Logger(MailSignatureService.name);
-  /** 사용자별 그림 올리기 차례 — 보관 한도(10장)를 동시 업로드로 넘지 못하게 (프로세스 메모리 — 인스턴스를 늘리면 DB 잠금으로) */
+  /** 사용자별 그림 올리기 차례 — 보관 한도(20장)를 동시 업로드로 넘지 못하게 (프로세스 메모리 — 인스턴스를 늘리면 DB 잠금으로) */
   private readonly uploadQueues = new Map<string, Promise<void>>();
 
   constructor(
@@ -84,76 +178,236 @@ export class MailSignatureService {
     private readonly storage: SignatureImageStorage,
   ) {}
 
-  async getSignature(userEmail: string): Promise<MailSignature> {
+  /** 내 서명 — 만든 차례, 한 번에 모두 (hasNext 늘 false) */
+  async listSignatures(
+    userEmail: string,
+  ): Promise<PaginatedResult<MailSignature>> {
     const user = normalizeUser(userEmail);
-    const [row, images] = await Promise.all([
-      this.repository.findSignature(user),
+    const [rows, images] = await Promise.all([
+      this.repository.listSignatures(user),
       this.repository.listImages(user),
     ]);
-    if (!row) return { ...DEFAULT_SIGNATURE, images: [] };
-    return this.toSignature(row, images);
+    return toPaginatedResult(
+      rows.map((row) => toSignature(row, images)),
+      { hasNext: false, nextCursor: null, total: rows.length },
+    );
   }
 
   /**
-   * 서명을 저장한다. 서명 HTML 이 더는 가리키지 않는 그림은 지운다(표와 파일) — 막 올린 그림(10분 안)은 남긴다
-   * (올리기와 저장이 엇갈린 경우 — SIGNATURE_IMAGE_UPLOAD_GRACE_MS).
-   * 한도 — 텍스트 2,000자·정화한 HTML 10,000자(JS 문자열 길이), 정화 전 비용, 서로 다른 그림 3장 — 를 넘으면 VAL_001.
+   * 서명을 만든다 — 서명이 하나도 없던 사람이면 이 서명이 「새 메일」 · 「답장 · 전달」 두 곳의 기본이 된다.
+   * 11번째 · 같은 이름(ASCII 대소문자 무시)이면 VAL_001 (아무것도 저장하지 않는다)
    */
-  async saveSignature(
+  async createSignature(
     userEmail: string,
     input: MailSignatureInput,
   ): Promise<MailSignature> {
     const user = normalizeUser(userEmail);
-    const body = input.body ? input.body : null;
-    if (body !== null && body.length > SIGNATURE_TEXT_MAX_LENGTH) {
-      throw new BusinessException('VAL_001', {
-        context: { reason: 'signature-text-too-long', length: body.length },
-      });
-    }
-
-    const bodyHtml = await this.sanitizeSignatureHtml(user, input.bodyHtml);
-    // 정화한 HTML 에는 내 그림만 남는다 — 같은 그림을 두 번 넣으면 한 장으로 센다
-    const referenced = bodyHtml ? findSignatureImageIds(bodyHtml) : [];
-    if (referenced.length > SIGNATURE_IMAGES_PER_SIGNATURE) {
-      throw new BusinessException('VAL_001', {
-        context: {
-          reason: 'signature-too-many-images',
-          count: referenced.length,
-        },
-      });
-    }
-
-    const now = new Date();
-    const saved = await this.repository.saveSignature(
-      user,
-      (images) => {
-        // 잠근 뒤 본 그림 기준으로 — 정화한 뒤 그사이 지워진 그림(다른 탭의 저장·정리 작업)은 서명에서 뺀다 (없는 그림을 가리키지 않게)
-        const existing = new Set(images.map((image) => image.id));
-        const html =
-          bodyHtml === null
-            ? null
-            : rewriteSignatureImages(bodyHtml, (id) =>
-                existing.has(id) ? signatureImagePath(id) : null,
-              );
-        const kept = html !== null && html.trim() !== '' ? html : null;
-        return {
-          signature: {
-            userEmail: user,
-            bodyHtml: kept,
-            bodyText: body,
-            isForNew: input.isForNew,
-            isForReply: input.isForReply,
-            updatedAt: now,
+    const prepared = await this.prepareBody(user, input);
+    const id = randomUUID();
+    const result = await this.change(user, (snapshot, now) => {
+      if (snapshot.signatures.length >= SIGNATURES_MAX) {
+        throw new BusinessException('VAL_001', {
+          context: {
+            reason: 'too-many-signatures',
+            count: snapshot.signatures.length,
           },
-          referencedImageIds: kept ? findSignatureImageIds(kept) : [],
-        };
-      },
-      now,
-      new Date(now.getTime() - SIGNATURE_IMAGE_UPLOAD_GRACE_MS),
-    );
-    await this.removeFiles(saved.removed, user);
+        });
+      }
+      this.assertNameFree(snapshot.signatures, input.name, null);
+      const bodyHtml = this.keepExistingImages(prepared.bodyHtml, snapshot);
+      const row = {
+        id,
+        userEmail: user,
+        name: input.name,
+        bodyHtml,
+        bodyText: prepared.body,
+        createdAt: createdAfter(snapshot.signatures, now),
+        updatedAt: now,
+      };
+      return {
+        insert: row,
+        // 첫 서명은 두 곳의 기본 — 지금까지 서명이 처음에 두 곳에 들어가던 것과 같다
+        ...(snapshot.signatures.length === 0
+          ? { defaults: { newMessageId: id, replyId: id } }
+          : {}),
+        referencedImageIds: referencedImageIdsOf([...snapshot.signatures, row]),
+      };
+    });
+    return this.signatureIn(result, id);
+  }
 
-    return this.toSignature(saved.signature, saved.images);
+  /**
+   * 서명을 고친다(이름 · 본문 — 전체 교체). 기본 표시는 그대로. 없는 서명 · 남의 서명은 RES_001, 다른 서명과 같은 이름은 VAL_001.
+   * 어느 서명도 더는 가리키지 않는 그림은 지운다 — 막 올린 그림(10분 안)은 남긴다 (올리기와 저장이 엇갈린 경우 — SIGNATURE_IMAGE_UPLOAD_GRACE_MS)
+   */
+  async updateSignature(
+    userEmail: string,
+    signatureId: string,
+    input: MailSignatureInput,
+  ): Promise<MailSignature> {
+    const user = normalizeUser(userEmail);
+    const id = normalizeId(signatureId);
+    const prepared = await this.prepareBody(user, input);
+    const result = await this.change(user, (snapshot, now) => {
+      this.requireSignature(snapshot, id);
+      this.assertNameFree(snapshot.signatures, input.name, id);
+      const update = {
+        id,
+        name: input.name,
+        bodyHtml: this.keepExistingImages(prepared.bodyHtml, snapshot),
+        bodyText: prepared.body,
+        updatedAt: now,
+      };
+      return {
+        update,
+        referencedImageIds: referencedImageIdsOf(
+          snapshot.signatures.map((row) => (row.id === id ? update : row)),
+        ),
+      };
+    });
+    return this.signatureIn(result, id);
+  }
+
+  /**
+   * 서명을 지운다 — 이 서명을 기본으로 쓰던 곳은 "넣지 않음"이 된다(다른 서명이 저절로 기본이 되지 않는다).
+   * 이 서명에만 쓰던 그림은 함께 지운다. 없는 서명 · 남의 서명은 RES_001
+   */
+  async deleteSignature(userEmail: string, signatureId: string): Promise<void> {
+    const user = normalizeUser(userEmail);
+    const id = normalizeId(signatureId);
+    await this.change(user, (snapshot) => {
+      this.requireSignature(snapshot, id);
+      return {
+        removeId: id,
+        referencedImageIds: referencedImageIdsOf(
+          snapshot.signatures.filter((row) => row.id !== id),
+        ),
+      };
+    });
+  }
+
+  /** 「메일에 넣을 서명」 둘 — null 은 넣지 않음 */
+  async getDefaults(userEmail: string): Promise<MailSignatureDefaults> {
+    return defaultsOf(
+      await this.repository.listSignatures(normalizeUser(userEmail)),
+    );
+  }
+
+  /** 「메일에 넣을 서명」 둘을 바꾼다 — 내 서명이 아닌 id(없음 · 남의 것 · 형식이 틀림)는 RES_001 (아무것도 바꾸지 않는다) */
+  async setDefaults(
+    userEmail: string,
+    defaults: MailSignatureDefaults,
+  ): Promise<MailSignatureDefaults> {
+    const user = normalizeUser(userEmail);
+    const wanted: MailSignatureDefaults = {
+      newMessageId:
+        defaults.newMessageId === null
+          ? null
+          : normalizeId(defaults.newMessageId),
+      replyId: defaults.replyId === null ? null : normalizeId(defaults.replyId),
+    };
+    const result = await this.change(user, (snapshot) => {
+      for (const id of [wanted.newMessageId, wanted.replyId]) {
+        if (id !== null) this.requireSignature(snapshot, id);
+      }
+      return {
+        defaults: wanted,
+        referencedImageIds: referencedImageIdsOf(snapshot.signatures),
+      };
+    });
+    return defaultsOf(result.signatures);
+  }
+
+  /**
+   * 옛 경로 — 「새 메일」 기본 서명을 15단계까지의 모양으로 (앱 첫 판이 읽는다). 「새 메일」 기본이 없으면 「답장 · 전달」 기본 서명을
+   * isForNew false · isForReply true 로, 둘 다 없으면 본문 없음 · 두 표시 false.
+   * 「새 메일」 기본이 있을 때 isForReply 는 답장 기본이 같은 서명일 때만 true — 다른 서명이면 앱 첫 판은 답장에 서명을 넣지 않는다(알려진 한계)
+   */
+  async getLegacySignature(userEmail: string): Promise<LegacyMailSignature> {
+    const user = normalizeUser(userEmail);
+    const [rows, images] = await Promise.all([
+      this.repository.listSignatures(user),
+      this.repository.listImages(user),
+    ]);
+    return toLegacySignature(rows, images);
+  }
+
+  /**
+   * 옛 경로의 저장(16단계 전의 웹 탭) — 옛 GET 이 보이는 서명(「새 메일」 기본, 없으면 「답장 · 전달」 기본)의 본문을 바꾸고 두 표시를 기본 둘로 옮긴다.
+   * 기본 서명이 둘 다 없으면 "기본 서명"이라는 이름의 서명(ASCII 대소문자 무시 — 있으면 그것, 없으면 새로 만든다)을 쓴다 —
+   * 옛 탭이 두 표시를 끈 채 저장을 거듭해도 서명이 늘지 않게.
+   * isForNew → 「새 메일」 기본을 이 서명으로(false 면 넣지 않음), isForReply → 「답장 · 전달」 기본을 이 서명으로
+   * (false 면 이 서명이 기본이었을 때만 넣지 않음 — 다른 서명이 기본이면 그대로 둔다)
+   */
+  async saveLegacySignature(
+    userEmail: string,
+    input: LegacyMailSignatureInput,
+  ): Promise<LegacyMailSignature> {
+    const user = normalizeUser(userEmail);
+    const prepared = await this.prepareBody(user, input);
+    const newId = randomUUID();
+    const result = await this.change(user, (snapshot, now) => {
+      const current = defaultsOf(snapshot.signatures);
+      const target =
+        legacyTargetOf(snapshot.signatures) ??
+        snapshot.signatures.find(
+          (row) => nameKey(row.name) === nameKey(LEGACY_SIGNATURE_NAME),
+        ) ??
+        null;
+      const bodyHtml = this.keepExistingImages(prepared.bodyHtml, snapshot);
+      const id = target?.id ?? newId;
+      const defaults: MailSignatureDefaults = {
+        newMessageId: input.isForNew
+          ? id
+          : current.newMessageId === id
+            ? null
+            : current.newMessageId,
+        replyId: input.isForReply
+          ? id
+          : current.replyId === id
+            ? null
+            : current.replyId,
+      };
+      if (target) {
+        const update = {
+          id,
+          name: target.name,
+          bodyHtml,
+          bodyText: prepared.body,
+          updatedAt: now,
+        };
+        return {
+          update,
+          defaults,
+          referencedImageIds: referencedImageIdsOf(
+            snapshot.signatures.map((row) => (row.id === id ? update : row)),
+          ),
+        };
+      }
+      if (snapshot.signatures.length >= SIGNATURES_MAX) {
+        throw new BusinessException('VAL_001', {
+          context: {
+            reason: 'too-many-signatures',
+            count: snapshot.signatures.length,
+          },
+        });
+      }
+      const row = {
+        id,
+        userEmail: user,
+        name: LEGACY_SIGNATURE_NAME,
+        bodyHtml,
+        bodyText: prepared.body,
+        createdAt: createdAfter(snapshot.signatures, now),
+        updatedAt: now,
+      };
+      return {
+        insert: row,
+        defaults,
+        referencedImageIds: referencedImageIdsOf([...snapshot.signatures, row]),
+      };
+    });
+    return toLegacySignature(result.signatures, result.images);
   }
 
   /** 서명 그림을 올린다 — 내용이 PNG·JPEG·GIF 이고 확장자·MIME 과 같은 형식이어야 한다 (아니면 FILE_001) */
@@ -284,59 +538,125 @@ export class MailSignatureService {
     return loaded;
   }
 
-  /** 서명 HTML 정화 — 비었으면 null. 정화 전 비용·정화 뒤 길이 한도를 넘으면 VAL_001 */
-  private async sanitizeSignatureHtml(
+  /**
+   * 서명 본문 — 텍스트 2,000자, 서식은 정화 전 비용 · 정화 뒤 10,000자(JS 문자열 길이), 서로 다른 그림 3장(정화가 남의 그림은 지웠다 —
+   * 같은 그림 두 번은 한 장). 넘으면 VAL_001
+   */
+  private async prepareBody(
     user: string,
-    html: string | null | undefined,
-  ): Promise<string | null> {
-    if (!html) return null;
-    // 정화 전 — 쓰기 화면의 서식 본문과 같은 길이 한도와 파서 비용 (정화가 이벤트 루프를 오래 붙잡지 않게)
-    if (html.length > MAX_BODY_HTML_LENGTH) {
+    input: { readonly bodyHtml?: string | null; readonly body?: string | null },
+  ): Promise<PreparedSignatureBody> {
+    const body = input.body ? input.body : null;
+    if (body !== null && body.length > SIGNATURE_TEXT_MAX_LENGTH) {
       throw new BusinessException('VAL_001', {
-        context: { reason: 'signature-html-too-long', length: html.length },
-      });
-    }
-    const budget = checkHtmlParseBudget(html);
-    if (!budget.ok) {
-      throw new BusinessException('VAL_001', {
-        context: {
-          reason: 'signature-html-too-complex',
-          detail: budget.reason,
-        },
+        context: { reason: 'signature-text-too-long', length: body.length },
       });
     }
 
-    const sanitized = sanitizeOutgoingHtml(html, {
-      signatureImageIds: await this.imageIdsOf(user),
+    const signatureImageIds = input.bodyHtml
+      ? await this.imageIdsOf(user)
+      : undefined;
+    const sanitized = sanitizeStoredHtml(input.bodyHtml, {
+      maxLength: SIGNATURE_HTML_MAX_LENGTH,
+      signatureImageIds,
     });
-    if (sanitized.length > SIGNATURE_HTML_MAX_LENGTH) {
+    if (!sanitized.ok) {
       throw new BusinessException('VAL_001', {
         context: {
-          reason: 'signature-html-too-long',
+          reason:
+            sanitized.problem === 'too-complex'
+              ? 'signature-html-too-complex'
+              : 'signature-html-too-long',
           length: sanitized.length,
         },
       });
     }
-    return sanitized === '' ? null : sanitized;
+    const referenced = sanitized.html
+      ? findSignatureImageIds(sanitized.html)
+      : [];
+    if (referenced.length > SIGNATURE_IMAGES_PER_SIGNATURE) {
+      throw new BusinessException('VAL_001', {
+        context: {
+          reason: 'signature-too-many-images',
+          count: referenced.length,
+        },
+      });
+    }
+    return { bodyHtml: sanitized.html, body };
   }
 
-  private toSignature(
-    row: MailSignatureEntity,
-    images: readonly MailSignatureImageEntity[],
+  /**
+   * 잠근 뒤 본 그림 기준으로 — 정화한 뒤 그사이 지워진 그림(다른 탭의 저장 · 정리 작업)은 서명에서 뺀다 (없는 그림을 가리키지 않게).
+   * 남는 것이 없으면 null
+   */
+  private keepExistingImages(
+    html: string | null,
+    snapshot: SignatureSnapshot,
+  ): string | null {
+    if (html === null) return null;
+    const existing = new Set(snapshot.images.map((image) => image.id));
+    const kept = rewriteSignatureImages(html, (id) =>
+      existing.has(id) ? signatureImagePath(id) : null,
+    );
+    return kept.trim() !== '' ? kept : null;
+  }
+
+  /** 같은 이름(ASCII 대소문자 무시)의 다른 서명이 있으면 VAL_001 */
+  private assertNameFree(
+    signatures: readonly MailSignatureEntity[],
+    name: string,
+    exceptId: string | null,
+  ): void {
+    const key = nameKey(name);
+    if (
+      signatures.some((row) => row.id !== exceptId && nameKey(row.name) === key)
+    ) {
+      throw new BusinessException('VAL_001', {
+        context: { reason: 'signature-name-taken' },
+      });
+    }
+  }
+
+  /** 그 사람의 서명이어야 한다 — 없으면(남의 것 · 형식이 틀린 id 포함) RES_001 */
+  private requireSignature(snapshot: SignatureSnapshot, id: string): void {
+    if (!snapshot.signatures.some((row) => row.id === id)) {
+      throw new BusinessException('RES_001', {
+        context: { reason: 'signature-not-found' },
+      });
+    }
+  }
+
+  /** 잠근 뒤 바꾸고, 지운 그림의 파일을 지운다 */
+  private async change(
+    user: string,
+    plan: (snapshot: SignatureSnapshot, now: Date) => SignaturePlan,
+  ) {
+    const now = new Date();
+    const result = await this.repository.change(
+      user,
+      (snapshot) => plan(snapshot, now),
+      now,
+      new Date(now.getTime() - SIGNATURE_IMAGE_UPLOAD_GRACE_MS),
+    );
+    await this.removeFiles(result.removed, user);
+    return result;
+  }
+
+  /** 바꾼 뒤의 서명 하나 — 방금 넣거나 고친 줄은 늘 있다 */
+  private signatureIn(
+    result: {
+      readonly signatures: readonly MailSignatureEntity[];
+      readonly images: readonly MailSignatureImageEntity[];
+    },
+    id: string,
   ): MailSignature {
-    const byId = new Map(images.map((image) => [image.id, image]));
-    const used = row.bodyHtml ? findSignatureImageIds(row.bodyHtml) : [];
-    return {
-      bodyHtml: row.bodyHtml,
-      body: row.bodyText,
-      isForNew: row.isForNew,
-      isForReply: row.isForReply,
-      images: used.flatMap((id) => {
-        const image = byId.get(id);
-        return image ? [toImage(image)] : [];
-      }),
-      updatedAt: row.updatedAt.toISOString(),
-    };
+    const row = result.signatures.find((candidate) => candidate.id === id);
+    if (!row) {
+      throw new BusinessException('SYS_001', {
+        context: { reason: 'signature-missing-after-save' },
+      });
+    }
+    return toSignature(row, result.images);
   }
 
   /** 지운 그림의 파일을 지운다 — 실패해도 서명 저장은 끝났다 (남은 파일은 정리 작업이 지운다) */
@@ -370,3 +690,38 @@ export class MailSignatureService {
     return run;
   }
 }
+
+/**
+ * 옛 경로가 다루는 서명 — 「새 메일」 기본, 없으면 「답장 · 전달」 기본, 둘 다 없으면 null.
+ * 답장 기본까지 보는 까닭: 옛 두 체크가 새 메일 끔 · 답장 켬이던 직원(옮기면 답장 기본만 있다)이 앱 첫 판의 답장에서 서명을 잃지 않게 (리뷰 L4).
+ * 옛 PUT 도 이 서명을 고친다 — 옛 탭이 읽은 서명을 그대로 저장하게
+ */
+function legacyTargetOf(
+  rows: readonly MailSignatureEntity[],
+): MailSignatureEntity | null {
+  return (
+    rows.find((candidate) => candidate.isNewMessageDefault) ??
+    rows.find((candidate) => candidate.isReplyDefault) ??
+    null
+  );
+}
+
+/**
+ * 옛 경로의 모양 — 「새 메일」 기본 서명(isForNew true · isForReply 는 답장 기본도 그 서명일 때), 없으면 「답장 · 전달」 기본 서명
+ * (isForNew false · isForReply true), 둘 다 없으면 본문 없음 · 두 표시 false
+ */
+function toLegacySignature(
+  rows: readonly MailSignatureEntity[],
+  images: readonly MailSignatureImageEntity[],
+): LegacyMailSignature {
+  const row = legacyTargetOf(rows);
+  if (!row) return NO_LEGACY_SIGNATURE;
+  return {
+    bodyHtml: row.bodyHtml,
+    body: row.bodyText,
+    isForNew: row.isNewMessageDefault,
+    isForReply: row.isReplyDefault,
+    images: imagesOf(row.bodyHtml, images),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}

backend/src/modules/mail-signature/mail-signature.types.ts

@@ -1,7 +1,7 @@
 import type { SignatureImageType } from './signature-image-format';
 
 /**
- * 서명 도메인 타입 — 계약 2절 "서명"과 같은 모양이다.
+ * 서명 도메인 타입 — 계약 2절 "서명"과 같은 모양이다 (16단계부터 한 사람에 여러 개).
  */
 
 export interface SignatureImage {
@@ -14,21 +14,51 @@ export interface SignatureImage {
   readonly height: number;
 }
 
+/** 서명 하나 — `GET · POST /api/mail-signatures` · `PUT /api/mail-signatures/{id}` (16단계) */
 export interface MailSignature {
-  /** 서명 서식 — 서식 본문 규칙 + 서명 그림. 정화 뒤 10,000자 이하 */
+  readonly id: string;
+  /** 앞뒤 공백을 뺀 1~30자 — 같은 사람 안에서 겹치지 않는다(ASCII 대소문자 무시) */
+  readonly name: string;
+  /** 서명 서식 — 서식 본문 규칙 + 서명 그림. 정화 뒤 10,000자 이하. 없으면 null */
+  readonly bodyHtml: string | null;
+  /** 텍스트 서명 (텍스트 대체 본문에 넣는다) — 2,000자 이하. 없으면 null */
+  readonly body: string | null;
+  /** 서명 HTML 이 쓰는 그림 (HTML 에 나온 순서) */
+  readonly images: SignatureImage[];
+  /** 마지막으로 저장한 시각 (ISO 8601 UTC) */
+  readonly updatedAt: string;
+}
+
+/** 서명 만들기 · 고치기 본문 (전체 교체) */
+export interface MailSignatureInput {
+  /** 앞뒤 공백을 뺀 값 (요청 검증이 지운다) */
+  readonly name: string;
+  readonly bodyHtml?: string | null;
+  readonly body?: string | null;
+}
+
+/** 「메일에 넣을 서명」 둘 — `GET · PUT /api/mail-signature-defaults` (16단계). null = 넣지 않음 */
+export interface MailSignatureDefaults {
+  readonly newMessageId: string | null;
+  readonly replyId: string | null;
+}
+
+/**
+ * 옛 경로의 서명 — `GET /api/mail-signature` (앱 첫 판 · 16단계 전의 웹 탭). 「새 메일」 기본 서명을 15단계까지의 네 칸으로 내준다
+ * (없으면 「답장 · 전달」 기본 서명을 isForNew false 로). isForNew = 「새 메일」 기본 서명이 있음, isForReply = 「답장 · 전달」 기본이 이 서명
+ */
+export interface LegacyMailSignature {
   readonly bodyHtml: string | null;
-  /** 텍스트 서명 (텍스트 대체 본문에 넣는다) — 2,000자 이하 */
   readonly body: string | null;
   readonly isForNew: boolean;
   readonly isForReply: boolean;
-  /** 서명 HTML 이 쓰는 그림 (HTML 에 나온 순서) */
   readonly images: SignatureImage[];
-  /** 저장한 적 없으면 null */
+  /** 기본 서명이 둘 다 없으면 null */
   readonly updatedAt: string | null;
 }
 
-/** PUT /api/mail-signature 본문 */
-export interface MailSignatureInput {
+/** 옛 경로의 저장 본문 — `PUT /api/mail-signature` */
+export interface LegacyMailSignatureInput {
   readonly bodyHtml?: string | null;
   readonly body?: string | null;
   readonly isForNew: boolean;

backend/src/modules/mail-signature/mail-signatures.controller.ts

@@ -0,0 +1,184 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Param,
+  Post,
+  Put,
+  UseGuards,
+} from '@nestjs/common';
+import {
+  ApiCookieAuth,
+  ApiOperation,
+  ApiParam,
+  ApiResponse,
+  ApiTags,
+} from '@nestjs/swagger';
+
+import {
+  ApiErrorResponse,
+  ApiSessionErrors,
+  ApiStandardResponse,
+} from '@/common/decorators/api-standard-response.decorator';
+import {
+  CurrentUser,
+  type AuthenticatedUser,
+} from '@/common/decorators/current-user.decorator';
+import { SkipTransform } from '@/common/decorators/skip-transform.decorator';
+import { JwtAuthGuard } from '@/common/guards/jwt-auth.guard';
+import {
+  MailSignatureDefaultsDto,
+  MailSignatureDto,
+  MailSignaturePageDto,
+  SaveMailSignatureDto,
+} from './dto/mail-signature.dto';
+import {
+  SIGNATURES_MAX,
+  SIGNATURE_HTML_MAX_LENGTH,
+  SIGNATURE_IMAGES_PER_SIGNATURE,
+  SIGNATURE_NAME_MAX_LENGTH,
+  SIGNATURE_TEXT_MAX_LENGTH,
+} from './mail-signature.constants';
+import { MailSignatureService } from './mail-signature.service';
+import { MailSignatureIdPipe } from './signature-image-id.pipe';
+
+/** 서명 저장(만들기 · 고치기)의 400 VAL_001 사유 */
+const SAVE_REJECTIONS =
+  `형식 오류 · 이름(앞뒤 공백을 뺀 1~${SIGNATURE_NAME_MAX_LENGTH}자 · 제어 문자 없음) · 같은 이름의 다른 서명(영문 대소문자 무시) · ` +
+  `텍스트 서명 ${SIGNATURE_TEXT_MAX_LENGTH.toLocaleString('ko-KR')}자 초과 · 정화한 서식 서명 ${SIGNATURE_HTML_MAX_LENGTH.toLocaleString('ko-KR')}자 초과 · ` +
+  `서식 서명이 너무 깊게 중첩됨 · 그림 ${SIGNATURE_IMAGES_PER_SIGNATURE}장 초과 · 모르는 필드`;
+
+const SIGNATURE_ID_PARAM = {
+  name: 'id',
+  description: '서명 id (서버가 만든 UUID) — 형식이 틀리면 404 RES_001',
+  example: '0b6f7c1e-3a52-4c4e-9f0e-2d1f5a7b8c9d',
+};
+
+// 여러 서명 (계약 2절 "서명" — 16단계) — 로그인한 직원 자신의 서명만 다룬다. 서명 그림 경로는 그대로 /api/mail-signature/images (mail-signature.controller.ts)
+@ApiTags('Mail')
+@ApiCookieAuth()
+@UseGuards(JwtAuthGuard)
+@ApiSessionErrors('로그인 필요 (쿠키 없음·만료)')
+@Controller('mail-signatures')
+export class MailSignaturesController {
+  constructor(private readonly signatures: MailSignatureService) {}
+
+  @Get()
+  @ApiOperation({
+    summary: '내 서명 목록',
+    description: `만든 차례 · ${SIGNATURES_MAX}개까지 한 번에 모두 (hasNext=false). 「메일에 넣을 서명」은 /api/mail-signature-defaults`,
+  })
+  @ApiStandardResponse(MailSignaturePageDto, { description: '서명 목록' })
+  list(@CurrentUser() user: AuthenticatedUser) {
+    return this.signatures.listSignatures(user.email);
+  }
+
+  @Post()
+  @ApiOperation({
+    summary: '서명 만들기',
+    description:
+      `${SIGNATURES_MAX}개까지. 서명이 하나도 없던 직원이면 이 서명이 「새 메일」 · 「답장 · 전달」 두 곳의 기본이 된다(그 밖에는 기본을 바꾸지 않는다). ` +
+      'bodyHtml 은 서식 본문 허용 목록 + 내 서명 그림으로 정화해 저장한다. 어느 서명도 더는 가리키지 않는 그림은 지운다 — 막 올리고(10분 안) 아직 넣지 않은 그림은 남긴다.',
+  })
+  @ApiStandardResponse(MailSignatureDto, {
+    status: HttpStatus.CREATED,
+    description: '만든 서명',
+  })
+  @ApiErrorResponse(
+    'VAL_001',
+    `${SAVE_REJECTIONS} · 이미 ${SIGNATURES_MAX}개 — 저장하지 않았다`,
+  )
+  create(
+    @CurrentUser() user: AuthenticatedUser,
+    @Body() dto: SaveMailSignatureDto,
+  ) {
+    return this.signatures.createSignature(user.email, dto);
+  }
+
+  @Put(':id')
+  @ApiOperation({
+    summary: '서명 고치기 (이름 · 본문 — 전체 교체)',
+    description:
+      '「메일에 넣을 서명」 표시는 그대로다. 어느 서명도 더는 가리키지 않는 그림은 지운다 — 막 올리고(10분 안) 아직 넣지 않은 그림은 남긴다.',
+  })
+  @ApiParam(SIGNATURE_ID_PARAM)
+  @ApiStandardResponse(MailSignatureDto, { description: '고친 서명' })
+  @ApiErrorResponse('VAL_001', `${SAVE_REJECTIONS} — 저장하지 않았다`)
+  @ApiErrorResponse('RES_001', '없는 서명 · 남의 서명 · 형식이 틀린 id')
+  update(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param('id', MailSignatureIdPipe) id: string,
+    @Body() dto: SaveMailSignatureDto,
+  ) {
+    return this.signatures.updateSignature(user.email, id, dto);
+  }
+
+  @Delete(':id')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @SkipTransform()
+  @ApiOperation({
+    summary: '서명 지우기',
+    description:
+      '이 서명을 기본으로 쓰던 곳(새 메일 · 답장과 전달)은 넣지 않음이 된다 — 다른 서명이 저절로 기본이 되지 않는다. ' +
+      '이 서명에만 쓰던 그림은 함께 지운다. 이미 보냈거나 임시 저장한 메일에 들어간 서명 글은 그대로다.',
+  })
+  @ApiParam(SIGNATURE_ID_PARAM)
+  @ApiResponse({
+    status: HttpStatus.NO_CONTENT,
+    description: '지웠다 — 본문 없음',
+  })
+  @ApiErrorResponse('RES_001', '없는 서명 · 남의 서명 · 형식이 틀린 id')
+  async remove(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param('id', MailSignatureIdPipe) id: string,
+  ): Promise<void> {
+    await this.signatures.deleteSignature(user.email, id);
+  }
+}
+
+// 「메일에 넣을 서명」 둘 (계약 2절 "서명" — 16단계) — 새 메일 · 답장과 전달에 저절로 넣는 서명. 15단계까지의 두 체크(isForNew · isForReply)를 대신한다
+@ApiTags('Mail')
+@ApiCookieAuth()
+@UseGuards(JwtAuthGuard)
+@ApiSessionErrors('로그인 필요 (쿠키 없음·만료)')
+@Controller('mail-signature-defaults')
+export class MailSignatureDefaultsController {
+  constructor(private readonly signatures: MailSignatureService) {}
+
+  @Get()
+  @ApiOperation({
+    summary: '메일에 넣을 서명',
+    description:
+      '새 메일 · 답장과 전달에 넣는 서명의 id — null 이면 넣지 않음. 서명이 하나도 없으면 둘 다 null',
+  })
+  @ApiStandardResponse(MailSignatureDefaultsDto, {
+    description: '메일에 넣을 서명',
+  })
+  get(@CurrentUser() user: AuthenticatedUser) {
+    return this.signatures.getDefaults(user.email);
+  }
+
+  @Put()
+  @ApiOperation({
+    summary: '메일에 넣을 서명 바꾸기 (전체 교체)',
+    description:
+      '두 키를 모두 보낸다(null = 넣지 않음). 두 곳이 같은 서명이어도 된다. 바꾼 뒤의 값을 돌려준다',
+  })
+  @ApiStandardResponse(MailSignatureDefaultsDto, {
+    description: '바꾼 뒤의 값',
+  })
+  @ApiErrorResponse('VAL_001', '형식 오류 · 빠진 키 · 모르는 필드')
+  @ApiErrorResponse(
+    'RES_001',
+    '내 서명이 아닌 id(없음 · 남의 것 · 형식이 틀림) — 아무것도 바꾸지 않았다',
+  )
+  update(
+    @CurrentUser() user: AuthenticatedUser,
+    @Body() dto: MailSignatureDefaultsDto,
+  ) {
+    return this.signatures.setDefaults(user.email, dto);
+  }
+}

backend/src/modules/mail-signature/signature-image-id.pipe.ts

@@ -2,10 +2,18 @@ import { Injectable, PipeTransform } from '@nestjs/common';
 
 import { BusinessException } from '@/common/errors/business.exception';
 
-/** 서명 그림 id — 서버가 만든 UUID */
-const SIGNATURE_IMAGE_ID =
+/** 서명 · 서명 그림 id — 서버가 만든 UUID */
+const SERVER_UUID =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+/** 경로의 UUID 를 소문자로 — 형식이 틀리면 "그런 것이 없다"와 같으므로 RES_001 (그 사유로) */
+function serverUuid(value: unknown, reason: string): string {
+  if (typeof value === 'string' && SERVER_UUID.test(value)) {
+    return value.toLowerCase();
+  }
+  throw new BusinessException('RES_001', { context: { reason } });
+}
+
 /**
  * 경로의 서명 그림 id 형식 확인 — 형식이 틀리면 "그런 그림이 없다"와 같으므로 RES_001 (DB 의 uuid 열에 넣기 전에 막는다 —
  * 형식이 틀린 값이 DB 오류(SYS_001)로 새어 나가지 않게).
@@ -13,11 +21,14 @@ const SIGNATURE_IMAGE_ID =
 @Injectable()
 export class SignatureImageIdPipe implements PipeTransform<unknown, string> {
   transform(value: unknown): string {
-    if (typeof value === 'string' && SIGNATURE_IMAGE_ID.test(value)) {
-      return value.toLowerCase();
-    }
-    throw new BusinessException('RES_001', {
-      context: { reason: 'malformed-signature-image-id' },
-    });
+    return serverUuid(value, 'malformed-signature-image-id');
+  }
+}
+
+/** 경로의 서명 id 형식 확인 (16단계 — `/api/mail-signatures/{id}`) — 그림 id 와 같은 규칙, 틀리면 RES_001 */
+@Injectable()
+export class MailSignatureIdPipe implements PipeTransform<unknown, string> {
+  transform(value: unknown): string {
+    return serverUuid(value, 'malformed-signature-id');
   }
 }

backend/src/modules/mail/dto/mail-block-run.dto.ts

@@ -0,0 +1,86 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, Matches, MaxLength, ValidateIf } from 'class-validator';
+
+import {
+  MAIL_FILTER_RUN_CURSOR_PATTERN,
+  MAX_EMAIL_LENGTH,
+  MAX_MAIL_FILTER_RUN_CURSOR_LENGTH,
+} from '@/modules/mail/mail.constants';
+import type {
+  MailBlockRunRequest,
+  MailFilterRun,
+} from '@/modules/mail/mail.types';
+import { BlockAddress } from './mail-block.dto';
+
+/**
+ * 차단할 때 받은편지함 정리 — POST /api/mail-block-runs 의 본문과 응답 (계약 2절 "보낸 사람 차단" — 15단계).
+ * 보낸 사람은 차단하기와 같은 검사(주소 · `@도메인` 모양 · 254자 — mail-blocks.ts), 차단 목록에 있는지는 서비스가 본다(없으면 404 RES_001).
+ * cursor 는 이미 받은 메일에 필터 적용(dto/mail-filter-run.dto.ts)과 같은 검사다
+ */
+
+/** null 은 "처음부터"로 받는다 — 키가 없으면(undefined) 형식 오류다 (늘 보낸다) */
+const unlessNull = (_object: object, value: unknown) => value !== null;
+
+/** POST /api/mail-block-runs — 정리할 보낸 사람(차단 목록의 값)과 이어 할 자리 */
+export class MailBlockRunRequestDto implements MailBlockRunRequest {
+  @ApiProperty({
+    description:
+      '차단 목록의 값 그대로 — 소문자 주소("kim@spam.example") 또는 도메인("@spam.example"). 차단한 뒤에만 부른다 — 차단 목록에 없으면 404 RES_001',
+    example: '@spam.example',
+    maxLength: MAX_EMAIL_LENGTH,
+  })
+  @BlockAddress()
+  sender!: string;
+
+  @ApiProperty({
+    description:
+      '이어 할 자리 — 처음은 null, 이어 할 때는 앞 응답의 cursor 그대로(해석하지 않는다). 늘 보낸다. ' +
+      '다른 보낸 사람의 cursor · 깨진 cursor 는 400 VAL_001',
+    nullable: true,
+    type: String,
+    maxLength: MAX_MAIL_FILTER_RUN_CURSOR_LENGTH,
+    example: null,
+  })
+  @ValidateIf(unlessNull)
+  @IsString({ message: '이어 할 자리를 다시 받아 주세요.' })
+  @MaxLength(MAX_MAIL_FILTER_RUN_CURSOR_LENGTH, {
+    message: '이어 할 자리를 다시 받아 주세요.',
+  })
+  @Matches(MAIL_FILTER_RUN_CURSOR_PATTERN, {
+    message: '이어 할 자리를 다시 받아 주세요.',
+  })
+  cursor!: string | null;
+}
+
+/** POST /api/mail-block-runs 의 응답 — 이미 받은 메일에 필터 적용(MailFilterRun)과 같은 꼴 */
+export class MailBlockRunDto implements MailFilterRun {
+  @ApiProperty({
+    description: '이번 요청에서 확인한 받은편지함 메일 수',
+    example: 500,
+  })
+  scanned!: number;
+
+  @ApiProperty({
+    description:
+      '그중 그 보낸 사람의 메일이라 스팸메일함으로 옮긴 수 (스팸 표시도 붙였다). 보내기를 기다리는 메일은 옮기지 않아 세지 않는다',
+    example: 37,
+  })
+  matched!: number;
+
+  @ApiProperty({
+    description:
+      '아직 확인하지 않은 메일 수 — 어림(그사이 들어오고 나간 메일이 있다). 진행의 전체는 지금까지 확인한 수 + 이 값',
+    example: 4_300,
+  })
+  remaining!: number;
+
+  @ApiProperty({
+    description:
+      'null = 끝. 아니면 같은 본문에 이 cursor 를 넣어 다시 보낸다 (해석하지 않는다)',
+    nullable: true,
+    type: String,
+    example:
+      'eyJ2IjoyLCJiIjoxNzkzMjY0NDAxLCJhIjoic2VhYWFhZXIiLCJ0IjoxNzkzMjY0MzQwLCJyIjoiZDJWM2R0ejdOMmdCVVRyZyJ9',
+  })
+  cursor!: string | null;
+}

backend/src/modules/mail/dto/mail-block.dto.ts

@@ -32,7 +32,8 @@ function IsBlockTarget() {
   );
 }
 
-function BlockAddress(): PropertyDecorator {
+/** 차단 대상 칸 — 차단하기(POST /api/mail-blocks) · 받은편지함 정리(POST /api/mail-block-runs — 15단계)가 같이 쓴다 */
+export function BlockAddress(): PropertyDecorator {
   return applyDecorators(
     TrimString(),
     IsString({ message: '메일 주소나 @도메인 형식으로 써 주세요.' }),

backend/src/modules/mail/dto/mail-vacation.dto.spec.ts

@@ -1,5 +1,5 @@
 import { plainToInstance } from 'class-transformer';
-import { validate } from 'class-validator';
+import { validate, type ValidationError } from 'class-validator';
 
 import {
   MAX_VACATION_SUBJECT_LENGTH,
@@ -18,6 +18,22 @@ async function constraintsOf(body: object): Promise<string[]> {
   return errors.flatMap((error) => Object.keys(error.constraints ?? {}));
 }
 
+/** 안쪽 객체(external — 16단계)까지 — `칸.규칙` 모양으로 모두 */
+async function allConstraintsOf(body: object): Promise<string[]> {
+  const errors = await validate(plainToInstance(MailVacationDto, body), {
+    whitelist: true,
+    forbidNonWhitelisted: true,
+  });
+  const flatten = (list: ValidationError[], prefix: string): string[] =>
+    list.flatMap((error) => [
+      ...Object.keys(error.constraints ?? {}).map(
+        (name) => `${prefix}${error.property}.${name}`,
+      ),
+      ...flatten(error.children ?? [], `${prefix}${error.property}.`),
+    ]);
+  return flatten(errors, '');
+}
+
 describe('부재중 자동 응답 본문 (PUT /api/mail-vacation)', () => {
   const enabled = {
     isEnabled: true,
@@ -72,7 +88,7 @@ describe('부재중 자동 응답 본문 (PUT /api/mail-vacation)', () => {
     ).toEqual([]);
   });
 
-  it(`요청 검증의 길이 한도는 켬 · 끔과 상관없이 제목 ${MAX_VACATION_SUBJECT_LENGTH_WHEN_OFF}자 · 내용 ${MAX_VACATION_TEXT_LENGTH_WHEN_OFF}자 (JS 문자열 길이) — 서식 본문은 받지 않는다`, async () => {
+  it(`요청 검증의 길이 한도는 켬 · 끔과 상관없이 제목 ${MAX_VACATION_SUBJECT_LENGTH_WHEN_OFF}자 · 내용 ${MAX_VACATION_TEXT_LENGTH_WHEN_OFF}자 (JS 문자열 길이) — 16단계부터 서식 본문(htmlBody)도 받는다`, async () => {
     for (const isEnabled of [false, true]) {
       expect(
         await constraintsOf({
@@ -102,7 +118,7 @@ describe('부재중 자동 응답 본문 (PUT /api/mail-vacation)', () => {
     );
     expect(
       await constraintsOf({ ...enabled, htmlBody: '<p>휴가</p>' }),
-    ).toEqual(['whitelistValidation']);
+    ).toEqual([]);
   });
 
   it(`꺼 둔 채로는 켤 때의 한도(제목 ${MAX_VACATION_SUBJECT_LENGTH}자 · 내용 ${MAX_VACATION_TEXT_LENGTH}자)를 넘는 글도 받는다 — 제목 151~200자 · 내용 601~4,000자 (켤 때의 한도는 서비스가 본다)`, async () => {
@@ -212,6 +228,134 @@ describe('부재중 자동 응답 본문 (PUT /api/mail-vacation)', () => {
   });
 });
 
+describe('부재중 서식 본문 · 회사 밖 응답 (16단계)', () => {
+  const enabled = {
+    isEnabled: true,
+    fromDate: null,
+    toDate: null,
+    subject: '부재중입니다',
+    textBody: '11월 7일까지 휴가입니다.',
+  };
+  const external = {
+    mode: 'separate',
+    subject: 'Out of office',
+    textBody: 'I am away until Nov 7.',
+    htmlBody: '<p>I am away until <strong>Nov 7</strong>.</p>',
+  };
+
+  it('htmlBody · external 은 보내지 않아도 된다(옛 요청) — 보내면 htmlBody 는 글 · null, external 은 네 키(글 칸은 null 가능) · null', async () => {
+    expect(await allConstraintsOf(enabled)).toEqual([]);
+    expect(
+      await allConstraintsOf({
+        ...enabled,
+        htmlBody: '<p>휴가</p>',
+        external,
+      }),
+    ).toEqual([]);
+    expect(
+      await allConstraintsOf({ ...enabled, htmlBody: null, external: null }),
+    ).toEqual([]);
+    for (const mode of ['same', 'none', 'separate']) {
+      expect(
+        await allConstraintsOf({
+          ...enabled,
+          external: { mode, subject: null, textBody: null, htmlBody: null },
+        }),
+      ).toEqual([]);
+    }
+  });
+
+  it('형식이 틀리면 VAL_001 — 모르는 고르기 · 빠진 키 · 글이 아닌 값 · 모르는 키 · 객체가 아님', async () => {
+    expect(await allConstraintsOf({ ...enabled, htmlBody: 1 })).toEqual([
+      'htmlBody.isString',
+    ]);
+    expect(
+      await allConstraintsOf({
+        ...enabled,
+        external: { ...external, mode: 'internal' },
+      }),
+    ).toEqual(['external.mode.isIn']);
+    // 빠진 키 — 전체 교체라 null 로 보낸다(이 검사는 stopAtFirstError 를 빼 걸린 규칙이 모두 보인다)
+    expect(
+      await allConstraintsOf({ ...enabled, external: { mode: 'same' } }),
+    ).toEqual(
+      expect.arrayContaining([
+        'external.subject.isString',
+        'external.textBody.isString',
+        'external.htmlBody.isString',
+      ]),
+    );
+    expect(
+      await allConstraintsOf({
+        ...enabled,
+        external: { ...external, subject: 1, htmlBody: [] },
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        'external.subject.isString',
+        'external.htmlBody.isString',
+      ]),
+    );
+    expect(
+      await allConstraintsOf({
+        ...enabled,
+        external: { ...external, isActive: true },
+      }),
+    ).toEqual(['external.isActive.whitelistValidation']);
+    for (const value of [[], 'same', 1]) {
+      expect(await allConstraintsOf({ ...enabled, external: value })).toEqual(
+        expect.arrayContaining(['external.isObject']),
+      );
+    }
+  });
+
+  it(`회사 밖 제목 · 내용은 사내 칸과 같은 형식 한도를 늘 본다 — ${MAX_VACATION_SUBJECT_LENGTH_WHEN_OFF}자 · ${MAX_VACATION_TEXT_LENGTH_WHEN_OFF}자 · 제어 문자 (켤 때의 150 · 600자는 서비스가)`, async () => {
+    for (const isEnabled of [false, true]) {
+      expect(
+        await allConstraintsOf({
+          ...enabled,
+          isEnabled,
+          external: {
+            ...external,
+            subject: 'x'.repeat(MAX_VACATION_SUBJECT_LENGTH_WHEN_OFF),
+            textBody: 'x'.repeat(MAX_VACATION_TEXT_LENGTH_WHEN_OFF),
+          },
+        }),
+      ).toEqual([]);
+    }
+    expect(
+      await allConstraintsOf({
+        ...enabled,
+        external: {
+          ...external,
+          subject: 'x'.repeat(MAX_VACATION_SUBJECT_LENGTH_WHEN_OFF + 1),
+          textBody: 'x'.repeat(MAX_VACATION_TEXT_LENGTH_WHEN_OFF + 1),
+        },
+      }),
+    ).toEqual([
+      'external.subject.maxCodeUnits',
+      'external.textBody.maxCodeUnits',
+    ]);
+    expect(
+      await allConstraintsOf({
+        ...enabled,
+        external: { ...external, subject: 'a\nb', textBody: 'a\u0000' },
+      }),
+    ).toEqual(['external.subject.matches', 'external.textBody.matches']);
+    // 켤 때의 한도(150 · 600)를 넘는 글도 형식으로는 맞다 — 켤 때 따로 쓰기면 서비스가 VAL_001
+    expect(
+      await allConstraintsOf({
+        ...enabled,
+        external: {
+          ...external,
+          subject: 'x'.repeat(MAX_VACATION_SUBJECT_LENGTH + 1),
+          textBody: 'x'.repeat(MAX_VACATION_TEXT_LENGTH + 1),
+        },
+      }),
+    ).toEqual([]);
+  });
+});
+
 describe('isUtcDateTime', () => {
   it('JS toISOString 모양(소수 초 3자리까지)과 소수 초 없는 모양을 받는다', () => {
     expect(isUtcDateTime('2026-11-02T15:00:00.000Z')).toBe(true);

backend/src/modules/mail/dto/mail-vacation.dto.ts

@@ -1,15 +1,22 @@
-import { ApiProperty } from '@nestjs/swagger';
+import { ApiProperty, ApiPropertyOptional, OmitType } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
 import {
   IsBoolean,
+  IsIn,
+  IsObject,
+  IsOptional,
   IsString,
   Matches,
   ValidateBy,
   ValidateIf,
+  ValidateNested,
   type ValidationOptions,
 } from 'class-validator';
 
 import { MaxCodeUnits } from '@/common/decorators/code-units.decorator';
 import {
+  MAIL_VACATION_EXTERNAL_MODES,
+  MAX_VACATION_HTML_LENGTH,
   MAX_VACATION_SUBJECT_LENGTH,
   MAX_VACATION_SUBJECT_LENGTH_WHEN_OFF,
   MAX_VACATION_TEXT_LENGTH,
@@ -18,7 +25,8 @@ import {
   SINGLE_LINE_TEXT_PATTERN,
 } from '@/modules/mail/mail.constants';
 import type {
-  MailVacation,
+  MailVacationExternal,
+  MailVacationExternalMode,
   MailVacationState,
 } from '@/modules/mail/mail.types';
 
@@ -46,16 +54,84 @@ export function IsUtcDateTime(options: ValidationOptions) {
   );
 }
 
-/** null 은 "날짜 없음"으로 받는다 — 키가 없으면(undefined) 형식 오류다 (전체 교체라 다섯 필드를 모두 보낸다) */
+/** null 은 "날짜 없음" · "쓴 적 없음"으로 받는다 — 키가 없으면(undefined) 형식 오류다 (전체 교체라 키를 모두 보낸다) */
 const unlessNull = (_object: object, value: unknown) => value !== null;
 
+const HTML_BODY_DESCRIPTION =
+  `서식 본문 — 서식 본문과 같은 허용 목록으로 정화해 저장한다(그림은 넣을 수 없다). 정화 뒤 ${MAX_VACATION_HTML_LENGTH.toLocaleString('ko-KR')}자까지(켤 때만 본다 — 넘으면 400 VAL_001). ` +
+  'null · 빈 글이면 글만. 받는 사람에게는 글(textBody) + 서식 두 벌로 간다';
+
+/**
+ * 회사 밖 응답 (16단계) — 네 키를 모두 보낸다(글 칸은 null 가능). 따로 쓰기(separate)이고 켤 때는 제목 · 내용이 1자 이상 ·
+ * 제목 150자 · 내용 600자 · 서식 10,000자(서비스가 본다). 다른 고르기여도 써 둔 글은 그대로 저장한다
+ */
+export class MailVacationExternalDto implements MailVacationExternal {
+  @ApiProperty({
+    description:
+      '회사 밖(봉투 보낸 사람의 도메인이 회사 메일 도메인이 아님)에서 온 메일에 — same: 사내와 같은 응답(처음 값) · none: 보내지 않기 · separate: 아래 제목 · 내용으로',
+    enum: MAIL_VACATION_EXTERNAL_MODES,
+    example: 'separate',
+  })
+  @IsIn(MAIL_VACATION_EXTERNAL_MODES, {
+    message: '회사 밖 응답을 다시 선택해 주세요.',
+  })
+  mode!: MailVacationExternalMode;
+
+  @ApiProperty({
+    description: `회사 밖에 보낼 제목 — 켜고 따로 쓰기면 1~${MAX_VACATION_SUBJECT_LENGTH}자, 그 밖에는 ${MAX_VACATION_SUBJECT_LENGTH_WHEN_OFF}자까지. 빈 글은 null 로 저장한다. 제어 문자는 쓸 수 없다`,
+    nullable: true,
+    type: String,
+    maxLength: MAX_VACATION_SUBJECT_LENGTH_WHEN_OFF,
+    example: 'Out of office',
+  })
+  @ValidateIf(unlessNull)
+  @IsString({ message: '회사 밖에 보낼 제목 형식이 올바르지 않습니다.' })
+  @MaxCodeUnits(MAX_VACATION_SUBJECT_LENGTH_WHEN_OFF, {
+    message: `회사 밖에 보낼 제목은 ${MAX_VACATION_SUBJECT_LENGTH_WHEN_OFF}자 이하로 입력해 주세요.`,
+  })
+  @Matches(SINGLE_LINE_TEXT_PATTERN, {
+    message: '회사 밖에 보낼 제목에는 줄바꿈 같은 제어 문자를 쓸 수 없습니다.',
+  })
+  subject!: string | null;
+
+  @ApiProperty({
+    description: `회사 밖에 보낼 내용(보이는 글) — 켜고 따로 쓰기면 1~${MAX_VACATION_TEXT_LENGTH}자, 그 밖에는 ${MAX_VACATION_TEXT_LENGTH_WHEN_OFF.toLocaleString('ko-KR')}자까지. 빈 글은 null 로 저장한다`,
+    nullable: true,
+    type: String,
+    maxLength: MAX_VACATION_TEXT_LENGTH_WHEN_OFF,
+    example: 'I am out of the office until November 7.',
+  })
+  @ValidateIf(unlessNull)
+  @IsString({ message: '회사 밖에 보낼 내용 형식이 올바르지 않습니다.' })
+  @MaxCodeUnits(MAX_VACATION_TEXT_LENGTH_WHEN_OFF, {
+    message: `회사 밖에 보낼 내용은 ${MAX_VACATION_TEXT_LENGTH_WHEN_OFF.toLocaleString('ko-KR')}자 이하로 입력해 주세요.`,
+  })
+  @Matches(MULTI_LINE_TEXT_PATTERN, {
+    message:
+      '회사 밖에 보낼 내용에는 탭 · 줄바꿈 밖의 제어 문자를 쓸 수 없습니다.',
+  })
+  textBody!: string | null;
+
+  @ApiProperty({
+    description: `회사 밖에 보낼 ${HTML_BODY_DESCRIPTION}`,
+    nullable: true,
+    type: String,
+    example:
+      '<p style="margin: 0">I am out of the office until <strong>November 7</strong>.</p>',
+  })
+  @ValidateIf(unlessNull)
+  @IsString({ message: '회사 밖에 보낼 내용 형식이 올바르지 않습니다.' })
+  htmlBody!: string | null;
+}
+
 /**
  * 부재중 자동 응답 — PUT 본문(전체 교체). GET · PUT 응답은 이것에 isActive 를 더한 MailVacationStateDto 다 (계약 2절 "부재중 자동 응답", 7단계).
- * 켤 때 제목 · 내용이 비었는지 · 켤 때의 길이(150자 · 600자), 시작이 끝보다 앞인지는 서비스가 본다 (400 VAL_001).
+ * 켤 때 제목 · 내용이 비었는지 · 켤 때의 길이(150자 · 600자 · 서식 10,000자), 시작이 끝보다 앞인지는 서비스가 본다 (400 VAL_001).
  * 여기서는 켬 · 끔과 상관없는 한도(4단계의 200자 · 4,000자)만 본다 — 같은 속성에 ValidateIf 를 걸면 그 속성의 검사가 모두 빠져
- * 켤 때만의 한도를 함께 걸 수 없다. 서식 본문은 받지 않는다.
+ * 켤 때만의 한도를 함께 걸 수 없다.
+ * 16단계의 htmlBody · external 은 보내지 않아도 된다 — 없으면 글만 · 사내와 같은 응답(회사 밖 글 칸 null)으로 저장한다(옛 화면이 보는 그대로)
  */
-export class MailVacationDto implements MailVacation {
+export class MailVacationDto {
   @ApiProperty({
     description: `켜짐 — 켜면 제목 · 내용이 1자 이상, 제목 ${MAX_VACATION_SUBJECT_LENGTH}자 · 내용 ${MAX_VACATION_TEXT_LENGTH}자까지여야 한다 (아니면 400 VAL_001)`,
     example: true,
@@ -102,8 +178,8 @@ export class MailVacationDto implements MailVacation {
 
   @ApiProperty({
     description:
-      `자동 응답 내용 — 글자만(서식 없음). 켤 때는 1~${MAX_VACATION_TEXT_LENGTH.toLocaleString('ko-KR')}자(엔진의 바이트 한도 안), ` +
-      `꺼 둔 채로는 ${MAX_VACATION_TEXT_LENGTH_WHEN_OFF.toLocaleString('ko-KR')}자까지 (JS 문자열 길이). 서명은 붙지 않는다`,
+      `자동 응답 내용(보이는 글 — 서식을 뺀 글). 켤 때는 1~${MAX_VACATION_TEXT_LENGTH.toLocaleString('ko-KR')}자(엔진의 바이트 한도 안), ` +
+      `꺼 둔 채로는 ${MAX_VACATION_TEXT_LENGTH_WHEN_OFF.toLocaleString('ko-KR')}자까지 (JS 문자열 길이). 서식 본문(htmlBody)이 있으면 받는 쪽의 글 판이다. 서명은 붙지 않는다`,
     maxLength: MAX_VACATION_TEXT_LENGTH_WHEN_OFF,
     example: '11월 7일까지 휴가입니다. 급한 일은 이도윤 님께 연락해 주세요.',
   })
@@ -115,16 +191,52 @@ export class MailVacationDto implements MailVacation {
     message: '자동 응답 내용에는 탭 · 줄바꿈 밖의 제어 문자를 쓸 수 없습니다.',
   })
   textBody!: string;
+
+  @ApiPropertyOptional({
+    description: `${HTML_BODY_DESCRIPTION} (16단계 — 보내지 않으면 null)`,
+    nullable: true,
+    type: String,
+    example:
+      '<p style="margin: 0">11월 7일까지 <strong>휴가</strong>입니다.</p>',
+  })
+  @IsOptional()
+  @IsString({ message: '자동 응답 내용 형식이 올바르지 않습니다.' })
+  htmlBody?: string | null;
+
+  @ApiPropertyOptional({
+    description:
+      '회사 밖에서 온 메일에 하는 응답 (16단계) — 보내지 않거나 null 이면 사내와 같은 응답(글 칸 null)으로 저장한다',
+    type: MailVacationExternalDto,
+  })
+  @IsOptional()
+  @IsObject({ message: '회사 밖 응답 형식이 올바르지 않습니다.' })
+  @ValidateNested()
+  @Type(() => MailVacationExternalDto)
+  external?: MailVacationExternalDto | null;
 }
 
 /**
  * GET · PUT /api/mail-vacation 의 응답 (계약 2절의 MailVacationState — 7단계) — 저장한 값 + 지금 동작하는지.
- * PUT 본문에는 isActive 를 넣지 않는다 (넣으면 모르는 필드 — 400 VAL_001). 응답 문서용이라 검사 데코레이터를 더하지 않는다
+ * 16단계의 htmlBody · external 은 응답에 늘 있다. PUT 본문에는 isActive 를 넣지 않는다 (넣으면 모르는 필드 — 400 VAL_001).
+ * 응답 문서용이라 검사 데코레이터를 더하지 않는다
  */
 export class MailVacationStateDto
-  extends MailVacationDto
+  extends OmitType(MailVacationDto, ['htmlBody', 'external'] as const)
   implements MailVacationState
 {
+  @ApiProperty({
+    description: `${HTML_BODY_DESCRIPTION} — 늘 있다(없으면 null)`,
+    nullable: true,
+    type: String,
+  })
+  htmlBody!: string | null;
+
+  @ApiProperty({
+    description: '회사 밖에서 온 메일에 하는 응답 — 늘 있다',
+    type: MailVacationExternalDto,
+  })
+  external!: MailVacationExternalDto;
+
   @ApiProperty({
     description:
       'false = 메일 엔진에서 우리 규칙(메일 필터와 한 규칙)이 꺼져 있어 켜 둔 자동 응답이 지금은 동작하지 않는다 — 저장하면 다시 켜진다. ' +

backend/src/modules/mail/dto/mailbox.dto.spec.ts

@@ -4,8 +4,9 @@ import { validate } from 'class-validator';
 import { MAX_MAILBOX_NAME_LENGTH } from '@/modules/mail/mail.constants';
 import {
   CreateMailboxDto,
+  MailboxDeleteQueryDto,
   MailboxMessagesPatchDto,
-  RenameMailboxDto,
+  UpdateMailboxDto,
 } from './mailbox.dto';
 
 /** 전역 ValidationPipe 와 같은 옵션으로 검증한다 (app.setup.ts — stopAtFirstError 만 빼고 — 걸린 규칙을 모두 본다, 통과 · 실패는 같다) — 변환한 값과 걸린 규칙 이름 */
@@ -29,7 +30,7 @@ async function check<T extends object>(
 describe('메일함 요청 본문 (계약 2절 "메일함 관리")', () => {
   it.each([
     ['만들기', CreateMailboxDto],
-    ['이름 바꾸기', RenameMailboxDto],
+    ['바꾸기', UpdateMailboxDto],
   ] as const)(
     `%s — 이름은 앞뒤 공백을 뺀 1~${MAX_MAILBOX_NAME_LENGTH}자 (JS 문자열 길이)`,
     async (_name, type) => {
@@ -65,7 +66,7 @@ describe('메일함 요청 본문 (계약 2절 "메일함 관리")', () => {
 
   it.each([
     ['만들기', CreateMailboxDto],
-    ['이름 바꾸기', RenameMailboxDto],
+    ['바꾸기', UpdateMailboxDto],
   ] as const)(
     '%s — "/" 와 제어 문자(줄바꿈 · 탭 등)는 쓸 수 없다, 문자열이 아니면 형식 오류',
     async (_name, type) => {
@@ -87,31 +88,72 @@ describe('메일함 요청 본문 (계약 2절 "메일함 관리")', () => {
       expect((await check(type, { name: 7 })).constraints).toEqual(
         expect.arrayContaining(['isString']),
       );
-      expect((await check(type, {})).constraints).toEqual(
+      expect((await check(type, { name: null })).constraints).toEqual(
         expect.arrayContaining(['isString']),
       );
     },
   );
 
-  it('만들기의 상위는 없거나 null(맨 위) · 메일함 id 형식 — 이름 바꾸기에는 상위가 없다', async () => {
+  it('만들기는 이름이 없으면 형식 오류 — 바꾸기는 이름을 보내지 않아도 된다(빈 본문은 서비스가 VAL_001)', async () => {
+    expect((await check(CreateMailboxDto, {})).constraints).toEqual(
+      expect.arrayContaining(['isString']),
+    );
+    expect((await check(UpdateMailboxDto, {})).constraints).toEqual([]);
+  });
+
+  it.each([
+    ['만들기', CreateMailboxDto, { name: '거래처' }],
+    ['바꾸기(옮기기 — 15단계)', UpdateMailboxDto, {}],
+  ] as const)(
+    '%s의 상위는 없거나 null(맨 위) · 메일함 id 형식',
+    async (_name, type, base) => {
+      expect((await check(type, base)).constraints).toEqual([]);
+      expect(
+        (await check(type, { ...base, parentId: null })).constraints,
+      ).toEqual([]);
+      expect(
+        (await check(type, { ...base, parentId: 'a' })).constraints,
+      ).toEqual([]);
+      for (const parentId of ['../a', '', 'a b', 7]) {
+        expect((await check(type, { ...base, parentId })).constraints).toEqual([
+          'matches',
+        ]);
+      }
+    },
+  );
+
+  it('바꾸기는 이름 · 상위를 함께 받고, 보낸 값을 그대로 둔다 — null 상위는 null(맨 위), 보내지 않은 칸은 undefined', async () => {
+    const both = await check(UpdateMailboxDto, {
+      name: ' 2025 ',
+      parentId: 'u1',
+    });
+    expect(both.constraints).toEqual([]);
+    expect(both.dto).toMatchObject({ name: '2025', parentId: 'u1' });
+
+    const top = await check(UpdateMailboxDto, { parentId: null });
+    expect(top.constraints).toEqual([]);
+    expect(top.dto.parentId).toBeNull();
+    expect(top.dto.name).toBeUndefined();
+
     expect(
-      (await check(CreateMailboxDto, { name: '거래처' })).constraints,
-    ).toEqual([]);
+      (await check(UpdateMailboxDto, { name: '거래처', role: 'inbox' }))
+        .constraints,
+    ).toEqual(['whitelistValidation']);
+  });
+
+  it('지우기의 쿼리는 withChildren=true 만 받는다 (15단계 — 하위 메일함까지)', async () => {
+    expect((await check(MailboxDeleteQueryDto, {})).constraints).toEqual([]);
     expect(
-      (await check(CreateMailboxDto, { name: '거래처', parentId: null }))
+      (await check(MailboxDeleteQueryDto, { withChildren: 'true' }))
         .constraints,
     ).toEqual([]);
+    for (const withChildren of ['false', 'TRUE', '1', '', true]) {
+      expect(
+        (await check(MailboxDeleteQueryDto, { withChildren })).constraints,
+      ).toEqual(['isIn']);
+    }
     expect(
-      (await check(CreateMailboxDto, { name: '거래처', parentId: 'a' }))
-        .constraints,
-    ).toEqual([]);
-    expect(
-      (await check(CreateMailboxDto, { name: '거래처', parentId: '../a' }))
-        .constraints,
-    ).toEqual(['matches']);
-    expect(
-      (await check(RenameMailboxDto, { name: '거래처', parentId: 'a' }))
-        .constraints,
+      (await check(MailboxDeleteQueryDto, { recursive: 'true' })).constraints,
     ).toEqual(['whitelistValidation']);
   });
 

backend/src/modules/mail/dto/mailbox.dto.ts

@@ -1,6 +1,13 @@
 import { applyDecorators } from '@nestjs/common';
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { Equals, IsOptional, IsString, Matches } from 'class-validator';
+import {
+  Equals,
+  IsIn,
+  IsOptional,
+  IsString,
+  Matches,
+  ValidateIf,
+} from 'class-validator';
 
 import {
   MaxCodeUnits,
@@ -16,15 +23,32 @@ import {
 /** 메일함 이름에 쓸 수 없는 '/' — 경로 구분자로 읽는 메일 프로그램이 있다 (계약 2절 "메일함 관리") */
 const NO_SLASH_PATTERN = /^[^/]*$/;
 
-/** 메일함 이름 — 앞뒤 공백을 뺀 1~MAX_MAILBOX_NAME_LENGTH 자(JS 문자열 길이), `/` · 제어 문자 없음. 만들기 · 이름 바꾸기가 같이 쓴다 */
-function MailboxName() {
+/** 메일함 이름 칸의 설명 */
+const MAILBOX_NAME_DESCRIPTION = `메일함 이름 — 앞뒤 공백을 뺀 1~${MAX_MAILBOX_NAME_LENGTH}자(JS 문자열 길이). "/" 와 제어 문자(줄바꿈 · 탭 등)는 쓸 수 없다. 같은 상위 안에 같은 이름이 있으면 409 MAIL_009`;
+
+/** 보낸 칸만 검사한다 — 없으면(undefined) 건너뛰고, null 은 검사해 형식 오류로 막는다 (이름 · 상위 가운데 바꿀 것만 보내는 PATCH) */
+const unlessAbsent = (_object: object, value: unknown) => value !== undefined;
+
+/**
+ * 메일함 이름 — 앞뒤 공백을 뺀 1~MAX_MAILBOX_NAME_LENGTH 자(JS 문자열 길이), `/` · 제어 문자 없음. 만들기 · 바꾸기가 같이 쓴다.
+ * `optional` 이면(바꾸기 — 15단계) 보내지 않아도 된다 — 보낸 값은 같은 검사를 한다(null 도 형식 오류)
+ */
+function MailboxName({ optional = false }: { optional?: boolean } = {}) {
   return applyDecorators(
-    ApiProperty({
-      description: `메일함 이름 — 앞뒤 공백을 뺀 1~${MAX_MAILBOX_NAME_LENGTH}자(JS 문자열 길이). "/" 와 제어 문자(줄바꿈 · 탭 등)는 쓸 수 없다. 같은 상위 안에 같은 이름이 있으면 409 MAIL_009`,
-      example: '프로젝트',
-      minLength: 1,
-      maxLength: MAX_MAILBOX_NAME_LENGTH,
-    }),
+    optional
+      ? ApiPropertyOptional({
+          description: `${MAILBOX_NAME_DESCRIPTION}. 보내지 않으면 이름은 그대로`,
+          example: '프로젝트',
+          minLength: 1,
+          maxLength: MAX_MAILBOX_NAME_LENGTH,
+        })
+      : ApiProperty({
+          description: MAILBOX_NAME_DESCRIPTION,
+          example: '프로젝트',
+          minLength: 1,
+          maxLength: MAX_MAILBOX_NAME_LENGTH,
+        }),
+    ...(optional ? [ValidateIf(unlessAbsent)] : []),
     TrimString(),
     IsString({ message: '메일함 이름 형식이 올바르지 않습니다.' }),
     MinCodeUnits(1, { message: '메일함 이름을 입력해 주세요.' }),
@@ -59,10 +83,43 @@ export class CreateMailboxDto {
   parentId?: string | null;
 }
 
-/** PATCH /api/mailboxes/{id} — 이름만 바꾼다 (다른 상위로 옮기기는 이 단계에서 하지 않는다) */
-export class RenameMailboxDto {
-  @MailboxName()
-  name!: string;
+/**
+ * PATCH /api/mailboxes/{id} — 이름 · 상위(옮기기 — 15단계) 가운데 바꿀 것만. 둘 다 없으면(빈 본문) 서비스가 400 VAL_001.
+ * 상위의 자리 규칙(만들기와 같다) · 자기 자신 · 하위 아래로 옮기기는 어댑터가 본다
+ */
+export class UpdateMailboxDto {
+  @MailboxName({ optional: true })
+  name?: string;
+
+  @ApiPropertyOptional({
+    description:
+      '새 상위 메일함 id — null 이면 맨 위, 보내지 않으면 상위는 그대로. 만들기와 같은 자리만(받은편지함 · 보관함 · 내 메일함 아래 — 그 밖 400 VAL_001, 없는 id 는 404 RES_001). ' +
+      '자기 자신 · 자기 하위 아래로는 400 VAL_001. 하위 메일함과 안의 메일은 함께 간다',
+    nullable: true,
+    type: String,
+    example: 'a',
+  })
+  @IsOptional()
+  @Matches(MAIL_ID_PATTERN, { message: '옮길 곳을 다시 선택해 주세요.' })
+  parentId?: string | null;
+}
+
+/** 하위 메일함까지 지우기의 값 — 이것만 받는다 (15단계) */
+export const WITH_CHILDREN = 'true';
+
+/** DELETE /api/mailboxes/{id} 의 쿼리 — withChildren=true 면 하위 메일함까지 지운다 (15단계). 모르는 쿼리는 400 VAL_001 */
+export class MailboxDeleteQueryDto {
+  @ApiPropertyOptional({
+    description:
+      'true 면 하위 메일함이 있어도 그 메일함과 하위 모두를 지운다(깊은 것부터 — 안의 메일은 휴지통으로). 없으면 하위가 있을 때 400 VAL_001(옛 화면이 모르고 하위를 지우지 않게). 다른 값은 400 VAL_001',
+    enum: [WITH_CHILDREN],
+    example: WITH_CHILDREN,
+  })
+  @IsOptional()
+  @IsIn([WITH_CHILDREN], {
+    message: '하위 메일함 지우기 값이 올바르지 않습니다.',
+  })
+  withChildren?: typeof WITH_CHILDREN;
 }
 
 /** PATCH /api/mailboxes/{id}/messages — 그 메일함 전체를 읽음으로 (true 만 받는다) */

backend/src/modules/mail/html/sanitize-outgoing-html.spec.ts

@@ -775,4 +775,60 @@ describe('sanitizeOutgoingHtml (보내는 서식 본문)', () => {
       }
     });
   });
+
+  /**
+   * 쓰기 화면의 서명 자리(16단계 — 계약 2절 "앱이 만드는 모양") — 빈 문단 하나 뒤의 **속성 없는 div 하나**가 서명 경계다.
+   * 웹 편집기도 같은 경계로 서명을 넣고 임시 저장 · 이어 쓰기에서 다시 찾으므로, 보내는 정화 · 임시 저장본 다시 읽기 · 받은 메일 정화를 지나도 남아야 한다
+   */
+  describe('서명 자리 — 빈 문단 뒤 속성 없는 div (16단계)', () => {
+    const IMAGE_ID = '3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d';
+    const signatureBlock =
+      '<div><p style="margin: 0"><strong>김아라</strong> · 인프라팀</p>' +
+      `<img src="/api/mail-signature/images/${IMAGE_ID}" width="144" alt=""></div>`;
+    const composed =
+      `<div style="font-family: ${DEFAULT_FONT}; font-size: 14px; line-height: 1.75">` +
+      '<p style="margin: 0">안녕하세요.</p><p style="margin: 0"><br></p>' +
+      signatureBlock +
+      '<div data-ara-quote-start=""></div>' +
+      '<blockquote style="margin: 0; padding-left: 12px; border-left: 2px solid #D0D5DD"><p style="margin: 0">원문</p></blockquote></div>';
+    /** 정화한 서명 자리 — 빈 문단 바로 뒤의 속성 없는 div, 안은 서명 */
+    const keptBoundary =
+      '<p style="margin:0"><br /></p><div><p style="margin:0"><strong>김아라</strong> · 인프라팀</p>' +
+      `<img src="/api/mail-signature/images/${IMAGE_ID}" width="144" alt="" /></div>`;
+
+    it('보낼 때 · 임시 저장할 때(인용 경계 표시를 남기는 정화)와 저장본을 다시 열 때(표시 없는 정화) 모두 경계 div 가 속성 없이 남는다', () => {
+      const ids = new Set([IMAGE_ID]);
+      for (const options of [
+        { signatureImageIds: ids, keepQuoteStart: true },
+        { signatureImageIds: ids },
+      ]) {
+        const html = clean(composed, options);
+        expect(html).toContain(keptBoundary);
+        // 정화한 것을 다시 정화해도 같다 — 이어 쓰기를 거듭해도 경계가 그대로다
+        expect(clean(html, { signatureImageIds: ids })).toBe(
+          clean(composed, { signatureImageIds: ids }),
+        );
+      }
+    });
+
+    it('받은 메일 정화(보낸편지함 · 받는 사람이 다시 읽을 때)도 속성 없는 div 를 그대로 둔다', () => {
+      const sent = clean(composed, { signatureImageIds: new Set([IMAGE_ID]) });
+      const { html } = sanitizeMailHtml(sent);
+      expect(html).toContain(
+        '<p style="margin:0"><br /></p><div><p style="margin:0"><strong>김아라</strong> · 인프라팀</p>',
+      );
+    });
+
+    it('속성이 모두 지워진 div 도 속성 없는 div 가 된다 — 경계는 자리(빈 문단 바로 뒤)로 알아본다 (화면 · 앱이 함께 보는 알려진 모양)', () => {
+      for (const div of [
+        '<div style="">',
+        '<div style="position: absolute">',
+        '<div class="sig" data-x="1">',
+      ]) {
+        expect(
+          clean(`<p style="margin: 0"><br></p>${div}<p>서명</p></div>`),
+        ).toBe('<p style="margin:0"><br /></p><div><p>서명</p></div>');
+      }
+    });
+  });
 });

backend/src/modules/mail/html/sanitize-stored-html.spec.ts

@@ -0,0 +1,65 @@
+import { MAX_BODY_HTML_LENGTH } from '@/modules/mail/mail.constants';
+import { sanitizeStoredHtml } from './sanitize-stored-html';
+
+describe('sanitizeStoredHtml — 저장해 두는 짧은 서식 글(서명 · 부재중 응답)의 정화', () => {
+  const IMAGE_ID = '3f1c0a2e-0f1b-4f2a-9a1e-6c9f0a1b2c3d';
+  const image = `<img src="/api/mail-signature/images/${IMAGE_ID}" width="96">`;
+
+  it('보내는 정화를 거친다 — 스크립트 · 이벤트 속성은 지우고, 그림은 넘겨준 서명 그림만 남긴다', () => {
+    expect(
+      sanitizeStoredHtml(
+        `<p onclick="x()"><strong>휴가</strong><script>x()</script></p>${image}`,
+        { maxLength: null },
+      ),
+    ).toEqual({ ok: true, html: '<p><strong>휴가</strong></p>' });
+    expect(
+      sanitizeStoredHtml(`<p>서명</p>${image}`, {
+        maxLength: null,
+        signatureImageIds: new Set([IMAGE_ID]),
+      }),
+    ).toEqual({
+      ok: true,
+      html: `<p>서명</p><img src="/api/mail-signature/images/${IMAGE_ID}" width="96" />`,
+    });
+  });
+
+  it('없거나 비었거나 정화해서 남는 것이 없으면 null', () => {
+    for (const html of [null, undefined, '', '<script>x()</script>', '  ']) {
+      expect(sanitizeStoredHtml(html, { maxLength: 10 })).toEqual({
+        ok: true,
+        html: null,
+      });
+    }
+  });
+
+  it('정화 뒤 길이는 maxLength 일 때만 본다 — 정화 전 길이 · 파서 비용은 늘 본다', () => {
+    const long = `<p>${'가'.repeat(10_000)}</p>`;
+    expect(sanitizeStoredHtml(long, { maxLength: 10_000 })).toEqual({
+      ok: false,
+      problem: 'too-long',
+      length: 10_007,
+    });
+    expect(sanitizeStoredHtml(long, { maxLength: null })).toEqual({
+      ok: true,
+      html: long,
+    });
+    expect(
+      sanitizeStoredHtml(`<p>${'가'.repeat(10_000 - 7)}</p>`, {
+        maxLength: 10_000,
+      }),
+    ).toMatchObject({ ok: true });
+
+    expect(
+      sanitizeStoredHtml('x'.repeat(MAX_BODY_HTML_LENGTH + 1), {
+        maxLength: null,
+      }),
+    ).toEqual({
+      ok: false,
+      problem: 'too-long',
+      length: MAX_BODY_HTML_LENGTH + 1,
+    });
+    expect(
+      sanitizeStoredHtml('<b>'.repeat(166_666), { maxLength: null }),
+    ).toMatchObject({ ok: false, problem: 'too-complex' });
+  });
+});

backend/src/modules/mail/html/sanitize-stored-html.ts

@@ -0,0 +1,54 @@
+import { MAX_BODY_HTML_LENGTH } from '@/modules/mail/mail.constants';
+import { checkHtmlParseBudget } from './html-parse-budget';
+import { sanitizeOutgoingHtml } from './sanitize-outgoing-html';
+
+/**
+ * 저장해 두고 다시 쓰는 짧은 서식 글의 정화 (순수 함수) — 서명(계약 2절 "서명")과 부재중 응답의 서식 본문(16단계 — "부재중 자동 응답").
+ * 쓰기 화면의 서식 본문과 같은 규칙이다:
+ * 1. 정화 전 — 길이(MAX_BODY_HTML_LENGTH — 500,000자)와 파서 비용(html-parse-budget.ts — 정화가 이벤트 루프를 오래 붙잡지 않게)
+ * 2. 보내는 정화(sanitize-outgoing-html.ts) — 그림은 `signatureImageIds` 에 든 그 사람의 서명 그림만 남는다(없으면 그림 없음 — 부재중)
+ * 3. 정화 뒤 — `maxLength`(JS 문자열 길이)를 넘으면 실패. null 이면 보지 않는다(부재중을 꺼 둔 채 저장할 때)
+ * 비었거나 정화해서 남는 것이 없으면 null 이다. 실패는 부르는 쪽이 400 VAL_001 로 던진다(사유만 — 글은 로그에 남기지 않는다)
+ */
+
+/** too-long: 정화 전 · 뒤의 길이 한도 초과, too-complex: 파서 비용 한도 초과(깊은 중첩 등) */
+export type StoredHtmlProblem = 'too-long' | 'too-complex';
+
+export type StoredHtmlResult =
+  | { readonly ok: true; readonly html: string | null }
+  | {
+      readonly ok: false;
+      readonly problem: StoredHtmlProblem;
+      /** 걸린 글의 길이 (JS 문자열 길이) — 로그용 */
+      readonly length: number;
+    };
+
+export interface StoredHtmlOptions {
+  /** 정화한 뒤의 최대 길이 — null 이면 보지 않는다 */
+  readonly maxLength: number | null;
+  /** 남겨도 되는 서명 그림 id — 없으면 그림을 하나도 남기지 않는다 */
+  readonly signatureImageIds?: ReadonlySet<string>;
+}
+
+export function sanitizeStoredHtml(
+  html: string | null | undefined,
+  options: StoredHtmlOptions,
+): StoredHtmlResult {
+  if (!html) return { ok: true, html: null };
+  if (html.length > MAX_BODY_HTML_LENGTH) {
+    return { ok: false, problem: 'too-long', length: html.length };
+  }
+  if (!checkHtmlParseBudget(html).ok) {
+    return { ok: false, problem: 'too-complex', length: html.length };
+  }
+  const sanitized = sanitizeOutgoingHtml(
+    html,
+    options.signatureImageIds
+      ? { signatureImageIds: options.signatureImageIds }
+      : {},
+  );
+  if (options.maxLength !== null && sanitized.length > options.maxLength) {
+    return { ok: false, problem: 'too-long', length: sanitized.length };
+  }
+  return { ok: true, html: sanitized === '' ? null : sanitized };
+}

backend/src/modules/mail/jmap/filter-run-cursor.spec.ts

@@ -1,7 +1,9 @@
 import { BusinessException } from '@/common/errors/business.exception';
 import type { MailFilterRunRequest } from '@/modules/mail/mail.types';
 import {
+  decodeBlockRunCursor,
   decodeFilterRunCursor,
+  encodeBlockRunCursor,
   encodeFilterRunCursor,
   MAX_FILTER_RUN_SECONDS,
   type FilterRunPosition,
@@ -172,3 +174,62 @@ describe('이미 받은 메일에 필터 적용의 cursor (계약 2절 "이미
     ).toEqual({ before: NINE, anchor: null, anchorTime: null });
   });
 });
+
+describe('차단할 때 받은편지함 정리의 cursor (15단계 — 계약 2절 "보낸 사람 차단")', () => {
+  const position: FilterRunPosition = {
+    before: NINE + 1,
+    anchor: 'seaaaaer',
+    anchorTime: NINE - 60,
+  };
+
+  it('자리는 필터 적용과 같은 모양으로 되돌린다 — 지문은 그 보낸 사람', () => {
+    for (const sender of ['kim@spam.example', '@spam.example']) {
+      expect(
+        decodeBlockRunCursor(encodeBlockRunCursor(position, sender), sender),
+      ).toEqual(position);
+    }
+    expect(encodeBlockRunCursor(position, '@spam.example')).toMatch(
+      /^[A-Za-z0-9_-]+$/,
+    );
+  });
+
+  it('다른 보낸 사람의 cursor · 필터 적용의 cursor 는 VAL_001 — 거꾸로 차단 정리의 cursor 로 필터를 이어 하지도 못한다', () => {
+    const cursor = encodeBlockRunCursor(position, 'kim@spam.example');
+    for (const other of ['lee@spam.example', '@spam.example']) {
+      expect(failureOf(() => decodeBlockRunCursor(cursor, other))).toEqual({
+        code: 'VAL_001',
+        reason: 'invalid-mail-block-run-cursor:other-sender',
+      });
+    }
+    expect(
+      failureOf(() =>
+        decodeBlockRunCursor(
+          encodeFilterRunCursor(position, rule),
+          'kim@spam.example',
+        ),
+      ),
+    ).toEqual({
+      code: 'VAL_001',
+      reason: 'invalid-mail-block-run-cursor:other-sender',
+    });
+    expect(failureOf(() => decodeFilterRunCursor(cursor, rule))).toEqual({
+      code: 'VAL_001',
+      reason: 'invalid-filter-run-cursor:other-rule',
+    });
+  });
+
+  it('깨진 cursor 는 필터 적용과 같은 검사로 VAL_001', () => {
+    for (const [cursor, reason] of [
+      ['%%%', 'not-json'],
+      [forged({ v: 1, b: NINE }), 'shape'],
+      ['a'.repeat(1_025), 'too-long'],
+    ] as const) {
+      expect(
+        failureOf(() => decodeBlockRunCursor(cursor, 'kim@spam.example')),
+      ).toEqual({
+        code: 'VAL_001',
+        reason: `invalid-mail-block-run-cursor:${reason}`,
+      });
+    }
+  });
+});

backend/src/modules/mail/jmap/filter-run-cursor.ts

@@ -17,7 +17,10 @@ import type { MailFilterRunRequest } from '@/modules/mail/mail.types';
  * - anchorTime: 그 메일의 받은 시각(초) — 그 메일이 그사이 받은편지함에서 빠졌으면(`anchorNotFound`) `before: anchorTime + 1초` 의 처음부터 읽는다
  *   (그 초의 메일을 다시 판정한다 — 건너뛰지 않는다). 그렇게 읽은 차례에 남긴 메일이 없으면 anchor 는 없고 anchorTime 만 남는다
  * - 규칙의 지문: 묶는 방법 · 조건 · 할 일 — 다른 규칙의 cursor 를 섞어 쓰지 못하게 (충돌보다는 "다른 규칙" 감지가 목적이라 짧게 둔다)
- * 시각은 UTC 의 초(epoch)다 — 해석할 때 범위(0 ~ 9999-12-31)를 본다. 깨졌거나 다른 규칙의 것이면 400 VAL_001 — 엔진에 묻기 전에 본다
+ * 시각은 UTC 의 초(epoch)다 — 해석할 때 범위(0 ~ 9999-12-31)를 본다. 깨졌거나 다른 규칙의 것이면 400 VAL_001 — 엔진에 묻기 전에 본다.
+ *
+ * 차단할 때 받은편지함 정리(15단계 — 계약 2절 "보낸 사람 차단")도 같은 자리 · 같은 모양을 쓴다 — 지문만 그 보낸 사람(차단 목록의 값)이다.
+ * 지문의 재료가 달라(필터는 규칙의 세 칸, 차단은 표시 글 + 보낸 사람) 필터 적용의 cursor 를 차단 정리에 쓰면 다른 주인의 것으로 막힌다
  */
 const CURSOR_VERSION = 2;
 
@@ -51,9 +54,20 @@ interface EncodedFilterRunCursor {
   r: string;
 }
 
+/** 차단 정리 cursor 의 지문 재료 앞에 두는 표시 — 필터 규칙의 재료(첫 칸이 묶는 방법)와 섞이지 않게 */
+const MAIL_BLOCK_SCOPE = 'mail-block';
+
+/** 정해진 차례의 JSON 을 SHA-256 으로 — 짧게 자른다 */
+function scopeHash(canonical: unknown[]): string {
+  return createHash('sha256')
+    .update(JSON.stringify(canonical), 'utf8')
+    .digest('base64url')
+    .slice(0, RULE_HASH_LENGTH);
+}
+
 /** 규칙의 지문 — 정해진 차례의 JSON 을 SHA-256 으로 (들어온 객체의 키 순서 · 다른 속성과 상관없다) */
 function ruleHash(rule: FilterRunRule): string {
-  const canonical = JSON.stringify([
+  return scopeHash([
     rule.match,
     rule.conditions.map(({ field, operator, value }) => [
       field,
@@ -62,15 +76,19 @@ function ruleHash(rule: FilterRunRule): string {
     ]),
     [rule.actions.moveToMailboxId, rule.actions.markAsRead, rule.actions.flag],
   ]);
-  return createHash('sha256')
-    .update(canonical, 'utf8')
-    .digest('base64url')
-    .slice(0, RULE_HASH_LENGTH);
 }
 
-function invalidCursor(reason: string): BusinessException {
+/** 차단 정리의 지문 — 보낸 사람(차단 목록의 값 — 소문자) */
+function senderHash(sender: string): string {
+  return scopeHash([MAIL_BLOCK_SCOPE, sender]);
+}
+
+/** 깨진 cursor 의 로그 까닭 — 필터 적용 · 차단 정리를 가른다 */
+type CursorKind = 'filter-run' | 'mail-block-run';
+
+function invalidCursor(kind: CursorKind, reason: string): BusinessException {
   return new BusinessException('VAL_001', {
-    context: { reason: `invalid-filter-run-cursor:${reason}` },
+    context: { reason: `invalid-${kind}-cursor:${reason}` },
   });
 }
 
@@ -84,50 +102,85 @@ function isSeconds(value: unknown): value is number {
   );
 }
 
-export function encodeFilterRunCursor(
-  position: FilterRunPosition,
-  rule: FilterRunRule,
-): string {
+/** 자리와 지문을 cursor 로 */
+function encodeRunCursor(position: FilterRunPosition, hash: string): string {
   const payload: EncodedFilterRunCursor = {
     v: CURSOR_VERSION,
     b: position.before,
     a: position.anchor,
     t: position.anchorTime,
-    r: ruleHash(rule),
+    r: hash,
   };
   return Buffer.from(JSON.stringify(payload)).toString('base64url');
 }
 
+/** cursor 를 해석한다 — 형식 · 범위가 틀리거나 지문이 다르면(다른 주인의 cursor) VAL_001 */
+function decodeRunCursor(
+  cursor: string,
+  hash: string,
+  kind: CursorKind,
+): FilterRunPosition {
+  if (cursor.length > MAX_MAIL_FILTER_RUN_CURSOR_LENGTH) {
+    throw invalidCursor(kind, 'too-long');
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+  } catch {
+    throw invalidCursor(kind, 'not-json');
+  }
+
+  const { v, b, a, t, r } = (parsed ?? {}) as Partial<EncodedFilterRunCursor>;
+  if (v !== CURSOR_VERSION || !isSeconds(b) || b === 0) {
+    throw invalidCursor(kind, 'shape');
+  }
+  if (!(a === null || (typeof a === 'string' && MAIL_ID_PATTERN.test(a)))) {
+    throw invalidCursor(kind, 'shape');
+  }
+  // anchor 가 있으면 그 받은 시각도 있다 — 위 경계보다 앞선다
+  if (!(t === null || (isSeconds(t) && t < b)) || (a !== null && t === null)) {
+    throw invalidCursor(kind, 'shape');
+  }
+  if (typeof r !== 'string') throw invalidCursor(kind, 'shape');
+
+  if (r !== hash) {
+    throw invalidCursor(
+      kind,
+      kind === 'filter-run' ? 'other-rule' : 'other-sender',
+    );
+  }
+
+  return { before: b, anchor: a, anchorTime: t };
+}
+
+export function encodeFilterRunCursor(
+  position: FilterRunPosition,
+  rule: FilterRunRule,
+): string {
+  return encodeRunCursor(position, ruleHash(rule));
+}
+
 /** cursor 를 해석한다 — 형식 · 범위가 틀리거나 다른 규칙의 것이면 VAL_001 */
 export function decodeFilterRunCursor(
   cursor: string,
   rule: FilterRunRule,
 ): FilterRunPosition {
-  if (cursor.length > MAX_MAIL_FILTER_RUN_CURSOR_LENGTH) {
-    throw invalidCursor('too-long');
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
-  } catch {
-    throw invalidCursor('not-json');
-  }
-
-  const { v, b, a, t, r } = (parsed ?? {}) as Partial<EncodedFilterRunCursor>;
-  if (v !== CURSOR_VERSION || !isSeconds(b) || b === 0) {
-    throw invalidCursor('shape');
-  }
-  if (!(a === null || (typeof a === 'string' && MAIL_ID_PATTERN.test(a)))) {
-    throw invalidCursor('shape');
-  }
-  // anchor 가 있으면 그 받은 시각도 있다 — 위 경계보다 앞선다
-  if (!(t === null || (isSeconds(t) && t < b)) || (a !== null && t === null)) {
-    throw invalidCursor('shape');
-  }
-  if (typeof r !== 'string') throw invalidCursor('shape');
-
-  if (r !== ruleHash(rule)) throw invalidCursor('other-rule');
-
-  return { before: b, anchor: a, anchorTime: t };
+  return decodeRunCursor(cursor, ruleHash(rule), 'filter-run');
+}
+
+/** 차단 정리의 cursor (15단계) — 자리는 필터 적용과 같고 지문은 그 보낸 사람 */
+export function encodeBlockRunCursor(
+  position: FilterRunPosition,
+  sender: string,
+): string {
+  return encodeRunCursor(position, senderHash(sender));
+}
+
+/** 차단 정리의 cursor 를 해석한다 — 형식 · 범위가 틀리거나 다른 보낸 사람(또는 필터 적용)의 것이면 VAL_001 */
+export function decodeBlockRunCursor(
+  cursor: string,
+  sender: string,
+): FilterRunPosition {
+  return decodeRunCursor(cursor, senderHash(sender), 'mail-block-run');
 }

backend/src/modules/mail/jmap/filter-run-texts.ts

@@ -83,6 +83,33 @@ function decodedHeaders(email: JmapEmail, names: readonly string[]): string[] {
   );
 }
 
+/**
+ * 차단할 때 받은편지함 정리(15단계)가 읽는 보낸 사람 — 엔진이 푼 From 머리글의 주소 목록, 같은 이름의 머리글이 여럿이면 모두(머리글마다 배열).
+ * Sieve 의 `address` 판정(jmap/sieve-script.ts 의 blockSection)이 견주는 것과 같다 — 표시 이름에 쓴 주소는 들지 않는다.
+ * 엔진은 물은 이름 그대로 답한다(Stalwart 0.16.27 — 2026-11-09 확인: `[[{ name, email }]]`)
+ */
+export const FROM_ADDRESSES_PROPERTY = 'header:From:asAddresses:all';
+
+/** From 머리글들의 주소 — 물은 이름으로 찾되 대소문자가 달라도 찾는다. 모양이 틀린 칸은 건너뛴다 */
+export function fromAddressesOf(email: JmapEmail): string[] {
+  const wanted = FROM_ADDRESSES_PROPERTY.toLowerCase();
+  for (const [key, value] of Object.entries(email)) {
+    if (key.toLowerCase() !== wanted || !Array.isArray(value)) continue;
+    return value.flatMap((header: unknown) =>
+      Array.isArray(header)
+        ? header.flatMap((address: unknown) => {
+            const found =
+              typeof address === 'object' && address !== null
+                ? (address as { email?: unknown }).email
+                : undefined;
+            return typeof found === 'string' ? [found] : [];
+          })
+        : [],
+    );
+  }
+  return [];
+}
+
 /** 머리글의 견줄 글 — 보낸 사람 · 받는 사람 · 제목 (본문은 bodyTextsOf) */
 export function headerTextsOf(email: JmapEmail): Omit<MailFilterTexts, 'body'> {
   const subject = email.subject;

backend/src/modules/mail/jmap/filter-source.spec.ts

@@ -11,11 +11,14 @@ import type {
 import {
   FILTER_SOURCE_FORMAT,
   FILTER_SOURCE_FORMAT_WITH_BLOCKS,
+  FILTER_SOURCE_FORMAT_WITH_RICH_VACATION,
   FILTER_SOURCE_MARKER,
   LATEST_FILTER_SOURCE_FORMAT,
+  SAME_AS_INTERNAL_REPLY,
   filterRulesVersion,
   filterSourceLine,
   readFilterSource,
+  usesRichVacation,
   type FilterScriptSource,
 } from './filter-source';
 
@@ -46,6 +49,8 @@ const vacation: MailVacation = {
   toDate: null,
   subject: '부재중 ${x} "따옴표"',
   textBody: '첫 줄\r\n둘째 줄\n\t탭',
+  htmlBody: null,
+  external: SAME_AS_INTERNAL_REPLY,
 };
 
 const source: FilterScriptSource = {
@@ -186,7 +191,9 @@ describe('filterSourceLine · readFilterSource — 스크립트 머리의 원본
   });
 
   it('새 판(이 서버가 아는 가장 새 판보다 큰 정수)은 깨짐과 나눈다 — 나머지 모양은 보지 않는다', () => {
-    expect(LATEST_FILTER_SOURCE_FORMAT).toBe(FILTER_SOURCE_FORMAT_WITH_BLOCKS);
+    expect(LATEST_FILTER_SOURCE_FORMAT).toBe(
+      FILTER_SOURCE_FORMAT_WITH_RICH_VACATION,
+    );
     expect(
       readFilterSource(
         scriptWithJson(stored({ v: LATEST_FILTER_SOURCE_FORMAT + 1 })),
@@ -422,6 +429,153 @@ describe('차단 목록(판 2 — 9단계 "보낸 사람 차단")', () => {
   });
 });
 
+describe('부재중의 서식 본문 · 회사 밖 응답(판 3 — 16단계)', () => {
+  const rich: MailVacation = {
+    ...vacation,
+    htmlBody:
+      '<p style="margin:0">11월 7일까지 <strong>휴가</strong>입니다.</p>',
+    external: {
+      mode: 'separate',
+      subject: 'Out of office',
+      textBody: 'I am away until Nov 7.',
+      htmlBody: '<p>I am away until <strong>Nov 7</strong>.</p>',
+    },
+  };
+  const richSource: FilterScriptSource = { ...source, vacation: rich };
+  const formatOf = (value: FilterScriptSource) =>
+    (
+      JSON.parse(
+        filterSourceLine(value).slice(FILTER_SOURCE_MARKER.length),
+      ) as Record<string, unknown>
+    ).v;
+  const storedV3 = (overrides: Record<string, unknown> = {}) =>
+    stored({
+      v: FILTER_SOURCE_FORMAT_WITH_RICH_VACATION,
+      vacation: rich,
+      blocked: [],
+      ...overrides,
+    });
+
+  it('새 칸을 쓴 직원만 판 3 — 서식 본문 · 사내와 다른 회사 밖 응답 · 써 둔 회사 밖 글 가운데 하나라도. 아니면 판 1 · 2 그대로', () => {
+    expect(LATEST_FILTER_SOURCE_FORMAT).toBe(
+      FILTER_SOURCE_FORMAT_WITH_RICH_VACATION,
+    );
+    expect(formatOf(source)).toBe(FILTER_SOURCE_FORMAT);
+    expect(usesRichVacation(vacation)).toBe(false);
+
+    for (const changed of [
+      { ...vacation, htmlBody: '<p>휴가</p>' },
+      { ...vacation, external: { ...SAME_AS_INTERNAL_REPLY, mode: 'none' } },
+      {
+        ...vacation,
+        external: { ...SAME_AS_INTERNAL_REPLY, mode: 'separate' },
+      },
+      // 사내와 같은 응답이어도 써 둔 회사 밖 글이 있으면 남겨야 한다
+      {
+        ...vacation,
+        external: { ...SAME_AS_INTERNAL_REPLY, textBody: '써 둔 글' },
+      },
+    ] as MailVacation[]) {
+      expect(usesRichVacation(changed)).toBe(true);
+      expect(formatOf({ ...source, vacation: changed })).toBe(
+        FILTER_SOURCE_FORMAT_WITH_RICH_VACATION,
+      );
+    }
+    // 판 3 은 차단 목록 칸을 늘 담는다(비었어도) — 차단이 있으면 그대로
+    const v3 = JSON.parse(
+      filterSourceLine(richSource).slice(FILTER_SOURCE_MARKER.length),
+    ) as Record<string, unknown>;
+    expect(v3.blocked).toEqual([]);
+    expect(v3.vacation).toEqual(rich);
+  });
+
+  it('판 3 을 그대로 읽는다 — 차단 목록도. 판 1 · 2 는 글만 · 사내와 같은 응답으로', () => {
+    const blocked: BlockedSender[] = [
+      { address: 'spam@example.net', blockedAt: '2026-10-29T01:02:03.000Z' },
+    ];
+    for (const value of [richSource, { ...richSource, blocked }]) {
+      expect(readFilterSource(scriptWith(filterSourceLine(value)))).toEqual({
+        status: 'ok',
+        source: value,
+      });
+    }
+    // 판 1 · 2 에 새 칸이 적혀 있어도 보지 않는다 — 그 판을 쓰는 서버는 그 칸을 모른다
+    for (const v of [FILTER_SOURCE_FORMAT, FILTER_SOURCE_FORMAT_WITH_BLOCKS]) {
+      expect(
+        sourceOf(scriptWithJson(stored({ v, vacation: rich, blocked: [] })))
+          ?.vacation,
+      ).toEqual({
+        ...vacation,
+        htmlBody: null,
+        external: SAME_AS_INTERNAL_REPLY,
+      });
+    }
+  });
+
+  it('판 3 의 서식 본문은 읽을 때 보내는 정화를 다시 거친다 — 다른 프로그램이 고친 원본의 스크립트 · 이벤트 속성 · 그림은 화면에 가지 않는다', () => {
+    const read = sourceOf(
+      scriptWithJson(
+        storedV3({
+          vacation: {
+            ...rich,
+            htmlBody:
+              '<p onclick="x()">휴가<script>alert(1)</script></p><img src="https://evil.example/x.png">',
+            external: {
+              ...rich.external,
+              htmlBody: '<a href="javascript:x()">링크</a><b>굵게</b>',
+            },
+          },
+        }),
+      ),
+    );
+    expect(read?.vacation.htmlBody).toBe('<p>휴가</p>');
+    expect(read?.vacation.external.htmlBody).toBe(
+      '<span>링크</span><b>굵게</b>',
+    );
+    // 정화해서 비면 null — 글만
+    expect(
+      sourceOf(
+        scriptWithJson(
+          storedV3({ vacation: { ...rich, htmlBody: '<script>x()</script>' } }),
+        ),
+      )?.vacation.htmlBody,
+    ).toBeNull();
+  });
+
+  it.each<[string, Record<string, unknown>]>([
+    ['회사 밖 응답 없음', { ...rich, external: undefined }],
+    ['회사 밖 응답이 객체가 아님', { ...rich, external: 'same' }],
+    [
+      '모르는 고르기',
+      { ...rich, external: { ...rich.external, mode: 'internal' } },
+    ],
+    [
+      '회사 밖 제목이 글이 아님',
+      { ...rich, external: { ...rich.external, subject: 1 } },
+    ],
+    [
+      '회사 밖 글 칸 없음',
+      { ...rich, external: { mode: 'same', subject: null, htmlBody: null } },
+    ],
+    ['서식 본문이 글이 아님', { ...rich, htmlBody: 1 }],
+    ['서식 본문 칸 없음', { ...rich, htmlBody: undefined }],
+    [
+      '정화할 수 없는 서식(깊은 중첩)',
+      { ...rich, htmlBody: '<b>'.repeat(166_666) },
+    ],
+  ])('판 3 의 부재중이 계약에 맞지 않으면 깨진 원본 — %s', (_label, value) => {
+    expect(
+      readFilterSource(scriptWithJson(storedV3({ vacation: value }))),
+    ).toEqual(BROKEN);
+  });
+
+  it('판 3 의 차단 목록은 판 2 와 같은 규칙 — 칸이 없으면 깨진 원본', () => {
+    expect(
+      readFilterSource(scriptWithJson(storedV3({ blocked: undefined }))),
+    ).toEqual(BROKEN);
+  });
+});
+
 describe('filterRulesVersion — 규칙의 지문(version)', () => {
   const rules = source.rules;
 

backend/src/modules/mail/jmap/filter-source.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'crypto';
 
+import { sanitizeStoredHtml } from '@/modules/mail/html/sanitize-stored-html';
 import { parseBlockTarget } from '@/modules/mail/mail-blocks';
 import {
   MAIL_FILTER_FIELDS,
@@ -8,6 +9,7 @@ import {
   findFilterRulesProblem,
 } from '@/modules/mail/mail-filters';
 import {
+  MAIL_VACATION_EXTERNAL_MODES,
   MAX_MAIL_BLOCKS,
   MAX_MAIL_FILTER_RULES,
 } from '@/modules/mail/mail.constants';
@@ -17,6 +19,7 @@ import type {
   MailFilterCondition,
   MailFilterRule,
   MailVacation,
+  MailVacationExternal,
 } from '@/modules/mail/mail.types';
 import { toUtcIso } from './jmap.mapper';
 
@@ -43,12 +46,19 @@ export const FILTER_SOURCE_MARKER = '# arasystem-source: ';
  * - 2: 1 + 차단 목록 `blocked` (9단계 "보낸 사람 차단") — **차단한 주소가 있을 때만** 쓴다. 판 2 를 아는 서버는 판 1 을 "차단 없음"으로 읽는다.
  *   판 2 를 모르는 서버로 되돌리면 차단한 주소가 있는 직원만 필터 · 부재중 저장이 503 MAIL_001 로 막힌다(계약 2절 — 되돌리기 계획:
  *   판 2 를 읽기만 하는 서버를 먼저 배포할 수 있게 둔다)
+ * - 3: 2 + 부재중의 서식 본문 `vacation.htmlBody` · 회사 밖 응답 `vacation.external` (16단계) — **새 칸을 쓴 직원만** 쓴다
+ *   (usesRichVacation — 서식 본문이 있거나 · 회사 밖 응답이 사내와 같지 않거나 · 회사 밖 글을 써 둔 경우). 판 3 은 `blocked` 를 늘 담는다(비었어도).
+ *   판 3 을 아는 서버는 판 1 · 2 를 "글만 · 사내와 같은 응답"으로 읽는다. 판 3 을 모르는 서버로 되돌리면 새 칸을 쓴 직원만
+ *   필터 · 부재중 · 차단 저장이 503 MAIL_001 로 막힌다 — 엔진의 응답(Sieve)은 그대로 돈다(계약 2절 "부재중 자동 응답"의 되돌리기 계획)
  */
 export const FILTER_SOURCE_FORMAT = 1;
 /** 차단 목록이 든 원본의 판 (9단계) */
 export const FILTER_SOURCE_FORMAT_WITH_BLOCKS = 2;
+/** 부재중의 서식 본문 · 회사 밖 응답이 든 원본의 판 (16단계) */
+export const FILTER_SOURCE_FORMAT_WITH_RICH_VACATION = 3;
 /** 이 서버가 아는 가장 새 판 — 이보다 크면 newer */
-export const LATEST_FILTER_SOURCE_FORMAT = FILTER_SOURCE_FORMAT_WITH_BLOCKS;
+export const LATEST_FILTER_SOURCE_FORMAT =
+  FILTER_SOURCE_FORMAT_WITH_RICH_VACATION;
 
 /**
  * 스크립트 글에서 원본을 읽은 결과
@@ -69,6 +79,14 @@ export interface FilterScriptSource {
   readonly blocked: readonly BlockedSender[];
 }
 
+/** 회사 밖 응답의 처음 값 — 사내와 같은 응답, 따로 써 둔 글 없음 (16단계 — 판 1 · 2 의 원본 · 새 칸이 없는 옛 요청도 이것) */
+export const SAME_AS_INTERNAL_REPLY: MailVacationExternal = {
+  mode: 'same',
+  subject: null,
+  textBody: null,
+  htmlBody: null,
+};
+
 /** 한 번도 설정하지 않은 부재중 자동 응답 (계약 2절 "부재중 자동 응답") */
 export const NEVER_CONFIGURED_VACATION: MailVacation = {
   isEnabled: false,
@@ -76,8 +94,25 @@ export const NEVER_CONFIGURED_VACATION: MailVacation = {
   toDate: null,
   subject: '',
   textBody: '',
+  htmlBody: null,
+  external: SAME_AS_INTERNAL_REPLY,
 };
 
+/**
+ * 16단계의 새 칸을 쓰는가 — 서식 본문이 있거나 · 회사 밖 응답이 사내와 같지 않거나 · 회사 밖 글을 써 둔 경우. 그때만 원본 판 3 으로 쓴다
+ * (새 칸을 쓰지 않은 직원은 판 1 · 2 그대로 — 판 3 을 모르는 서버로 되돌려도 막히지 않는다)
+ */
+export function usesRichVacation(vacation: MailVacation): boolean {
+  const { external } = vacation;
+  return (
+    vacation.htmlBody !== null ||
+    external.mode !== 'same' ||
+    external.subject !== null ||
+    external.textBody !== null ||
+    external.htmlBody !== null
+  );
+}
+
 /** 원본을 읽지 못할 때(깨짐 · 새 판) 보이는 것 — 규칙 없음 · 부재중 꺼짐 · 차단 없음 (깨진 원본은 저장하면 덮어쓴다 · 새 판은 쓰지 않는다) */
 export const EMPTY_FILTER_SOURCE: FilterScriptSource = {
   rules: [],
@@ -102,7 +137,8 @@ function canonicalRule(rule: MailFilterRule): MailFilterRule {
   };
 }
 
-function canonicalVacation(vacation: MailVacation): MailVacation {
+/** 판 1 · 2 의 부재중 — 다섯 칸 */
+function canonicalVacation(vacation: MailVacation) {
   return {
     isEnabled: vacation.isEnabled,
     fromDate: vacation.fromDate,
@@ -112,6 +148,16 @@ function canonicalVacation(vacation: MailVacation): MailVacation {
   };
 }
 
+/** 판 3 의 부재중 — 다섯 칸 + 서식 본문 · 회사 밖 응답 */
+function canonicalRichVacation(vacation: MailVacation): MailVacation {
+  const { mode, subject, textBody, htmlBody } = vacation.external;
+  return {
+    ...canonicalVacation(vacation),
+    htmlBody: vacation.htmlBody,
+    external: { mode, subject, textBody, htmlBody },
+  };
+}
+
 /** 같은 규칙이면 같은 사본 목록 — 저장 · 지문 · 응답이 이것을 쓴다 */
 export function canonicalRules(
   rules: readonly MailFilterRule[],
@@ -130,24 +176,28 @@ export function filterRulesVersion(rules: readonly MailFilterRule[]): string {
 }
 
 /**
- * 원본 줄 — 표지 + JSON 한 줄 (판 · 규칙 · 부재중 · 차단). 차단한 주소가 없으면 판 1 그대로(blocked 없이) — 판 2 를 모르는 서버도 읽는다
+ * 원본 줄 — 표지 + JSON 한 줄 (판 · 규칙 · 부재중 · 차단). 가장 낮은 판으로 쓴다 — 부재중의 새 칸(16단계)을 쓰면 판 3,
+ * 아니고 차단한 주소가 있으면 판 2, 둘 다 아니면 판 1(blocked 없이) — 낮은 판만 아는 서버도 읽는다
  */
 export function filterSourceLine(source: FilterScriptSource): string {
-  const base = {
-    rules: canonicalRules(source.rules),
-    vacation: canonicalVacation(source.vacation),
-  };
+  const rules = canonicalRules(source.rules);
+  const blocked = source.blocked.map(({ address, blockedAt }) => ({
+    address,
+    blockedAt,
+  }));
+  if (usesRichVacation(source.vacation)) {
+    return `${FILTER_SOURCE_MARKER}${JSON.stringify({
+      v: FILTER_SOURCE_FORMAT_WITH_RICH_VACATION,
+      rules,
+      vacation: canonicalRichVacation(source.vacation),
+      blocked,
+    })}`;
+  }
+  const base = { rules, vacation: canonicalVacation(source.vacation) };
   return `${FILTER_SOURCE_MARKER}${JSON.stringify(
-    source.blocked.length === 0
+    blocked.length === 0
       ? { v: FILTER_SOURCE_FORMAT, ...base }
-      : {
-          v: FILTER_SOURCE_FORMAT_WITH_BLOCKS,
-          ...base,
-          blocked: source.blocked.map(({ address, blockedAt }) => ({
-            address,
-            blockedAt,
-          })),
-        },
+      : { v: FILTER_SOURCE_FORMAT_WITH_BLOCKS, ...base, blocked },
   )}`;
 }
 
@@ -252,8 +302,9 @@ function readDate(raw: unknown): string | null | undefined {
 }
 
 /**
- * 부재중 — 모양만 본다. 길이 한도는 보지 않는다: 저장해 둔 값은 4단계 요청 검증 · 엔진의 VacationResponse 한도 안에서 온 것이고
- * (VacationResponse 에서 가져온 값은 우리 한도보다 길 수 있다), Sieve 에는 base64 로 들어가 글이 문법을 깨지 않는다
+ * 부재중(판 1 · 2) — 모양만 본다. 길이 한도는 보지 않는다: 저장해 둔 값은 4단계 요청 검증 · 엔진의 VacationResponse 한도 안에서 온 것이고
+ * (VacationResponse 에서 가져온 값은 우리 한도보다 길 수 있다), Sieve 에는 base64 로 들어가 글이 문법을 깨지 않는다.
+ * 16단계의 칸은 처음 값이다 — 글만 · 사내와 같은 응답
  */
 function toVacation(raw: unknown): MailVacation | null {
   if (
@@ -273,9 +324,52 @@ function toVacation(raw: unknown): MailVacation | null {
     toDate,
     subject: raw.subject,
     textBody: raw.textBody,
+    htmlBody: null,
+    external: SAME_AS_INTERNAL_REPLY,
   };
 }
 
+/**
+ * 원본의 서식 본문 — null 이면 null, 글이면 보내는 정화(그림 없음)를 **다시** 거친 값(비면 null), 정화할 수 없는 글(길이 · 파서 비용)이면 undefined(깨짐).
+ * 다시 정화하는 까닭: 다른 메일 프로그램(ManageSieve 등)이 고친 원본의 HTML 이 화면 · 받는 사람에게 그대로 가지 않게 — 우리가 쓴 값은 이미 정화한 값이라 그대로다
+ */
+function readVacationHtml(raw: unknown): string | null | undefined {
+  if (raw === null) return null;
+  if (typeof raw !== 'string') return undefined;
+  const sanitized = sanitizeStoredHtml(raw, { maxLength: null });
+  return sanitized.ok ? sanitized.html : undefined;
+}
+
+/** 회사 밖 응답(판 3) — 고르기는 셋 가운데 하나, 글 칸은 글 또는 null. 어긋나면 null(깨짐) */
+function toVacationExternal(raw: unknown): MailVacationExternal | null {
+  if (
+    !isRecord(raw) ||
+    !isOneOf(raw.mode, MAIL_VACATION_EXTERNAL_MODES) ||
+    !isNullableString(raw.subject) ||
+    !isNullableString(raw.textBody)
+  ) {
+    return null;
+  }
+  const htmlBody = readVacationHtml(raw.htmlBody);
+  if (htmlBody === undefined) return null;
+  return {
+    mode: raw.mode,
+    subject: raw.subject,
+    textBody: raw.textBody,
+    htmlBody,
+  };
+}
+
+/** 부재중(판 3) — 판 1 · 2 의 다섯 칸 + 서식 본문 · 회사 밖 응답. 어긋나면 null(깨짐) */
+function toRichVacation(raw: unknown): MailVacation | null {
+  const base = toVacation(raw);
+  if (base === null || !isRecord(raw)) return null;
+  const htmlBody = readVacationHtml(raw.htmlBody);
+  const external = toVacationExternal(raw.external);
+  if (htmlBody === undefined || external === null) return null;
+  return { ...base, htmlBody, external };
+}
+
 /**
  * 차단 목록 (판 2) — 500개까지 · 주소는 차단 대상 모양(소문자 — mail-blocks.ts)이고 겹치지 않음 · 차단한 시각은 읽을 수 있는 시각.
  * 어긋나면 null(깨짐) — 다른 메일 프로그램이 고친 원본으로 Sieve 를 만들면 엔진의 변수 펼침 · 한도에 걸릴 수 있다
@@ -313,8 +407,9 @@ const BROKEN: FilterSourceReading = { status: 'broken' };
 /**
  * 스크립트 글에서 원본을 읽는다 (FilterSourceReading).
  * 판(`v`)이 이 서버가 아는 가장 새 판보다 큰 정수면 나머지를 보지 않고 newer 다 — 모양이 달라졌을 수 있다.
- * 아는 판이면 모양과 규칙을 계약대로 다시 본다(mail-filters.ts — 50개 · 겹친 id · 조건 수 · `${` 등, 판 2 는 차단 목록도) — 어긋나면 broken.
- * 판 1 은 차단 없음이다. 다시 보는 까닭: 다른 메일 프로그램(ManageSieve 등)이 고친 원본으로 Sieve 를 다시 만들면 엔진 한도 · 변수 펼침에 걸릴 수 있다
+ * 아는 판이면 모양과 규칙을 계약대로 다시 본다(mail-filters.ts — 50개 · 겹친 id · 조건 수 · `${` 등, 판 2 · 3 은 차단 목록도,
+ * 판 3 은 부재중의 서식 본문(다시 정화) · 회사 밖 응답도) — 어긋나면 broken.
+ * 판 1 은 차단 없음, 판 1 · 2 는 부재중이 글만 · 사내와 같은 응답이다. 다시 보는 까닭: 다른 메일 프로그램(ManageSieve 등)이 고친 원본으로 Sieve 를 다시 만들면 엔진 한도 · 변수 펼침에 걸릴 수 있다
  */
 export function readFilterSource(script: string): FilterSourceReading {
   const line = findSourceLine(script);
@@ -337,7 +432,8 @@ export function readFilterSource(script: string): FilterSourceReading {
   }
   if (
     (format !== FILTER_SOURCE_FORMAT &&
-      format !== FILTER_SOURCE_FORMAT_WITH_BLOCKS) ||
+      format !== FILTER_SOURCE_FORMAT_WITH_BLOCKS &&
+      format !== FILTER_SOURCE_FORMAT_WITH_RICH_VACATION) ||
     !Array.isArray(parsed.rules) ||
     parsed.rules.length > MAX_MAIL_FILTER_RULES
   ) {
@@ -353,12 +449,13 @@ export function readFilterSource(script: string): FilterSourceReading {
   if (findFilterRulesProblem(rules)) return BROKEN;
 
   const blocked =
-    format === FILTER_SOURCE_FORMAT_WITH_BLOCKS
-      ? toBlocked(parsed.blocked)
-      : [];
+    format === FILTER_SOURCE_FORMAT ? [] : toBlocked(parsed.blocked);
   if (blocked === null) return BROKEN;
 
-  const vacation = toVacation(parsed.vacation);
+  const vacation =
+    format === FILTER_SOURCE_FORMAT_WITH_RICH_VACATION
+      ? toRichVacation(parsed.vacation)
+      : toVacation(parsed.vacation);
   return vacation
     ? { status: 'ok', source: { rules, vacation, blocked } }
     : BROKEN;

backend/src/modules/mail/jmap/jmap-account-security.provider.spec.ts

@@ -190,6 +190,81 @@ describe('JmapAccountSecurityProvider (x:AccountPassword · x:AppPassword —
       expect(failure?.code).toBe('MAIL_001');
       expect(JSON.stringify(failure?.context)).not.toContain('secret details');
     });
+
+    it('휴대폰 바꾸기(16단계) — 켠 채 currentSecret + otpAuth {otpCode: 지금 코드, otpUrl: 새 주소} 한 요청, updated → replaced · forbidden → code-rejected · 결과를 모르면 unknown', async () => {
+      callAccountChange.mockResolvedValueOnce(
+        answered([
+          'x:AccountPassword/set',
+          { updated: { singleton: null } },
+          's',
+        ]),
+      );
+      await expect(
+        provider.replaceTwoFactor(ARA, 'pw', '123456', OTPAUTH),
+      ).resolves.toBe('replaced');
+      expect(lastCalls(callAccountChange)).toEqual([
+        [
+          'x:AccountPassword/set',
+          {
+            accountId: 'x1',
+            update: {
+              singleton: {
+                currentSecret: 'pw',
+                otpAuth: { otpCode: '123456', otpUrl: OTPAUTH },
+              },
+            },
+          },
+          's',
+        ],
+      ]);
+
+      callAccountChange.mockResolvedValueOnce(
+        answered([
+          'x:AccountPassword/set',
+          {
+            notUpdated: {
+              singleton: {
+                type: 'forbidden',
+                description: 'Current secret is incorrect.',
+              },
+            },
+          },
+          's',
+        ]),
+      );
+      await expect(
+        provider.replaceTwoFactor(ARA, 'pw', '000000', OTPAUTH),
+      ).resolves.toBe('code-rejected');
+
+      const warn = jest.spyOn(Logger.prototype, 'warn');
+      callAccountChange.mockResolvedValueOnce({
+        kind: 'unknown',
+        detail: 'timeout',
+      });
+      await expect(
+        provider.replaceTwoFactor(ARA, 'pw', '123456', OTPAUTH),
+      ).resolves.toBe('unknown');
+      const logged = warn.mock.calls
+        .map(([message]) => String(message))
+        .join('\n');
+      expect(logged).toContain('가를 수 없어 MAIL_001');
+      expect(logged).not.toMatch(/123456|otpauth|pw\b/);
+
+      callAccountChange.mockResolvedValueOnce(
+        answered([
+          'x:AccountPassword/set',
+          { notUpdated: { singleton: { type: 'serverFail' } } },
+          's',
+        ]),
+      );
+      expect(
+        (await failureOf(provider.replaceTwoFactor(ARA, 'pw', '1', OTPAUTH)))
+          ?.context,
+      ).toMatchObject({
+        reason: 'two-factor-replace-refused',
+        jmapType: 'serverFail',
+      });
+    });
   });
 
   describe('앱 비밀번호', () => {

backend/src/modules/mail/jmap/jmap-account-security.provider.ts

@@ -8,6 +8,7 @@ import type {
   CreatedAppPassword,
   TwoFactorDisableResult,
   TwoFactorEnableResult,
+  TwoFactorReplaceResult,
 } from '@/modules/account-security/account-security.provider';
 import { traceTag } from '@/shared/logger/request-context';
 import { maskEmail } from '@/shared/utils/mask';
@@ -59,6 +60,8 @@ function toIso(value: unknown): string | null {
  * - 켜기: `x:AccountPassword/set` 에 currentSecret + otpAuth.otpUrl — 엔진은 코드를 보지 않고 저장한다. 지금 비밀번호가 틀리거나
  *   이미 켜져 있으면(지금 코드를 요구) forbidden
  * - 끄기: currentSecret + otpAuth {otpCode, otpUrl: null} — 코드 틀림도 비밀번호 틀림과 같은 forbidden "Current secret is incorrect."
+ * - 휴대폰 바꾸기(16단계): 켠 채 currentSecret + otpAuth {otpCode: 지금 코드, otpUrl: 새 주소} 한 요청 → updated(옛 비밀은 바로 죽는다).
+ *   코드 없음 · 틀린 코드 · 틀린 비밀번호 모두 forbidden (2026-11-10 개발 엔진 확인)
  * - 앱 비밀번호: 값은 엔진이 만들어 만들 때 한 번만 준다(우리가 넣으면 거절), 상한(기본 5)을 넘으면 overQuota, 지운 번호를 다시 쓴다
  * 엔진 오류의 설명 문장 · 비밀번호 · 코드 · otpauth 주소 · 앱 비밀번호 값 · 이름은 로그 · 오류 context 에 남기지 않는다 (type 만)
  */
@@ -139,6 +142,33 @@ export class JmapAccountSecurityProvider implements AccountSecurityProvider {
     return outcome === 'forbidden' ? 'code-rejected' : 'unknown';
   }
 
+  async replaceTwoFactor(
+    user: string,
+    currentPassword: string,
+    otpCode: string,
+    otpauthUrl: string,
+  ): Promise<TwoFactorReplaceResult> {
+    // 켠 채 지금 코드와 새 주소를 한 요청으로 — 엔진이 지금 코드를 확인하고 새 비밀로 바꾼다(옛 비밀은 바로 죽는다 — 2026-11-10 확인)
+    const reply = await this.jmap.callAccountChange(user, (accountId) => [
+      [
+        PASSWORD_SET,
+        {
+          accountId,
+          update: {
+            [PASSWORD_OBJECT_ID]: {
+              currentSecret: currentPassword,
+              otpAuth: { otpCode, otpUrl: otpauthUrl },
+            },
+          },
+        },
+        's',
+      ],
+    ]);
+    const outcome = this.passwordUpdate(user, reply, 'two-factor-replace');
+    if (outcome === 'updated') return 'replaced';
+    return outcome === 'forbidden' ? 'code-rejected' : 'unknown';
+  }
+
   async listAppPasswords(user: string): Promise<AppPasswordRecord[]> {
     const responses = await this.jmap.callAccount(user, (accountId) => [
       [
@@ -251,7 +281,7 @@ export class JmapAccountSecurityProvider implements AccountSecurityProvider {
   ): 'updated' | 'forbidden' | 'unknown' {
     if (reply.kind === 'unknown') {
       this.logger.warn(
-        `[MAIL_001]${traceTag()} 2단계 인증 바꾸기의 결과를 알 수 없습니다 — 엔진을 다시 읽어 맞춥니다: user=${maskEmail(user)}, call=${call}, 원인=${reply.detail}`,
+        `[MAIL_001]${traceTag()} 2단계 인증 바꾸기의 결과를 알 수 없습니다 — ${this.unknownFollowUp(call)}: user=${maskEmail(user)}, call=${call}, 원인=${reply.detail}`,
       );
       return 'unknown';
     }
@@ -275,7 +305,7 @@ export class JmapAccountSecurityProvider implements AccountSecurityProvider {
     if (failure?.type === 'forbidden') return 'forbidden';
     if (!failure) {
       this.logger.warn(
-        `[MAIL_001]${traceTag()} 2단계 인증 바꾸기 응답이 결과를 말하지 않습니다 — 엔진을 다시 읽어 맞춥니다: user=${maskEmail(user)}, call=${call}`,
+        `[MAIL_001]${traceTag()} 2단계 인증 바꾸기 응답이 결과를 말하지 않습니다 — ${this.unknownFollowUp(call)}: user=${maskEmail(user)}, call=${call}`,
       );
       return 'unknown';
     }
@@ -285,6 +315,13 @@ export class JmapAccountSecurityProvider implements AccountSecurityProvider {
     });
   }
 
+  /** 결과를 모를 때 부르는 쪽이 하는 일 — 켜기 · 끄기는 다시 읽어 맞추고, 휴대폰 바꾸기는 가릴 수 없어 MAIL_001 로 답한다 */
+  private unknownFollowUp(call: string): string {
+    return call === 'two-factor-replace'
+      ? '엔진이 otpUrl 을 가려 다시 읽어도 가를 수 없어 MAIL_001 로 답합니다'
+      : '엔진을 다시 읽어 맞춥니다';
+  }
+
   /** 만들기 거절 → 코드 (상한 AUTH_009, 그 밖은 MAIL_001 — type 만 남긴다) */
   private createRefusal(error: JmapError): BusinessException {
     if (error.type === 'overQuota') {

backend/src/modules/mail/jmap/jmap-contacts.provider.spec.ts

@@ -674,6 +674,147 @@ describe('JmapContactsProvider (엔진 주소록)', () => {
       expect(logged).not.toMatch(/박지훈|jihoon|Invalid email|ara\.kim@/);
     });
 
+    it('가져오기(allowPartialCreate) — 받지 않은 만들기는 던지지 않고 refusedKeys 로, 받은 것만 createdIds · 카드 모양 (warn 로그는 개수 · 종류만)', async () => {
+      engine.setReply = (args) => {
+        const create = args.create as Record<string, Record<string, unknown>>;
+        expect(Object.keys(create)).toEqual(['import-0', 'import-1']);
+        return [
+          'ContactCard/set',
+          {
+            newState: 's11',
+            created: { 'import-0': { id: 'n7' } },
+            notCreated: {
+              'import-1': {
+                type: 'invalidProperties',
+                description: 'Invalid 박지훈 jihoon@x',
+              },
+            },
+            updated: { g: null },
+          },
+          'w',
+        ];
+      };
+
+      const outcome = await provider.writeAddressBook(
+        ARA,
+        version('book', 's10'),
+        {
+          create: [
+            {
+              kind: 'contact',
+              key: 'import-0',
+              uid: 'urn:uuid:a',
+              fields: { ...newPerson, name: '받음' },
+            },
+            {
+              kind: 'contact',
+              key: 'import-1',
+              uid: 'urn:uuid:b',
+              fields: { ...newPerson, name: '박지훈' },
+            },
+          ],
+          update: [
+            {
+              kind: 'group',
+              id: 'g',
+              memberUids: ['urn:uuid:a', 'urn:uuid:b'],
+            },
+          ],
+          destroy: [],
+        },
+        { allowPartialCreate: true },
+      );
+
+      if (outcome.kind !== 'written') throw new Error('written 이 아니다');
+      expect(outcome.createdIds).toEqual(new Map([['import-0', 'n7']]));
+      expect(outcome.refusedKeys).toEqual(new Set(['import-1']));
+      expect([...outcome.cards.keys()]).toEqual(['n7']);
+      expect(outcome.version).toBe(version('book', 's11'));
+      const logged = warnSpy.mock.calls
+        .map(([message]) => String(message))
+        .join('\n');
+      expect(logged).toContain('받지 않음 1/2');
+      expect(logged).toContain('jmapType=invalidProperties');
+      expect(logged).not.toMatch(/박지훈|jihoon|Invalid|ara\.kim@/);
+    });
+
+    it('가져오기라도 고치기 · 지우기의 거절은 지금처럼 던진다 · 모두 받으면 refusedKeys 는 비어 있다', async () => {
+      engine.setReply = () => [
+        'ContactCard/set',
+        {
+          newState: 's11',
+          created: { 'import-0': { id: 'n7' } },
+          notUpdated: { g: { type: 'invalidProperties' } },
+        },
+        'w',
+      ];
+      const changes: AddressBookChanges = {
+        create: [
+          {
+            kind: 'contact',
+            key: 'import-0',
+            uid: 'urn:uuid:a',
+            fields: newPerson,
+          },
+        ],
+        update: [{ kind: 'group', id: 'g', memberUids: ['urn:uuid:a'] }],
+        destroy: [],
+      };
+      const error = await failureOf(
+        provider.writeAddressBook(ARA, version('book', 's10'), changes, {
+          allowPartialCreate: true,
+        }),
+      );
+      expect(error.code).toBe('VAL_001');
+
+      const outcome = await provider.writeAddressBook(
+        ARA,
+        version('book', 's10'),
+        { ...changes, update: [] },
+        { allowPartialCreate: true },
+      );
+      if (outcome.kind !== 'written') throw new Error('written 이 아니다');
+      expect(outcome.refusedKeys).toEqual(new Set());
+      expect(outcome.createdIds).toEqual(new Map([['import-0', 'n1']]));
+    });
+
+    it('한꺼번에 지우기(withoutOriginals) — 지울 카드는 id 만 읽어 있는지 보고, 원본은 주지 않는다', async () => {
+      engine.add({
+        id: 'c1',
+        uid: 'urn:uuid:c1',
+        name: { full: '하나' },
+        photos: { p: { href: 'https://x.example/p.jpg' } },
+      } as JmapContactCard);
+
+      const outcome = await provider.writeAddressBook(
+        ARA,
+        version('book', 's10'),
+        { ...noChanges, destroy: ['c1'] },
+        { withoutOriginals: true },
+      );
+
+      const [read] = engine.requests;
+      expect(read?.calls).toEqual([
+        [
+          'ContactCard/get',
+          { accountId: 'acc', ids: ['c1'], properties: ['id'] },
+          'd',
+        ],
+      ]);
+      if (outcome.kind !== 'written') throw new Error('written 이 아니다');
+      expect(outcome.removed.size).toBe(0);
+      expect(engine.cardOf('c1')).toBeUndefined();
+
+      // 그 판에 없는 카드면 conflict (보내지 않는다)
+      const missing = await provider.writeAddressBook(
+        ARA,
+        version('book', 's11'),
+        { ...noChanges, destroy: ['c1'] },
+        { withoutOriginals: true },
+      );
+      expect(missing).toEqual({ kind: 'conflict' });
+    });
+
     it('되돌리기 — 원본에서 id 만 빼고 uid · 기본 주소록을 바꿔 만든다. 엔진이 받지 않으면 MAIL_001(입력 오류가 아니다)', async () => {
       const original = {
         source: JSON.stringify({

backend/src/modules/mail/jmap/jmap-contacts.provider.ts

@@ -7,6 +7,7 @@ import type {
   AddressBookContactCard,
   AddressBookGroupCard,
   AddressBookSnapshot,
+  AddressBookWriteOptions,
   AddressBookWriteOutcome,
   ContactsProvider,
   RemovedCardOriginal,
@@ -49,6 +50,9 @@ const READ_PAGE_SIZE = 500;
  */
 export const ADDRESS_BOOK_READ_MAX_CARDS = 5_000;
 
+/** 원본이 필요 없는 지우기(한꺼번에 지우기 — 16단계)에서 지울 카드가 있는지만 볼 때 읽는 칸 (id 는 늘 온다) */
+const EXISTENCE_PROPERTIES = ['id'];
+
 /** 카드에서 읽는 칸 — 사진 등 큰 칸은 읽지 않는다 */
 const CARD_PROPERTIES = [
   'uid',
@@ -118,6 +122,8 @@ function pickAddressBook(books: readonly JmapAddressBook[]): string | null {
  *   만들기 · 고치기 · 지우기를 담아 읽은 상태 그대로일 때만(ifInState) 한다. 어긋나면 stateMismatch → conflict, 동시 고치기 거절은 busy.
  *   엔진은 만든 뒤 uid 를 바꾸지 못하게 하고(invalidProperties), 구성원이 없는 그룹에 `members/<uid>` 패치를 받지 않는다 — 그래서 uid 는 만들 때
  *   넣고, 구성원은 통째로 바꾼다 (2026-10-29 확인)
+ * - 가져오기(16단계 — allowPartialCreate): 받지 않은 만들기는 던지지 않고 refusedKeys 로 알린다(받은 것은 들어갔다). 한 요청에 300명 90ms(2026-11-10 확인),
+ *   엔진의 한 요청 상한(maxObjectsInSet 500)은 서비스가 맞춘다. 한꺼번에 지우기(withoutOriginals)는 지울 카드를 id 만 읽는다
  * - 이름 · 주소 · 메모 등 카드 내용은 로그에 남기지 않는다 (개수 · 엔진 오류 종류만)
  */
 @Injectable()
@@ -211,6 +217,7 @@ export class JmapContactsProvider implements ContactsProvider {
     user: string,
     version: string,
     changes: AddressBookChanges,
+    options: AddressBookWriteOptions = {},
   ): Promise<AddressBookWriteOutcome> {
     const { addressBookId, state } = decodeVersion(version);
     if (changes.create.length > 0 && addressBookId === null) {
@@ -230,6 +237,7 @@ export class JmapContactsProvider implements ContactsProvider {
         change.kind === 'contact' ? [change.id] : [],
       ),
       changes.destroy,
+      options.withoutOriginals === true,
     );
     if (current === null) return { kind: 'conflict' };
     const removed = current.originals;
@@ -287,8 +295,14 @@ export class JmapContactsProvider implements ContactsProvider {
       this.warnBusy(user, 'set-error');
       return { kind: 'busy', removed };
     }
+    // 가져오기(16단계) — 받지 않은 만들기는 던지지 않고 적는다 (고치기 · 지우기의 거절은 아래에서 지금처럼 던진다)
+    const refusedKeys = options.allowPartialCreate
+      ? this.refusedCreates(user, set, changes)
+      : new Set<string>();
     const refusal =
-      firstSetError(set.notCreated) ??
+      (options.allowPartialCreate
+        ? undefined
+        : firstSetError(set.notCreated)) ??
       firstSetError(set.notUpdated) ??
       firstSetError(set.notDestroyed);
     if (refusal) {
@@ -318,6 +332,7 @@ export class JmapContactsProvider implements ContactsProvider {
 
     const createdIds = new Map<string, string>();
     for (const card of changes.create) {
+      if (refusedKeys.has(card.key)) continue;
       const id = set.created?.[card.key]?.id;
       if (typeof id !== 'string' || id === '') {
         throw new BusinessException('MAIL_001', {
@@ -337,11 +352,35 @@ export class JmapContactsProvider implements ContactsProvider {
       createdIds,
       cards,
       removed,
+      ...(options.allowPartialCreate ? { refusedKeys } : {}),
     };
   }
 
+  /**
+   * 엔진이 받지 않은 만들기의 key (가져오기 — 16단계). 우리가 보낸 key 만 센다. 있으면 warn 로그 — 개수 · 엔진 오류 종류만
+   * (카드 내용 · 엔진 설명 문장은 남기지 않는다)
+   */
+  private refusedCreates(
+    user: string,
+    set: JmapSetResult,
+    changes: AddressBookChanges,
+  ): Set<string> {
+    const sent = new Set(changes.create.map((card) => card.key));
+    const refused = new Set(
+      Object.keys(set.notCreated ?? {}).filter((key) => sent.has(key)),
+    );
+    const first = firstSetError(set.notCreated);
+    if (refused.size > 0) {
+      this.logger.warn(
+        `[${mapJmapErrorType(first?.type)}]${traceTag()} 엔진이 가져오기의 일부 연락처를 받지 않았습니다 — 받은 것만 넣었습니다: user=${maskEmail(user)}, jmapType=${first?.type ?? 'unknown'}, 받지 않음 ${refused.size}/${changes.create.length}`,
+      );
+    }
+    return refused;
+  }
+
   /**
    * 고칠 연락처(우리가 다루는 칸)와 지울 카드(카드 전체 — 되돌리기 원본)를 그 판(state)에서 읽는다 — 엔진 요청 하나.
+   * withoutOriginals 면 지울 카드는 있는지만 본다(id 만 — 사진이 든 카드 500장을 통째로 읽지 않게, 원본은 주지 않는다).
    * 판이 달라졌거나 카드가 없으면 null (그사이 다른 곳에서 바뀌었다 — 서비스가 다시 읽고 다시 정한다)
    */
   private async readCurrentCards(
@@ -349,6 +388,7 @@ export class JmapContactsProvider implements ContactsProvider {
     state: string,
     updateIds: readonly string[],
     destroyIds: readonly string[],
+    withoutOriginals: boolean,
   ): Promise<{
     cards: ReadonlyMap<string, Record<string, unknown>>;
     originals: ReadonlyMap<string, RemovedCardOriginal>;
@@ -370,8 +410,12 @@ export class JmapContactsProvider implements ContactsProvider {
         ? [
             [
               'ContactCard/get',
-              // 되돌리기 원본 — 다른 프로그램의 칸까지 모두
-              { accountId, ids: [...destroyIds], properties: null },
+              // 되돌리기 원본 — 다른 프로그램의 칸까지 모두 (원본이 필요 없으면 있는지만)
+              {
+                accountId,
+                ids: [...destroyIds],
+                properties: withoutOriginals ? EXISTENCE_PROPERTIES : null,
+              },
               'd',
             ] as JmapInvocation,
           ]
@@ -396,9 +440,11 @@ export class JmapContactsProvider implements ContactsProvider {
     if (updating === null || destroying === null) return null;
     return {
       cards: updating,
-      originals: new Map(
-        [...destroying].map(([id, card]) => [id, cardOriginal(card)]),
-      ),
+      originals: withoutOriginals
+        ? new Map()
+        : new Map(
+            [...destroying].map(([id, card]) => [id, cardOriginal(card)]),
+          ),
     };
   }
 

backend/src/modules/mail/jmap/jmap-filter-run.spec.ts

@@ -11,6 +11,7 @@ import type {
 } from '@/modules/mail/mail.types';
 import {
   decodeFilterRunCursor,
+  encodeBlockRunCursor,
   encodeFilterRunCursor,
 } from './filter-run-cursor';
 import type { JmapClient } from './jmap.client';
@@ -1180,6 +1181,278 @@ describe('JmapFilterRunner — 이미 받은 메일에 필터 적용 (계약 2
         ).toMatchObject({ code: 'MAIL_001', reason: 'timeout' });
       });
     });
+
+    describe('차단할 때 받은편지함 정리 (runBlock — 15단계)', () => {
+      const JUNK = 'k';
+      const BLOCK_MAILBOXES: readonly Mailbox[] = [
+        mailbox(INBOX, 'inbox', 3),
+        mailbox(TARGET, null),
+        mailbox(JUNK, 'junk'),
+      ];
+      const blockContext = (
+        overrides: Partial<MailFilterRunContext> = {},
+      ): MailFilterRunContext => ({
+        mailboxes: BLOCK_MAILBOXES,
+        startedAt: Date.now(),
+        ...overrides,
+      });
+      /** 받은편지함의 메일 — 엔진이 푼 From 머리글의 주소(머리글마다 배열) */
+      const fromMail = (
+        id: string,
+        ...headers: { name: string | null; email: string }[][]
+      ) => ({
+        id,
+        mailboxIds: { [INBOX]: true },
+        receivedAt: utc(T0),
+        'header:From:asAddresses:all': headers,
+      });
+      const KIM = { name: null, email: 'kim@spam.example' };
+      const junkPatch = {
+        [`mailboxIds/${INBOX}`]: null,
+        [`mailboxIds/${JUNK}`]: true,
+        'keywords/$junk': true,
+        'keywords/$notjunk': null,
+      };
+
+      it('받은편지함을 받은 시각 내림차순으로 읽어 엔진이 푼 From 주소로 판정하고, 맞은 메일을 스팸메일함으로 옮기며 스팸 표시 — 옮기기는 읽은 상태 그대로일 때만', async () => {
+        const { runner, recorded } = fakeRunner([
+          page(
+            ['m1', 'm2', 'm3'],
+            [
+              fromMail('m1', [KIM]),
+              fromMail('m2', [{ name: null, email: 'lee@spam.example' }]),
+              fromMail('m3', [{ name: 'Kim', email: 'KIM@Spam.Example' }]),
+            ],
+          ),
+          updated(['m1', 'm3']),
+        ]);
+
+        await expect(
+          runner.runBlock(
+            ARA,
+            { sender: 'kim@spam.example', cursor: null },
+            blockContext(),
+          ),
+        ).resolves.toEqual({
+          scanned: 3,
+          matched: 2,
+          remaining: 0,
+          cursor: null,
+          rounds: 1,
+        });
+        expect(argsOf(recorded[0])).toMatchObject({
+          filter: { inMailbox: INBOX },
+          sort: [{ property: 'receivedAt', isAscending: false }],
+          limit: 500,
+          calculateTotal: true,
+        });
+        expect(argsOf(recorded[0], 1)).toMatchObject({
+          properties: [
+            'id',
+            'mailboxIds',
+            'receivedAt',
+            'header:From:asAddresses:all',
+          ],
+        });
+        // 붙잡힌 메일을 같은 요청에서 묻는다 (9단계 — 옮기지 않는다)
+        expect(methodsOf([recorded[0]])).toEqual([
+          'Email/query',
+          'Email/get',
+          'EmailSubmission/query',
+          'EmailSubmission/get',
+        ]);
+        expect(argsOf(recorded[1])).toEqual({
+          accountId: 'd',
+          ifInState: 's1',
+          update: { m1: junkPatch, m3: junkPatch },
+        });
+      });
+
+      it('판정은 차단 규칙(Sieve 의 address)과 같다 — 주소 전체가 같을 때 · From 이 여럿이면 하나라도 · 표시 이름의 주소 · 비슷한 주소는 아니다 (대소문자는 ASCII 만)', async () => {
+        const cases: [string, ReturnType<typeof fromMail>][] = [
+          ['맞음', fromMail('m1', [KIM])],
+          [
+            '맞음',
+            fromMail('m2', [
+              { name: 'First', email: 'first@example.net' },
+              { name: 'Kim', email: 'kim@spam.example' },
+            ]),
+          ],
+          [
+            '맞음',
+            fromMail('m3', [{ name: null, email: 'first@example.net' }], [KIM]),
+          ],
+          [
+            '아님',
+            fromMail('m4', [
+              { name: 'kim@spam.example', email: 'other@example.net' },
+            ]),
+          ],
+          [
+            '아님',
+            fromMail('m5', [{ name: null, email: 'kim.lee@spam.example' }]),
+          ],
+          [
+            '아님',
+            fromMail('m6', [{ name: null, email: 'kim@sub.spam.example' }]),
+          ],
+          [
+            '아님',
+            fromMail('m7', [{ name: null, email: 'akim@spam.example' }]),
+          ],
+          ['아님', fromMail('m8')],
+        ];
+        const { runner, recorded } = fakeRunner([
+          page(
+            cases.map(([, mail]) => mail.id),
+            cases.map(([, mail]) => mail),
+          ),
+          updated(['m1', 'm2', 'm3']),
+        ]);
+
+        await runner.runBlock(
+          ARA,
+          { sender: 'kim@spam.example', cursor: null },
+          blockContext(),
+        );
+        expect(Object.keys(argsOf(recorded[1]).update as object)).toEqual(
+          cases
+            .filter(([verdict]) => verdict === '맞음')
+            .map(([, mail]) => mail.id),
+        );
+      });
+
+      it('도메인 차단(@도메인)은 From 주소의 @ 뒤가 그 도메인일 때만 — 하위 도메인 · 더 긴 도메인 · 표시 이름은 아니다', async () => {
+        const mails = [
+          fromMail('m1', [{ name: null, email: 'kim@spam.example' }]),
+          fromMail('m2', [{ name: null, email: 'Lee@SPAM.example' }]),
+          fromMail('m3', [{ name: null, email: 'kim@sub.spam.example' }]),
+          fromMail('m4', [{ name: null, email: 'kim@spam.example.net' }]),
+          fromMail('m5', [
+            { name: '@spam.example', email: 'kim@other.example' },
+          ]),
+        ];
+        const { runner, recorded } = fakeRunner([
+          page(
+            mails.map(({ id }) => id),
+            mails,
+          ),
+          updated(['m1', 'm2']),
+        ]);
+
+        await runner.runBlock(
+          ARA,
+          { sender: '@spam.example', cursor: null },
+          blockContext(),
+        );
+        expect(Object.keys(argsOf(recorded[1]).update as object)).toEqual([
+          'm1',
+          'm2',
+        ]);
+      });
+
+      it('붙잡힌 메일(9단계)은 맞아도 옮기지 않는다 — 받은편지함에 남긴 것으로 세고 matched 에 넣지 않는다', async () => {
+        const later = utc(Math.floor(Date.now() / 1_000) + 3_600);
+        const { runner, recorded } = fakeRunner([
+          page(['m1', 'm2'], [fromMail('m1', [KIM]), fromMail('m2', [KIM])], {
+            held: [
+              {
+                id: 'sub1',
+                emailId: 'm2',
+                undoStatus: 'pending',
+                sendAt: later,
+              },
+            ],
+          }),
+          updated(['m1']),
+        ]);
+
+        await expect(
+          runner.runBlock(
+            ARA,
+            { sender: 'kim@spam.example', cursor: null },
+            blockContext(),
+          ),
+        ).resolves.toMatchObject({ scanned: 2, matched: 1 });
+        expect(argsOf(recorded[1])).toMatchObject({
+          update: { m1: junkPatch },
+        });
+        expect(argsOf(recorded[1]).update).not.toHaveProperty('m2');
+      });
+
+      it('스팸메일함이 없으면 엔진에 묻지 않고 MAIL_001 · 받은편지함이 없으면 할 메일이 없다', async () => {
+        const noJunk = fakeRunner([]);
+        expect(
+          await failureOf(
+            noJunk.runner.runBlock(
+              ARA,
+              { sender: 'kim@spam.example', cursor: null },
+              blockContext({
+                mailboxes: BLOCK_MAILBOXES.filter(
+                  ({ role }) => role !== 'junk',
+                ),
+              }),
+            ),
+          ),
+        ).toMatchObject({ code: 'MAIL_001', reason: 'junk-mailbox-missing' });
+        expect(noJunk.recorded).toHaveLength(0);
+
+        const noInbox = fakeRunner([]);
+        await expect(
+          noInbox.runner.runBlock(
+            ARA,
+            { sender: 'kim@spam.example', cursor: null },
+            blockContext({
+              mailboxes: BLOCK_MAILBOXES.filter(({ role }) => role !== 'inbox'),
+            }),
+          ),
+        ).resolves.toEqual({
+          scanned: 0,
+          matched: 0,
+          remaining: 0,
+          cursor: null,
+          rounds: 0,
+        });
+      });
+
+      it('이어 할 자리 — 다른 보낸 사람의 cursor · 필터 적용의 cursor · 깨진 cursor 는 엔진에 묻기 전에 VAL_001', async () => {
+        const position = { before: T0 + 1, anchor: 'm1', anchorTime: T0 };
+        const others = [
+          encodeBlockRunCursor(position, 'lee@spam.example'),
+          encodeFilterRunCursor(position, request()),
+          'not-a-cursor',
+        ];
+        for (const cursor of others) {
+          const fake = fakeRunner([]);
+          expect(
+            await failureOf(
+              fake.runner.runBlock(
+                ARA,
+                { sender: 'kim@spam.example', cursor },
+                blockContext(),
+              ),
+            ),
+          ).toMatchObject({ code: 'VAL_001' });
+          expect(fake.recorded).toHaveLength(0);
+        }
+
+        // 같은 보낸 사람의 cursor 는 그 자리부터 — anchor 다음 · 위 경계 미만
+        const fake = fakeRunner([page([], [])]);
+        await fake.runner.runBlock(
+          ARA,
+          {
+            sender: 'kim@spam.example',
+            cursor: encodeBlockRunCursor(position, 'kim@spam.example'),
+          },
+          blockContext(),
+        );
+        expect(argsOf(fake.recorded[0])).toMatchObject({
+          filter: { inMailbox: INBOX, before: utc(T0 + 1) },
+          anchor: 'm1',
+          anchorOffset: 1,
+        });
+      });
+    });
   });
 
   /**
@@ -1369,6 +1642,10 @@ describe('JmapFilterRunner — 이미 받은 메일에 필터 적용 (계약 2
           ),
           receivedAt: utc(email.receivedAt),
           'header:From:all': [` ${email.from}`],
+          // 엔진이 푼 주소 — 꺾쇠 안 (차단 정리 — 15단계)
+          'header:From:asAddresses:all': [
+            [{ name: null, email: /<([^>]+)>/.exec(email.from)?.[1] ?? '' }],
+          ],
         };
       }
 
@@ -1706,5 +1983,68 @@ describe('JmapFilterRunner — 이미 받은 메일에 필터 적용 (계약 2
       }
       expect(engine.sorted(TARGET)).toHaveLength(700 - kept.length);
     });
+
+    it('차단 정리(15단계)도 같은 틀로 끝까지 — 그 보낸 사람의 메일만 스팸메일함으로(스팸 표시) · 요청 사이에 온 새 메일은 건드리지 않는다', async () => {
+      const JUNK = 'k';
+      const engine = new FakeEngine();
+      fill(engine, 1_200);
+      let now = 1_000_000;
+      jest.spyOn(Date, 'now').mockImplementation(() => now);
+      const client = {
+        call: jest.fn(
+          (_user: string, build: (accountId: string) => JmapInvocation[]) => {
+            const calls = build('d');
+            if (calls[0][0] === 'Email/query') now += 21_000;
+            return Promise.resolve(engine.handle(calls));
+          },
+        ),
+      };
+      const runner = new JmapFilterRunner(client as unknown as JmapClient);
+      const sender = 'sales@hanbit-partners.co.kr';
+      const wanted = engine
+        .sorted(INBOX)
+        .filter(({ from }) => from.includes(sender)).length;
+
+      let cursor: string | null = null;
+      let requests = 0;
+      let matched = 0;
+      do {
+        // 요청 사이에 그 보낸 사람의 새 메일이 온다 — 시작한 뒤 온 메일은 보지 않는다 (새 메일은 Sieve 가 이미 판정했다)
+        if (cursor !== null) engine.add(T0 + 10_000 + requests, HANBIT_FROM);
+        const result = await runner.runBlock(
+          ARA,
+          { sender, cursor },
+          {
+            mailboxes: [
+              mailbox(INBOX, 'inbox', engine.sorted(INBOX).length),
+              mailbox(JUNK, 'junk'),
+            ],
+            startedAt: now,
+          },
+        );
+        matched += result.matched;
+        cursor = result.cursor;
+        requests += 1;
+        now += 100_000;
+      } while (cursor !== null && requests < 100);
+
+      expect(cursor).toBeNull();
+      expect(requests).toBeGreaterThan(1);
+      expect(matched).toBe(wanted);
+      const moved = engine.sorted(JUNK);
+      expect(moved).toHaveLength(wanted);
+      for (const email of moved) {
+        expect(email.keywords.has('$junk')).toBe(true);
+        expect(email.receivedAt).toBeLessThan(T0 + 10_000);
+      }
+      // 받은편지함에 남은 그 보낸 사람의 메일은 요청 사이에 온 새 메일뿐
+      const left = engine
+        .sorted(INBOX)
+        .filter(({ from }) => from.includes(sender));
+      expect(left).toHaveLength(requests - 1);
+      expect(left.every(({ receivedAt }) => receivedAt >= T0 + 10_000)).toBe(
+        true,
+      );
+    });
   });
 });

backend/src/modules/mail/jmap/jmap-filter-run.ts

@@ -1,6 +1,7 @@
 import { Injectable, Logger } from '@nestjs/common';
 
 import { BusinessException } from '@/common/errors/business.exception';
+import { isBlockedSenderMail } from '@/modules/mail/mail-block-match';
 import {
   filterFields,
   judgeFilter,
@@ -8,6 +9,7 @@ import {
 } from '@/modules/mail/mail-filter-match';
 import type {
   Mailbox,
+  MailBlockRunRequest,
   MailFilterRunContext,
   MailFilterRunOutcome,
   MailFilterRunRequest,
@@ -15,15 +17,20 @@ import type {
 import { BulkRun } from './bulk-run';
 import {
   MAX_FILTER_RUN_SECONDS,
+  decodeBlockRunCursor,
   decodeFilterRunCursor,
+  encodeBlockRunCursor,
   encodeFilterRunCursor,
+  type FilterRunPosition,
 } from './filter-run-cursor';
 import {
   FILTER_RUN_BODY_PROPERTIES,
   FILTER_RUN_PART_PROPERTIES,
+  FROM_ADDRESSES_PROPERTY,
   bodyTextsOf,
   estimatedBodyBytes,
   filterRunProperties,
+  fromAddressesOf,
   headerTextsOf,
   textPartsOf,
 } from './filter-run-texts';
@@ -97,6 +104,32 @@ const HELD_GUARD_CALLS = 'h';
 /** 붙잡힌 메일이 없다 — 옮기지 않는 규칙 · 읽은 메일이 없는 쪽 */
 const NO_HELD: HeldEmails = { ids: new Set(), complete: true };
 
+/** 처음부터 — 위 경계 · 남긴 메일 · 그 받은 시각을 아직 모른다 (첫 차례가 위 경계를 잡는다) */
+const FROM_TOP: RunState = { before: null, anchor: null, anchorTime: null };
+
+/** 바꾼 것이 없다 — 맞은 메일이 없거나 모두 바꿀 것이 없는 차례 */
+const NOTHING_APPLIED: Applied = { updated: new Set(), gone: new Set() };
+
+/**
+ * 차단 정리(15단계)가 차례마다 읽는 속성 — 받은편지함에 아직 있는지 · 받은 시각(이어 할 자리) · 엔진이 푼 From 머리글의 주소(filter-run-texts.ts).
+ * 표시는 읽지 않는다 — 맞은 메일은 늘 옮기고 스팸 표시를 붙인다(이미 붙어 있어도 같은 패치)
+ */
+const BLOCK_RUN_PROPERTIES = [
+  'id',
+  'mailboxIds',
+  'receivedAt',
+  FROM_ADDRESSES_PROPERTY,
+];
+
+/** 받은편지함이 없는 계정 — 할 메일이 없다 (필터 적용 · 차단 정리 모두) */
+const NOTHING_TO_RUN: MailFilterRunOutcome = {
+  scanned: 0,
+  matched: 0,
+  remaining: 0,
+  cursor: null,
+  rounds: 0,
+};
+
 /**
  * 한 통의 본문을 부분마다 읽는 몫 (바이트) — 한 부분은 FILTER_RUN_BODY_VALUE_BYTES 까지, 한 통은 모두 합쳐 FILTER_RUN_MESSAGE_BODY_BYTES 까지.
  * 글자 부분이 많으면 같은 몫씩 나눈다 (적어도 1바이트). 엔진의 maxBodyValueBytes 는 요청 단위라 몫이 다른 메일은 따로 읽는다
@@ -185,6 +218,37 @@ interface BodyBatch {
   readonly ids: readonly string[];
 }
 
+/** 한 차례를 판정하고 할 일을 한다 — 필터 적용(applyRound) · 차단 정리(applyBlockRound). 멈춰야 하면 null */
+type RoundRunner = (page: RoundPage) => Promise<RoundResult | null>;
+
+/** 받은편지함을 차례로 훑은 결과 (sweep) */
+interface SweepResult {
+  readonly scanned: number;
+  readonly matched: number;
+  readonly remaining: number;
+  /** 끝까지 했다 — 이어 할 자리가 없다 */
+  readonly finished: boolean;
+  /** 마지막으로 마친 차례까지의 자리 */
+  readonly position: RunState;
+  readonly rounds: number;
+}
+
+/** 판정 — true 맞음 · false 안 맞음 · 'gone' 받은편지함에서 빠진 메일(건너뛰고 세지 않는다) */
+type Verdict = boolean | 'gone';
+
+/**
+ * 차단 정리(15단계)의 패치 — 받은편지함에서 빼고 스팸메일함에 넣고 스팸 표시(`$junk` 를 붙이고 `$notjunk` 를 뗀다 — 스팸 신고 `isJunk: true` 와 같다,
+ * jmap-mail.provider.ts 의 toEmailPatch)
+ */
+function blockPatch(inboxId: string, junkId: string): Record<string, unknown> {
+  return {
+    [`mailboxIds/${inboxId}`]: null,
+    [`mailboxIds/${junkId}`]: true,
+    'keywords/$junk': true,
+    'keywords/$notjunk': null,
+  };
+}
+
 /** 옮길 메일함 — 규칙에 없거나 · 받은편지함이거나 · 메일함 목록에 없으면(지워짐) 옮기지 않는다 (계약 — 표시는 한다) */
 function runPlan(
   request: MailFilterRunRequest,
@@ -242,6 +306,41 @@ function utcDate(seconds: number): string {
   return toJmapUtcDate(new Date(seconds * MS_PER_SECOND).toISOString());
 }
 
+/**
+ * 한 차례를 마친 결과 — 판정한 수(받은편지함에서 빠진 메일은 빼고)와 받은편지함에 남긴 마지막 메일(다음 차례의 anchor).
+ * 옮긴 메일(moving 가운데 바뀐 것)과 그사이 없어진 메일은 남긴 것이 아니다
+ * @param moving 옮기기가 든 패치를 보낸 메일 — 바뀌면 받은편지함을 떠난다
+ * @param matched 이 차례에서 할 일을 한 수 (필터 적용은 이미 표시가 있던 메일 포함 · 차단 정리는 옮긴 수)
+ */
+function roundResult(
+  page: RoundPage,
+  verdicts: ReadonlyMap<string, Verdict>,
+  moving: ReadonlySet<string>,
+  applied: Applied,
+  matched: number,
+): RoundResult {
+  let judged = 0;
+  let lastStayed: string | null = null;
+  for (const id of page.ids) {
+    const verdict = verdicts.get(id);
+    if (verdict === undefined || verdict === 'gone') continue;
+    judged += 1;
+    const moved = moving.has(id) && applied.updated.has(id);
+    if (!moved && !applied.gone.has(id)) lastStayed = id;
+  }
+  return {
+    judged,
+    matched,
+    lastStayed:
+      lastStayed === null
+        ? null
+        : {
+            id: lastStayed,
+            time: receivedSeconds(page.emails.get(lastStayed)),
+          },
+  };
+}
+
 /** 차례에서 가장 최근의 받은 시각(초) — 받은편지함 맨 위 메일 (읽은 메일이 없으면 null) */
 function newestSecond(page: RoundPage): number | null {
   let newest: number | null = null;
@@ -305,6 +404,9 @@ function bodyBatches(emails: readonly JmapEmail[]): BodyBatch[] {
  *   진행(processed)은 판정한 메일 수다 — 판정한 것이 없는 차례는 멈춘 차례로 센다
  * - 이어 할 자리는 cursor — 한 차례를 다 마친 곳까지만 (도중에 멈춘 차례는 다음 요청이 다시 한다 — 할 일은 다시 해도 같다)
  * - 받은편지함 · 옮길 메일함은 서비스가 읽은 메일함 목록(context.mailboxes)에서 찾는다 — 다시 읽지 않는다
+ *
+ * 차단할 때 받은편지함 정리(runBlock — 15단계, 계약 2절 "보낸 사람 차단")도 같은 틀이다 — 차례 · 위 경계 · 자리 · 시간 · 멈춤 · 옮기기의 조건(ifInState) ·
+ * 붙잡힌 메일 막기는 그대로(sweep · readPage · applyPatches), 판정만 차단 규칙(Sieve 의 `address` — mail-block-match.ts)이고 할 일은 스팸메일함으로 옮기기 + 스팸 표시다
  */
 @Injectable()
 export class JmapFilterRunner {
@@ -318,17 +420,15 @@ export class JmapFilterRunner {
     context: MailFilterRunContext,
   ): Promise<MailFilterRunOutcome> {
     // 이어 할 자리는 엔진에 묻기 전에 본다 — 다른 규칙 · 깨진 cursor 면 VAL_001
-    let position: RunState =
+    const start: RunState =
       request.cursor === null
-        ? { before: null, anchor: null, anchorTime: null }
+        ? FROM_TOP
         : decodeFilterRunCursor(request.cursor, request);
 
     const run = new BulkRun(context.startedAt);
     const inbox = context.mailboxes.find((mailbox) => mailbox.role === 'inbox');
     // 받은편지함이 없는 계정 — 적용할 메일이 없다
-    if (!inbox) {
-      return { scanned: 0, matched: 0, remaining: 0, cursor: null, rounds: 0 };
-    }
+    if (!inbox) return NOTHING_TO_RUN;
 
     const plan = runPlan(request, inbox.id, context.mailboxes);
     const fields = filterFields(request);
@@ -341,6 +441,78 @@ export class JmapFilterRunner {
       withHeld: plan.moveTo !== null,
     };
 
+    const swept = await this.sweep(user, inbox, start, read, run, (page) =>
+      this.applyRound(user, request, plan, page, run),
+    );
+    if (!swept.finished) run.assertProgress('filter-run');
+    return this.outcomeOf(swept, (position) =>
+      encodeFilterRunCursor(position, request),
+    );
+  }
+
+  /**
+   * 차단할 때 받은편지함 정리 (계약 2절 "보낸 사람 차단" — 15단계) — 받은편지함의 그 보낸 사람 메일을 스팸메일함으로 옮기고 스팸 표시를 붙인다.
+   * 판정은 엔진이 푼 From 머리글의 주소로 차단 규칙과 같게(mail-block-match.ts) — 머리글 원문을 읽지 않는다(표시 이름에 쓴 주소가 걸리지 않게).
+   * 맞은 메일은 늘 옮긴다(옮기기라 읽은 상태 그대로일 때만 — ifInState). 붙잡힌 메일(9단계)은 옮기지 않는다(받은편지함에는 없지만 지금 규칙대로).
+   * 스팸메일함이 없으면 엔진에 묻기 전에 MAIL_001, cursor 가 깨졌거나 다른 보낸 사람의 것이면 그 앞에 VAL_001.
+   * 응답의 matched 는 스팸메일함으로 옮긴 수다
+   */
+  async runBlock(
+    user: string,
+    request: MailBlockRunRequest,
+    context: MailFilterRunContext,
+  ): Promise<MailFilterRunOutcome> {
+    const start: RunState =
+      request.cursor === null
+        ? FROM_TOP
+        : decodeBlockRunCursor(request.cursor, request.sender);
+
+    const run = new BulkRun(context.startedAt);
+    const inbox = context.mailboxes.find((mailbox) => mailbox.role === 'inbox');
+    if (!inbox) return NOTHING_TO_RUN;
+    const junk = context.mailboxes.find((mailbox) => mailbox.role === 'junk');
+    if (!junk) {
+      throw new BusinessException('MAIL_001', {
+        context: { reason: 'junk-mailbox-missing' },
+      });
+    }
+
+    const plan: RunPlan = {
+      inboxId: inbox.id,
+      moveTo: junk.id,
+      markAsRead: false,
+      flag: false,
+    };
+    const read: PageRead = {
+      properties: BLOCK_RUN_PROPERTIES,
+      needsBody: false,
+      limit: HEADER_ROUND_SIZE,
+      withHeld: true,
+    };
+
+    const swept = await this.sweep(user, inbox, start, read, run, (page) =>
+      this.applyBlockRound(user, request.sender, plan, junk.id, page, run),
+    );
+    if (!swept.finished) run.assertProgress('mail-block-run');
+    return this.outcomeOf(swept, (position) =>
+      encodeBlockRunCursor(position, request.sender),
+    );
+  }
+
+  /**
+   * 받은편지함을 받은 시각이 최근인 메일부터 차례로 훑는다 — 차례마다 읽고(readPage) 판정 · 할 일(applyRound)을 한 뒤 자리를 옮긴다.
+   * 한 요청의 시간 · 멈춤은 BulkRun. 처음 차례가 맨 위 메일의 받은 시각 + 1초를 위 경계로 잡는다(그 뒤에 온 메일은 보지 않는다).
+   * 남은 시간 때문에 끊긴 호출은 진행한 것이 있으면 거기까지로 답한다(cutOffAfterProgress)
+   */
+  private async sweep(
+    user: string,
+    inbox: Mailbox,
+    start: RunState,
+    read: PageRead,
+    run: BulkRun,
+    applyRound: RoundRunner,
+  ): Promise<SweepResult> {
+    let position = start;
     let scanned = 0;
     let matched = 0;
     let rounds = 0;
@@ -359,7 +531,7 @@ export class JmapFilterRunner {
         const newest = position.before === null ? newestSecond(page) : null;
         if (newest !== null) position = { ...position, before: newest + 1 };
 
-        const round = await this.applyRound(user, request, plan, page, run);
+        const round = await applyRound(page);
         // 멈춘다 — 이 차례는 하지 않은 것으로 (다음 요청이 같은 자리부터 다시 한다)
         if (round === null) break;
 
@@ -387,22 +559,38 @@ export class JmapFilterRunner {
     } catch (error) {
       if (!run.cutOffAfterProgress(error)) throw error;
     }
-    if (!finished) run.assertProgress('filter-run');
-
     return {
       scanned,
       matched,
       remaining: finished ? 0 : remaining,
-      cursor: finished ? null : this.cursorOf(position, request),
+      finished,
+      position,
       rounds,
     };
   }
 
+  /** 훑은 결과 → 응답 — 끝까지 했으면 cursor 없음, 아니면 마친 자리의 cursor (cursorOf) */
+  private outcomeOf(
+    swept: SweepResult,
+    encode: (position: FilterRunPosition) => string,
+  ): MailFilterRunOutcome {
+    return {
+      scanned: swept.scanned,
+      matched: swept.matched,
+      remaining: swept.remaining,
+      cursor: swept.finished ? null : this.cursorOf(swept.position, encode),
+      rounds: swept.rounds,
+    };
+  }
+
   /**
    * 이어 할 자리 — 위 경계와 남긴 마지막 메일의 받은 시각이 있어야 한다. 없으면 엔진이 받은 시각을 주지 않은 것 — MAIL_001
    * (끝까지 했으면 이어 할 자리가 필요 없어 묻지 않는다)
    */
-  private cursorOf(position: RunState, request: MailFilterRunRequest): string {
+  private cursorOf(
+    position: RunState,
+    encode: (position: FilterRunPosition) => string,
+  ): string {
     if (
       position.before === null ||
       (position.anchor !== null && position.anchorTime === null)
@@ -411,14 +599,11 @@ export class JmapFilterRunner {
         context: { reason: 'received-at-missing' },
       });
     }
-    return encodeFilterRunCursor(
-      {
-        before: position.before,
-        anchor: position.anchor,
-        anchorTime: position.anchorTime,
-      },
-      request,
-    );
+    return encode({
+      before: position.before,
+      anchor: position.anchor,
+      anchorTime: position.anchorTime,
+    });
   }
 
   /**
@@ -571,7 +756,7 @@ export class JmapFilterRunner {
     run: BulkRun,
   ): Promise<RoundResult | null> {
     /** 판정 — 'gone' 은 받은편지함에서 빠진 메일(건너뛰고 세지 않는다) */
-    const verdicts = new Map<string, boolean | 'gone'>();
+    const verdicts = new Map<string, Verdict>();
     const undecided: JmapEmail[] = [];
     const headerTexts = new Map<string, Omit<MailFilterTexts, 'body'>>();
     for (const id of page.ids) {
@@ -641,30 +826,69 @@ export class JmapFilterRunner {
 
     const applied: Applied | null =
       patches.size === 0
-        ? { updated: new Set(), gone: new Set() }
+        ? NOTHING_APPLIED
         : await this.applyPatches(user, plan, page.state, patches, run);
     if (applied === null) return null;
 
-    let judged = 0;
-    let lastStayed: string | null = null;
+    return roundResult(
+      page,
+      verdicts,
+      moving,
+      applied,
+      unchanged + applied.updated.size,
+    );
+  }
+
+  /**
+   * 차단 정리의 한 차례 (15단계) — 엔진이 푼 From 주소로 판정하고(mail-block-match.ts) 맞은 메일을 스팸메일함으로 옮긴다(스팸 표시와 함께).
+   * 붙잡힌 메일(9단계)은 옮기지 않는다 — 받은편지함에 남은 것으로 센다. matched 는 옮긴 수다. 멈춰야 하면 null (applyPatches)
+   */
+  private async applyBlockRound(
+    user: string,
+    sender: string,
+    plan: RunPlan,
+    junkId: string,
+    page: RoundPage,
+    run: BulkRun,
+  ): Promise<RoundResult | null> {
+    const verdicts = new Map<string, Verdict>();
     for (const id of page.ids) {
-      const verdict = verdicts.get(id);
-      if (verdict === undefined || verdict === 'gone') continue;
-      judged += 1;
-      const moved = moving.has(id) && applied.updated.has(id);
-      if (!moved && !applied.gone.has(id)) lastStayed = id;
+      const email = page.emails.get(id);
+      verdicts.set(
+        id,
+        email?.mailboxIds?.[plan.inboxId] !== true
+          ? 'gone'
+          : isBlockedSenderMail(fromAddressesOf(email), sender),
+      );
     }
-    return {
-      judged,
-      matched: unchanged + applied.updated.size,
-      lastStayed:
-        lastStayed === null
-          ? null
-          : {
-              id: lastStayed,
-              time: receivedSeconds(page.emails.get(lastStayed)),
-            },
-    };
+
+    const matchedIds = page.ids.filter((id) => verdicts.get(id) === true);
+    const held =
+      matchedIds.length === 0
+        ? new Set<string>()
+        : await heldAmong(
+            page.held,
+            matchedIds,
+            this.heldLookup(user, run.callOptions()),
+          );
+    const patches = new Map<string, Record<string, unknown>>();
+    for (const id of matchedIds) {
+      if (!held.has(id)) patches.set(id, blockPatch(plan.inboxId, junkId));
+    }
+
+    const applied: Applied | null =
+      patches.size === 0
+        ? NOTHING_APPLIED
+        : await this.applyPatches(user, plan, page.state, patches, run);
+    if (applied === null) return null;
+
+    return roundResult(
+      page,
+      verdicts,
+      new Set(patches.keys()),
+      applied,
+      applied.updated.size,
+    );
   }
 
   /**

backend/src/modules/mail/jmap/jmap-filter-script.spec.ts

@@ -7,7 +7,10 @@ import type {
   MailVacation,
 } from '@/modules/mail/mail.types';
 import {
+  FILTER_SOURCE_FORMAT_WITH_RICH_VACATION,
+  FILTER_SOURCE_MARKER,
   NEVER_CONFIGURED_VACATION,
+  SAME_AS_INTERNAL_REPLY,
   filterRulesVersion,
   readFilterSource,
   type FilterScriptSource,
@@ -57,6 +60,8 @@ const vacationOn: MailVacation = {
   toDate: '2026-11-07T15:00:00.000Z',
   subject: '부재중입니다',
   textBody: '11월 7일까지 휴가입니다.',
+  htmlBody: null,
+  external: SAME_AS_INTERNAL_REPLY,
 };
 
 interface FakeScript {
@@ -139,8 +144,12 @@ class FakeSieveEngine {
     ),
   };
 
+  /** 회사 메일 도메인 설정 (MAIL_SETTINGS 의 domain) — 부재중의 회사 밖 응답을 가를 때 */
+  readonly settings: { domain: string | null } = { domain: 'arasystem.test' };
+
   readonly store = new JmapFilterScriptStore(
     this.client as unknown as JmapClient,
+    this.settings,
   );
 
   /** 스크립트를 하나 둔다 (다른 메일 프로그램 · 앞선 저장이 만든 것) */
@@ -341,12 +350,15 @@ describe('JmapFilterScriptStore — 필터 · 부재중 자동 응답의 저장
         version: filterRulesVersion([]),
         isActive: true,
       });
+      // 엔진의 서식 본문은 가져오지 않는다 — 글만 · 사내와 같은 응답(16단계 칸의 처음 값)
       await expect(engine.store.getVacation(ARA)).resolves.toEqual({
         isEnabled: true,
         fromDate: '2026-11-02T15:00:00.000Z',
         toDate: null,
         subject: '4단계 부재중',
         textBody: '휴가입니다.',
+        htmlBody: null,
+        external: SAME_AS_INTERNAL_REPLY,
         isActive: true,
       });
       expect(engine.recorded[0]).toEqual({
@@ -392,6 +404,8 @@ describe('JmapFilterScriptStore — 필터 · 부재중 자동 응답의 저장
         toDate: '2026-11-07T15:00:00.000Z',
         subject: '',
         textBody: '',
+        htmlBody: null,
+        external: SAME_AS_INTERNAL_REPLY,
       };
 
       await expect(engine.store.getVacation(ARA)).resolves.toEqual({
@@ -532,7 +546,7 @@ describe('JmapFilterScriptStore — 필터 · 부재중 자동 응답의 저장
           context: {
             reason: 'filter-source-newer',
             format: 99,
-            supportedFormat: 2,
+            supportedFormat: FILTER_SOURCE_FORMAT_WITH_RICH_VACATION,
           },
         });
       }
@@ -1060,6 +1074,55 @@ describe('JmapFilterScriptStore — 필터 · 부재중 자동 응답의 저장
       expect(engine.ours()?.isActive).toBe(true);
     });
 
+    it('회사 밖 따로 쓰기 · 서식 본문(16단계) — 회사 메일 도메인으로 봉투 보낸 사람을 가르는 글을 올리고, 원본은 판 3', async () => {
+      const engine = new FakeSieveEngine();
+      engine.settings.domain = 'arasystem.it.kr';
+      const rich: MailVacation = {
+        ...vacationOn,
+        htmlBody: '<p>11월 7일까지 <strong>휴가</strong>입니다.</p>',
+        external: {
+          mode: 'separate',
+          subject: 'Out of office',
+          textBody: 'I am away until Nov 7.',
+          htmlBody: null,
+        },
+      };
+
+      await expect(engine.store.setVacation(ARA, rich)).resolves.toEqual({
+        ...rich,
+        isActive: true,
+      });
+      const text = engine.blobs.get(engine.ours()!.blobId) ?? '';
+      expect(text).toContain(
+        'if envelope :domain :is "from" "arasystem.it.kr" {',
+      );
+      expect(text).toContain('multipart/alternative');
+      expect(text).toContain(':handle "ara-external-');
+      expect(text.split('\r\n')[1]).toContain(
+        `${FILTER_SOURCE_MARKER}{"v":${FILTER_SOURCE_FORMAT_WITH_RICH_VACATION},`,
+      );
+      expect(engine.ourSource()?.vacation).toEqual(rich);
+      await expect(engine.store.getVacation(ARA)).resolves.toEqual({
+        ...rich,
+        isActive: true,
+      });
+    });
+
+    it('회사 메일 도메인 설정이 없으면 직원 주소의 도메인으로 가른다 (로그인한 직원은 늘 그 도메인이다)', async () => {
+      const engine = new FakeSieveEngine();
+      engine.settings.domain = null;
+
+      await engine.store.setVacation(ARA, {
+        ...vacationOn,
+        external: { ...SAME_AS_INTERNAL_REPLY, mode: 'none' },
+      });
+      const text = engine.blobs.get(engine.ours()!.blobId) ?? '';
+      expect(text).toContain(
+        'if envelope :domain :is "from" "arasystem.test" {',
+      );
+      expect(text).not.toContain('else');
+    });
+
     it('우리 스크립트가 없으면 만든다 — 규칙 없음 + 부재중, 켠다', async () => {
       const engine = new FakeSieveEngine();
       engine.addScript('vacation', 'require ["vacation"];\r\n', true);

backend/src/modules/mail/jmap/jmap-filter-script.ts

@@ -1,7 +1,8 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Inject, Injectable, Logger } from '@nestjs/common';
 
 import { BusinessException } from '@/common/errors/business.exception';
 import { MAX_MAIL_BLOCKS } from '@/modules/mail/mail.constants';
+import { MAIL_SETTINGS, type MailSettings } from '@/modules/mail/mail.settings';
 import type {
   BlockedSender,
   MailBlockAdded,
@@ -121,7 +122,10 @@ interface ScriptSnapshot extends ScriptView {
   readonly newerFormat: number | null;
 }
 
-/** 로그 · 오류 context 에 남기는 스크립트 요약 — 크기와 규칙 · 차단 수만 (규칙의 글 · 차단한 주소는 남기지 않는다) */
+/**
+ * 로그 · 오류 context 에 남기는 스크립트 요약 — 크기와 규칙 · 차단 수, 부재중의 켬 · 서식 있음 · 회사 밖 고르기만
+ * (규칙의 글 · 차단한 주소 · 부재중 글은 남기지 않는다)
+ */
 function scriptSummary(
   script: BuiltFilterScript,
   source: FilterScriptSource,
@@ -131,10 +135,17 @@ function scriptSummary(
     rules: source.rules.length,
     enabledRules: source.rules.filter((rule) => rule.isEnabled).length,
     vacation: source.vacation.isEnabled,
+    vacationHtml: source.vacation.htmlBody !== null,
+    vacationExternal: source.vacation.external.mode,
     blocked: source.blocked.length,
   };
 }
 
+/** 사용자 주소의 도메인 (소문자) — 회사 메일 도메인 설정이 없을 때만 쓴다(로그인한 직원은 늘 그 도메인이다) */
+function domainOf(user: string): string {
+  return user.slice(user.lastIndexOf('@') + 1).toLowerCase();
+}
+
 function toFilterSet(view: ScriptView): MailFilterSet {
   return {
     rules: canonicalRules(view.source.rules),
@@ -175,7 +186,12 @@ function toBlockList(view: ScriptView): MailBlockList {
 export class JmapFilterScriptStore {
   private readonly logger = new Logger(JmapFilterScriptStore.name);
 
-  constructor(private readonly jmap: JmapClient) {}
+  constructor(
+    private readonly jmap: JmapClient,
+    /** 회사 메일 도메인 — 부재중의 회사 밖 응답(16단계)을 봉투 보낸 사람의 도메인으로 가를 때 */
+    @Inject(MAIL_SETTINGS)
+    private readonly settings: Pick<MailSettings, 'domain'>,
+  ) {}
 
   /** 지금 규칙 · 지문 · 동작하는지 */
   async getFilters(user: string): Promise<MailFilterSet> {
@@ -407,7 +423,10 @@ export class JmapFilterScriptStore {
       if (next.blocked.length > 0 && junkMailbox === null) {
         junkMailbox = await this.junkMailbox(user);
       }
-      const script = buildFilterScript(next, { junkMailbox });
+      const script = buildFilterScript(next, {
+        junkMailbox,
+        internalDomain: this.settings.domain ?? domainOf(user),
+      });
       if (
         script.bytes > FILTER_SCRIPT_MAX_BYTES ||
         script.longestStringBytes > SIEVE_STRING_MAX_BYTES
@@ -429,7 +448,7 @@ export class JmapFilterScriptStore {
       const saved = await this.save(user, current, blobId, script, next);
       if (saved !== null) {
         this.logger.debug(
-          `${traceTag()} 엔진 규칙(Sieve)을 저장했습니다: user=${maskEmail(user)}, ${script.bytes}바이트, 규칙 ${next.rules.length}개, 부재중 ${next.vacation.isEnabled ? '켬' : '끔'}, 차단 ${next.blocked.length}개, ${attempt}번째`,
+          `${traceTag()} 엔진 규칙(Sieve)을 저장했습니다: user=${maskEmail(user)}, ${script.bytes}바이트, 규칙 ${next.rules.length}개, 부재중 ${next.vacation.isEnabled ? '켬' : '끔'}(서식 ${next.vacation.htmlBody !== null ? '있음' : '없음'}, 회사 밖 ${next.vacation.external.mode}), 차단 ${next.blocked.length}개, ${attempt}번째`,
         );
         return { source: next, isActive: saved.isActive };
       }

backend/src/modules/mail/jmap/jmap-ops-engine.spec.ts

@@ -133,6 +133,8 @@ describe('JmapOpsEngine — 관리 API · 대리 접근 (13단계)', () => {
       toDate: null,
       subject: '',
       textBody: '',
+      htmlBody: null,
+      external: { mode: 'same', subject: null, textBody: null, htmlBody: null },
       isActive: true,
     };
     filterScripts = {
@@ -899,12 +901,15 @@ describe('JmapOpsEngine — 관리 API · 대리 접근 (13단계)', () => {
       match: 'always',
       actions: { forwardTo: `doyun.lee@${DOMAIN}` },
     });
+    // 운영자의 안내 글은 글만 · 회사 안팎 모두에게 (16단계 칸은 처음 값)
     expect(filterScripts.setVacation).toHaveBeenCalledWith(ARA, {
       isEnabled: true,
       fromDate: null,
       toDate: null,
       subject: '부재 안내',
       textBody: '퇴사했습니다.',
+      htmlBody: null,
+      external: { mode: 'same', subject: null, textBody: null, htmlBody: null },
     });
 
     filterScripts.getFilters.mockResolvedValue({
@@ -912,12 +917,20 @@ describe('JmapOpsEngine — 관리 API · 대리 접근 (13단계)', () => {
       version: 'v2',
       isActive: true,
     });
+    const external = {
+      mode: 'separate' as const,
+      subject: 'Left the company',
+      textBody: 'Please contact doyun.',
+      htmlBody: null,
+    };
     filterScripts.getVacation.mockResolvedValue({
       isEnabled: true,
       fromDate: null,
       toDate: null,
       subject: '부재 안내',
       textBody: '퇴사했습니다.',
+      htmlBody: '<p>퇴사했습니다.</p>',
+      external,
       isActive: true,
     });
     await expect(engine.getLockRules(ARA)).resolves.toEqual({
@@ -929,10 +942,16 @@ describe('JmapOpsEngine — 관리 API · 대리 접근 (13단계)', () => {
       rules: [saved.rules[1]],
       version: 'v2',
     });
-    expect(filterScripts.setVacation).toHaveBeenLastCalledWith(
-      ARA,
-      expect.objectContaining({ isEnabled: false, subject: '부재 안내' }),
-    );
+    // 끄기만 한다 — 글 · 서식 · 회사 밖 응답은 그대로 (isActive 는 넘기지 않는다)
+    expect(filterScripts.setVacation).toHaveBeenLastCalledWith(ARA, {
+      isEnabled: false,
+      fromDate: null,
+      toDate: null,
+      subject: '부재 안내',
+      textBody: '퇴사했습니다.',
+      htmlBody: '<p>퇴사했습니다.</p>',
+      external,
+    });
   });
 
   it('필터가 이미 50개면 넘기기 규칙을 더하지 않는다 (too-many-rules)', async () => {

backend/src/modules/mail/jmap/jmap-ops-engine.ts

@@ -529,12 +529,20 @@ export class JmapOpsEngine implements OpsEngine {
       });
     }
     if (rules.autoReply !== null) {
+      // 운영자의 안내 글 — 글만, 회사 안팎 모두에게 (16단계의 서식 본문 · 회사 밖 응답은 쓰지 않는다)
       await this.filterScripts.setVacation(email, {
         isEnabled: true,
         fromDate: null,
         toDate: null,
         subject: rules.autoReply.subject,
         textBody: rules.autoReply.body,
+        htmlBody: null,
+        external: {
+          mode: 'same',
+          subject: null,
+          textBody: null,
+          htmlBody: null,
+        },
       });
     }
   }
@@ -549,12 +557,15 @@ export class JmapOpsEngine implements OpsEngine {
     }
     const vacation = await this.filterScripts.getVacation(email);
     if (vacation.isEnabled) {
+      // 끄기만 한다 — 글 · 서식 · 회사 밖 응답은 그대로 둔다
       await this.filterScripts.setVacation(email, {
         isEnabled: false,
         fromDate: vacation.fromDate,
         toDate: vacation.toDate,
         subject: vacation.subject,
         textBody: vacation.textBody,
+        htmlBody: vacation.htmlBody,
+        external: vacation.external,
       });
     }
   }

backend/src/modules/mail/jmap/jmap.mapper.ts

@@ -355,7 +355,8 @@ export function toUsage(quota: JmapQuota): MailUsage {
  * 엔진의 VacationResponse → 우리 모양 (계약 2절 "부재중 자동 응답") — 필터 · 부재중을 두는 우리 스크립트가 아직 없을 때 가져온다
  * (4단계에 저장한 값 이어받기 — jmap-filter-script.ts).
  * 엔진에 없는 값(null)의 제목·내용은 빈 문자열, 날짜는 ISO 8601 UTC 로 — 한 번도 설정하지 않은 계정은
- * `{ isEnabled: false, fromDate: null, toDate: null, subject: '', textBody: '' }` 가 된다. 서식 본문(htmlBody)은 쓰지 않는다.
+ * `{ isEnabled: false, fromDate: null, toDate: null, subject: '', textBody: '', htmlBody: null, external: 사내와 같은 응답 }` 가 된다.
+ * 엔진의 서식 본문(htmlBody)은 가져오지 않는다 — 글만 · 사내와 같은 응답(16단계 칸의 처음 값 — filter-source.ts 의 SAME_AS_INTERNAL_REPLY 와 같다)
  */
 export function toVacation(
   response: JmapVacationResponse | undefined,
@@ -366,6 +367,8 @@ export function toVacation(
     toDate: toUtcIso(response?.toDate),
     subject: response?.subject ?? '',
     textBody: response?.textBody ?? '',
+    htmlBody: null,
+    external: { mode: 'same', subject: null, textBody: null, htmlBody: null },
   };
 }