From 21d7189d229277c67315e46055e4801594116a48 Mon Sep 17 00:00:00 2001
From: zl-q <zl-q@local>
Date: Thu, 19 Mar 2026 00:52:02 +0800
Subject: [PATCH] =?UTF-8?q?docs(apps):=20=E6=B7=BB=E5=8A=A0=20Home=20?=
 =?UTF-8?q?=E9=A6=96=E9=A1=B5=E6=B6=88=E6=81=AF=E5=8A=A0=E8=BD=BD=E4=B8=8E?=
 =?UTF-8?q?=E6=BB=9A=E5=8A=A8=E8=A7=84=E5=88=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 apps/AGENTS.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

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