@bovinphang/frontend-craft 2.6.0 → 2.7.0

package/templates/shared/rules/fec-responsive-design.md

@@ -1,227 +1,50 @@
 # 响应式设计规则
 
-凡是任务涉及移动端适配、响应式布局、多端兼容时，都应用本文件。
+凡是任务涉及移动端适配、响应式布局、多端兼容、触摸目标或视口行为时，都应用本文件。本文只保留项目常驻约束；布局模式、container query、响应式表格、媒体和验证细节交给 `fec-responsive-layout`。
 
 ## 核心原则
 
-- **移动优先**: 从小屏幕开始设计，逐步增强到大屏幕
-- **内容优先**: 移动端优先展示核心内容，次要内容折叠或延后
-- **触摸友好**: 所有交互元素必须适配手指操作
-- **性能优先**: 移动端网络和设备性能较弱，需优化加载
-- **容器感知**: 可复用组件优先适配所在容器，而不是假设整页断点
-- **稳定尺寸**: 工具栏、表格列、棋盘、卡片网格和计数器需要稳定约束，避免状态变化导致布局跳动
+- **移动优先**：从小屏幕开始设计，逐步增强到大屏幕。
+- **内容优先**：小屏优先展示核心任务、关键操作和反馈，次要内容折叠、延后或进入详情层。
+- **触摸友好**：所有交互元素必须适配手指操作，关键功能不能只依赖 hover。
+- **性能优先**：移动端网络和设备性能较弱，首屏资源、图表、动效和大列表要克制。
+- **容器感知**：可复用组件优先适配所在容器，而不是假设整页断点。
+- **稳定尺寸**：工具栏、表格列、棋盘、卡片网格和计数器需要稳定约束，避免状态变化导致布局跳动。
 
-## 断点策略
+## 断点与容器策略
 
-| 断点        | 宽度   | 设备            | Tailwind | 说明                 |
-| ----------- | ------ | --------------- | -------- | -------------------- |
-| **Mobile**  | 375px  | 手机竖屏        | （默认） | 基础样式，无媒体查询 |
-| **Tablet**  | 768px  | 平板 / 手机横屏 | `md:`    | 两列布局起点         |
-| **Desktop** | 1024px | 笔记本          | `lg:`    | 完整布局             |
-| **Large**   | 1280px | 桌面显示器      | `xl:`    | 宽屏优化             |
-| **XLarge**  | 1536px | 超宽屏          | `2xl:`   | 最大内容宽度         |
+- 默认验证 375px、768px、1024px、1440px，以及断点中间值。
+- 使用 mobile-first `min-width` 断点；不要先写桌面样式再用 `max-width` 补移动端。
+- Tailwind 前缀从小到大使用：默认 → `sm:` → `md:` → `lg:` → `xl:` → `2xl:`。
+- 页面级结构可以使用断点；会被放进侧栏、弹窗、卡片或主内容区的复用组件优先使用 container query。
+- grid/flex 子项包含长文本、图表、代码、媒体或表格时，必须考虑 `min-width: 0`、`minmax()`、`aspect-ratio` 和明确溢出策略。
 
-### 移动优先 CSS
+## 触摸目标与移动端交互
 
-```css
-/* 基础样式 — 移动端 */
-.container {
-  padding: 16px;
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
+- 空间允许时，按钮、链接、关闭按钮等交互目标至少 44x44px；紧凑工具界面最低也要保证可操作。
+- 输入框字号避免低于 16px，防止 iOS Safari 自动缩放。
+- 固定底部栏、操作条、抽屉和对话框必须考虑 safe area 与虚拟键盘。
+- hover-only 信息必须有点击、焦点或常驻可见替代方案。
+- 横竖屏切换后，主操作、焦点位置、滚动容器和错误提示仍应可达。
 
-/* Tablet — 768px+ */
-@media (min-width: 768px) {
-  .container {
-    padding: 24px;
-    flex-direction: row;
-    gap: 24px;
-  }
-}
+## 数据密集区域
 
-/* Desktop — 1024px+ */
-@media (min-width: 1024px) {
-  .container {
-    max-width: 960px;
-    margin: 0 auto;
-    padding: 32px;
-  }
-}
-```
+- 表格、列表、看板、编辑器和画布可以局部横向滚动，但页面整体不应出现无意水平溢出。
+- 移动端数据密集视图需先定义列优先级：主标识、状态和主操作优先保留；低优先级字段进入详情、展开行或抽屉。
+- 小屏仍要保留排序、筛选、分页和选择能力。
+- 虚拟滚动只解决 DOM 数量问题，不能替代信息层级设计。
 
-### Tailwind 移动优先
+## 响应式媒体
 
-Tailwind 默认移动优先，无前缀类作用于所有屏幕，前缀仅覆盖更大断点：
-
-```html
-<!-- 移动端: 单列, 小间距 | Tablet: 双列 | Desktop: 三列 -->
-<div
-  class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 md:gap-6 lg:gap-8"
->
-  <!-- 卡片: 移动端小字, Desktop 大字 -->
-  <div class="p-4 md:p-6 text-sm md:text-base">...</div>
-</div>
-
-<!-- 导航: 移动端隐藏, Desktop 显示 -->
-<nav class="hidden md:flex">...</nav>
-
-<!-- 移动端汉堡菜单, Desktop 隐藏 -->
-<button class="md:hidden" aria-label="菜单">☰</button>
-```
-
-**关键约定**：
-
-- 始终使用 `min-width` 媒体查询（mobile-first），不用 `max-width`
-- Tailwind 前缀从小到大：`sm:` → `md:` → `lg:` → `xl:`
-- 不要在桌面端写默认样式然后用 `max-width` 覆盖移动端
-
-## 触摸目标
-
-| 元素        | 最小尺寸  | 说明                        |
-| ----------- | --------- | --------------------------- |
-| 按钮        | 44×44px   | WCAG 2.2 触摸目标要求       |
-| 链接        | 44×44px   | 可通过 padding 扩大点击区域 |
-| 表单输入    | 44px 高度 | 避免 iOS 自动缩放           |
-| 复选框/单选 | 24×24px   | 最小可见尺寸                |
-| 关闭按钮    | 44×44px   | 模态框、Toast 的关闭按钮    |
-
-```css
-/* 扩大点击区域（视觉尺寸不变） */
-.icon-button {
-  width: 24px;
-  height: 24px;
-  padding: 10px; /* 实际点击区域 44×44 */
-}
-
-/* 表单输入 — 避免 iOS 缩放 */
-input,
-select,
-textarea {
-  font-size: 16px; /* < 16px 时 iOS Safari 会自动缩放页面 */
-}
-```
-
-## 布局模式
-
-### Container Query
-
-当组件会出现在侧栏、弹窗、卡片和主内容区等不同容器时，优先使用容器查询：
-
-```css
-.summary-panel {
-  container-type: inline-size;
-}
-
-@container (min-width: 42rem) {
-  .summary-panel__body {
-    display: grid;
-    grid-template-columns: 16rem minmax(0, 1fr);
-  }
-}
-```
-
-Flex/Grid 子项包含长文本、图表、代码或表格时，记得设置 `min-width: 0`。
-
-### Stack → Row
-
-移动端纵向堆叠，桌面端横向排列：
-
-```html
-<div class="flex flex-col md:flex-row gap-4">
-  <div class="flex-1">主内容</div>
-  <div class="md:w-64 md:flex-shrink-0">侧边栏</div>
-</div>
-```
-
-### 响应式表格
-
-```html
-<!-- 小屏横向滚动 -->
-<div class="overflow-x-auto">
-  <table class="min-w-full">
-    ...
-  </table>
-</div>
-
-<!-- 或：移动端卡片式布局 -->
-<div class="hidden md:block">
-  <table>
-    ...
-  </table>
-</div>
-<div class="md:hidden">
-  <!-- 每行变为卡片 -->
-</div>
-```
-
-移动端数据密集视图需先定义列优先级：主标识、状态和主操作优先保留；低优先级字段进入详情、展开行或抽屉。
-
-### 响应式图片
-
-```html
-<!-- srcset 按设备像素比加载 -->
-<img
-  src="/img/hero-800.jpg"
-  srcset="
-    /img/hero-400.jpg   400w,
-    /img/hero-800.jpg   800w,
-    /img/hero-1200.jpg 1200w
-  "
-  sizes="(max-width: 768px) 100vw, 800px"
-  alt="描述"
-  loading="lazy"
-/>
-
-<!-- picture 元素按断点切换 -->
-<picture>
-  <source
-    media="(min-width: 1024px)"
-    srcset="/img/hero-desktop.webp"
-    type="image/webp"
-  />
-  <source
-    media="(min-width: 768px)"
-    srcset="/img/hero-tablet.webp"
-    type="image/webp"
-  />
-  <img src="/img/hero-mobile.webp" alt="描述" loading="lazy" />
-</picture>
-```
-
-## 移动端交互注意
-
-- **悬停不可靠**: 移动端无 hover 状态，不要将关键功能隐藏在 hover 中（如 tooltip 改为点击触发）
-- **键盘弹出**: 移动端虚拟键盘会缩小可视区域，固定定位元素需注意位置调整
-- **滚动性能**: 使用 `-webkit-overflow-scrolling: touch`（iOS）或 `overscroll-behavior` 优化滚动体验
-- **安全区域**: 适配 iPhone 刘海/底部横条，使用 `env(safe-area-inset-*)`：
-
-```css
-.app-content {
-  padding-top: env(safe-area-inset-top);
-  padding-bottom: env(safe-area-inset-bottom);
-  padding-left: env(safe-area-inset-left);
-  padding-right: env(safe-area-inset-right);
-}
-```
-
-## 测试策略
-
-- 使用 Chrome DevTools Device Mode 测试主流设备
-- 优先在真实设备上测试（iOS Safari / Android Chrome）
-- 测试方向切换（横屏 / 竖屏）
-- 测试不同网络条件（3G / 4G / 弱网）
-- 不要假设桌面端是"默认"，移动端优先验证
+- 图片和视频要有稳定尺寸、`aspect-ratio` 或容器约束，避免加载后推挤布局。
+- 需要多尺寸资源时使用 `srcset`、`sizes`、`picture` 或框架图片组件，避免移动端下载桌面大图。
+- 媒体裁切必须保留主体信息，不为填满卡片裁掉产品、人物、图表或状态关键区域。
 
 ## 检查清单
 
-- [ ] 375px 宽度下布局正常，无水平溢出
-- [ ] 所有交互元素 ≥ 44×44px（触摸目标）
-- [ ] 输入框 font-size ≥ 16px（避免 iOS 缩放）
-- [ ] 无 hover 依赖的关键功能
-- [ ] 图片使用 srcset / picture 按设备加载
-- [ ] iPhone 安全区域适配（safe-area-inset）
-- [ ] 内容在断点间平滑过渡，无突变
-- [ ] 断点中间值、横竖屏切换和虚拟键盘弹出不遮挡主操作
-- [ ] 数据密集区域有列优先级或局部滚动策略
+- [ ] 320-375px 页面级无水平溢出。
+- [ ] 断点切换后阅读顺序合理，主操作不被隐藏。
+- [ ] 触摸目标、输入字号、safe area、虚拟键盘和横竖屏行为已验证。
+- [ ] loading、empty、error、disabled、hover/focus、长翻译文本和大数字不会撑坏固定格式控件。
+- [ ] 数据密集区域有列优先级、局部滚动或移动端摘要策略。
+- [ ] 首屏媒体尺寸稳定，非首屏媒体不会拖慢移动端主路径。

package/templates/shared/rules/fec-state-management.md

@@ -1,163 +1,60 @@
 # 状态管理规范
 
+本文件约定前端状态归属底线。状态清单、Store 形状示例、URL 状态、持久化适配器和 SSR 隔离细节交给 `fec-state-management`；请求缓存细节交给数据获取 workflow；表单字段和校验交给表单 workflow。
+
 ## 状态分类
 
-| 类型         | 示例                             | 存放位置            |
-| ------------ | -------------------------------- | ------------------- |
-| 组件 UI 状态 | modal 开关、tab 索引、hover 状态 | 组件内 state        |
-| 表单状态     | 输入值、校验错误                 | 表单库或组件 state  |
-| 服务端数据   | 用户列表、订单详情               | 数据请求库缓存      |
-| 全局业务状态 | 当前用户、权限、主题             | 全局 Store          |
-| URL 状态     | 当前页码、筛选条件、排序         | 路由参数 / 搜索参数 |
+| 类型 | 示例 | 默认归属 |
+| ---- | ---- | -------- |
+| 本地 UI 状态 | modal 开关、tab、展开行、hover 编辑态 | 组件内 state / ref |
+| 表单状态 | 输入值、脏字段、校验错误、提交中 | 表单库或表单组件 |
+| 服务端状态 | 列表、详情、分页结果、远程错误 | 请求缓存库 |
+| URL 状态 | 搜索词、筛选、排序、页码、选中 tab | 路由参数 / search params |
+| 全局客户端状态 | 登录用户、主题、权限快照、购物车草稿 | 全局 store |
+| 浏览器持久化状态 | 偏好、非敏感草稿、离线队列 | 存储层 + 状态适配器 |
 
 ## 核心原则
 
-- **就近管理**: 状态放在需要它的最近公共祖先
-- **单一数据源**: 同一份数据只在一个地方维护
-- **派生优于同步**: 可计算的值用 computed / useMemo，而不是手动同步多个 state
-- **最小状态**: 不存储可以从已有状态推导的值
-
-## React 状态管理
-
-### 本地状态
-
-```tsx
-// 简单值 - useState
-const [count, setCount] = useState(0);
-
-// 复杂逻辑 - useReducer
-const [state, dispatch] = useReducer(formReducer, initialState);
-```
-
-### 全局状态（Zustand 示例）
-
-<!-- 请根据项目实际选型调整：Redux Toolkit / Zustand / Jotai -->
-
-```tsx
-const useAuthStore = create<AuthState>((set) => ({
-  user: null,
-  login: async (credentials) => {
-    const user = await authApi.login(credentials);
-    set({ user });
-  },
-  logout: () => set({ user: null }),
-}));
-```
-
-### 服务端状态
-
-<!-- 请根据项目实际选型调整：React Query / SWR -->
-
-```tsx
-const { data, isLoading, error } = useQuery({
-  queryKey: ["users", params],
-  queryFn: () => fetchUsers(params),
-  staleTime: 5 * 60 * 1000,
-});
-```
-
-## Vue 状态管理
-
-### 本地状态
-
-```typescript
-const count = ref(0);
-const form = reactive({ name: "", email: "" });
-```
-
-### 全局状态（Pinia）
-
-```typescript
-export const useAuthStore = defineStore("auth", () => {
-  const user = ref<User | null>(null);
-
-  async function login(credentials: LoginParams) {
-    user.value = await authApi.login(credentials);
-  }
-
-  function logout() {
-    user.value = null;
-  }
-
-  const isLoggedIn = computed(() => user.value !== null);
-
-  return { user: readonly(user), isLoggedIn, login, logout };
-});
-```
-
-### 服务端状态
-
-<!-- 请根据项目实际选型调整：VueQuery / 自定义 composable -->
-
-```typescript
-const { data, isLoading, error } = useQuery({
-  queryKey: ["users", params],
-  queryFn: () => fetchUsers(toValue(params)),
-});
-```
-
-## 选型决策矩阵
-
-### React 全局状态管理选型
-
-| 维度           | Context API                            | Zustand                                | Redux Toolkit                   | Jotai               |
-| -------------- | -------------------------------------- | -------------------------------------- | ------------------------------- | ------------------- |
-| **适用场景**   | 全局常量（主题、语言、用户信息）       | 复杂业务状态（购物车、Dashboard 筛选） | 大型应用，需要严格的状态流控制  | 细粒度原子状态      |
-| **重渲染性能** | ❌ 任何 value 变化导致所有消费者重渲染 | ✅ 通过 selector 精确订阅              | ✅ connect/useSelector 精确订阅 | ✅ 原子级订阅       |
-| **样板代码**   | 少（Provider + createContext）         | 极少（一个 create 调用）               | 多（slice / action / selector） | 极少（atom）        |
-| **DevTools**   | ❌ 无                                  | ✅ Redux DevTools（中间件）            | ✅ Redux DevTools               | ✅ 专用 DevTools    |
-| **TypeScript** | ⚠️ 需手动类型标注                      | ✅ 自动推导                            | ✅ 自动推导                     | ✅ 自动推导         |
-| **中间件**     | ❌                                     | ✅（persist / devtools / immer）       | ✅（thunk / listener）          | ✅                  |
-| **Provider**   | ✅ 必须包裹                            | ❌ 不需要（外部 store）                | ✅ Provider                     | ❌（可选 Provider） |
+- **先归属，后选库**：不要先选 Redux、Zustand、Pinia 或 Context；先确定每个状态的唯一 owner。
+- **就近管理**：状态放在需要它的最近公共祖先。
+- **单一数据源**：同一份数据只在一个地方维护。
+- **派生优于同步**：可从 props、server state、URL 或已有 state 推导的值，不另存一份。
+- **最小全局状态**：全局 store 只保存真正跨页面、跨 feature 或需要统一动作的客户端状态。
 
-**推荐决策流程**：
+## React 状态边界
 
-```
-状态是否跨组件共享？
-├── 否 → useState / useReducer（本地状态）
-└── 是
-    ├── 值是否几乎不变？（主题、语言、配置）
-    │   └── 是 → Context API
-    │
-    ├── 是否需要严格状态流 + 时间旅行调试？
-    │   └── 是 → Redux Toolkit
-    │
-    ├── 状态是否高度关联、需要集中管理？
-    │   └── 是 → Zustand
-    │
-    └── 状态是否独立、需要细粒度订阅？
-        └── 是 → Jotai
-```
+- 单组件或小子树使用 `useState` / `useReducer`。
+- 低频全局配置、主题或依赖注入可用 Context；高频变化的大对象不要放 Context。
+- 中等复杂业务状态可用 Zustand、Jotai 或仓库既有方案；大型严格动作流可用 Redux Toolkit。
+- 服务端数据使用请求缓存库，不复制到全局 store。
 
-### Vue 全局状态管理选型
+## Vue 状态边界
 
-| 维度           | provide/inject                     | Pinia            |
-| -------------- | ---------------------------------- | ---------------- |
-| **适用场景**   | 局部跨层级传递（主题、表单上下文） | 全局业务状态     |
-| **响应式**     | ✅（传入 reactive/ref）            | ✅               |
-| **DevTools**   | ❌                                 | ✅ Vue DevTools  |
-| **TypeScript** | ⚠️ 需 InjectionKey                 | ✅ 自动推导      |
-| **SSR 安全**   | ⚠️ 需注意作用域                    | ✅ 内置 SSR 支持 |
+- 局部状态使用 `ref` / `reactive` / `computed`。
+- 局部跨层级上下文使用 `provide/inject`。
+- 全局业务状态使用 Pinia 或项目既有 store。
+- 服务端数据优先使用请求库或 composable 管理，不原封不动写入 Pinia。
 
-**Vue 选型结论**：Pinia 是 Vue 3 官方推荐，新项目直接使用。provide/inject 仅用于局部上下文传递。
+## URL 与持久化状态
 
----
+- 搜索、筛选、排序、分页、选中 tab 等需要分享或刷新保留的视图状态优先放 URL。
+- 浏览器持久化只保存稳定偏好或非敏感草稿，并明确字段白名单、版本号、迁移路径、过期策略和敏感字段排除。
+- SSR 场景不要在模块顶层创建带用户数据的单例 store；每次请求需要独立实例。
 
 ## 反模式
 
-- 将所有状态都放进全局 store（应优先本地状态）
-- 在 store 中存放 UI 临时状态（modal 开关、表单输入等）
-- 手动同步多份相同数据而不是用计算属性
-- 在组件中直接修改 store 的内部数据（应通过 action / mutation）
-- 将服务端响应原封不动存入全局 store 而不用请求缓存库
-- 过度使用 Context / provide 替代 props 传递
-- 用 Context 管理频繁更新的状态（导致全量消费者重渲染，应改用 Zustand/Pinia）
+- 将所有状态都放进全局 store。
+- 在 store 中存放 UI 临时状态或表单每个字段。
+- 手动同步多份相同数据，而不是从源状态派生。
+- 将服务端响应原封不动存入全局 store，而不用请求缓存库。
+- 用 Context / provide 承载高频变化大对象，导致大范围重渲染。
+- 持久化 token、权限细节、个人敏感数据或未版本化的大对象。
 
 ## 检查清单
 
-- [ ] 每个状态都有明确的归属（本地 / 全局 / URL / 服务端缓存）
-- [ ] 可派生的值没有被存为独立 state
-- [ ] 全局 store 仅包含真正需要跨组件共享的数据
-- [ ] 服务端数据通过请求库管理，而非手动存入 store
-- [ ] URL 状态（搜索、分页、筛选）与路由参数同步
-- [ ] Context 仅用于低频变更的全局值（主题、语言、用户信息）
+- [ ] 每个状态都有明确归属：本地 / 表单 / 服务端缓存 / URL / 全局 store / 浏览器持久化。
+- [ ] 可派生的值没有被存为独立 state。
+- [ ] 全局 store 只包含真正跨边界共享的数据。
+- [ ] 服务端数据通过请求库管理，刷新、回退、权限变化和错误状态仍可恢复。
+- [ ] URL 状态与路由参数同步，刷新和分享行为符合预期。
+- [ ] 持久化状态有白名单、版本、迁移和敏感字段排除。