[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F2NP49SXVV0ZH73WG7C0DM":3,"skill-same:01M7F2NP49SXVV0ZH73WG7C0DM":72},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":12,"updatedAt":31,"install":32,"resources":45},"01M7F2NP49SXVV0ZH73WG7C0DM","broker-expert",null,"A-RMS 실시간 협업 브로커 저장소(Java-Service-Tree-Framework-Broker-Hub)의 작업 규약. Spring Boot 3.5.6 · Java 21 · Spring Cloud 2025.0.1 기반이며 Backend-Core(Boot 2.6 · Java 11 · JPA) · Middle-Proxy(Boot 2.6 · WebFlux)와 스택도 규칙도 전혀 다르다. STOMP\u002FSockJS 웹소켓 채널 · OT(Operational Transformation) 동시편집 엔진 · Redis 문서 상태\u002F히스토리\u002F참가자 레지스트리 · 위키 편집락 방송(Middle-Proxy 위임) · 세션 생명주기(join · leave · disconnect) · 채팅 · 코드실행 프록시를 건드릴 때 반드시 먼저 읽을 것. WebSocketConfig · enableSimpleBroker · registerStompEndpoints · withSockJS · @MessageMapping · SimpMessagingTemplate · \u002Fapp\u002Fjoin · \u002Fapp\u002Foperation · \u002Fapp\u002Fselection · \u002Fapp\u002Flock\u002Facquire · \u002Ftopic\u002Fsessions\u002F{sessionId}\u002Fstate\u002Fdocument\u002F{documentId} · OtService · OtUtils · TextOperation · retain\u002Finsert\u002Fdelete · revision · updateContentAndHistoryScript · doc:{sessionId}:content · session:users · user:active_docs · SessionRegistryService · WebSocketEventListener · SessionDisconnectEvent · WikiLockClient · LockState · LockCommand · SlackNotificationService · 동시편집이 깨짐 · 참가자 목록이 안 지워짐 · 락이 안 풀림 · 웹소켓 404 같은 주제도 대상이다. \"브로커 허브\", \"broker hub\", \"브로커허브\", \"실시간 협업\", \"동시편집\", \"위키 편집\", \"STOMP\", \"웹소켓\" 요청도 여기서 시작한다. 단, 같은 \"위키 락\" 이라도 락의 획득·해제·TTL·takeover 같은 **정책과 원자 로직**은 Middle-Proxy 소유이므로 middleproxy-expert 다. 여기는 그 락을 STOMP 로 방송하고 편집 활동을 감지하는 쪽이다 — \"브라우저를 닫았는데 락이 안 풀린다\" · \"락 상태가 화면에 안 뜬다\" 는 여기서 시작한다. javax.* · WebSecurityConfigurerAdapter · JPA · WebFlux(Mono\u002FFlux)로 작성하지 않는다 — 이 저장소는 Boot 3 \u002F Java 21 \u002F MVC + STOMP 이고 영속은 Redis 뿐이다.","313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace","313DEVGRP","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F34762848?v=4","01M7F2M535Z5X8XGHYD8TDVAB3","A-RMS by 313DEVGRP","01M7F2M54CR0P3631F4YM0D014",0,"MIT","https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fbroker-expert\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: broker-expert\ndescription: >-\n  A-RMS 실시간 협업 브로커 저장소(Java-Service-Tree-Framework-Broker-Hub)의 작업 규약.\n  Spring Boot 3.5.6 · Java 21 · Spring Cloud 2025.0.1 기반이며 Backend-Core(Boot 2.6 · Java 11 · JPA) ·\n  Middle-Proxy(Boot 2.6 · WebFlux)와 스택도 규칙도 전혀 다르다.\n  STOMP\u002FSockJS 웹소켓 채널 · OT(Operational Transformation) 동시편집 엔진 ·\n  Redis 문서 상태\u002F히스토리\u002F참가자 레지스트리 · 위키 편집락 방송(Middle-Proxy 위임) ·\n  세션 생명주기(join · leave · disconnect) · 채팅 · 코드실행 프록시를 건드릴 때 반드시 먼저 읽을 것.\n  WebSocketConfig · enableSimpleBroker · registerStompEndpoints · withSockJS · @MessageMapping ·\n  SimpMessagingTemplate · \u002Fapp\u002Fjoin · \u002Fapp\u002Foperation · \u002Fapp\u002Fselection · \u002Fapp\u002Flock\u002Facquire ·\n  \u002Ftopic\u002Fsessions\u002F{sessionId}\u002Fstate\u002Fdocument\u002F{documentId} · OtService · OtUtils · TextOperation ·\n  retain\u002Finsert\u002Fdelete · revision · updateContentAndHistoryScript · doc:{sessionId}:content ·\n  session:users · user:active_docs · SessionRegistryService · WebSocketEventListener ·\n  SessionDisconnectEvent · WikiLockClient · LockState · LockCommand · SlackNotificationService ·\n  동시편집이 깨짐 · 참가자 목록이 안 지워짐 · 락이 안 풀림 · 웹소켓 404 같은 주제도 대상이다.\n  \"브로커 허브\", \"broker hub\", \"브로커허브\", \"실시간 협업\", \"동시편집\", \"위키 편집\", \"STOMP\", \"웹소켓\" 요청도 여기서 시작한다.\n  단, 같은 \"위키 락\" 이라도 락의 획득·해제·TTL·takeover 같은 **정책과 원자 로직**은 Middle-Proxy 소유이므로\n  middleproxy-expert 다. 여기는 그 락을 STOMP 로 방송하고 편집 활동을 감지하는 쪽이다 —\n  \"브라우저를 닫았는데 락이 안 풀린다\" · \"락 상태가 화면에 안 뜬다\" 는 여기서 시작한다.\n  javax.* · WebSecurityConfigurerAdapter · JPA · WebFlux(Mono\u002FFlux)로 작성하지 않는다 —\n  이 저장소는 Boot 3 \u002F Java 21 \u002F MVC + STOMP 이고 영속은 Redis 뿐이다.\n---\n\n# A-RMS Broker-Hub 작업 규약\n\n대상 저장소: `Java-Service-Tree-Framework-Broker-Hub\u002F`\n(워크스페이스 루트 `C:\\DEV\\Project\\Java-Service-Tree-Framework` 하위, 중첩 git 저장소 · 브랜치 `dev`)\n\n이 저장소는 **A-RMS 위키 문서의 실시간 동시편집을 담당하는 STOMP 브로커**다.\n전체가 Java 약 3,900줄 · 47개 파일로 작고, **문서도 테스트도 없다.** 코드가 유일한 정본이다.\n\n작은 대신 계약이 촘촘하다 — 목적지 문자열 하나, Redis 키 하나, 리비전 숫자 하나가 어긋나면\n**예외 없이 조용히 틀어진다.** 아래 계약을 먼저 파악하는 것이 이 저장소에서 가장 비용이 싼 길이다.\n\n---\n\n## 0. 30초 요약 — 반드시 먼저 각인할 것\n\n| 항목 | 값 |\n|------|----|\n| 스택 | Spring Boot **3.5.6** · Spring Cloud **2025.0.1** · **Java 21**(toolchain) · Gradle 8.13 |\n| 네임스페이스 | **`jakarta.*`** (워크스페이스에서 Engine-Fire 와 이 저장소만 Boot 3) |\n| 웹 모델 | Spring **MVC** + **STOMP over SockJS** (`spring-boot-starter-websocket`) |\n| 메시지 브로커 | **`enableSimpleBroker(\"\u002Ftopic\")`** — 인메모리. 외부 브로커 릴레이 없음 |\n| 영속 | **Redis 전용**(Lettuce). RDB · JPA · MyBatis 없음 |\n| 인증 | **없음.** Spring Security 의존성 자체가 없다 — 게이트웨이 뒤 내부 전용 |\n| 애플리케이션명 | `javaServiceTreeFrameworkBrokerHub` |\n| 포트 | **31113** (Global-Config `arms.broker-hub.url` 기준 추정 — `server.port` 는 Config 서버가 주입) |\n| 설정 | 저장소 yml 은 뼈대뿐. 대부분 **Spring Cloud Config(Global-Config)가 주입** |\n| 배포 | Docker(`313.co.kr:5550\u002F313devgrp\u002Fopenjdk:21-jdk`) + Nexus + Spinnaker |\n| 테스트 | **없음** (`src\u002Ftest` 디렉토리 자체가 없다) |\n\n> ⚠️ 루트 `README.md` 는 \"Java 17\" 이라 적혀 있으나 **틀렸다.** `build.gradle` 의 toolchain 은 21,\n> Dockerfile 베이스도 `openjdk:21-jdk` 다. 버전 사실은 언제나 `build.gradle` 이 정본이다.\n\n### 이 저장소에서 쓰면 안 되는 것\n\n```\n✗ javax.annotation \u002F javax.servlet         → ✓ jakarta.*\n✗ WebSecurityConfigurerAdapter \u002F 보안 설정  → ✓ 없음. 인증은 게이트웨이(Middle-Proxy) 책임\n✗ @Transactional \u002F JPA Entity              → ✓ RedisTemplate \u002F StringRedisTemplate\n✗ Mono \u002F Flux                              → ✓ 값 직접 반환 (이 저장소는 MVC다)\n✗ 편집락 로직 직접 구현                     → ✓ WikiLockClient 로 Middle-Proxy 위임 (§5)\n✗ 인스턴스 로컬 상태에 의존하는 신규 코드    → ✓ Redis (현재 코드가 이미 위반 중 — §7)\n```\n\n---\n\n## 1. 이 서비스가 전체 흐름에서 어디에 있는가\n\n```\n브라우저(위키 편집 화면)\n  │  arms\u002Fjs\u002Fadms\u002Fsession-manager.js   ← 클라이언트 정본\n  │\n  ├─ SockJS  \u002Fauth-user\u002Fws ────────────┐\n  └─ AJAX    \u002Fauth-user\u002Fhub\u002Fapi\u002F... ───┤\n                                       ▼\n                        Middle-Proxy :13131 (게이트웨이 · Keycloak 인증)\n                                       │  라우트는 Global-Config 주입 yml 에 정의\n                                       ▼\n                        ┌──────── Broker-Hub :31113 ────────┐\n                        │  \u002Fws        STOMP 엔드포인트       │\n                        │  \u002Fapi\u002F**    REST                   │\n                        │                                    │\n                        │  OT 엔진 · 참가자 레지스트리        │\n                        └──────┬──────────────────┬──────────┘\n                               │                  │\n                       Redis(문서·참가자)   Feign → Middle-Proxy \u002Fwiki\u002Flock\u002F**\n                                                  (편집락의 실제 소유자)\n```\n\n**핵심 비대칭 두 가지를 먼저 이해할 것.**\n\n1. **문서 내용·참가자는 Broker-Hub 가 직접 Redis 에 쓴다.**\n2. **편집락은 Broker-Hub 가 소유하지 않는다.** Middle-Proxy 가 Redis Lua 로 소유하고,\n   Broker-Hub 는 그 결과를 STOMP 로 **방송만** 한다. 락을 고치라는 요청이 오면\n   대부분 실제 수정 지점은 이 저장소가 아니다(§5).\n\n---\n\n## 2. STOMP 채널 계약 — 이 저장소의 공개 API\n\n`WebSocketConfig`:\n- 애플리케이션 목적지 접두 `\u002Fapp`\n- 브로커 목적지 접두 `\u002Ftopic` (SimpleBroker, 인메모리)\n- 엔드포인트 `\u002Fws` + `setAllowedOriginPatterns(\"*\")` + `withSockJS()`\n\n> ⚠️ 엔드포인트에 `\u002Fauth-user` 접두를 붙이면 **404 가 난다**(커밋 95a7b62 에서 되돌린 이력).\n> 접두는 게이트웨이가 붙였다 떼는 것이다. 이 저장소는 `\u002Fws` 그대로 유지한다.\n\n### 2.1 클라이언트 → 서버 (`@MessageMapping`)\n\n| 목적지 | 핸들러 | 페이로드 | 하는 일 |\n|--------|--------|----------|---------|\n| `\u002Fapp\u002Fjoin` | `EditorController` | `JoinPayload` | 참가자 등록 → 전체 상태 + 락 스냅샷 방송 |\n| `\u002Fapp\u002Fleave` | `EditorController` | `JoinPayload` | 참가자 제거 → 전체 상태 방송 |\n| `\u002Fapp\u002Fselection` | `EditorController` | `CursorMessage` | 커서\u002F선택 저장 + 방송 + **락 활동 갱신** |\n| `\u002Fapp\u002Foperation` | `OtController` | `IncomingOperationPayload` | OT 변환·적용·방송 + 발신자 ACK |\n| `\u002Fapp\u002Fget-document-state` | `OtController` | `Map{documentId, sessionId}` | 현재 내용·리비전·참가자 회신 |\n| `\u002Fapp\u002Fchat` | `ChatController` | `ChatMessage` | 세션 채팅 방송 |\n| `\u002Fapp\u002Fmessage` | `WebSocketController` | `WebSocketMessage` | Redis `messages` 리스트 적재 + `\u002Ftopic\u002Fmessages` |\n| `\u002Fapp\u002Flock\u002Facquire` | `LockController` | `LockCommand` | 락 획득 위임 → 상태 방송 |\n| `\u002Fapp\u002Flock\u002Frelease` | `LockController` | `LockCommand` | 락 해제 위임 → 상태 방송 |\n| `\u002Fapp\u002Flock\u002Fheartbeat` | `LockController` | `LockCommand` | TTL 연장 → 상태 방송 |\n| `\u002Fapp\u002Flock\u002Fforce-release` | `LockController` | `LockCommand` | 유휴 점유 강제 회수 → 상태 방송 |\n\n### 2.2 서버 → 클라이언트 (토픽)\n\n```\n\u002Ftopic\u002Fsessions\u002F{sessionId}\u002Fstate\u002Fdocument\u002F{documentId}        DocumentState (내용·리비전·참가자)\n\u002Ftopic\u002Fsessions\u002F{sessionId}\u002Foperations\u002Fdocument\u002F{documentId}   변환된 op 브로드캐스트\n\u002Ftopic\u002Fsessions\u002F{sessionId}\u002Fselections\u002Fdocument\u002F{documentId}   CursorMessage 원문 그대로\n\u002Ftopic\u002Fsessions\u002F{sessionId}\u002Flock\u002Fdocument\u002F{documentId}         LockState\n\u002Ftopic\u002Fsessions\u002F{sessionId}\u002Fchat                               ChatMessage\n\u002Ftopic\u002Fack\u002F{clientId}                                          \"ack\" 문자열 (op 수신 확인)\n\u002Ftopic\u002Fmessages                                                WebSocketMessage (범용, 사실상 미사용)\n```\n\n> **토픽 문자열은 세 곳에 흩어져 있다** — `EditorController` · `OtController` ·\n> `WebSocketEventListener` 의 `String.format`. 락만 `WikiLockService.lockDestination()` 으로\n> 상수화돼 있다. 채널을 바꾸면 **전부** 고치고 프론트 `session-manager.js` 도 함께 고친다.\n\n### 2.3 REST\n\n| 메서드 | 경로 | 컨트롤러 | 비고 |\n|--------|------|----------|------|\n| POST | `\u002Fapi\u002Fsessions\u002Fcreate` | `SessionController` | `sessionId = UUID.nameUUIDFromBytes(creatorName)` — **결정적** |\n| GET | `\u002Fapi\u002Fsessions\u002F{sessionId}` | `SessionController` | **static 인메모리 맵** 조회 |\n| POST | `\u002Fapi\u002Fsessions\u002F{sessionId}\u002Fset-document` | `SessionController` | 초기 내용 주입 + 히스토리 삭제(리비전 0) |\n| POST | `\u002Fapi\u002Fexecute` | `CodeExecutionController` | 외부 Piston API(`emkc.org`) 프록시 |\n| GET | `\u002Fapi\u002Fhealth\u002Fredis` | `RedisHealthCheckController` | Redis 왕복 확인 |\n\n> 프론트는 `creatorName` 에 **documentId 를 넣어서** 호출한다(`session-manager.js`).\n> 즉 같은 문서는 항상 같은 sessionId 로 결정된다. 세션 생성 API 지만 실제로는 **문서 키 해시**다.\n\n상세: `references\u002Fstomp-contract.md`\n\n---\n\n## 3. OT 엔진 — 이 저장소의 심장\n\n`ot.js` 를 Java 로 포팅한 것이다. `TextOperation` 은 op 를 **한 리스트에 3종으로 섞어** 표현한다.\n\n```\n양수 Integer  → retain(n)     n글자 건너뛰기\nString        → insert(str)   삽입\n음수 Integer  → delete(-n)    n글자 삭제\n```\n\n`baseLength`(적용 전 문서 길이) \u002F `targetLength`(적용 후 길이)가 불변식이다.\n`OtUtils.transform(a, b)` 는 **두 op 의 baseLength 가 같을 것**을 요구하고 `[a', b']` 를 돌려준다.\n\n### 3.1 리비전 모델 — 반드시 이해할 것\n\n```\n서버 리비전 = Redis 히스토리 리스트의 길이 (LLEN)\n```\n\n`\u002Fapp\u002Foperation` 처리 순서(`OtService.receiveOperation`):\n\n```\n1. serviceLock.lock()                          ← 인스턴스 로컬 ReentrantLock\n2. currentContent = GET  doc:{sid}:content:{did}\n   serverRevision = LLEN doc:{sid}:history:{did}\n3. clientRevision 검증  (0 \u003C= clientRevision \u003C= serverRevision)\n4. clientRevision \u003C serverRevision 이면\n       LRANGE history clientRevision .. serverRevision-1  → 동시 op 들\n       각각에 대해 transform → transformedOp 갱신\n5. newContent = OtUtils.apply(currentContent, transformedOp)\n6. Lua 스크립트 원자 실행:  SET content, RPUSH history, LTRIM(최대 500)\n7. 변환된 op 를 토픽 방송 + 발신자에게 \u002Ftopic\u002Fack\u002F{clientId}\n```\n\n### 3.2 반드시 알아야 할 결함\n\n> ⚠️ **히스토리 500 트림이 리비전 모델을 깨뜨린다.**\n> `MAX_HISTORY_SIZE_PER_DOC = 500` 이고 Lua 가 `LTRIM` 으로 앞을 잘라낸다.\n> 그런데 리비전은 `LLEN` 이므로 **히스토리가 500 에 도달한 뒤로는 서버 리비전이 500 에서 멈춘다.**\n> 동시에 `LRANGE clientRevision .. serverRevision-1` 의 인덱스는 트림으로 **의미가 어긋난다**\n> (인덱스 0 이 더 이상 리비전 0 이 아니다). 결과: 장시간 편집한 문서에서 잘못된 op 로 변환되어\n> **사용자마다 내용이 갈라진다.** 예외는 나지 않는다.\n>\n> 증상(\"오래 편집하면 화면이 틀어진다\")이 보고되면 먼저 여기를 의심한다.\n> 고칠 때는 리비전을 별도 카운터(`INCR`)로 분리하고 히스토리 인덱스를 오프셋 보정해야 한다 —\n> LTRIM 만 끄는 것은 메모리 증가로 이어지므로 설계 판단이 필요하다. 사용자에게 보고할 것.\n\n상세: `references\u002Fot-engine.md`\n\n---\n\n## 4. Redis 키 지도\n\n| 키 | 타입 | TTL | 쓰는 곳 | 용도 |\n|----|------|-----|---------|------|\n| `doc:{sessionId}:content:{documentId}` | String | 없음 | `OtService` | 문서 현재 내용 |\n| `doc:{sessionId}:history:{documentId}` | List | 없음 | `OtService` | op JSON 히스토리(최대 500) |\n| `session:users:{sessionId}:{documentId}` | Hash | **60분** | `SessionRegistryService` | `userId → UserInfoDTO` |\n| `user:active_docs:{userId}` | Set | **24시간** | `EditorController` · `WebSocketEventListener` | `\"{sessionId}:{documentId}\"` 목록 |\n| `messages` | List | 없음 | `WebSocketController` | 범용 메시지(사실상 미사용) |\n| `health-check` | String | 없음 | `RedisHealthCheckController` | 헬스체크 흔적 |\n\n- `doc:{...}` 키가 **`{sessionId}` 를 해시태그로** 감싼 이유: Redis Cluster 에서 content 와 history 가\n  같은 슬롯에 놓여야 Lua 멀티키 스크립트가 돈다. 키 포맷을 바꿀 때 이 제약을 깨지 말 것.\n- **문서 내용에는 TTL 이 없다.** 세션이 끝나도 Redis 에 남는다. 정리 주체는 현재 없다.\n- 직렬화: `RedisTemplate\u003CString,Object>` 는 key\u002FhashKey `StringRedisSerializer`,\n  value\u002FhashValue `GenericJackson2JsonRedisSerializer`. `StringRedisTemplate` 은 순수 문자열.\n  **두 템플릿이 같은 키를 건드리면 깨진다** — 현재는 용도가 분리돼 있으니 그 경계를 유지할 것.\n\n상세: `references\u002Fredis-and-state.md`\n\n---\n\n## 5. 편집락 — 소유자는 Middle-Proxy 다\n\n이 저장소의 `WikiLockService` 는 **이름과 달리 락을 구현하지 않는다.** Feign 어댑터 + 실패 폴백이다.\n\n```\nLockController (@MessageMapping \u002Fapp\u002Flock\u002F**)\n    → com.arms.api.wiki.service.WikiLockService      ← 얇은 위임 계층\n        → WikiLockClient (Feign, ${arms.middle-proxy.url})\n            → Middle-Proxy  POST \u002Fwiki\u002Flock\u002F{acquire,release,renew,touch,force-release}\n                            GET  \u002Fwiki\u002Flock\u002Fsnapshot\n                → Redis (Lua, 원자적)   ← 락의 진짜 주인\n```\n\n정책 상수는 **Middle-Proxy `WikiLockService`** 에 있다: TTL **120초**, 유휴 **60초** 후 takeover 허용.\n이 값을 바꾸라는 요청은 이 저장소가 아니라 Middle-Proxy 변경이다.\n\n### 5.1 이 저장소가 실제로 책임지는 것\n\n- **방송**: 모든 락 명령 결과를 `\u002Ftopic\u002Fsessions\u002F{sid}\u002Flock\u002Fdocument\u002F{did}` 로 내보낸다.\n  거부(`DENIED`)도 같은 토픽으로 나가고 클라이언트가 `requesterId` 로 자기 것만 소비한다.\n- **활동 연장**: `\u002Fapp\u002Fselection` 수신 시 `touchActivity` 호출 — **실제 타이핑만이 문서를 예약한다.**\n  하트비트만으로는 유휴 takeover 창이 리셋되지 않는다(의도된 설계).\n- **join 시 스냅샷**: 문서를 여는 모든 사람(편집자·관람자)이 별도 채널 없이 현재 점유자를 알게 된다.\n- **연결 종료 시 회수**: `WebSocketEventListener` 가 `REASON_DISCONNECT` 로 release + 방송.\n- **폴백**: Feign 이 실패하면 예외를 밖으로 던지지 않고 `IDLE` 상태를 반환한다.\n  ⚠️ 즉 **Middle-Proxy 가 죽으면 UI 상 \"아무도 안 잡고 있음\"으로 보인다.** 조용한 실패다.\n\n### 5.2 상태 상수 불일치 (주의)\n\nBroker-Hub `LockState` 에는 `STATE_LOCKED` · `EVENT_ACQUIRED` 상수가 **없다**(Middle-Proxy 에만 있음).\n대신 Broker-Hub 에만 `EVENT_HEARTBEAT` · `REASON_DONE\u002FDISCONNECT\u002FFORCED` 가 있다.\n필드는 동일하므로 JSON 역직렬화는 성공하지만, **두 DTO 는 별개 클래스이고 상수 집합이 다르다.**\n문자열 리터럴을 새로 만들지 말고 반드시 양쪽을 대조한 뒤 상수를 추가한다.\n\n상세: `references\u002Flock-delegation.md`\n\n---\n\n## 6. 세션 생명주기 — 참가자가 사라지는 경로\n\n```\n정상 이탈:   \u002Fapp\u002Fleave        → userLeftDocument + 추적셋에서 제거 + 상태 방송\n비정상 종료: SessionDisconnectEvent → user:active_docs:{userId} 를 읽어 모든 문서에서 제거\n                                     + 각 문서 락 release + 상태\u002F락 방송 + 추적셋 삭제\n방치:        session:users:{...} 키 TTL 60분 만료\n```\n\n> ⚠️ **disconnect 정리 경로는 `Principal` 에 전적으로 의존한다.**\n> `WebSocketEventListener` 는 `SimpMessageHeaderAccessor.getUser(headers)` 가 null 이면\n> 경고 로그만 남기고 **아무것도 정리하지 않는다.**\n> 그런데 이 저장소에는 Spring Security 도, `Principal` 을 채워 넣는 `HandshakeHandler` 나\n> `ChannelInterceptor` 도 **없다.** 따라서 현재 구성에서 이 경로는 사실상 죽은 코드이고,\n> 정리는 오직 `\u002Fapp\u002Fleave` 와 TTL 만료에만 의존한다.\n> \"브라우저를 강제로 닫으면 참가자 목록에 계속 남는다 \u002F 락이 안 풀린다\" 는 증상의 원인이 이것이다.\n> 고치려면 Principal 을 주입하는 설계가 필요하다(게이트웨이가 전달하는 사용자 식별자를\n> 핸드셰이크\u002FCONNECT 헤더에서 읽어 `DefaultHandshakeHandler` 또는 인터셉터로 바인딩).\n> **추측으로 고치지 말고 사용자에게 설계 판단을 확인할 것.**\n\n상세: `references\u002Fredis-and-state.md` §생명주기\n\n---\n\n## 7. 단일 인스턴스 전제 — 수평 확장 금지\n\n이 서비스는 **2대 이상 띄우면 동작이 깨진다.** 세 가지 이유가 겹쳐 있다.\n\n| 지점 | 문제 |\n|------|------|\n| `enableSimpleBroker(\"\u002Ftopic\")` | 인메모리 브로커. A 인스턴스의 방송이 B 의 구독자에게 안 간다 |\n| `OtService.serviceLock`(`ReentrantLock`) | 인스턴스 로컬. 두 인스턴스가 동시에 같은 문서를 변환 → 내용 파손 |\n| `SessionController.activeSessions` | `static ConcurrentHashMap`. 재시작·다른 인스턴스에서 세션 조회 404 |\n\nRedis 키 설계(해시태그)와 Lua 원자 갱신은 클러스터를 염두에 둔 흔적이지만, **위 3가지가 남아 있는 한\n단일 인스턴스가 전제**다. 확장이 필요하면 외부 브로커 릴레이(RabbitMQ\u002FActiveMQ STOMP) +\n분산 락 + 세션 저장소 외부화가 함께 필요하다 — 코드 몇 줄 수정이 아니라 설계 변경임을 보고한다.\n\n---\n\n## 8. 설정 — 대부분 이 저장소에 없다\n\n로컬 yml 에 있는 것은 사실상 이것뿐이다.\n\n| 프로파일 | 내용 |\n|----------|------|\n| `application.yml` | `spring.application.name` 한 줄 |\n| `application-dev.yml` | Config 서버(`www.313.co.kr:33133`), Redis `www.313.co.kr:36379`, actuator, `mat.*` |\n| `application-stg\u002Flive.yml` | Config 서버(`global-config:33133`), actuator, `mat.*` |\n\nConfig 서버가 주입해야 하는 것: **`server.port`**, **live\u002Fstg 의 Redis 접속**,\n**`arms.middle-proxy.url`**(Feign 대상), `slack.*`.\n\n> ⚠️ **`RedisConfig` 는 Boot 3 에서 제거된 구키를 직접 읽는다.**\n>\n> ```java\n> @Value(\"${spring.redis.host}\")            \u002F\u002F Boot 3 표준은 spring.data.redis.host\n> @Value(\"${spring.redis.port}\")\n> @Value(\"${spring.redis.ssl.enabled:false}\")\n> ```\n>\n> 기본값이 없는 host\u002Fport 가 주입되지 않으면 **컨텍스트 생성 단계에서 기동 실패**한다.\n> `application-dev.yml` 이 `spring.data.redis` 와 `spring.redis` 를 **둘 다** 적어 놓은 이유가 이것이다.\n> 한쪽만 지우면 뜨지 않는다. 또한 dev yml 은 `spring.redis.ssl.enable` 이라 적혀 있는데\n> 코드는 `...ssl.enabled` 를 읽는다 — **키 이름이 어긋난 죽은 설정**이다(기본값 false 라 조용히 넘어간다).\n\n`spring.config.import` 가 `optional:` 이므로 Config 서버가 없어도 부팅은 시도하지만,\n위 값들이 비면 그 다음 단계에서 실패한다.\n\n상세: `references\u002Fbuild-and-ops.md`\n\n---\n\n## 9. 실행해서 확인하기\n\n```bash\n# 컴파일만 (가장 빠른 검증)\ngradlew.bat compileJava          # Bash: .\u002Fgradlew compileJava\n```\n\n- **`build` 전체를 그냥 돌리지 말 것.** `build.gradle` 의 `ext` 블록이 Nexus 에서\n  `metadata.xml` 을 `wget` 으로 받아 버전을 산정한다. Windows·Mac 은 스킵하고 동봉 파일을 쓰지만,\n  Linux 는 네트워크가 필요하다. 버전은 `majorVersion=26` \u002F `minorVersion=9` + metadata 기준 자동 patch.\n- 로컬 구동: Active Profile **`dev`**. Redis 는 `www.313.co.kr:36379` 를 본다.\n- 확인: `GET \u002Fapi\u002Fhealth\u002Fredis` → `\"Redis connection is OK\"`,\n  Actuator `\u002Factuator\u002F{health,env,beans,refresh}`.\n- **테스트가 하나도 없다.** `OtUtils` · `TextOperation` 은 순수 함수이므로\n  스프링 없는 JUnit 5 단위 테스트가 가장 값싼 검증이다(`useJUnitPlatform()` 은 이미 설정돼 있다).\n\n---\n\n## 10. 제출 전 자가 점검\n\n- [ ] `jakarta.*` 를 썼는가? (`javax.*` 는 이 저장소에서 컴파일 안 된다)\n- [ ] 컨트롤러가 값을 직접 반환하는가? (`Mono`\u002F`Flux` 는 Middle-Proxy 규칙이다)\n- [ ] STOMP 목적지를 바꿨다면 서버 3곳(`EditorController`·`OtController`·`WebSocketEventListener`)과\n      프론트 `session-manager.js` 를 모두 반영했는가?\n- [ ] 락 관련 변경이면 실제 수정 지점이 Middle-Proxy 인지 먼저 판별했는가?\n- [ ] Redis 키를 추가했다면 TTL·정리 주체·클러스터 해시태그를 정했는가?\n- [ ] `RedisTemplate`(JSON)과 `StringRedisTemplate`(문자열)이 같은 키를 건드리지 않는가?\n- [ ] 인스턴스 로컬 상태(static 필드 · 인스턴스 락)를 새로 늘리지 않았는가?\n- [ ] 새 설정 키가 필요하면 Global-Config 변경 필요를 보고했는가?\n- [ ] 예외를 삼키는 자리(락 폴백 · Redis 실패)에서 **조용한 실패**를 만들지 않았는가? 로그는 남겼는가?\n- [ ] 로깅 방식을 그 파일의 기존 것(SLF4J 또는 JUL)에 맞췄는가?\n- [ ] 시크릿(Sonar 자격증명 · `SLACK_TOKEN`)을 코드·로그·문서에 복제하지 않았는가?\n\n---\n\n## 11. 산출 및 인계\n\n- 사용자 대상 설명은 **한국어**로 한다.\n- **commit·push 하지 않는다.** 작업 요약과 커밋 메시지 초안만 제시하고 커밋은 사용자가 한다.\n  이 저장소의 실제 컨벤션(YouTrack 연동):\n\n  ```\n  feat : [ARMS-1195] #comment✅문서 저장시 락 해제 안되는 문제 2026.09.10 #close #time 1h +review SR @sevoon0909\n  feat: [ARMS-223] #comment 위키 편집락 기능 추가 2026.08.22 #close #time 1h +review SR @sevoon0909\n  ```\n\n  현재 작업 브랜치는 `dev` 다(`main` 아님).\n- 확신이 없는 지점(Config 서버가 주입하는 실제 값, 게이트웨이 라우트 정의, 프론트 동작)은\n  추측으로 메우지 말고 **가정을 명시**하거나 질문한다.\n\n---\n\n## 12. 참조 파일 지도\n\n| 파일 | 언제 읽나 |\n|------|----------|\n| `references\u002Fpitfalls.md` | 이상 동작이 보일 때 \u002F 착수 전 함정 확인 (**먼저 읽으면 시간을 가장 많이 아낀다**) |\n| `references\u002Fstomp-contract.md` | 채널·페이로드·토픽을 추가\u002F변경할 때. DTO 필드 전수 목록 |\n| `references\u002Fot-engine.md` | 동시편집이 깨질 때. transform\u002Fapply\u002Fcompose 규칙과 리비전 모델 |\n| `references\u002Fredis-and-state.md` | Redis 키·직렬화·참가자 레지스트리·세션 생명주기를 다룰 때 |\n| `references\u002Flock-delegation.md` | 편집락 관련 작업 전부. Middle-Proxy 와의 계약 대조표 |\n| `references\u002Fbuild-and-ops.md` | 빌드·버전·Docker·설정 주입·로깅·모니터링·Slack |\n\n이 저장소에는 자체 문서가 없다. 연관 저장소가 보조 정본이다 —\nMiddle-Proxy `docs\u002Fai\u002F06_domain_playbooks\u002Fwiki-lock.md`(락 소유자 관점),\n프론트 `Java-Service-Tree-Framework-Frontend-Web\u002Farms\u002Fjs\u002Fadms\u002Fsession-manager.js` ·\n`arms\u002Fjs\u002Fadms.js`(클라이언트 정본).\n","# A-RMS Broker-Hub 작업 규약\n\n대상 저장소: `Java-Service-Tree-Framework-Broker-Hub\u002F`\n(워크스페이스 루트 `C:\\DEV\\Project\\Java-Service-Tree-Framework` 하위, 중첩 git 저장소 · 브랜치 `dev`)\n\n이 저장소는 **A-RMS 위키 문서의 실시간 동시편집을 담당하는 STOMP 브로커**다.\n전체가 Java 약 3,900줄 · 47개 파일로 작고, **문서도 테스트도 없다.** 코드가 유일한 정본이다.\n\n작은 대신 계약이 촘촘하다 — 목적지 문자열 하나, Redis 키 하나, 리비전 숫자 하나가 어긋나면\n**예외 없이 조용히 틀어진다.** 아래 계약을 먼저 파악하는 것이 이 저장소에서 가장 비용이 싼 길이다.\n\n---\n\n## 0. 30초 요약 — 반드시 먼저 각인할 것\n\n| 항목 | 값 |\n|------|----|\n| 스택 | Spring Boot **3.5.6** · Spring Cloud **2025.0.1** · **Java 21**(toolchain) · Gradle 8.13 |\n| 네임스페이스 | **`jakarta.*`** (워크스페이스에서 Engine-Fire 와 이 저장소만 Boot 3) |\n| 웹 모델 | Spring **MVC** + **STOMP over SockJS** (`spring-boot-starter-websocket`) |\n| 메시지 브로커 | **`enableSimpleBroker(\"\u002Ftopic\")`** — 인메모리. 외부 브로커 릴레이 없음 |\n| 영속 | **Redis 전용**(Lettuce). RDB · JPA · MyBatis 없음 |\n| 인증 | **없음.** Spring Security 의존성 자체가 없다 — 게이트웨이 뒤 내부 전용 |\n| 애플리케이션명 | `javaServiceTreeFrameworkBrokerHub` |\n| 포트 | **31113** (Global-Config `arms.broker-hub.url` 기준 추정 — `server.port` 는 Config 서버가 주입) |\n| 설정 | 저장소 yml 은 뼈대뿐. 대부분 **Spring Cloud Config(Global-Config)가 주입** |\n| 배포 | Docker(`313.co.kr:5550\u002F313devgrp\u002Fopenjdk:21-jdk`) + Nexus + Spinnaker |\n| 테스트 | **없음** (`src\u002Ftest` 디렉토리 자체가 없다) |\n\n> ⚠️ 루트 `README.md` 는 \"Java 17\" 이라 적혀 있으나 **틀렸다.** `build.gradle` 의 toolchain 은 21,\n> Dockerfile 베이스도 `openjdk:21-jdk` 다. 버전 사실은 언제나 `build.gradle` 이 정본이다.\n\n### 이 저장소에서 쓰면 안 되는 것\n\n```\n✗ javax.annotation \u002F javax.servlet         → ✓ jakarta.*\n✗ WebSecurityConfigurerAdapter \u002F 보안 설정  → ✓ 없음. 인증은 게이트웨이(Middle-Proxy) 책임\n✗ @Transactional \u002F JPA Entity              → ✓ RedisTemplate \u002F StringRedisTemplate\n✗ Mono \u002F Flux                              → ✓ 값 직접 반환 (이 저장소는 MVC다)\n✗ 편집락 로직 직접 구현                     → ✓ WikiLockClient 로 Middle-Proxy 위임 (§5)\n✗ 인스턴스 로컬 상태에 의존하는 신규 코드    → ✓ Redis (현재 코드가 이미 위반 중 — §7)\n```\n\n---\n\n## 1. 이 서비스가 전체 흐름에서 어디에 있는가\n\n```\n브라우저(위키 편집 화면)\n  │  arms\u002Fjs\u002Fadms\u002Fsession-manager.js   ← 클라이언트 정본\n  │\n  ├─ SockJS  \u002Fauth-user\u002Fws ────────────┐\n  └─ AJAX    \u002Fauth-user\u002Fhub\u002Fapi\u002F... ───┤\n                                       ▼\n                        Middle-Proxy :13131 (게이트웨이 · Keycloak 인증)\n                                       │  라우트는 Global-Config 주입 yml 에 정의\n                                       ▼\n                        ┌──────── Broker-Hub :31113 ────────┐\n                        │  \u002Fws        STOMP 엔드포인트       │\n                        │  \u002Fapi\u002F**    REST                   │\n                        │                                    │\n                        │  OT 엔진 · 참가자 레지스트리        │\n                        └──────┬──────────────────┬──────────┘\n                               │                  │\n                       Redis(문서·참가자)   Feign → Middle-Proxy \u002Fwiki\u002Flock\u002F**\n                                                  (편집락의 실제 소유자)\n```\n\n**핵심 비대칭 두 가지를 먼저 이해할 것.**\n\n1. **문서 내용·참가자는 Broker-Hub 가 직접 Redis 에 쓴다.**\n2. **편집락은 Broker-Hub 가 소유하지 않는다.** Middle-Proxy 가 Redis Lua 로 소유하고,\n   Broker-Hub 는 그 결과를 STOMP 로 **방송만** 한다. 락을 고치라는 요청이 오면\n   대부분 실제 수정 지점은 이 저장소가 아니다(§5).\n\n---\n\n## 2. STOMP 채널 계약 — 이 저장소의 공개 API\n\n`WebSocketConfig`:\n- 애플리케이션 목적지 접두 `\u002Fapp`\n- 브로커 목적지 접두 `\u002Ftopic` (SimpleBroker, 인메모리)\n- 엔드포인트 `\u002Fws` + `setAllowedOriginPatterns(\"*\")` + `withSockJS()`\n\n> ⚠️ 엔드포인트에 `\u002Fauth-user` 접두를 붙이면 **404 가 난다**(커밋 95a7b62 에서 되돌린 이력).\n> 접두는 게이트웨이가 붙였다 떼는 것이다. 이 저장소는 `\u002Fws` 그대로 유지한다.\n\n### 2.1 클라이언트 → 서버 (`@MessageMapping`)\n\n| 목적지 | 핸들러 | 페이로드 | 하는 일 |\n|--------|--------|----------|---------|\n| `\u002Fapp\u002Fjoin` | `EditorController` | `JoinPayload` | 참가자 등록 → 전체 상태 + 락 스냅샷 방송 |\n| `\u002Fapp\u002Fleave` | `EditorController` | `JoinPayload` | 참가자 제거 → 전체 상태 방송 |\n| `\u002Fapp\u002Fselection` | `EditorController` | `CursorMessage` | 커서\u002F선택 저장 + 방송 + **락 활동 갱신** |\n| `\u002Fapp\u002Foperation` | `OtController` | `IncomingOperationPayload` | OT 변환·적용·방송 + 발신자 ACK |\n| `\u002Fapp\u002Fget-document-state` | `OtController` | `Map{documentId, sessionId}` | 현재 내용·리비전·참가자 회신 |\n| `\u002Fapp\u002Fchat` | `ChatController` | `ChatMessage` | 세션 채팅 방송 |\n| `\u002Fapp\u002Fmessage` | `WebSocketController` | `WebSocketMessage` | Redis `messages` 리스트 적재 + `\u002Ftopic\u002Fmessages` |\n| `\u002Fapp\u002Flock\u002Facquire` | `LockController` | `LockCommand` | 락 획득 위임 → 상태 방송 |\n| `\u002Fapp\u002Flock\u002Frelease` | `LockController` | `LockCommand` | 락 해제 위임 → 상태 방송 |\n| `\u002Fapp\u002Flock\u002Fheartbeat` | `LockController` | `LockCommand` | TTL 연장 → 상태 방송 |\n| `\u002Fapp\u002Flock\u002Fforce-release` | `LockController` | `LockCommand` | 유휴 점유 강제 회수 → 상태 방송 |\n\n### 2.2 서버 → 클라이언트 (토픽)\n\n```\n\u002Ftopic\u002Fsessions\u002F{sessionId}\u002Fstate\u002Fdocument\u002F{documentId}        DocumentState (내용·리비전·참가자)\n\u002Ftopic\u002Fsessions\u002F{sessionId}\u002Foperations\u002Fdocument\u002F{documentId}   변환된 op 브로드캐스트\n\u002Ftopic\u002Fsessions\u002F{sessionId}\u002Fselections\u002Fdocument\u002F{documentId}   CursorMessage 원문 그대로\n\u002Ftopic\u002Fsessions\u002F{sessionId}\u002Flock\u002Fdocument\u002F{documentId}         LockState\n\u002Ftopic\u002Fsessions\u002F{sessionId}\u002Fchat                               ChatMessage\n\u002Ftopic\u002Fack\u002F{clientId}                                          \"ack\" 문자열 (op 수신 확인)\n\u002Ftopic\u002Fmessages                                                WebSocketMessage (범용, 사실상 미사용)\n```\n\n> **토픽 문자열은 세 곳에 흩어져 있다** — `EditorController` · `OtController` ·\n> `WebSocketEventListener` 의 `String.format`. 락만 `WikiLockService.lockDestination()` 으로\n> 상수화돼 있다. 채널을 바꾸면 **전부** 고치고 프론트 `session-manager.js` 도 함께 고친다.\n\n### 2.3 REST\n\n| 메서드 | 경로 | 컨트롤러 | 비고 |\n|--------|------|----------|------|\n| POST | `\u002Fapi\u002Fsessions\u002Fcreate` | `SessionController` | `sessionId = UUID.nameUUIDFromBytes(creatorName)` — **결정적** |\n| GET | `\u002Fapi\u002Fsessions\u002F{sessionId}` | `SessionController` | **static 인메모리 맵** 조회 |\n| POST | `\u002Fapi\u002Fsessions\u002F{sessionId}\u002Fset-document` | `SessionController` | 초기 내용 주입 + 히스토리 삭제(리비전 0) |\n| POST | `\u002Fapi\u002Fexecute` | `CodeExecutionController` | 외부 Piston API(`emkc.org`) 프록시 |\n| GET | `\u002Fapi\u002Fhealth\u002Fredis` | `RedisHealthCheckController` | Redis 왕복 확인 |\n\n> 프론트는 `creatorName` 에 **documentId 를 넣어서** 호출한다(`session-manager.js`).\n> 즉 같은 문서는 항상 같은 sessionId 로 결정된다. 세션 생성 API 지만 실제로는 **문서 키 해시**다.\n\n상세: `references\u002Fstomp-contract.md`\n\n---\n\n## 3. OT 엔진 — 이 저장소의 심장\n\n`ot.js` 를 Java 로 포팅한 것이다. `TextOperation` 은 op 를 **한 리스트에 3종으로 섞어** 표현한다.\n\n```\n양수 Integer  → retain(n)     n글자 건너뛰기\nString        → insert(str)   삽입\n음수 Integer  → delete(-n)    n글자 삭제\n```\n\n`baseLength`(적용 전 문서 길이) \u002F `targetLength`(적용 후 길이)가 불변식이다.\n`OtUtils.transform(a, b)` 는 **두 op 의 baseLength 가 같을 것**을 요구하고 `[a', b']` 를 돌려준다.\n\n### 3.1 리비전 모델 — 반드시 이해할 것\n\n```\n서버 리비전 = Redis 히스토리 리스트의 길이 (LLEN)\n```\n\n`\u002Fapp\u002Foperation` 처리 순서(`OtService.receiveOperation`):\n\n```\n1. serviceLock.lock()                          ← 인스턴스 로컬 ReentrantLock\n2. currentContent = GET  doc:{sid}:content:{did}\n   serverRevision = LLEN doc:{sid}:history:{did}\n3. clientRevision 검증  (0 \u003C= clientRevision \u003C= serverRevision)\n4. clientRevision \u003C serverRevision 이면\n       LRANGE history clientRevision .. serverRevision-1  → 동시 op 들\n       각각에 대해 transform → transformedOp 갱신\n5. newContent = OtUtils.apply(currentContent, transformedOp)\n6. Lua 스크립트 원자 실행:  SET content, RPUSH history, LTRIM(최대 500)\n7. 변환된 op 를 토픽 방송 + 발신자에게 \u002Ftopic\u002Fack\u002F{clientId}\n```\n\n### 3.2 반드시 알아야 할 결함\n\n> ⚠️ **히스토리 500 트림이 리비전 모델을 깨뜨린다.**\n> `MAX_HISTORY_SIZE_PER_DOC = 500` 이고 Lua 가 `LTRIM` 으로 앞을 잘라낸다.\n> 그런데 리비전은 `LLEN` 이므로 **히스토리가 500 에 도달한 뒤로는 서버 리비전이 500 에서 멈춘다.**\n> 동시에 `LRANGE clientRevision .. serverRevision-1` 의 인덱스는 트림으로 **의미가 어긋난다**\n> (인덱스 0 이 더 이상 리비전 0 이 아니다). 결과: 장시간 편집한 문서에서 잘못된 op 로 변환되어\n> **사용자마다 내용이 갈라진다.** 예외는 나지 않는다.\n>\n> 증상(\"오래 편집하면 화면이 틀어진다\")이 보고되면 먼저 여기를 의심한다.\n> 고칠 때는 리비전을 별도 카운터(`INCR`)로 분리하고 히스토리 인덱스를 오프셋 보정해야 한다 —\n> LTRIM 만 끄는 것은 메모리 증가로 이어지므로 설계 판단이 필요하다. 사용자에게 보고할 것.\n\n상세: `references\u002Fot-engine.md`\n\n---\n\n## 4. Redis 키 지도\n\n| 키 | 타입 | TTL | 쓰는 곳 | 용도 |\n|----|------|-----|---------|------|\n| `doc:{sessionId}:content:{documentId}` | String | 없음 | `OtService` | 문서 현재 내용 |\n| `doc:{sessionId}:history:{documentId}` | List | 없음 | `OtService` | op JSON 히스토리(최대 500) |\n| `session:users:{sessionId}:{documentId}` | Hash | **60분** | `SessionRegistryService` | `userId → UserInfoDTO` |\n| `user:active_docs:{userId}` | Set | **24시간** | `EditorController` · `WebSocketEventListener` | `\"{sessionId}:{documentId}\"` 목록 |\n| `messages` | List | 없음 | `WebSocketController` | 범용 메시지(사실상 미사용) |\n| `health-check` | String | 없음 | `RedisHealthCheckController` | 헬스체크 흔적 |\n\n- `doc:{...}` 키가 **`{sessionId}` 를 해시태그로** 감싼 이유: Redis Cluster 에서 content 와 history 가\n  같은 슬롯에 놓여야 Lua 멀티키 스크립트가 돈다. 키 포맷을 바꿀 때 이 제약을 깨지 말 것.\n- **문서 내용에는 TTL 이 없다.** 세션이 끝나도 Redis 에 남는다. 정리 주체는 현재 없다.\n- 직렬화: `RedisTemplate\u003CString,Object>` 는 key\u002FhashKey `StringRedisSerializer`,\n  value\u002FhashValue `GenericJackson2JsonRedisSerializer`. `StringRedisTemplate` 은 순수 문자열.\n  **두 템플릿이 같은 키를 건드리면 깨진다** — 현재는 용도가 분리돼 있으니 그 경계를 유지할 것.\n\n상세: `references\u002Fredis-and-state.md`\n\n---\n\n## 5. 편집락 — 소유자는 Middle-Proxy 다\n\n이 저장소의 `WikiLockService` 는 **이름과 달리 락을 구현하지 않는다.** Feign 어댑터 + 실패 폴백이다.\n\n```\nLockController (@MessageMapping \u002Fapp\u002Flock\u002F**)\n    → com.arms.api.wiki.service.WikiLockService      ← 얇은 위임 계층\n        → WikiLockClient (Feign, ${arms.middle-proxy.url})\n            → Middle-Proxy  POST \u002Fwiki\u002Flock\u002F{acquire,release,renew,touch,force-release}\n                            GET  \u002Fwiki\u002Flock\u002Fsnapshot\n                → Redis (Lua, 원자적)   ← 락의 진짜 주인\n```\n\n정책 상수는 **Middle-Proxy `WikiLockService`** 에 있다: TTL **120초**, 유휴 **60초** 후 takeover 허용.\n이 값을 바꾸라는 요청은 이 저장소가 아니라 Middle-Proxy 변경이다.\n\n### 5.1 이 저장소가 실제로 책임지는 것\n\n- **방송**: 모든 락 명령 결과를 `\u002Ftopic\u002Fsessions\u002F{sid}\u002Flock\u002Fdocument\u002F{did}` 로 내보낸다.\n  거부(`DENIED`)도 같은 토픽으로 나가고 클라이언트가 `requesterId` 로 자기 것만 소비한다.\n- **활동 연장**: `\u002Fapp\u002Fselection` 수신 시 `touchActivity` 호출 — **실제 타이핑만이 문서를 예약한다.**\n  하트비트만으로는 유휴 takeover 창이 리셋되지 않는다(의도된 설계).\n- **join 시 스냅샷**: 문서를 여는 모든 사람(편집자·관람자)이 별도 채널 없이 현재 점유자를 알게 된다.\n- **연결 종료 시 회수**: `WebSocketEventListener` 가 `REASON_DISCONNECT` 로 release + 방송.\n- **폴백**: Feign 이 실패하면 예외를 밖으로 던지지 않고 `IDLE` 상태를 반환한다.\n  ⚠️ 즉 **Middle-Proxy 가 죽으면 UI 상 \"아무도 안 잡고 있음\"으로 보인다.** 조용한 실패다.\n\n### 5.2 상태 상수 불일치 (주의)\n\nBroker-Hub `LockState` 에는 `STATE_LOCKED` · `EVENT_ACQUIRED` 상수가 **없다**(Middle-Proxy 에만 있음).\n대신 Broker-Hub 에만 `EVENT_HEARTBEAT` · `REASON_DONE\u002FDISCONNECT\u002FFORCED` 가 있다.\n필드는 동일하므로 JSON 역직렬화는 성공하지만, **두 DTO 는 별개 클래스이고 상수 집합이 다르다.**\n문자열 리터럴을 새로 만들지 말고 반드시 양쪽을 대조한 뒤 상수를 추가한다.\n\n상세: `references\u002Flock-delegation.md`\n\n---\n\n## 6. 세션 생명주기 — 참가자가 사라지는 경로\n\n```\n정상 이탈:   \u002Fapp\u002Fleave        → userLeftDocument + 추적셋에서 제거 + 상태 방송\n비정상 종료: SessionDisconnectEvent → user:active_docs:{userId} 를 읽어 모든 문서에서 제거\n                                     + 각 문서 락 release + 상태\u002F락 방송 + 추적셋 삭제\n방치:        session:users:{...} 키 TTL 60분 만료\n```\n\n> ⚠️ **disconnect 정리 경로는 `Principal` 에 전적으로 의존한다.**\n> `WebSocketEventListener` 는 `SimpMessageHeaderAccessor.getUser(headers)` 가 null 이면\n> 경고 로그만 남기고 **아무것도 정리하지 않는다.**\n> 그런데 이 저장소에는 Spring Security 도, `Principal` 을 채워 넣는 `HandshakeHandler` 나\n> `ChannelInterceptor` 도 **없다.** 따라서 현재 구성에서 이 경로는 사실상 죽은 코드이고,\n> 정리는 오직 `\u002Fapp\u002Fleave` 와 TTL 만료에만 의존한다.\n> \"브라우저를 강제로 닫으면 참가자 목록에 계속 남는다 \u002F 락이 안 풀린다\" 는 증상의 원인이 이것이다.\n> 고치려면 Principal 을 주입하는 설계가 필요하다(게이트웨이가 전달하는 사용자 식별자를\n> 핸드셰이크\u002FCONNECT 헤더에서 읽어 `DefaultHandshakeHandler` 또는 인터셉터로 바인딩).\n> **추측으로 고치지 말고 사용자에게 설계 판단을 확인할 것.**\n\n상세: `references\u002Fredis-and-state.md` §생명주기\n\n---\n\n## 7. 단일 인스턴스 전제 — 수평 확장 금지\n\n이 서비스는 **2대 이상 띄우면 동작이 깨진다.** 세 가지 이유가 겹쳐 있다.\n\n| 지점 | 문제 |\n|------|------|\n| `enableSimpleBroker(\"\u002Ftopic\")` | 인메모리 브로커. A 인스턴스의 방송이 B 의 구독자에게 안 간다 |\n| `OtService.serviceLock`(`ReentrantLock`) | 인스턴스 로컬. 두 인스턴스가 동시에 같은 문서를 변환 → 내용 파손 |\n| `SessionController.activeSessions` | `static ConcurrentHashMap`. 재시작·다른 인스턴스에서 세션 조회 404 |\n\nRedis 키 설계(해시태그)와 Lua 원자 갱신은 클러스터를 염두에 둔 흔적이지만, **위 3가지가 남아 있는 한\n단일 인스턴스가 전제**다. 확장이 필요하면 외부 브로커 릴레이(RabbitMQ\u002FActiveMQ STOMP) +\n분산 락 + 세션 저장소 외부화가 함께 필요하다 — 코드 몇 줄 수정이 아니라 설계 변경임을 보고한다.\n\n---\n\n## 8. 설정 — 대부분 이 저장소에 없다\n\n로컬 yml 에 있는 것은 사실상 이것뿐이다.\n\n| 프로파일 | 내용 |\n|----------|------|\n| `application.yml` | `spring.application.name` 한 줄 |\n| `application-dev.yml` | Config 서버(`www.313.co.kr:33133`), Redis `www.313.co.kr:36379`, actuator, `mat.*` |\n| `application-stg\u002Flive.yml` | Config 서버(`global-config:33133`), actuator, `mat.*` |\n\nConfig 서버가 주입해야 하는 것: **`server.port`**, **live\u002Fstg 의 Redis 접속**,\n**`arms.middle-proxy.url`**(Feign 대상), `slack.*`.\n\n> ⚠️ **`RedisConfig` 는 Boot 3 에서 제거된 구키를 직접 읽는다.**\n>\n> ```java\n> @Value(\"${spring.redis.host}\")            \u002F\u002F Boot 3 표준은 spring.data.redis.host\n> @Value(\"${spring.redis.port}\")\n> @Value(\"${spring.redis.ssl.enabled:false}\")\n> ```\n>\n> 기본값이 없는 host\u002Fport 가 주입되지 않으면 **컨텍스트 생성 단계에서 기동 실패**한다.\n> `application-dev.yml` 이 `spring.data.redis` 와 `spring.redis` 를 **둘 다** 적어 놓은 이유가 이것이다.\n> 한쪽만 지우면 뜨지 않는다. 또한 dev yml 은 `spring.redis.ssl.enable` 이라 적혀 있는데\n> 코드는 `...ssl.enabled` 를 읽는다 — **키 이름이 어긋난 죽은 설정**이다(기본값 false 라 조용히 넘어간다).\n\n`spring.config.import` 가 `optional:` 이므로 Config 서버가 없어도 부팅은 시도하지만,\n위 값들이 비면 그 다음 단계에서 실패한다.\n\n상세: `references\u002Fbuild-and-ops.md`\n\n---\n\n## 9. 실행해서 확인하기\n\n```bash\n# 컴파일만 (가장 빠른 검증)\ngradlew.bat compileJava          # Bash: .\u002Fgradlew compileJava\n```\n\n- **`build` 전체를 그냥 돌리지 말 것.** `build.gradle` 의 `ext` 블록이 Nexus 에서\n  `metadata.xml` 을 `wget` 으로 받아 버전을 산정한다. Windows·Mac 은 스킵하고 동봉 파일을 쓰지만,\n  Linux 는 네트워크가 필요하다. 버전은 `majorVersion=26` \u002F `minorVersion=9` + metadata 기준 자동 patch.\n- 로컬 구동: Active Profile **`dev`**. Redis 는 `www.313.co.kr:36379` 를 본다.\n- 확인: `GET \u002Fapi\u002Fhealth\u002Fredis` → `\"Redis connection is OK\"`,\n  Actuator `\u002Factuator\u002F{health,env,beans,refresh}`.\n- **테스트가 하나도 없다.** `OtUtils` · `TextOperation` 은 순수 함수이므로\n  스프링 없는 JUnit 5 단위 테스트가 가장 값싼 검증이다(`useJUnitPlatform()` 은 이미 설정돼 있다).\n\n---\n\n## 10. 제출 전 자가 점검\n\n- [ ] `jakarta.*` 를 썼는가? (`javax.*` 는 이 저장소에서 컴파일 안 된다)\n- [ ] 컨트롤러가 값을 직접 반환하는가? (`Mono`\u002F`Flux` 는 Middle-Proxy 규칙이다)\n- [ ] STOMP 목적지를 바꿨다면 서버 3곳(`EditorController`·`OtController`·`WebSocketEventListener`)과\n      프론트 `session-manager.js` 를 모두 반영했는가?\n- [ ] 락 관련 변경이면 실제 수정 지점이 Middle-Proxy 인지 먼저 판별했는가?\n- [ ] Redis 키를 추가했다면 TTL·정리 주체·클러스터 해시태그를 정했는가?\n- [ ] `RedisTemplate`(JSON)과 `StringRedisTemplate`(문자열)이 같은 키를 건드리지 않는가?\n- [ ] 인스턴스 로컬 상태(static 필드 · 인스턴스 락)를 새로 늘리지 않았는가?\n- [ ] 새 설정 키가 필요하면 Global-Config 변경 필요를 보고했는가?\n- [ ] 예외를 삼키는 자리(락 폴백 · Redis 실패)에서 **조용한 실패**를 만들지 않았는가? 로그는 남겼는가?\n- [ ] 로깅 방식을 그 파일의 기존 것(SLF4J 또는 JUL)에 맞췄는가?\n- [ ] 시크릿(Sonar 자격증명 · `SLACK_TOKEN`)을 코드·로그·문서에 복제하지 않았는가?\n\n---\n\n## 11. 산출 및 인계\n\n- 사용자 대상 설명은 **한국어**로 한다.\n- **commit·push 하지 않는다.** 작업 요약과 커밋 메시지 초안만 제시하고 커밋은 사용자가 한다.\n  이 저장소의 실제 컨벤션(YouTrack 연동):\n\n  ```\n  feat : [ARMS-1195] #comment✅문서 저장시 락 해제 안되는 문제 2026.09.10 #close #time 1h +review SR @sevoon0909\n  feat: [ARMS-223] #comment 위키 편집락 기능 추가 2026.08.22 #close #time 1h +review SR @sevoon0909\n  ```\n\n  현재 작업 브랜치는 `dev` 다(`main` 아님).\n- 확신이 없는 지점(Config 서버가 주입하는 실제 값, 게이트웨이 라우트 정의, 프론트 동작)은\n  추측으로 메우지 말고 **가정을 명시**하거나 질문한다.\n\n---\n\n## 12. 참조 파일 지도\n\n| 파일 | 언제 읽나 |\n|------|----------|\n| `references\u002Fpitfalls.md` | 이상 동작이 보일 때 \u002F 착수 전 함정 확인 (**먼저 읽으면 시간을 가장 많이 아낀다**) |\n| `references\u002Fstomp-contract.md` | 채널·페이로드·토픽을 추가\u002F변경할 때. DTO 필드 전수 목록 |\n| `references\u002Fot-engine.md` | 동시편집이 깨질 때. transform\u002Fapply\u002Fcompose 규칙과 리비전 모델 |\n| `references\u002Fredis-and-state.md` | Redis 키·직렬화·참가자 레지스트리·세션 생명주기를 다룰 때 |\n| `references\u002Flock-delegation.md` | 편집락 관련 작업 전부. Middle-Proxy 와의 계약 대조표 |\n| `references\u002Fbuild-and-ops.md` | 빌드·버전·Docker·설정 주입·로깅·모니터링·Slack |\n\n이 저장소에는 자체 문서가 없다. 연관 저장소가 보조 정본이다 —\nMiddle-Proxy `docs\u002Fai\u002F06_domain_playbooks\u002Fwiki-lock.md`(락 소유자 관점),\n프론트 `Java-Service-Tree-Framework-Frontend-Web\u002Farms\u002Fjs\u002Fadms\u002Fsession-manager.js` ·\n`arms\u002Fjs\u002Fadms.js`(클라이언트 정본).\n",{"name":5,"description":7},"main","f2cc95bc769ca4c3a398965b767dfb41cdf8d698",".claude\u002Fskills\u002Fbroker-expert",2,"https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace","https:\u002F\u002Fgithub.com\u002F313DEVGRP","https:\u002F\u002Fwww.a-rms.net","2026-10-18 12:48:10",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add 313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace --skill broker-expert",{"tool":38,"command":39},"bunx","bunx skills add 313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace --skill broker-expert",{"tool":41,"command":42},"pnpm","pnpm dlx skills add 313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace --skill broker-expert","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fbroker-expert\u002FSKILL.md",true,[46,52,56,60,64,68],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Fbuild-and-ops.md","REFERENCE","参考文档",11251,"https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fbroker-expert\u002Freferences\u002Fbuild-and-ops.md",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"references\u002Flock-delegation.md",9906,"https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fbroker-expert\u002Freferences\u002Flock-delegation.md",{"path":57,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Fot-engine.md",10121,"https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fbroker-expert\u002Freferences\u002Fot-engine.md",{"path":61,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":62,"sourceHtmlUrl":63},"references\u002Fpitfalls.md",13054,"https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fbroker-expert\u002Freferences\u002Fpitfalls.md",{"path":65,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":66,"sourceHtmlUrl":67},"references\u002Fredis-and-state.md",10361,"https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fbroker-expert\u002Freferences\u002Fredis-and-state.md",{"path":69,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":70,"sourceHtmlUrl":71},"references\u002Fstomp-contract.md",11154,"https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fbroker-expert\u002Freferences\u002Fstomp-contract.md",[73,80,87,94,101,108],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M7F343WNVHZWWYJDD77QEJ7J","voice-refine","Transform verbose voice input into structured, token-efficient Claude prompts. Use when cleaning up voice memos, dictation output, or speech-to-text transcriptions that contain filler words, repetitions, and unstructured thoughts.","https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002Freference\u002Fclaude-code-ultimate-guide-main\u002Fexamples\u002Fskills\u002Fvoice-refine\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M7F3417SNXASFTDA1B2X4XYZ","validate-changes","Evaluate staged changes using LLM-as-a-Judge before committing","https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002Freference\u002Fclaude-code-ultimate-guide-main\u002Fexamples\u002Fskills\u002Fvalidate-changes\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M7F33YN9QK88H2B81PVHMNG1","update-threat-db","Delegate threat-intelligence research and updates to AgentSec, then validate the guide and landing mirrors.","https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002Freference\u002Fclaude-code-ultimate-guide-main\u002Fexamples\u002Fskills\u002Fupdate-threat-db\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":19},"01M7F33SXQ57G2FVFK094T4584","token-audit","Audit Claude Code configuration to measure fixed-context token overhead and produce a prioritized action plan. Use when hitting rate limits, experiencing early context compression, or after adding significant config files.","https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002Freference\u002Fclaude-code-ultimate-guide-main\u002Fexamples\u002Fskills\u002Ftoken-audit\u002Fskill.md",[],[],{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":19},"01M7F33NAWXFPHW59CF52EAGGK","talk-stage6-revision","Produces revision sheets with quick navigation by act, a master concept-to-URL table, Q&A cheat-sheet with 6-10 anticipated questions, glossary, and external resources list. Use when preparing for a talk with Q&A, creating shareable reference material for attendees, or building a safety-net glossary for live delivery.","https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002Freference\u002Fclaude-code-ultimate-guide-main\u002Fexamples\u002Fskills\u002Ftalk-pipeline\u002Fstage-6-revision\u002FSKILL.md",[],[],{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":19},"01M7F33G9V96HVZKAGZ84J4EBR","talk-stage5-script","Produces a complete 5-act pitch with speaker notes, a slide-by-slide specification, and a ready-to-paste Kimi prompt for AI slide generation. Requires validated angle and title from Stage 4. Use when you have a confirmed talk angle and need the full script, slide spec, and AI-generated presentation prompt.","https:\u002F\u002Fgithub.com\u002F313DEVGRP\u002FJava-Service-Tree-Framework-Multi-Agent-Workspace\u002Fblob\u002Fmain\u002Freference\u002Fclaude-code-ultimate-guide-main\u002Fexamples\u002Fskills\u002Ftalk-pipeline\u002Fstage-5-script\u002FSKILL.md",[],[]]