diff --git a/apps/AGENTS.md b/apps/AGENTS.md index 9517e99..480fbc8 100644 --- a/apps/AGENTS.md +++ b/apps/AGENTS.md @@ -152,3 +152,29 @@ Auth is a global module. All auth/session behavior MUST follow a single state ma - session invalidation -> unauthenticated redirect path If a new auth-related requirement cannot fit this model, update this section first, then implement code. + +## 10) Home Message Loading & Scroll Rules (MUST) + +Home 首页历史消息加载与滚动策略属于高回归模块,必须遵循以下约束: + +- **MUST** use event-driven viewport decisions for Home message list behavior. + - Use `HomeMessageViewportController` as the decision engine. + - **MUST NOT** drive auto-scroll directly from `items.length` diffs or ad-hoc boolean combinations. +- **MUST** distinguish semantic events at minimum: + - initial history loaded + - history prepend start/finish + - new message appended + - sub-route resume + - refresh completed + - user scroll state changed +- **MUST** preserve reading position when user is away from bottom. + - New messages while reading history should show unread indicator instead of forcing bottom jump. +- **MUST** preserve viewport anchor during history prepend. + - **MUST NOT** mix prepend restore with unconditional bottom auto-scroll. +- **MUST** use `returnToHomePreserveState` for business-subroute returns to Home (calendar/todo/message-related flows). + - **MUST NOT** introduce new direct business-route `go('/home')` shortcuts. + - Auth entry flows (login/register success) are allowed to navigate to Home directly. +- **MUST** add or update tests when touching Home message loading/scroll behavior: + - controller-level state transition tests + - widget-level unread indicator and scroll behavior tests + - route-return stability tests when navigation behavior changes