fix(attribution): 实时监听 API 缺乏初始数据就绪通知机制 (issue_mnrzm5ru_70sm9m)

Author: CodeBuddy Attribution Bot

config/.claude/skills/no-sql-web-sdk/SKILL.md

@@ -46,6 +46,7 @@ Keep local `references/...` paths for files that ship with the current skill dir
 - Querying before the user is signed in when the collection rules require identity.
 - Using `wx.cloud.database()` or Node SDK patterns in browser code.
 - Initializing CloudBase lazily with dynamic imports instead of a shared synchronous app instance.
+- For realtime UI, assuming the listener is ready immediately after calling `watch()`. Treat the first `onChange` snapshot whose `docChanges` contain `dataType: 'init'` as the initial data ready signal before rendering room state, enabling actions, or concluding that the query returned no rows.
 - Treating security rules as result filters rather than request validators.
 - For CMS-style collections that need **app-level admin users** to edit/delete all records while editors can only edit/delete their own records, do not oversimplify the rule to `READONLY`. A validated pattern is a `CUSTOM` rule that reads role from `user_roles` by `auth.uid` and combines it with `doc.authorId == auth.uid`, while frontend writes can stay on `.doc(id).update()` / `.doc(id).remove()`.
 - Forgetting pagination or indexes for larger collections.
@@ -119,6 +120,11 @@ Important rules:
    - Database errors must become readable UI or application errors, not silent failures.
    - For writes, do not treat a resolved promise as success by default. Check write result fields such as `updated` / `deleted` or surfaced `code` / `message`.
 
+5. **Handle realtime initialization explicitly**
+   - `.watch()` becomes usable only after the first `onChange` snapshot arrives.
+   - Use the snapshot whose `docChanges` include `dataType: 'init'` as the canonical "initial data is ready" event.
+   - Until that event arrives, keep loading state explicit and avoid enabling turn-based actions that depend on the queried documents.
+
 ## Quick examples
 
 ### Simple query

config/.claude/skills/no-sql-web-sdk/realtime.md

@@ -88,6 +88,40 @@ Create a real-time data listener that returns a `watcher` object.
 - `add`: New document added
 - `delete`: Document deleted
 
+## Initial Readiness Contract
+
+Calling `.watch()` only starts the listener setup. Do not assume the queried data is ready immediately after `watch()` returns.
+
+- Treat the first `onChange` snapshot whose `docChanges` contain `dataType: 'init'` as the canonical "initial data is ready" signal.
+- Until that `init` snapshot arrives, keep loading state explicit.
+- Do not enable turn-based actions, render room state as authoritative, or conclude that the query returned no rows before the `init` snapshot.
+
+Example:
+
+```javascript
+let initialReady = false;
+
+const watcher = db.collection("rooms")
+  .where({ roomId })
+  .watch({
+    onChange(snapshot) {
+      const isInit = snapshot.docChanges?.some(
+        change => change.dataType === 'init'
+      );
+
+      syncRoomState(snapshot.docs);
+
+      if (isInit && !initialReady) {
+        initialReady = true;
+        setLoading(false);
+      }
+    },
+    onError(error) {
+      handleWatchError(error);
+    }
+  });
+```
+
 **Watcher object methods:**
 - `watcher.close()`: Close monitoring and release resources
 
@@ -120,10 +154,18 @@ import { useEffect } from 'react';
 
 function ChatRoom({ roomId }) {
   useEffect(() => {
+    let initialReady = false;
     const watcher = db.collection("messages")
       .where({ chatRoomId: roomId })
       .watch({
-        onChange: handleNewMessages,
+        onChange(snapshot) {
+          handleNewMessages(snapshot);
+
+          if (!initialReady && snapshot.docChanges?.some(change => change.dataType === 'init')) {
+            initialReady = true;
+            setLoading(false);
+          }
+        },
         onError: handleError
       });
 
@@ -133,4 +175,4 @@ function ChatRoom({ roomId }) {
     };
   }, [roomId]);
 }
-```
+```