PLAN

Aegis-Pi Wiki 개편 및 유지보수 계획

상태: 통합 프로젝트 기준 개편 계획 기준일: 2026-06-14

1. 목적

이 문서는 이 저장소의 코드베이스를 기준으로 Wiki를 유지하기 위한 실행 계획이다. PLAN.md는 Wiki 작성·검증 규칙과 페이지 구조를 관리하고, roadmap.md는 제품·기술 진행 계획을 관리한다.

2. Source of Truth

문서 사이 설명이 충돌하면 아래 순서로 판단한다.

우선순위	기준	용도
1	이 저장소 코드와 Terraform	실제 구현 여부 판단
2	docs/ops/	운영·배포·검증 기록
3	docs/specs/	데이터/API 계약
4	docs/changes/	ADR와 결정 이력
5	docs/planning/	설계 배경과 확장 계획
6	docs/issues/SESSION_STATE.md, docs/issues/MASTER_CHECKLIST.md	현재 진행 상태와 마일스톤 추적
7	기존 Wiki	수정 대상

docs/에 원본 저장소 기준 섹션이 함께 남은 문서는 통합 초안이다. Wiki 본문에는 그 표기를 그대로 옮기지 않고, 통합된 현재 상태로 재작성한다.

3. 상태 표현 원칙

상태	의미
구현 완료	이 저장소에 코드와 설정이 있으며 단위 테스트 또는 정적 검증이 수행됨
배포 검증 완료	실제 AWS/K3s 배포나 수동 실행으로 동작을 확인함
통합 완료	두 원본 저장소 기능이 이 저장소에 통합됨
통합본 검증 대기	로컬 앱 검증은 완료됐고, Terraform/state 재확인 또는 실환경 smoke test가 남음
계획	코드가 없거나 후속 설계로만 존재함
retired	과거 검증했지만 현재 기본 구성에서 제거됨

계획 기능을 현재 운영 기능처럼 쓰지 않는다. 반대로 구현·배포된 기능을 과거 M4/M6 대기 상태로 유지하지 않는다.

4. 파일 구조

Sidebar는 상대 .md 링크로 통일한다. 아직 생성되지 않은 신규 페이지도 아래 파일명 그대로 생성해야 한다.

msp-team03.wiki/
├── Home.md
├── _Sidebar.md
├── PLAN.md
├── req-background.md
├── req-system-constraints.md
├── req-monitoring-expansion.md
├── srs-functional.md
├── srs-nonfunctional.md
├── srs-acceptance.md
├── project-overview.md
├── project-current-status.md
├── roadmap.md
├── tech-stack.md
├── concept-*.md
├── architecture-*.md
├── component-*.md
├── dashboard-*.md
├── security-auth-rbac.md
├── operations-*.md
├── scenario-*.md
├── adr-*.md
├── reference-*.md
└── troubleshooting-*.md

5. 신규 페이지 목록

상태: 2026-06-10 최종 검수 기준 모두 생성됨. Sidebar에도 모두 포함한다.

요구사항 문서 (2026-06-10 추가, 6개)

파일	위치	목적
req-background.md	요구조건 식별서	사업 배경, 문제 인식, 사업 목표·범위
req-system-constraints.md	요구조건 식별서	Infra·Server·Network·Container·보안·Metric 요구조건
req-monitoring-expansion.md	요구조건 식별서	모니터링·컨테이너 가이드·기술내재화·서비스확장
srs-functional.md	요구사항 정의서	FR-INF·FR-DATA·FR-DASH·FR-OBS 기능 요구사항
srs-nonfunctional.md	요구사항 정의서	NFR-SEC·NFR-AVL·NFR-CON 비기능 요구사항
srs-acceptance.md	요구사항 정의서	인수 기준(AC-1~5)과 산출물 목록

구현 문서 (2026-06-09 완료, 18개)

파일	위치	목적
architecture-data-read-models.md	데이터 및 실시간 처리	DynamoDB/S3 read model과 TTL
architecture-realtime-update.md	데이터 및 실시간 처리	REST, delta refresh, WebSocket 경계
architecture-reporting-pipeline.md	데이터 및 실시간 처리	Daily Report batch pipeline
component-dashboard-backend.md	Dashboard	FastAPI/ECS backend 책임
component-dashboard-web.md	Dashboard	React SPA, route, UX, export
component-graph-aggregator.md	컴포넌트	5분 그래프 집계 Lambda
component-cloud-infra-collector.md	컴포넌트	CloudInfra Fast/Slow collector
component-daily-report-generator.md	컴포넌트	reporting app 내부 로직
component-risk-alert-dispatcher.md	컴포넌트	S3 snapshot 기반 Slack alert
component-image-snapshot-pipeline.md	컴포넌트	presigned upload와 image metadata
security-auth-rbac.md	보안	Cognito 인증과 RDS RBAC
operations-data-dashboard.md	운영	Dashboard 배포·검증·장애 대응
operations-data-pipeline.md	운영	IoT/DataProcessor/collector 운영
operations-daily-report.md	운영	report 수동 실행, backfill, 비용
operations-alerting.md	운영	Slack alert 배포와 noise control
operations-image-snapshot.md	운영	snapshot uploader/presigner 운영
operations-integrated-build-destroy.md	운영	전체 build/destroy 보호 순서
operations-dummy-generator-backtest.md	운영	factory-b/c dummy generator risk coverage 검증 기록
project-current-status.md	시작하기	현재 완료·검증·잔여 작업

운영 회고/보강 문서 (2026-06-14 이후 추가, 3개)

파일	위치	목적
lessons-learned.md	참조 및 문제 해결	모범사례(Best Practices)와 실패사례(Failure Cases) 회고. 출처: docs/ops/04_troubleshooting.md, docs/ops/09_failover_failback_test_results.md, docs/ops/10_edge_workload_placement.md
operations-iot-fleet-connectivity.md	운영	persistent MQTT 전환 이후 AWS IoT Fleet Indexing connectivity 확인 기준
operations-factory-a-ai-latency.md	운영	Factory A safe-edge-integrated-ai loop와 YOLO 추론 지연시간 기준

6. 이미지 관리

대표 이미지는 ADR 0035에서 확정한 agiespi_architecture_overview_final1.drawio와 agiespi_architecture_overview_final3.drawio.png를 원본 기준으로 삼는다. Wiki에 업로드한 이미지는 같은 다이어그램에서 export한 파일이어야 하며, 임시 파일명을 새 기준으로 만들지 않는다.

이미지를 갱신할 때는 다음을 확인한다.

항목	기준
DynamoDB TTL	GRAPH#5M 48h, HISTORY#STATE 목표 2h(마지막 문서화된 운영값 48h), LATEST TTL 없음
Reporting	Step Functions와 factory/cloud-infra Lambda 구조
VPC NAT	Hub와 Data/Dashboard 모두 현재 Terraform 기준 단일 NAT
RDS	단일 RDS 인스턴스, subnet group 2AZ, multi_az=false
Factory 구조	Factory A adapter/publisher/snapshot, Factory B/C dummy generator 분리
WAF	실제 리소스가 없으면 후속/선택 구성으로 표시

이미지에는 계정 번호, secret, 전체 endpoint 같은 민감값을 넣지 않는다.

7. 갱신 규칙

1. 대상 페이지를 수정하기 전에 관련 코드, Terraform, 운영 문서를 확인한다.
2. 문서 상단 또는 본문 초반에 기준일과 현재 상태를 명확히 둔다.
   • 기준일 표기 기준: 요구사항 섹션(req-*, srs-*)은 착수 전 작성 시점의 기준일(2026-05-20 등)을 유지한다. 이는 stale가 아니라 "요구가 확정된 시점"을 뜻한다. 구현·운영·아키텍처 문서는 최신 갱신 기준일(현재 2026-06-14)을 쓴다. 따라서 문서별 기준일이 다른 것은 정상이며, 같은 종류 문서끼리만 기준일을 비교한다.
3. 구현 완료, 배포 검증 완료, 통합본 검증 대기, 계획을 섞어 쓰지 않는다.
4. Dashboard, Data Pipeline, Reporting, Alerting, Snapshot은 독립 생명주기를 가진다.
5. 운영 명령은 operations-*에 두고, 아키텍처 페이지에는 책임과 흐름을 둔다.
6. 기존 멘토링 로그는 배경으로만 남기고 현재 설명보다 앞세우지 않는다.
7. retired AMP/Prometheus Agent는 현재 active 구성으로 쓰지 않는다.

8. 검증 체크리스트

Wiki 수정 후 다음을 확인한다.

검증	방법
Sidebar 중복 링크	_Sidebar.md에서 동일 링크가 반복되는지 확인
신규 18개 포함	_Sidebar.md 또는 이 문서의 신규 페이지 표에 모두 포함
파일명 대소문자	계획서의 파일명과 정확히 일치
Home 구조 일관성	Home.md의 문서 구조와 Sidebar 섹션이 충돌하지 않음
현재 상태 모순	project-current-status.md, roadmap.md, docs/issues/SESSION_STATE.md 표현 대조
계획/구현 구분	배포 검증이 없는 항목은 검증 대기 또는 계획으로 표시
민감정보	webhook URL, token 원문, certificate/private key, endpoint/IP 노출 여부 검색
Markdown 형식	git -C msp-team03.wiki diff --check

9. 세션별 개편 순서

세션	범위
01	대표 아키텍처 이미지, Home.md, project-current-status.md
02	_Sidebar.md, PLAN.md, project-overview.md, roadmap.md
03	전체 시스템, control/data plane, hardware, Tailscale
04	데이터 생명주기, local/cloud storage, read models, S3 reference
05	Factory/Edge/IoT 계약
06	DataProcessor, risk, graph aggregation
07	Dashboard VPC, backend, realtime, data model
08	Dashboard Web, UX, RBAC
09	Cloud Infra와 Alerting
10	Reporting
11	Image Snapshot
12	운영 문서
13	시나리오와 ADR
14	기술 스택, 참조, 최종 검수