docs: 업데이트 내역을 계약 7절 · 디자인 README · 스킬에 적는다

계약 7절(API 둘 · 글 파일 규칙)과 머리말의 달력 날짜 예외, 웹 · 앱 디자인 README 의 업데이트 내역 절, 세 스택 스킬 행을 더했다.
보드의 목록 최대 개수를 구현(100)에 맞추고, 편집 도구가 보이지 않는 글자의 이스케이프를 실제 글자로 푼 일을 공통 규칙에 적는다.

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

.claude/skills/nestjs/SKILL.md

@@ -47,6 +47,7 @@ description: NestJS 백엔드(backend/) 개발 규칙 — 컨트롤러/서비스
 | 앱 새 메일 알림 (앱 1단계 — FCM) | `modules/push` · `modules/mail/new-mail-push.service.ts` · `MailEventsService.hold` · `common/guards/app-client.guard.ts` | 계약 1절 "앱 새 메일 알림 · 앱 설정". **등록** `PUT`·`DELETE /api/push-registrations/current` · `DELETE …/current/unseen`(`push-registrations.controller.ts` — `@UseGuards(JwtAuthGuard, AppClientGuard)` + `@ApiBearerAuth()`: 앱 토큰만, 웹 쿠키 세션은 403 `AUTH_003`, 제한된 세션 403 `AUTH_010`). 표 `push_registrations`(마이그레이션 `AddPushRegistrations` — 세션(sid)마다 한 줄 · FID 유일 · 세션 표와 외래 키 없음). PUT 은 한 트랜잭션(`push-registrations.repository.ts` — 세션이 살아 있는 · 제한 없는 앱 세션인지 → 같은 FID 의 다른 줄 지우기(같은 FID 는 `pg_advisory_xact_lock('PSH1', hashtext(fid))` 로 차례) → upsert(새 줄만 `seen_at` = 지금) → 직원마다 10줄). 보낼 대상 · 붙잡을 직원은 늘 세션 표와 함께 고른다(살아 있는 · 제한 없는 앱 세션 — 끊은 세션은 `revoked_at` 으로 바로 빠진다), 끝난 세션의 줄은 5분 정리 `push-cleanup.service.ts`(그 휴대폰을 직원이 건드리지 않고 끝난 세션 — 저절로 끝남 · 다른 곳의 비밀번호 바꾸기 · 앱 갱신 유예 · 토큰 재사용 감지 — 의 휴대폰에만 한 번 session-ended, 끊은 까닭 표는 `push.constants.ts` 의 `SESSION_ENDED_NOTICE` 한 곳(`Record<SessionRevokedReason, boolean>` — 까닭을 더하면 거기서 정해야 컴파일된다) — `DELETE … RETURNING`). 등록이 바뀐 소식은 `PushRegistrationsService.onChanged`(메일 쪽이 듣는다 — 푸시 모듈은 메일을 모른다, 사내 도메인만 `MailEngineModule` 의 `MAIL_SETTINGS` 에서). **보내기** 포트 `PUSH_SENDER`(`push-sender.port.ts` — 알림은 종류 · 개수뿐) · 구현 `configured-push-sender.ts`(env `FCM_SERVICE_ACCOUNT_KEY` — 없으면 보내지 않고 기동은 한다) · `fcm/`: 키 읽기 `fcm-credentials.ts`(env 검사와 같은 함수 — 까닭에 값을 싣지 않는다), OAuth `fcm-auth.ts`(RS256 JWT → `oauth2.googleapis.com/token`, 만료 5분 전까지 기억 · 함께 부르면 한 번), 보내기 `fcm-sender.ts`(`message.fid` — 실패 표는 계약, 시도 3번 · 20초 · 서버 전체 4 · 429 는 `Retry-After` 가 있을 때만 그때 한 번 · 보내기 직전(다시 하기마다) 부른 쪽의 `stillValid` — 그 세션의 줄이 아직 그 FID 인가(`isDeliverable`) · 로그는 종류마다 한 시간에 한 번 · 서버 종료로 끊긴 것은 로그 없이), 메시지 `fcm-message.ts`(순수 함수 한 곳 — 글은 `push-text.ts`), HTTP `fcm-transport.ts`(전역 fetch · 두 주소 고정 · 응답 64KB — 시험만 `forTesting`). 새 의존성 없음. **새 메일** `NewMailPushService`(메일 모듈): 보낼 기기가 있는 사내 직원의 엔진 연결을 붙잡고(`MailEventsService.hold` — SSE 와 같은 연결 · 같은 판정, 신호만 받는다 · 연결 상한에 세지 않는다, 함께 여는 수 4, 실패하면 1 · 5 · 15 · 60분 — 계정 문제는 60분부터), 새 메일 신호 → 같은 직원 30초에 한 번(첫 알림 바로 · 끝에 한 번) → 기기마다 N(`MailProvider.countInboxUnreadSince` — 받은편지함 · 안 읽음 · 초안 아님 · `seen_at` 뒤, 한 요청 8개씩) → N ≥ 1 이면 보낸다 · 받지 않는 기기는 FID 가 그대로일 때만 지운다. 붙잡을 때마다 따라잡기(10분 안 · `seen_at` · `last_pushed_at` 의 **다음 초**부터 — 받은 시각은 초, N 은 `seen_at` 의 초부터 같은 초를 넣는다. 엔진의 `after` 는 그 초를 넣지 않아(0.16.27 — 2026-11-08 확인) 어댑터가 한 초 앞을 넘긴다. 붙잡은 뒤 신호가 먼저 오면 따라잡기는 건너뛰고, 따라잡기 뒤 첫 신호 보내기는 새로 받은 메일이 있는 기기에만 — 붙잡은 직후의 메일 하나에 한 번). 붙잡기가 끝나면(`ended` — 계정 문제 60분 · 그 밖 1분 뒤 다시, 서버 종료가 아닌데 허브가 닫혀도 알린다) 간격 끝 차례도 지운다, 등록이 바뀐 소식은 기다림을 풀고 바로 붙잡아 본다. 같은 직원의 보내기는 `KeyedQueue` 로 차례 |
 | 앱 설정 (앱 1단계) | `modules/app-config` | `GET /api/app-config`(로그인 없음 · 기본 요청 수 한도 · `Cache-Control: no-store`) → `{ minSupportedVersion: { android, ios: null }, pushAvailable }`. 최소 판은 코드 상수 `app-config.constants.ts` — 옛 앱을 막을 API 변경과 같은 커밋에서 올린다. `pushAvailable` = `PUSH_SENDER.available` |
 | 휴대폰 앱 받기 (사내 배포 — 2026-11-08) | `modules/app-releases` · `modules/ops/app-release-commands.ts` · `shared/utils/download-headers.ts` | 계약 1절 "휴대폰 앱 받기" — 스토어 없이 직접 빌드한 APK 를 로그인한 직원에게만. `GET /api/app-releases/android/latest`(`{ version, sizeBytes, releasedAt }` · `private, no-store` — 없으면 404 `RES_001`, 컨트롤러 필터가 404 를 debug 로) · `…/latest/file`(GET · HEAD · Range — `downloadHeaders()` 가 대용량 첨부 받기(`serveFile`)와 같은 머리글을 만든다, 형식만 APK · 이름 `ARA-SYSTEM-<버전>.apk`). 제한된 세션은 403 `AUTH_010`. **최신 = 가장 늦게 올린 판**(`created_at` — 버전 번호가 아니다, 옛 APK 를 다시 올리면 되돌리기). 표 `app_releases`(마이그레이션 `AddAppReleases`), 파일은 업로드 볼륨 `app-releases/<file_key>.apk`(`app-release-storage.ts` — 서버가 만든 UUID 만 경로로, `.part` 에 쓰고 datasync → rename, 표에 넣지 못하면 지운다, 한 시간 넘은 `.part` 는 다음 올리기가 지운다). 표에 있는데 파일이 없거나 크기가 다르면 404 + error 로그. **올리기는 API 가 없다** — 운영 도구 「휴대폰 앱 올리기」 · 「휴대폰 앱 목록」: `apk-file.ts` 의 `inspectApk`(O_NOFOLLOW · O_NONBLOCK 로 한 번 열어 fstat 일반 파일 · `.apk` · `PK\x03\x04` · 1KB~200MB · SHA-256 — 그 연 파일로 들이고, 들이며 다시 센 SHA-256 이 다르면 `AppReleaseFileChangedError`), 버전 규칙은 앱 알림 등록의 `APP_VERSION_PATTERN` 그대로(`app-release-version.ts`), app-config 의 최소 판보다 낮으면 막고 지금 최신보다 낮거나 같으면 묻는다. 실행 기록 `app-release-upload` |
+| 업데이트 내역 (2026-11-10) | `modules/release-notes` · 글 폴더 `backend/release-notes/`(src 밖) | 계약 7절 "업데이트 내역" — 직원이 웹메일 · 앱에서 읽는 게시판, 글은 운영자가 저장소에 **글마다 파일 하나**로 쓴다(올리는 API 없음 · 새 에러 코드 · DB 표 · env 없음). `GET /api/release-notes`(`CursorPaginationQueryDto` + `shared/utils/offset-cursor.ts` — 최근 글부터: 날짜 내림차순 · 같은 날은 뒤 번호 먼저, `total` = 글 수) · `GET /api/release-notes/{id}`(sections · previous(바로 더 옛 글) · next(바로 더 새 글) — 없는 글 · 모양이 틀린 id 모두 404 `RES_001`, `release-note-id.pipe.ts` — 길이 32 + 정규식만 보고 경로로 쓰지 않는다, 읽어 둔 목록에서 찾는다). 보호 라우트(`JwtAuthGuard` · 제한된 세션 403 `AUTH_010`) · `private, no-store`. 해석 `release-note-format.ts`(순수 함수 · 입력 길이에 비례 — 파일 이름 → id · 날짜(있는 날짜인지 · `-2`~`-99`), `# 제목`(첫 글 줄 · 한 번) · `## 머리` · `- 한 줄` · 빈칸 두 개(또는 탭) 이어 붙임 · `<!-- 메모 -->`(여러 줄 · 줄 앞에서 시작 — 앞 빈칸은 되고 글 뒤에 붙이지 않는다), 한도 100 · 40 · 500(UTF-16 — 다듬은 뒤: 앞뒤 빈칸 · 안의 빈칸 하나로 · NFC), 그 밖의 줄 · 하위 목록 · 글 안 `<!--` · 제어 문자는 틀림 — 줄 차례로 앞의 20개 문제(다 읽은 뒤 찾는 앞쪽 줄의 문제도 제자리에 — 메모리는 20개만)). 폴더 `release-notes-folder.ts`(`ReleaseNotesFolder` — **기동 때 한 번**(`onApplicationBootstrap` — 실패해도 던지지 않는다) · 그 뒤 요청 때 readdir + lstat, 이름 · 크기 · 바뀐 시각이 같으면 앞 결과, 함께 온 요청은 한 번 읽기. 글 파일은 `readReleaseNoteFile` 이 `O_RDONLY · O_NOFOLLOW · O_NONBLOCK` 로 한 번 열어 그 핸들로 fstat(일반 파일 · 크기) · 256KB + 1 바이트까지만 읽는다 — `modules/app-releases/apk-file.ts` 와 같은 꼴, Windows 는 두 표시가 0. 틀린 글 · 글이 아닌 파일(다른 이름 · 폴더 · 링크)은 건너뛰고 바뀔 때마다 error 한 번 — 파일 이름 · 줄 · 까닭만(글 내용 없음), 폴더가 없으면 빈 목록 + warn 한 번, UTF-8 만(fatal)). 폴더 자리 `RELEASE_NOTES_DIR`(`__dirname` 기준 — src · dist 모두 `backend/release-notes`, 운영 이미지는 `/app/release-notes` — `backend/Dockerfile` 의 `COPY --from=builder /app/release-notes`), 개발은 바인드 마운트라 다시 띄우지 않아도 새 글이 보인다. 시험은 `ReleaseNotesFolder` 를 임시 폴더로 바꿔 끼운다(useFactory — `AppReleaseStorage` 와 같은 꼴, e2e 의 overrideProvider). **실제 폴더를 엄격하게 읽는 시험** `release-notes.content.spec.ts` — 틀린 글 · 글이 아닌 파일이 있으면 CI 실패(운영자 오타를 잡는다, 고치는 법은 그 폴더의 `README.md`) |
 | Rate Limiting | `app.module.ts` 의 `ClientIpThrottlerGuard`(APP_GUARD, `common/guards/client-ip-throttler.guard.ts`) | 초과 시 429 → `REQ_001`. 루트 `.env` 의 `THROTTLE_*` 로 조정. `ThrottlerGuard` 를 상속해 tracker 만 바꿨다 — IP 는 `shared/utils/client-ip.ts` 의 `clientIpKey()`(IPv6 는 /64 로 묶음, 로그인 실패 카운터와 같은 함수) |
 | 로깅 | `shared/logger/winston.config.ts` | `console.log` 대신 사용 ([[logging]]) |
 | env 검증 | `shared/config/env.validation.ts` | 잘못된 설정이면 **기동 실패**(fail-fast) ([[env-structure]]) |
@@ -447,4 +448,5 @@ dc exec backend npm uninstall <패키지>
       새 메일을 알리는 쪽은 엔진 연결을 붙잡아 **신호만** 받는다(`MailEventsService.hold` — 보낸 사람 · 제목을 넘기지 않는다). FID · 서비스 계정 키 · access token · FCM 오류 글은 로그에 남기지 않는다.
       **대용량 첨부의 표시**(11단계 — `data-ara-large-files` · `<!--ara-large-files…-->` · `data-ara-quote-start`)는 서버만 넣는다 — 두 정화기가 사용자 HTML 의 `data-ara-*` · 주석을 지우는지
       정화를 고칠 때 함께 본다(지우지 못하면 남이 꾸민 덩이가 첨부처럼 보인다). 보내기에 실패해도 링크는 "확실한 실패"(`SendNotStartedException`)에서만 거둔다 — 결과를 모르면 남긴다(메일이 나갔을 수 있다).
+- [ ] **업데이트 내역 글**: 글은 `backend/release-notes/` 의 파일로만 더한다(API 없음). 글 형식을 바꾸면 `release-note-format.ts` · 계약 7절 · 그 폴더의 `README.md` · 보드 C 를 함께 고치고, `release-notes.content.spec.ts` 가 실제 폴더를 그대로 통과하는지 본다.
 - [ ] **env**: DB/Redis/CORS/포트는 루트 `.env` 에서 주입된다. 백엔드 고유 시크릿(`JWT_SECRET` 등)만 `backend/.env.{env}` 에 작성(compose `env_file` 로 로드).