@bovinphang/frontend-craft 2.5.0

package/skills/fec-responsive-layout/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fec-responsive-layout
+description: Use when designing, implementing, or reviewing responsive frontend layouts, mobile-first breakpoints, container queries, fluid grids, data-dense tables, touch targets, safe areas, orientation changes, viewport overflow, or cross-device UI behavior; Chinese triggers include 响应式布局, 移动端适配, 断点, 容器查询, 横竖屏, 触摸目标.
+---
+
+# 响应式布局
+
+适用于需要让页面、工具界面、表格、仪表盘或组件在多设备上稳定工作的前端任务。需要布局模式和检查清单时加载 [references/responsive-layout-patterns.md](references/responsive-layout-patterns.md)。
+
+## Purpose
+
+用内容优先、移动优先和容器感知的方式设计响应式布局，避免只靠固定断点修补溢出。
+
+## Procedure
+
+1. 明确信息优先级：小屏先保留核心任务、关键操作和反馈；次要信息折叠、延后或移入详情层。
+2. 选择布局策略：简单页面用 mobile-first 断点；嵌套组件、卡片网格和侧栏优先考虑 container query。
+3. 设计流式尺寸：用 `minmax()`、`clamp()`、`aspect-ratio`、`max-width`、`min-width: 0` 和稳定网格轨道控制伸缩。
+4. 处理数据密集界面：表格、列表、看板和编辑器需要明确横向滚动、列优先级、冻结列或移动端摘要视图。
+5. 保证触摸与键盘：触摸目标、焦点路径、hover 替代、虚拟键盘、安全区域和横竖屏切换都要复核。
+6. 关联性能与资源：移动端减少首屏大图、重型图表、同步动画和不必要列渲染。
+7. 验证断点之间：检查 375px、768px、1024px、1440px，以及断点中间值是否溢出、遮挡或跳变。
+
+## Constraints
+
+- 不把桌面版缩小当作移动端设计。
+- 不让关键功能只依赖 hover 或宽屏侧栏。
+- 不用固定高度掩盖内容变化；需要固定格式时用稳定约束和可滚动区域。
+- 不用 viewport 字体缩放替代真实排版层级。
+- 不让移动端横向溢出成为默认解决方案；只有数据表、画布或编辑器等明确场景可以局部横滚。
+
+## Expected Output
+
+输出响应式信息优先级、断点或容器策略、关键组件布局模式、触摸/键盘要求、数据密集区域处理方案和验证结果。完成后页面在常见视口和输入方式下不溢出、不遮挡、可操作。

package/skills/fec-responsive-layout/references/responsive-layout-patterns.md

@@ -0,0 +1,59 @@
+# 响应式布局模式
+
+## 策略选择
+
+| 场景 | 策略 |
+| ---- | ---- |
+| 页面级结构 | 移动优先断点 |
+| 会被放进未知父容器的复用组件 | 容器查询 |
+| 卡片网格 | `repeat(auto-fit, minmax())`，并设置合理最小宽度 |
+| 数据表格 | 列优先级、横向滚动或移动端摘要行 |
+| 编辑器 / 画布 / dashboard | 稳定外壳 + 可滚动工作区 |
+
+## CSS 模式
+
+```css
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(18rem, 100%), 1fr));
+  gap: 1rem;
+}
+
+.panel {
+  min-width: 0;
+  container-type: inline-size;
+}
+
+@container (min-width: 42rem) {
+  .panel-body {
+    display: grid;
+    grid-template-columns: 16rem minmax(0, 1fr);
+  }
+}
+```
+
+当 grid/flex 子项包含长文本、表格、代码、图表或媒体时，给子项设置 `min-width: 0`。
+
+## 数据密集型界面
+
+- 编码前先确定移动端列优先级。
+- 主标识、状态和主要操作保持可见。
+- 低优先级元数据移入详情行、抽屉或可展开面板。
+- 小屏仍要保留排序、筛选、分页和选择能力。
+- 虚拟滚动只解决 DOM 数量问题，不能解决信息层级问题。
+
+## 触控与视口检查
+
+- 空间允许时，交互目标至少 44x44px。
+- 移动端输入框字号避免低于 16px。
+- 固定底部栏和操作条必须考虑 `env(safe-area-inset-bottom)`。
+- 对话框和抽屉需要适配虚拟键盘导致的视口变化。
+- 只在 hover 时出现的内容必须提供点击、焦点或常驻可见替代方案。
+
+## 验证清单
+
+- 320-375px：页面级没有横向溢出。
+- 768px：布局切换后阅读顺序仍然合理。
+- 1024-1440px：内容宽度有约束，扫描路径清晰。
+- 长标签、翻译文本、数字以及 empty/error/loading 状态不会撑坏固定格式控件。
+- 横竖屏切换不会困住焦点或隐藏主操作。

package/skills/fec-route-protection/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: fec-route-protection
+description: Use when implementing or reviewing frontend route protection, auth guards, RBAC, permission routes, login state handling, redirects, middleware, React Router, Next.js, Vue Router, or Nuxt route middleware; Chinese triggers include 路由保护, 权限路由, 登录态.
+---
+
+# 路由保护
+
+## Purpose
+
+为前端应用建立清晰的认证、授权和重定向边界，避免越权访问与闪烁渲染。
+
+## When to Use
+
+- 页面需要登录后访问，或不同角色看到不同路由。
+- 需要实现 React Router、Next.js、Nuxt 或 Vue Router 的路由守卫。
+- 登录过期、权限不足、组织/租户切换需要统一处理。
+- 不用于替代服务端授权；前端路由保护只能改善体验，不能作为唯一安全边界。
+
+## Procedure
+
+### 1. 定义认证与授权状态
+
+```ts
+export type AuthStatus = "loading" | "anonymous" | "authenticated";
+
+export interface CurrentUser {
+  id: string;
+  roles: string[];
+  permissions: string[];
+}
+
+export function canAccess(user: CurrentUser, required: string[]) {
+  return required.every((permission) => user.permissions.includes(permission));
+}
+```
+
+### 2. React Router 使用布局守卫
+
+```tsx
+import { Navigate, Outlet, useLocation } from "react-router-dom";
+
+interface ProtectedRouteProps {
+  requiredPermissions?: string[];
+}
+
+export function ProtectedRoute({ requiredPermissions = [] }: ProtectedRouteProps) {
+  const location = useLocation();
+  const { status, user } = useAuth();
+
+  if (status === "loading") return <RouteLoading />;
+  if (status === "anonymous") {
+    return <Navigate to="/login" replace state={{ from: location }} />;
+  }
+  if (requiredPermissions.length > 0 && !canAccess(user, requiredPermissions)) {
+    return <Navigate to="/403" replace />;
+  }
+
+  return <Outlet />;
+}
+```
+
+```tsx
+const router = createBrowserRouter([
+  {
+    element: <ProtectedRoute requiredPermissions={["orders:read"]} />,
+    children: [{ path: "/orders", element: <OrdersPage /> }],
+  },
+]);
+```
+
+### 3. Next.js 优先在服务端边界处理
+
+```ts
+// middleware.ts
+import { NextResponse, type NextRequest } from "next/server";
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get("session")?.value;
+  const isPrivateRoute = request.nextUrl.pathname.startsWith("/dashboard");
+
+  if (isPrivateRoute && !token) {
+    const loginUrl = new URL("/login", request.url);
+    loginUrl.searchParams.set("redirect", request.nextUrl.pathname);
+    return NextResponse.redirect(loginUrl);
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*"],
+};
+```
+
+对需要精细权限的 App Router 页面，在 server component 或 server action 中重新校验权限，不依赖客户端状态。
+
+### 4. Vue Router / Nuxt 使用导航守卫
+
+```ts
+router.beforeEach(async (to) => {
+  const auth = useAuthStore();
+  if (auth.status === "unknown") await auth.fetchCurrentUser();
+
+  if (to.meta.requiresAuth && !auth.user) {
+    return { path: "/login", query: { redirect: to.fullPath } };
+  }
+
+  const required = to.meta.permissions as string[] | undefined;
+  if (required?.length && !auth.canAccess(required)) {
+    return { path: "/403" };
+  }
+});
+```
+
+### 5. 统一失败与跳转体验
+
+- `401`：清理过期会话，跳转登录页并保留 `redirect`。
+- `403`：进入无权限页，不反复重试。
+- `loading`：渲染稳定骨架屏，避免先显示私有内容再跳转。
+- 登录成功：只跳转到同源且允许的路径，防止 open redirect。
+- RBAC：权限矩阵来自可信会话或后端返回；前端只用于路由体验和 UI 裁剪，不能替代接口授权。
+- 会话刷新：401 刷新失败后统一清理状态；避免多个并发请求各自触发跳转或刷新风暴。
+
+## Constraints
+
+- 前端路由保护不是安全边界；API、SSR loader、server action 必须重复做授权校验。
+- 不要在组件渲染后用 `useEffect` 才跳转私有页面，否则会出现敏感内容闪烁。
+- redirect 参数必须限制为站内路径，不能直接信任 URL 输入。
+- 权限信息应来自可信会话或后端响应，不要只依赖 localStorage 中的角色字段。
+- 多租户应用必须把 tenant/org 上下文纳入权限判断。
+- 不把菜单隐藏视为授权完成；用户直接访问 URL、刷新页面、篡改 localStorage 和替换 tenant 都必须验证。
+
+## Expected Output
+
+产出一套路由守卫实现，覆盖 loading、未登录、权限不足、登录后回跳和会话过期。验证时直接访问私有 URL、刷新页面、切换角色、篡改 redirect 参数，确认行为稳定且 API 仍有服务端授权。

package/skills/fec-security-review/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: fec-security-review
+description: Use when reviewing frontend security risks such as XSS, CSRF, sensitive data exposure, unsafe DOM APIs, untrusted user input, authentication/token handling, payment flows, file upload, CSP, dependency risk, or third-party scripts; Chinese triggers include 安全审查, 安全检查.
+---
+
+# 前端安全审查
+
+## Purpose
+
+识别前端代码中的客户端安全风险，并给出可执行修复建议。
+
+## Procedure
+
+1. 先确认审查面：用户输入、动态 HTML、URL 跳转、认证态、RBAC、文件上传、支付/删除等敏感操作、第三方脚本和依赖。
+2. 搜索高危模式：`dangerouslySetInnerHTML`、`v-html`、`innerHTML`、`document.write`、动态 script、未校验 redirect、明文 token。
+3. 按风险类型审查：XSS、CSP、敏感数据、CSRF、依赖、输入校验、文件上传、开放重定向、认证授权和第三方脚本。
+4. 用边界模型判断责任：客户端只能改善体验和减少误用，鉴权、授权、上传信任和敏感操作必须由服务端最终裁决。
+5. 高危问题标记为阻塞合并；前端校验只能改善体验，不能作为唯一安全边界。
+6. 输出分级安全报告；报告格式见 [references/report-template.md](references/report-template.md)。
+
+## Detailed References
+
+- Load [references/security-checklist.md](references/security-checklist.md) for XSS, CSP, sensitive data, CSRF, dependency, and input validation details.
+- Load [references/report-template.md](references/report-template.md) when writing the security review report.
+
+## Constraints
+
+- 不要为了方便开发而绕过安全机制。
+- 不要依赖前端校验作为唯一安全防线。
+- 不要信任任何来自客户端的数据。
+- 发现高危问题时必须标记为阻塞合并。
+- 与通用代码质量 review 分工：本 skill 关注威胁、攻击面和数据泄露。
+- 不把依赖审计结果机械等同为可利用漏洞；需要结合运行路径、暴露面和修复成本判断。
+- 不把隐藏按钮、前端路由守卫或本地角色字段当作授权边界；API、SSR loader、server action 和敏感操作必须有服务端裁决。
+
+## Expected Output
+
+输出 CRITICAL/HIGH/MEDIUM/LOW 分级安全审查报告，每个问题关联具体文件和行号，给出修复建议；报告保存为 `reports/security-review-YYYY-MM-DD-HHmmss.md`。

package/skills/fec-security-review/references/report-template.md

@@ -0,0 +1,27 @@
+# 安全审查报告模板
+
+```markdown
+# 安全审查报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+
+## CRITICAL / 高危 (N项)
+- **[文件:行号]** 风险描述 -> 修复建议
+
+## HIGH / 中高危 (N项)
+- ...
+
+## MEDIUM / 中危 (N项)
+- ...
+
+## LOW / 低危或建议 (N项)
+- ...
+
+## 已通过的安全检查
+- ...
+
+**整体安全等级**: 安全 / 存在风险 / 高危需修复
+```
+
+审查完成后，将报告保存到 `reports/security-review-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/skills/fec-security-review/references/security-checklist.md

@@ -0,0 +1,64 @@
+# 前端安全审查清单
+
+## XSS
+
+- `dangerouslySetInnerHTML` 和 `v-html` 必须有明确理由和输入净化。
+- 用户输入不得直接插入 DOM、`innerHTML`、`document.write`。
+- URL 参数不得直接用于页面渲染。
+- 动态生成的 `<script>` 标签必须审查来源。
+- 富文本使用 DOMPurify 等库，并配置标签、属性、协议白名单。
+
+```ts
+import DOMPurify from "dompurify";
+
+const clean = DOMPurify.sanitize(dirtyHtml, {
+  ALLOWED_TAGS: ["b", "i", "em", "strong", "a", "ul", "ol", "li", "p", "br"],
+  ALLOWED_ATTR: ["href", "title"],
+  ALLOWED_URI_REGEXP: /^(https?|mailto):/i,
+});
+```
+
+## 安全重定向
+
+```ts
+function safeRedirect(url: string): string {
+  if (url.startsWith("/") && !url.startsWith("//")) return url;
+  return "/dashboard";
+}
+```
+
+## CSP
+
+- 推荐先用 `Content-Security-Policy-Report-Only` 验证。
+- `default-src 'self'`、`object-src 'none'`、`frame-ancestors 'none'`、`base-uri 'self'` 是常见底线。
+- 避免 `'unsafe-eval'`；内联脚本优先 nonce。
+
+```http
+Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'; frame-ancestors 'none'; base-uri 'self'; form-action 'self';
+```
+
+## 敏感数据
+
+- 禁止前端硬编码 API Key、Secret、密码。
+- 禁止 localStorage/sessionStorage/IndexedDB 存明文 token、密码、信用卡信息。
+- 禁止 URL query 参数传 token 或密码。
+- 禁止 console.log 或错误上报携带隐私数据。
+- Token 优先 httpOnly + Secure + SameSite cookie。
+
+## CSRF
+
+- 变更操作必须携带 CSRF token 或使用同等后端防护。
+- 关键操作不要使用 GET。
+- 检查后端是否校验 `Origin` / `Referer`。
+
+## 依赖与第三方脚本
+
+- 定期审查依赖安全公告。
+- 禁止从非官方 CDN 加载脚本，除非有 SRI 和来源审查。
+- 动态加载第三方脚本必须有业务必要性和降级策略。
+
+## 输入校验与文件上传
+
+- 前端校验不是安全边界，后端必须二次校验。
+- 文件上传校验 MIME、大小、扩展名和内容；不能只看扩展名。
+- 正则校验注意 ReDoS 风险。

package/skills/fec-source-driven-development/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: fec-source-driven-development
+description: Use when frontend decisions depend on framework, library, browser, runtime, package, API, or platform behavior that may have changed, including official documentation checks, version-sensitive patterns, migration choices, or public interface assumptions; Chinese triggers include 查官方文档, 以源码为准, source-driven, 版本差异.
+---
+
+# 来源驱动开发
+
+## Purpose
+
+在前端实现、评审和架构决策中优先依据项目内事实、官方文档和当前版本行为，避免沿用过时经验或未经验证的假设。
+
+## Procedure
+
+1. 判断是否需要查源
+   - 涉及框架新版本、路由、渲染模式、缓存、构建工具、浏览器 API、包发布格式、鉴权协议或公共接口时必须查源。
+   - 涉及项目约定时先读本仓库 README、配置、模板、已有实现、测试和迁移记录。
+   - 只是稳定语言语法或明显局部重构时，可使用项目现有模式作为事实来源。
+
+2. 收集权威材料
+   - 首选官方文档、规范、源码、release notes、migration guide、类型定义和项目内测试。
+   - 第三方文章只能作为线索，不能作为最终依据。
+   - 对快速变化的库记录包名、版本、文档日期或页面标题。
+
+3. 提炼决策
+   - 写清当前版本推荐做法、弃用做法、限制条件和迁移注意事项。
+   - 对多个可行方案说明选择理由、兼容性、维护成本和回退方式。
+   - 若文档和项目现状冲突，优先解释冲突并给出渐进调整，不直接推翻已运行系统。
+   - 对依赖升级、框架迁移和公共 API 变化，记录 release notes、migration guide、版本范围、破坏性变更和回滚方案。
+
+4. 落到实现
+   - 将外部行为隔离在适配层、配置层或小型工具函数中，避免在组件里散落版本假设。
+   - 公共接口变化要保持命名、错误形状、默认值和兼容策略清晰。
+   - 代码注释只记录非显而易见的来源约束，不粘贴大段文档。
+
+5. 验证假设
+   - 用类型检查、最小复现、单元测试、组件测试、E2E、构建或浏览器验证证明关键假设。
+   - 如果无法验证，报告不确定性、风险范围和需要用户或团队确认的信息。
+6. 留下轻量决策记录
+   - 当结论会影响公共接口、依赖版本、目录规范或团队工作流时，补充 ADR/变更记录或交给文档同步流程。
+
+## Source Priority
+
+| Priority | Source | Use |
+| -------- | ------ | --- |
+| 1 | 项目内配置、测试、已有实现 | 判断本仓库真实约定 |
+| 2 | 官方文档、源码、类型定义 | 判断当前推荐行为 |
+| 3 | 标准规范、浏览器兼容数据 | 判断平台能力和兼容边界 |
+| 4 | Issue、讨论、第三方文章 | 辅助排查，不能单独定案 |
+
+## Constraints
+
+- 不凭记忆给版本敏感结论。
+- 不把过时教程当作当前最佳实践。
+- 不引用无法复核的来源作为关键依据。
+- 不为追新而改动稳定项目约定；必须说明收益和迁移成本。
+- 不在交付中复制长篇外部文档；只保留必要结论和链接或文件路径。
+- 不把“查过文档”停留在口头；版本敏感决策需要能追溯到具体版本、路径或官方页面。
+
+## Expected Output
+
+输出来源清单、版本或项目事实、决策结论、实现影响、验证命令和未决风险。若修改代码，关键行为应有测试或构建验证支撑。

package/skills/fec-state-management/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: fec-state-management
+description: Use when choosing, implementing, reviewing, or refactoring frontend state ownership across React, Vue, Next.js, Nuxt, URL state, server state, form state, browser persistence, or global stores. Prefer narrower skills for TanStack Query cache details, browser storage persistence, or form validation internals; Chinese triggers include 状态管理, 状态归属, store 选型.
+---
+
+# 前端状态管理
+
+## Purpose
+
+为前端状态确定清晰归属，避免全局 store 膨胀、重复缓存和派生状态同步错误。
+
+## Procedure
+
+### 1. 先分类状态来源
+
+不要先选 Redux、Zustand、Pinia 或 Context。先把每个状态标到唯一归属，再决定工具。
+
+| 状态类型         | 典型例子                             | 默认归属                 |
+| ---------------- | ------------------------------------ | ------------------------ |
+| 本地 UI 状态     | 弹窗开关、tab、展开行、hover 编辑态  | 组件内 state / ref       |
+| 表单状态         | 输入值、脏字段、校验错误、提交中     | 表单库或表单组件         |
+| 服务端状态       | 列表、详情、分页结果、远程错误       | 请求缓存库               |
+| URL 状态         | 搜索词、筛选、排序、页码、选中 tab   | 路由参数 / search params |
+| 全局客户端状态   | 登录用户、主题、权限快照、购物车草稿 | 全局 store               |
+| 浏览器持久化状态 | 跨刷新保留的草稿、偏好、离线队列     | 存储层 + 状态适配器      |
+
+```tsx
+type ReportsStateMap = {
+  search: "url";
+  selectedReportId: "url";
+  reports: "server-state-cache";
+  isFilterPanelOpen: "local-ui";
+  draftColumns: "browser-persistence";
+};
+```
+
+### 2. 保持最小状态
+
+可从 props、server state、URL 或已有 state 推导出来的值，不要另存一份。
+
+```tsx
+interface Invoice {
+  id: string;
+  status: "draft" | "sent" | "paid";
+}
+
+function InvoiceList({ invoices }: { invoices: Invoice[] }) {
+  const paidInvoices = invoices.filter((invoice) => invoice.status === "paid");
+
+  return <span>{paidInvoices.length}</span>;
+}
+```
+
+### 3. 选择 React 全局状态方案
+
+React 中优先本地化和组合；只有跨页面、跨 feature 或需要统一动作时才引入全局 store。
+
+```tsx
+import { create } from "zustand";
+
+interface WorkspaceState {
+  activeWorkspaceId: string | null;
+  setActiveWorkspaceId: (workspaceId: string) => void;
+}
+
+export const useWorkspaceStore = create<WorkspaceState>((set) => ({
+  activeWorkspaceId: null,
+  setActiveWorkspaceId: (activeWorkspaceId) => set({ activeWorkspaceId }),
+}));
+```
+
+决策顺序：
+
+1. 只在一个组件或一个小子树使用：`useState` / `useReducer`。
+2. 低频全局配置或依赖注入：Context。
+3. 中等复杂业务状态：Zustand 或 Jotai，按仓库现有选型优先。
+4. 大型应用、严格动作流、审计或时间旅行调试：Redux Toolkit。
+5. 远程数据：使用数据获取 skill 管理 query key、缓存和失效策略。
+
+### 4. 选择 Vue 全局状态方案
+
+Vue 3 中，局部跨层级传递使用 `provide/inject`；全局业务状态使用 Pinia 或项目既有 store。
+
+```ts
+import { computed, readonly, ref } from "vue";
+import { defineStore } from "pinia";
+
+export const useSessionStore = defineStore("session", () => {
+  const userId = ref<string | null>(null);
+  const isSignedIn = computed(() => userId.value !== null);
+
+  function signIn(nextUserId: string) {
+    userId.value = nextUserId;
+  }
+
+  return {
+    userId: readonly(userId),
+    isSignedIn,
+    signIn,
+  };
+});
+```
+
+### 5. 明确状态边界和迁移步骤
+
+重构状态时先做状态清单，再逐步移动读写入口。每一步都应保持行为可验证。
+
+```ts
+interface StateMigrationItem {
+  name: string;
+  currentOwner: "component" | "context" | "store" | "query-cache" | "url";
+  targetOwner: "component" | "context" | "store" | "query-cache" | "url";
+  verification: string;
+}
+
+const migrationPlan: StateMigrationItem[] = [
+  {
+    name: "dashboard filters",
+    currentOwner: "store",
+    targetOwner: "url",
+    verification: "refreshing the page preserves filters through search params",
+  },
+];
+```
+
+## Detailed References
+
+需要 Store 形状示例、选择器模式、URL 状态同步、持久化适配器、SSR 边界或审查清单时，加载 [references/state-patterns.md](references/state-patterns.md)。
+
+## Constraints
+
+- 不把服务端响应复制到全局 store；缓存、失效和重试归数据获取层。
+- 不把表单每个字段提升到全局 store；跨步骤共享也优先由表单上下文或提交草稿适配器处理。
+- 不用 Context 承载高频变化的大对象；会扩大重渲染范围。
+- 持久化状态必须明确字段白名单、版本号、过期策略和敏感数据排除。
+- SSR 场景不要在模块顶层创建带用户数据的单例 store。
+
+## Expected Output
+
+产出状态归属清单、选型理由、store/API 边界和验证步骤。实现时应保留 loading/error/empty、刷新、回退、跨路由和权限变化等关键行为。

package/skills/fec-state-management/references/state-patterns.md

@@ -0,0 +1,109 @@
+# 状态管理模式
+
+## 所有权审查清单
+
+- 每个状态字段有唯一归属：本地状态、表单状态、服务端缓存、URL 状态、全局 Store 或浏览器持久化。
+- 派生值由源状态计算得出，而不是通过 effect 或 watcher 手动同步。
+- URL 状态用于可分享、刷新后需保留的视图状态，如筛选、搜索、排序和分页。
+- 服务端数据保留在请求缓存中；全局 Store 仅存放选中的 ID、本地偏好或乐观更新提示。
+- 持久化的客户端状态需有白名单、schema 版本号、迁移路径和敏感字段排除规则。
+- Store 的 action 以领域事件命名，而非组件处理器命名。
+
+## React Store 形状示例
+
+```tsx
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+
+interface CartLine {
+  sku: string;
+  quantity: number;
+}
+
+interface CartState {
+  lines: CartLine[];
+  addLine: (line: CartLine) => void;
+  removeLine: (sku: string) => void;
+}
+
+export const useCartStore = create<CartState>()(
+  subscribeWithSelector((set) => ({
+    lines: [],
+    addLine: (line) =>
+      set((state) => ({
+        lines: [...state.lines.filter((item) => item.sku !== line.sku), line],
+      })),
+    removeLine: (sku) =>
+      set((state) => ({
+        lines: state.lines.filter((line) => line.sku !== sku),
+      })),
+  })),
+);
+```
+
+选择器应尽可能返回稳定的原始值或经过 memo 的切片：
+
+```tsx
+const itemCount = useCartStore((state) =>
+  state.lines.reduce((total, line) => total + line.quantity, 0),
+);
+```
+
+## URL 状态边界
+
+当另一个用户应能打开相同视图，或刷新后需要保留视图时，使用 URL 状态。
+
+```tsx
+import { useSearchParams } from "react-router-dom";
+
+export function useReportFilters() {
+  const [params, setParams] = useSearchParams();
+  const status = params.get("status") ?? "open";
+
+  function setStatus(nextStatus: string) {
+    setParams((next) => {
+      next.set("status", nextStatus);
+      next.set("page", "1");
+      return next;
+    });
+  }
+
+  return { status, setStatus };
+}
+```
+
+## 持久化适配器边界
+
+仅持久化稳定的客户端偏好设置或非敏感草稿。序列化逻辑放在组件外部。
+
+```ts
+interface PersistedGridState {
+  version: 1;
+  visibleColumns: string[];
+}
+
+const storageKey = "reports:grid";
+
+export function readGridState(): PersistedGridState | null {
+  const raw = window.localStorage.getItem(storageKey);
+  if (!raw) return null;
+
+  try {
+    const parsed = JSON.parse(raw) as PersistedGridState;
+    return parsed.version === 1 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeGridState(state: PersistedGridState): void {
+  window.localStorage.setItem(storageKey, JSON.stringify(state));
+}
+```
+
+## SSR 与请求隔离
+
+- 当状态可能包含用户数据时，每次请求需创建独立的 Store。
+- 服务端渲染期间不要读取 `window`、`localStorage` 或 `document`。
+- 水合后再加载持久化偏好，并在水合前提供确定性默认值。
+- 服务端缓存脱水与纯客户端全局 Store 分开处理。