gt-agent-company/openspec/changes/add-notification-entry-and-unread-reminder/design.md

Context

The notification API returns the response payload through the existing request wrapper, so frontend API methods should expose the typed data payload directly. The home page is shared by agent and enterprise accounts and is loaded after login through /pages/agent-system/home/index.

Goals / Non-Goals

• Goals: expose notifications, show the newest unread message after login, and keep server read state aligned with what the user has actually seen.
• Non-Goals: notification target resolution, controlled-resource routing, push notifications, or a separate manual read button.

Decisions

• Decision: add a dedicated notification page for the notification entry. The entry is placed in the home page's top user-information card, and the page renders notification content only; notification rows have no click navigation.
• Decision: the login page writes a short-lived pending-reminder marker after storing a valid session. The home page consumes the marker after loading the authenticated user and requests the newest unread notification.
• Decision: use GET /api/admin/notifications/unread-count for the entry badge and GET /api/admin/notifications?is_read=false&page=1&page_size=1 for the login reminder. The notification page requests the newest notification page with page_size=50.
• Decision: call PUT /api/admin/notifications/{id}/read as soon as an unread notification becomes visible in the reminder or notification list, update local state optimistically, and treat the API as idempotent.
• Decision: if the unread-count or reminder request fails, keep the home page usable and do not show a fabricated notification. The normal request interceptor continues to handle authentication failures.

Risks / Trade-offs

• Marking on render means a message can become read before the user finishes reading it; this follows the requested “seen means read” behavior.
• A notification page displays the first 50 newest records; additional pagination is outside this change unless the API data requires it.

Migration Plan

No data migration is needed. Deploy the frontend after the notification endpoints and icon asset are available. Rolling back removes the entry and UI without changing notification records.

Open Questions

• None for the stated behavior. The entry opens the notification page, while notification content itself never navigates to a controlled target.