feat: implement real-time Pub/Sub alert broadcast system and update docs/GRPC.md

docs/GRPC.md

@@ -429,6 +429,127 @@ func AskDownloadFile(ctx context.Context, m protoapi.IoTServiceClient, fileName
   * **목록 조회**: 빈 메시지(`EmptyRequest`)를 동봉해 Unary RPC 채널을 트리거하고 메타데이터 배열 결과를 동기 획득합니다.
   * **파일 다운로드**: 서버 스트리밍 엔드포인트 기동 후, `stream.Recv()` 블로킹 수신 루프에 진입합니다. 채널 해제 지점(`io.EOF`)에 도달할 때까지 메모리 버퍼 슬라이스에 청크 바이트 배열을 병합 누적하여 재조립(Reassembly)을 마친 후 반환합니다.
 
+### 7.4 실시간 알림을 위한 Pub/Sub (발행/구독) 브로드캐스팅 구현
+
+스마트 가전이나 센서 등 실시간 경보 통지가 필요한 AIoT 도메인에서는, 서버가 상시 대기하는 여러 디바이스(클라이언트)들에게 비동기로 이벤트를 밀어 넣어주는 **발행/구독(Publish/Subscribe)** 연동 구조가 필수적입니다. gRPC의 **서버 스트리밍(Server Streaming)** 채널을 응용하면, 다수의 클라이언트가 스트림 통로를 상시 유지한 채 대기하고, 서버가 특정 이벤트 발생 시 채널 리스트를 순회하며 실시간 이벤트를 **브로드캐스팅(Broadcasting)**하는 Pub/Sub 인프라를 단순하고 가볍게 완성할 수 있습니다.
+
+#### 1. 스키마 설계 (`protoapi.proto`)
+구독 신청을 위한 파라미터(`AlertSubscription`)와 서버가 밀어 넣어줄 이벤트 규격(`AlertMessage`)을 IDL에 선언합니다:
+```proto
+message AlertSubscription {
+    string ClientId = 1;
+    string Topic = 2; // 구독할 주제 (예: "temperature_warnings")
+}
+
+message AlertMessage {
+    string AlertId = 1;
+    string DeviceId = 2;
+    string Message = 3; // 실시간 발생 경보 문자열
+    int64 Timestamp = 4;
+}
+```
+
+#### 2. 서버 사이드 구독자 관리 및 발행 구현 ([server.go](../lib/grpcentity/server.go))
+서버는 구독을 신청한 클라이언트들에게 메시지를 안전하게 분배하기 위해 스레드 세이프 맵과 고루틴 채널(`chan`) 구조를 구성합니다:
+
+```go
+type AlertSubscriber struct {
+	ClientId string
+	Channel  chan *protoapi.AlertMessage
+}
+
+var (
+	subscribers = make(map[string]*AlertSubscriber)
+	subMu       sync.Mutex
+)
+
+// 실시간 모든 구독 채널에 알림 이벤트 분배 (Publish/Broadcast)
+func publishAlert(alert *protoapi.AlertMessage) {
+	subMu.Lock()
+	defer subMu.Unlock()
+	for _, sub := range subscribers {
+		select {
+		case sub.Channel <- alert:
+		default:
+			// 채널 버퍼가 가득 찬 경우 병목 차단을 방지하기 위해 드롭 처리
+			fmt.Printf("Alert channel blocked for client %s, dropping event\n", sub.ClientId)
+		}
+	}
+}
+
+// 구독 채널 대기 핸들러
+func (IoTServer) SubscribeAlerts(r *protoapi.AlertSubscription, stream protoapi.IoTService_SubscribeAlertsServer) error {
+	clientId := r.GetClientId()
+	ch := make(chan *protoapi.AlertMessage, 10) // 버퍼 10의 수신 채널 생성
+	sub := &AlertSubscriber{
+		ClientId: clientId,
+		Channel:  ch,
+	}
+
+	subMu.Lock()
+	subscribers[clientId] = sub
+	subMu.Unlock()
+
+	fmt.Printf("Client %s subscribed to alerts on topic '%s'\n", clientId, r.GetTopic())
+
+	// 스트림 연결 유지 및 채널 대기 감시 루프
+	for {
+		select {
+		case alert := <-ch:
+			err := stream.Send(alert)
+			if err != nil {
+				subMu.Lock()
+				delete(subscribers, clientId)
+				subMu.Unlock()
+				return err
+			}
+		case <-stream.Context().Done():
+			subMu.Lock()
+			delete(subscribers, clientId)
+			subMu.Unlock()
+			return nil
+		}
+	}
+}
+```
+* **쉬운 설명**: 
+  * **구독 신청**: 클라이언트가 전화를 걸면 서버는 그 선을 닫지 않고 메모장(`subscribers`)에 해당 전화번호와 연결된 통로(Go 채널)를 적어둡니다. 그리고 그 선을 계속 붙잡고 대기(`stream.Send`) 상태를 유지합니다.
+  * **경보 발행**: 센서값 수신 핸들러(`UpdateSensingData`)에서 임계치(40도)를 초과하는 위험 열기가 감지되면, 메모장에 적힌 모든 연결된 통로에 경보 엽서(`AlertMessage`)를 휙 던져(Broadcast) 줍니다.
+* **상세 설명**: 
+  * **구독 신청**: `SubscribeAlerts` 엔드포인트는 호출과 동시에 전용 Go 비동기 버퍼 채널을 생성하고 전역 가입 맵에 등록합니다. `stream.Context().Done()` 채널 수신이나 스트림 유실 이벤트가 포착되기 전까지 루프 대기 상태를 안전하게 고정합니다.
+  * **경보 발행**: 동시성 경쟁 방지 락(`subMu.Lock()`) 임계 구역 내에서 연결된 모든 채널에 데이터를 `select-default` 논블로킹 패턴으로 분배 기입하여, 특정 클라이언트의 수신 병목이 서버 전체 성능에 미치는 파급 효과를 예방합니다.
+
+#### 3. 클라이언트 비동기 청취 구현 ([client.go](../lib/grpcentity/client.go))
+클라이언트는 메인 흐름을 방해하지 않고 알림을 백그라운드에서 실시간으로 대기 청취할 수 있도록 별도의 독자적인 비동기 고루틴 구조로 가동합니다.
+
+```go
+func AskSubscribeAlerts(ctx context.Context, m protoapi.IoTServiceClient, clientId string, topic string) {
+	stream, err := m.SubscribeAlerts(ctx, &protoapi.AlertSubscription{
+		ClientId: clientId,
+		Topic:    topic,
+	})
+	if err != nil {
+		fmt.Println("Failed to subscribe alerts:", err)
+		return
+	}
+
+	for {
+		alert, err := stream.Recv()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			break
+		}
+		fmt.Printf("\n🔔 [ALERT RECEIVED] ID: %s | Device: %s | Msg: %s | Time: %s\n\n",
+			alert.GetAlertId(), alert.GetDeviceId(), alert.GetMessage(),
+			time.Unix(alert.GetTimestamp(), 0).Format("15:04:05"))
+	}
+}
+```
+* **쉬운 설명**: 클라이언트는 메인 로직이 다른 볼일(파일 업로드/다운로드 등)을 보러 간 동안, 옆방에서 전화를 붙잡고 계속 귀를 기울이는 전담 직원(비동기 고루틴)을 기동시킵니다. 서버에서 "벨(알림)"이 울릴 때마다 그 내용을 즉시 가로채 화면에 실시간 경보 창을 출력해 줍니다.
+* **상세 설명**: 메인 쓰레드의 블로킹을 방지하기 위해 Go의 경량 쓰레드 고루틴(`go AskSubscribeAlerts`)으로 리스너 루프를 위임 기동합니다. gRPC 스트림 클라이언트의 `stream.Recv()` 메서드는 서버로부터 메시지가 전달될 때까지 스레드 리소스를 낭비하지 않는 대기 상태로 머물며, 데이터 수령 시 콘솔 스트림에 이를 비동기 매핑 출력합니다.
+
 ---
 
 ## 8. 한 걸음 더 나아가기 (다음 단계)