tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: synchronize MESSAGING.md, IMPROVEMENTS.md, implementation_plan.md and add D-31/D-32 freshness guards

Browse Source
This commit is contained in:
Godopu
2026-08-23 16:22:10 +09:00
parent 916185c751
commit adecff2194
8 changed files with 806 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
implementation_plan.md
+18 -13
View File
@@ -1,26 +1,26 @@
# 🚀 MAM 메시징 백플레인 전환 실행 로드맵 (`implementation_plan.md`)
- **문서 버전**: v1.0.0 (`8c651798` / `28bb7340`)
- **문서 버전**: v1.2.0
- **작성/관리 주체**: Multi-Agent Orchestration Team (`claude`, `agy`, `cline`)
- **기준 커밋**: `a9934ad` (276/276 baseline tests passing)
- **문서 목적**: MAM의 메시징 인프라를 공개 HiveMQ 브로커에서 `nats-server` 전용 사설 브로커로 무중단 전환하기 위한 4개 트랙(Track 0~3)과 5단계 마일스톤(M0~M4)의 구체적 실행 지침 및 진행 상황 추적.
- **기준 커밋**: `916185c` (306/306 baseline tests passing)
- **문서 목적**: MAM의 메시징 인프라를 공개 HiveMQ 브로커에서 `nats-server` 전용 사설 브로커로 무중단 전환하기 위한 5개 트랙(Track 0~3, Track 1R)과 6단계 마일스톤(M0~M4, M2b)의 구체적 실행 지침 및 진행 상황 추적.
- **연계 문서**: [`NATS_REPORT.md`](nats-docker/NATS_REPORT.md), [`PRIVATE_SERVER.md`](nats-docker/PRIVATE_SERVER.md), [`IMPROVEMENTS.md`](IMPROVEMENTS.md)
---
## 1. 개요 및 4개 트랙 구조
## 1. 개요 및 5개 트랙 구조
```
[M0: 문서 정합성] ──> [M1: 내결함성 확보] ──> [M2: 브로커 실증] ──> [M3: 보안 종결] ──> [M4: 동기화 완료]
(E-1~E-4 교정, (Track 0: B-14,B-15, (Track 1: O-5 (Track 2: A-2, (Track 3: 문서,
G-D1~G-D4 가드) G-1~G-10 가드) S-1~S-9 스파이크) 지문 토픽, G-11) 배포 스크립트)
[M0: 문서 정합성] ──> [M1: 내결함성 확보] ──> [M2a: 로컬스파이크 / M2b: 원격배포] ──> [M3: 보안 종결] ──> [M4: 동기화 완료]
(E-1~E-4 교정, (Track 0: B-14,B-15, (Track 1: O-5 스파이크 / (Track 2: A-2, (Track 3: 문서,
G-D1~G-D4 가드) G-1~G-10 가드) Track 1R: 원격 자산·서브모듈) 지문 토픽, G-11) 배포 스크립트)
```
| 트랙 | 대상 과제 | 핵심 목표 | 코드 변경 지점 |
|---|---|---|---|
| **Track 0** | `B-14`, `B-15` (P1) | 브로커 다운 시 65분 정지(Hang) 및 오판정 방지 (로컬 디스크 내결함성) | `publish_event.py`, `job_subscriber.py`, `multi-agent-mux-delegate-job` |
| **Track 1** | `O-5` (P2) | `nats-server` MQTT 3.1.1 어댑터 호환성 및 Retained 메시지 실측 검증 | 격리 클론 (`$SCRATCH/nats-spike`) |
| **Track 1R** | 원격 프로덕션 (P1) | VPS/홈랩 `nats-server` Docker 상시 가동 및 MAM 원격 백플레인 전환 | `PRIVATE_SERVER.md` §9, 서버측 `docker-compose.yml`/`nats.conf`, `.mam.env` |
| **Track 1R** | 원격 프로덕션 (P1) | VPS/홈랩 `nats-server` Docker 상시 가동, 서브모듈 분리 및 MAM 원격 백플레인 전환 | `nats-docker/PRIVATE_SERVER.md` §9, `nats-docker/docker/docker-compose.yaml`, `nats.conf`, `.mam.env` |
| **Track 2** | `A-2`, `B-16` (P2) | 워크스페이스 지문 토픽 격리 및 `auth_token` 무조건 발급 강제 | `mqtt_common.py`, `registry.py`, `reconcile.sh` |
| **Track 3** | 문서/설정 동기화 | 공식 가이드, 배포 스크립트, 환경변수 템플릿 일원화 | `MESSAGING.md`, `IMPROVEMENTS.md`, `VERSIONS.md`, `deploy/*` |
@@ -39,7 +39,7 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2a (로컬 스
| **M0** | 문서 정합성 확보 | `PRIVATE_SERVER.md` E-1~E-4 교정, 다능성 절 추가, 본 로드맵 작성 | **G-D1 ~ G-D4 가드 테스트 통과** (276 -> 280) |
| **M1** | 내결함성 확보 (Track 0) | `B-14`, `B-15` 코드 패치 완료 | **G-1 ~ G-10 가드 통과 + mutation 전건 FAIL 확인** (280 -> 290) |
| **M2a** | 로컬 스파이크 (Track 1) | 격리 클론에서 S-1 ~ S-9 스파이크 완수 | **S-3(Retained Terminal Event) 통과** (실패 시 mosquitto로 분기) |
| **M2b** | 원격 프로덕션 전환 (Track 1R) | D-1~D-5 교정 + §9 원격 배포 + §9.5 전환 | **R-3(노출0) · R-5(retained) · R-6(신원) · R-9(계정격리) 동시 통과** |
| **M2b** | 원격 프로덕션 전환 (Track 1R) | D-1~D-5 교정 + §9 원격 배포 + 서브모듈 분리 + §9.5 전환 | **R-3(노출0) · R-5(retained) · R-6(신원) · R-9(계정격리) 동시 통과** (290 -> 297 -> 306) |
| **M3** | 보안 종결 (Track 2) | A-2 지문 토픽 전환, G-11 무조건 토큰 발급 | 지문 토픽 동작 확인 **후** legacy 구독 제거 |
| **M4** | 동기화 완료 (Track 3) | `MESSAGING.md`, `IMPROVEMENTS.md`, `VERSIONS.md`, `deploy/*` 정합 | 전체 테스트 스위트 100% Green |
@@ -111,6 +111,8 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2a (로컬 스
▼
[P0.5 자산화] docker/ 4대 자산 정본화 + D-22~D-30 회귀 가드 (297 -> 306)
▼
[P0.6 서브모듈] nats-docker 서브모듈 분리 + 동적 경로 해석기 + CI checkout 동기화
▼
[P1 서버 준비] VPS/홈랩 프로비저닝, Docker, Tailscale 가입
▼
[P2 배포] nats.conf + compose 기동, healthcheck healthy 확인
@@ -141,8 +143,8 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2a (로컬 스
| 대상 파일 | 갱신 내용 |
|---|---|
| [`MESSAGING.md`](MESSAGING.md) | 브로커 표준을 `nats-server`로 갱신, F-1/C1 해소 기록, F-5 영속 세션 서술 정정 |
| [`IMPROVEMENTS.md`](IMPROVEMENTS.md) | A-2 완료 전환, B-14/B-15/B-16/O-5 해결 상태 갱신, B-17/B-18 신설 등록 |
| [`MESSAGING.md`](MESSAGING.md) | 브로커 표준을 `nats-server`로 갱신, F-1/C1 해소 기록, F-5 영속 세션 서술 정정, 10개 환경변수 및 해석 계층 문서화 |
| [`IMPROVEMENTS.md`](IMPROVEMENTS.md) | B-14/B-15 완료 상태 반영, O-6 신설, B-17/B-18 신설 등록 |
| [`VERSIONS.md`](VERSIONS.md) | `v2.0.0` 릴리스 노트에 메시징 백플레인 고도화 및 내결함성 패치 기록 |
| [`PRIVATE_SERVER.md`](nats-docker/PRIVATE_SERVER.md) | 스파이크 결과 반영 및 최종 가이드 확정 |
| [`deploy/install.sh`](deploy/install.sh) | `requirements.txt` 확인 (paho 유지) 및 개인 브로커 안내 추가 |
@@ -169,7 +171,7 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2a (로컬 스
- [ ] S-3 Retained 메시지 게이트 통과 확인
### M2b: Track 1R 원격 프로덕션 전환
- [x] D-1 `store_dir` 절대경로 교정 + 비인용 heredoc (`PRIVATE_SERVER.md:73`, `:146`)
- [x] D-1 `store_dir` 절대경로 교정 + 비인용 heredoc (`PRIVATE_SERVER.md` §4.1, §9.1)
- [x] D-2 이미지 핀 `nats:2.12-alpine` + `/healthz` healthcheck
- [x] D-3 8222/8080 바인드 주소 한정
- [x] D-4 TLS 절의 IP 예시 제거 및 DNS/SAN 요건 명시
@@ -177,8 +179,11 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2a (로컬 스
- [x] N-1 §5.2 에 retained=MQTT 전용 경계 명문화 + §9.1 `mam_observer` 추가
- [x] 신규 가드 G-D5 ~ G-D9, G-R1, G-R2 구현 및 검증 (290 -> 297)
- [x] P0.5: `docker/` 프로덕션 배포 자산 정본화 및 D-22 ~ D-30 회귀 가드 (297 -> 306)
- [x] P0.6: `docker/` 자산의 `nats-docker` 서브모듈 분리 및 `PRIVATE_SERVER.md`/`NATS_REPORT.md` 이전 (`629a67f`, `12ba30b`, `916185c`)
- [x] P0.6: 테스트 동적 경로 해석기(`_resolve_private_server_doc` / `_resolve_docker_dir`) 도입
- [x] P0.6: CI checkout 에 `submodules: recursive` 적용 (`deploy/gitea-ci.yml`)
- [ ] 서버 배포 및 R-3 노출 면적 0 단언
- [ ] §9.5 드레인·잔여 스캔 후 `.mam.env` 전환
- [x] §9.5 사설 브로커(`vm-ubuntu`)로 `.mam.env` 전환 완료 (사후 잔여 드레인 스캔 과제 기록)
- [ ] R-1 ~ R-13 전건 통과 (R-5 / R-9 / R-13 최종 관문)
### M3: Track 2 보안 및 토픽 격리 (`A-2`, `B-16`)