feat(team): add real-time team chat

ARCHITECTURE.md

@@ -12,6 +12,7 @@
 - API request functions stay in `src/lib/api/*`.
 - MSW request handlers stay in `src/lib/api/mocks/handlers.ts`, with reusable team-space fixture builders in `src/lib/api/mocks/team-space-fixtures.ts`.
 - `/team` uses project group, checklist, admin permission, and GitHub App installation request functions when a user is signed in.
+- The signed-in `/team` chat tab uses `src/features/team/components/real-team-chat-panel.tsx` for UI, `src/features/team/hooks/use-chat-queries.ts` for REST history/read state, and `src/features/team/hooks/use-project-group-chat.ts` for STOMP subscribe/publish.
 - In mock API mode, signed-in `/team` calls the same request functions through MSW; signed-out `/team` keeps the richer local demo workspace as a preview.
 
 ## Current User Flow
@@ -23,6 +24,7 @@
 ## Temporary UI State
 
 - Real API mode and signed-in mock mode use `src/lib/api/*` request functions for implemented team-space server capabilities.
+- In mock API mode, chat messages are backed by MSW and appended directly into the TanStack Query cache; in real API mode, the same cache is hydrated from REST and updated from `/topic/project-groups/{projectGroupId}/chat/messages`.
 - Signed-out mock mode still keeps team name, lifecycle status, rules Markdown, GitHub repository preview, random reviewer, and team messages in local React state.
 - Move remaining mock-only team surfaces to `src/lib/api/*` when matching backend endpoints are introduced.
 

DECISIONS.md

@@ -54,6 +54,11 @@
 - Remotion dependency policy: keep `remotion`, `@remotion/cli`, and `@remotion/player` on the same exact version to avoid render/runtime mismatches.
 - Remotion styling bridge: use `@remotion/tailwind` so Vite preview and Remotion CLI renders share the same Tailwind v3 visual system.
 
+## 2026-06-12
+- Team chat transport: use `@stomp/stompjs` for the signed-in team-space chat panel because the backend exposes Spring STOMP topics for real-time project-group messages.
+- Team chat state: keep message history in TanStack Query through `src/features/team/hooks/use-chat-queries.ts`, and append live STOMP messages into the same cache so REST history and real-time delivery share one UI source of truth.
+- Mock parity: keep chat handlers in MSW for `/project-groups/:projectGroupId/chat/messages` and `/project-groups/:projectGroupId/chat/read` so the same chat panel can be browser-tested without a running backend.
+
 ## 2026-06-13
 - Remotion sound design: use `@remotion/sfx` at the same exact Remotion version for predefined motion-graphic SFX cues instead of hand-generating local audio assets.
 - PR video BGM: use a locally generated light musical WAV under `public/audio/pr-video/` with Remotion fade controls, avoiding external music licensing and network-dependent playback.

README.md

@@ -32,7 +32,7 @@ pnpm dev
 
 ## API Mode
 
-API mode is controlled from [`src/lib/api/config.ts`](/Users/hwangjo/Client/src/lib/api/config.ts).
+API mode is controlled from [`src/lib/api/config.ts`](/Users/hwangjo/team-po/Client/src/lib/api/config.ts).
 
 - `VITE_API_MODE=mock`: use MSW-based mocked API
 - `VITE_API_MODE=real`: call a real backend
@@ -47,11 +47,19 @@ VITE_API_BASE_URL=https://api.example.com
 VITE_OAUTH_BASE_URL=https://api.example.com
 ```
 
+Local backend example:
+
+```bash
+VITE_API_MODE=real VITE_API_BASE_URL=http://localhost:8080/api pnpm dev --host 127.0.0.1
+```
+
+The team-space chat panel uses the same API mode. In real mode it connects to the backend STOMP endpoint derived from `VITE_API_BASE_URL`; for `http://localhost:8080/api`, chat connects to `ws://localhost:8080/ws`.
+
 ## Vercel Deployment
 
 This project uses React Router with `BrowserRouter`, so Vercel needs an SPA rewrite for deep links such as `/login`, `/signup`, and `/me`.
 
-The required rewrite is already configured in [`vercel.json`](/Users/hwangjo/Client/vercel.json).
+The required rewrite is already configured in [`vercel.json`](/Users/hwangjo/team-po/Client/vercel.json).
 
 ### Recommended Setup
 

openapi/openapi.yaml

@@ -12,6 +12,7 @@ tags:
   - name: Match
   - name: ProjectGroups
   - name: ProjectChecklists
+  - name: Chat
   - name: TeamSpace
 paths:
   /signup/email:
@@ -666,6 +667,75 @@ paths:
           $ref: '#/components/responses/NotFound'
         '500':
           $ref: '#/components/responses/InternalServerError'
+  /project-groups/{projectGroupId}/chat/messages:
+    get:
+      tags: [Chat]
+      security:
+        - bearerAuth: []
+      summary: Get project group chat messages
+      parameters:
+        - $ref: '#/components/parameters/ProjectGroupId'
+        - in: query
+          name: beforeMessageId
+          required: false
+          schema:
+            type: integer
+            format: int64
+          description: Return messages older than this message id.
+        - in: query
+          name: size
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 50
+            default: 30
+      responses:
+        '200':
+          description: Project group chat message page
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatMessagePage'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /project-groups/{projectGroupId}/chat/read:
+    patch:
+      tags: [Chat]
+      security:
+        - bearerAuth: []
+      summary: Mark project group chat messages as read
+      parameters:
+        - $ref: '#/components/parameters/ProjectGroupId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MarkChatReadRequest'
+      responses:
+        '200':
+          description: Chat read state updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatReadState'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
   /team-space/{projectGroupId}/dev-guide:
     get:
       tags: [TeamSpace]
@@ -1566,6 +1636,84 @@ components:
           format: int64
         aiAdvice:
           $ref: '#/components/schemas/ChecklistAiAdvice'
+    ChatMessageType:
+      type: string
+      enum: [TEXT, SYSTEM]
+    ChatMessage:
+      type: object
+      additionalProperties: false
+      required:
+        - messageId
+        - projectGroupId
+        - senderUserId
+        - senderNickname
+        - senderProfileImage
+        - type
+        - content
+        - createdAt
+        - mine
+      properties:
+        messageId:
+          type: integer
+          format: int64
+        projectGroupId:
+          type: integer
+          format: int64
+        senderUserId:
+          type: integer
+          format: int64
+        senderNickname:
+          type: string
+        senderProfileImage:
+          type:
+            - string
+            - 'null'
+        type:
+          $ref: '#/components/schemas/ChatMessageType'
+        content:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+        mine:
+          type: boolean
+    ChatMessagePage:
+      type: object
+      additionalProperties: false
+      required: [messages, nextBeforeMessageId, hasNext]
+      properties:
+        messages:
+          type: array
+          items:
+            $ref: '#/components/schemas/ChatMessage'
+        nextBeforeMessageId:
+          type:
+            - integer
+            - 'null'
+          format: int64
+        hasNext:
+          type: boolean
+    MarkChatReadRequest:
+      type: object
+      additionalProperties: false
+      required: [lastReadMessageId]
+      properties:
+        lastReadMessageId:
+          type: integer
+          format: int64
+    ChatReadState:
+      type: object
+      additionalProperties: false
+      required: [lastReadMessageId, updatedAt]
+      properties:
+        lastReadMessageId:
+          type:
+            - integer
+            - 'null'
+          format: int64
+        updatedAt:
+          type: string
+          format: date-time
     GithubInstallationStatus:
       type: object
       additionalProperties: false

package.json

@@ -27,6 +27,7 @@
 		"@radix-ui/react-slot": "^1.2.4",
 		"@remotion/player": "4.0.475",
 		"@remotion/sfx": "4.0.475",
+		"@stomp/stompjs": "^7.2.1",
 		"@tanstack/react-query": "^5.90.21",
 		"class-variance-authority": "^0.7.1",
 		"clsx": "^2.1.1",

pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+allowBuilds:
+  esbuild: true
+  msw: true