20260626173529

code/app/CLAUDE.md

@@ -107,13 +107,19 @@ All new business tables must include: `id BIGINT PRIMARY KEY` (snowflake), `crea
 ### 3. Family/Space-Centric Data Model
 All business data (finance, favorites, etc.) associates with `family_id`. Users link to families via `b_family_member`. Always filter queries by the current user's `family_id`.
 
-### 4. Family Feed Recording
+### 4. Frontend Family-Scoped Data Access
+On the frontend, keep using the generic data APIs in `app-rn/src/request/api.ts`. Pages are responsible for passing the right family/user scope in `search_condition`, `args`, and inserted rows. Use `useFamilyStore((s) => s.getFamilyId())` for the current family id and `useUserStore((s) => s.getUserId())` for the current user id.
+
+### 5. Family Feed Recording
 Certain actions must call `recordFeed()` from `@/helpers/feed`. Use `{nickname}` placeholder in content — do NOT hardcode nicknames. The `loadFeeds()` helper replaces it dynamically. Scenarios: creating/joining family (`join`), renaming (`rename`), recording bills (`bill`), favoriting apps (`fav`).
 
-### 5. Frontend: Use Existing Libraries Only
+### 6. Frontend: Use Existing Libraries Only
 Before writing any page/component, check `app-rn/package.json` for available dependencies. Use HeroUI Native for UI, `@legendapp/list` for long lists, `lucide-react-native` for icons, `sonner-native` for toasts. Use NativeWind `className` for styling, not inline `style={}`.
 
-### 6. Finance Convention
+### 7. Loading State: Always Use useLoading + LoadingOverlay
+Any async save/update/delete operation must use the `useLoading` hook + `<LoadingOverlay>` pattern — never roll per-field loading booleans. The hook provides `startLoading(message)` (shows toast.loading + page mask), `stopLoading(options?)` (dismisses toast, optionally shows success/error), and `isLoading` (boolean for disabling buttons). Place `<LoadingOverlay visible={isLoading} />` near the bottom of the page JSX (before closing `</PageLayout>`). Reference: `src/hooks/useLoading.ts`, `src/components/LoadingOverlay.tsx`.
+
+### 8. Finance Convention
 `type = 0` means expense, `type = 1` means income. Category icon names match iconfont names (e.g., `finance_jiaotong`, `finance_canyin`).
 
 ## Key Files
@@ -130,6 +136,8 @@ Before writing any page/component, check `app-rn/package.json` for available dep
 | `app-rn/src/store/` | Zustand stores (user, family, finance, app, favorite) |
 | `app-rn/src/layouts/` | Shell layouts (AppLayout, ModuleLayout, PageLayout) |
 | `app-rn/src/configs/pages.ts` | Sub-app definitions |
+| `app-rn/src/hooks/useLoading.ts` | Loading state hook (toast + overlay) |
+| `app-rn/src/components/LoadingOverlay.tsx` | Full-page loading mask component |
 | `app-rn/src/helpers/feed.ts` | Family feed recording |
 
 ## Known Risks