5.5 KiB
5.5 KiB
SDD: 사용자 알림 전달
위치
- Milestone: Milestone 문서
- Phase: PHASE.md
상태
[초안]
SDD 잠금
- 상태: 잠금
- 사용자 리뷰: USER_REVIEW.md
- 잠금 항목:
- [D01] 첫 외부 알림 채널을 확정한다.
문제 / 비목표
- 문제: 사용자의 조치가 필요한 상태를 능동적으로 알리되 조직 경계를 넘는 발송, 민감 정보 노출, 트랜잭션 유실과 재시도 중복을 막아야 한다.
- 비목표:
- 여러 외부 채널 동시 지원
- 당직 호출과 장애 단계별 상향 통지
- 알림을 통한 승인·거부 실행
Source of Truth
| 영역 | 기준 | 메모 |
|---|---|---|
| Roadmap | Milestone 문서 | 기능 범위와 완료 상태 |
| Code | internal/domain/, internal/integration/, internal/platform/database/ |
발송 대기열, 수신 정책과 채널 어댑터 |
| External Provider | 확인 필요 | D01에서 첫 채널과 제공자 계약 확정 |
| User Decision | D01 | 첫 외부 알림 채널 |
State Machine
| 상태 | 진입 조건 | 다음 상태 | 근거 |
|---|---|---|---|
| pending | 알림 대상 도메인 전이와 같은 트랜잭션에서 대기 사건 생성 | sending | 전달 임대 획득 |
| sending | 채널이 발송을 수락함 | delivered | 외부 식별자와 수락 시각 |
| sending | 일시 실패하고 한도가 남음 | retry_wait | 표준 실패와 다음 시도 시각 |
| retry_wait | 재시도 시각 도달 | sending | 새 전달 시도 이력 |
| sending | 영구 실패 또는 한도 소진 | failed | 누적 원인 스택 |
| pending 또는 retry_wait | 권한 상실 또는 구독 해제 | cancelled | 수신자 재검증 결과 |
Interface Contract
- 계약 원문: 없음
- 입력:
- 조직·프로젝트 범위, 사건 유형과 상관관계 ID
- 대상 도메인 식별자와 발생 시각
- 수신 사용자, 지역화 언어와 채널 주소 참조
- 출력:
- 전달 상태, 외부 식별자, 시도 횟수와 표준 실패
- 권한 검증이 적용되는 Ariadne 상세 화면 주소
- 금지:
- 오류 원문, 비밀값, 접속 정보와 전체 실행 로그 포함
- 권한을 잃었거나 구독하지 않은 사용자 발송
- 같은 사건·채널·수신자의 중복 발송
Acceptance Scenarios
| ID | Milestone Task | Given | When | Then |
|---|---|---|---|---|
| S01 | recipient-policy |
권한·구독 상태가 다른 조직 구성원이 있음 | 수신자를 계산함 | 같은 프로젝트 권한과 명시적 구독이 모두 유효한 사용자만 선택됨 |
| S02 | safe-message |
오류 원문에 비밀값과 접속 정보가 있음 | 알림을 구성함 | 최소 요약과 권한 검증 링크만 남고 민감 정보가 포함되지 않음 |
| S03 | notification-outbox |
알림 대상 상태 전이가 커밋됨 | 발송 대기 사건을 조회함 | 상태와 대기 사건이 함께 존재하며 어느 한쪽만 남지 않음 |
| S04 | channel-adapter |
D01 채널 연결이 준비됨 | 알림을 발송함 | 외부 수락 식별자와 전달 결과가 이력에 기록됨 |
| S05 | delivery-retry |
같은 사건이 중복 전달되고 일시 실패가 발생함 | 재시도함 | 한 건만 전달되고 제한된 시도와 원인 스택이 보존됨 |
| S06 | notification-smoke |
실제 채널과 테스트 사용자가 준비됨 | 권한 변경·구독 해제·중복·실패를 실행함 | 조직 격리와 전달 안전성이 현장에서 검증됨 |
Evidence Map
| Scenario | Required Evidence | agent-task 연결 |
완료 Evidence 기대 |
|---|---|---|---|
| S01 | 조직·프로젝트 권한과 구독 정책 검사 | agent-task/m-user-notification-delivery/... |
recipient-policy 완료 근거 |
| S02 | 민감 정보 제외 검사 | agent-task/m-user-notification-delivery/... |
safe-message 완료 근거 |
| S03 | 상태·발송 대기열 원자성 통합 검사 | agent-task/m-user-notification-delivery/... |
notification-outbox 완료 근거 |
| S04 | 첫 채널 전달 결과 | agent-task/m-user-notification-delivery/... |
channel-adapter 완료 근거 |
| S05 | 중복·재시도·한도 검사 | agent-task/m-user-notification-delivery/... |
delivery-retry 완료 근거 |
| S06 | 실제 알림 채널 field smoke 결과 | agent-task/m-user-notification-delivery/... |
notification-smoke 최종 검증 |
Cross-repo Dependencies
- D01에서 선택한 외부 채널의 테스트 계정과 제한된 자격 증명이 필요하다. 특정 프로젝트 Milestone 경로가 없어 workspace 잠금은 만들지 않는다.
Drift Check
- Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- Evidence Map이 code-review와
complete.log에서 검증 가능하다. - 외부 계약 원문을 SDD에 복제하지 않았다.
- 사용자 결정은 USER_REVIEW.md에 분리했다.
사용자 리뷰 이력
- [D01] 응답 대기
작업 컨텍스트
- 표준선: 권한과 명시적 구독을 발송 직전에 재검증하고, 외부 채널에는 최소 요약과 Ariadne 상세 화면 링크만 전달한다.
- 후속 SDD: 병합 요청 전달