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

Author: CodeBuddy Attribution Bot

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

@@ -46,7 +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.
+- For realtime UI, assuming the listener is ready immediately after calling `watch()`. Treat the first `onChange` snapshot whose `snapshot.type === 'init'` as the canonical 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.
@@ -122,7 +122,8 @@ Important rules:
 
 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.
+   - Use the snapshot whose `type` is `init` as the canonical "initial data is ready" event.
+   - If you also inspect `docChanges`, the initial payload may include `dataType: 'init'`, but do not treat the query as ready before that first init snapshot arrives.
    - Until that event arrives, keep loading state explicit and avoid enabling turn-based actions that depend on the queried documents.
 
 ## Quick examples

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

@@ -92,7 +92,8 @@ Create a real-time data listener that returns a `watcher` object.
 
 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.
+- Treat the first `onChange` snapshot whose `type` is `init` as the canonical "initial data is ready" signal.
+- The initial payload may also include `docChanges` items with `dataType: 'init'`, but the listener is not ready until that first init snapshot arrives.
 - 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.
 
@@ -105,9 +106,7 @@ const watcher = db.collection("rooms")
   .where({ roomId })
   .watch({
     onChange(snapshot) {
-      const isInit = snapshot.docChanges?.some(
-        change => change.dataType === 'init'
-      );
+      const isInit = snapshot.type === 'init';
 
       syncRoomState(snapshot.docs);
 
@@ -161,7 +160,7 @@ function ChatRoom({ roomId }) {
         onChange(snapshot) {
           handleNewMessages(snapshot);
 
-          if (!initialReady && snapshot.docChanges?.some(change => change.dataType === 'init')) {
+          if (!initialReady && snapshot.type === 'init') {
             initialReady = true;
             setLoading(false);
           }

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

@@ -46,7 +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.
+- For realtime UI, assuming the listener is ready immediately after calling `watch()`. Treat the first `onChange` snapshot whose `snapshot.type === 'init'` as the canonical 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.
@@ -122,7 +122,8 @@ Important rules:
 
 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.
+   - Use the snapshot whose `type` is `init` as the canonical "initial data is ready" event.
+   - If you also inspect `docChanges`, the initial payload may include `dataType: 'init'`, but do not treat the query as ready before that first init snapshot arrives.
    - Until that event arrives, keep loading state explicit and avoid enabling turn-based actions that depend on the queried documents.
 
 ## Quick examples

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

@@ -92,7 +92,8 @@ Create a real-time data listener that returns a `watcher` object.
 
 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.
+- Treat the first `onChange` snapshot whose `type` is `init` as the canonical "initial data is ready" signal.
+- The initial payload may also include `docChanges` items with `dataType: 'init'`, but the listener is not ready until that first init snapshot arrives.
 - 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.
 
@@ -105,9 +106,7 @@ const watcher = db.collection("rooms")
   .where({ roomId })
   .watch({
     onChange(snapshot) {
-      const isInit = snapshot.docChanges?.some(
-        change => change.dataType === 'init'
-      );
+      const isInit = snapshot.type === 'init';
 
       syncRoomState(snapshot.docs);
 
@@ -161,7 +160,7 @@ function ChatRoom({ roomId }) {
         onChange(snapshot) {
           handleNewMessages(snapshot);
 
-          if (!initialReady && snapshot.docChanges?.some(change => change.dataType === 'init')) {
+          if (!initialReady && snapshot.type === 'init') {
             initialReady = true;
             setLoading(false);
           }