@jahanxu/trellis 0.4.1

package/dist/templates/trellis/spec/roles/frontend-impl/state-management.md

@@ -0,0 +1,599 @@
+# 状态管理规范
+
+> Frontend 角色选择和实现状态管理方案的指南
+
+---
+
+## 核心原则
+
+状态管理应该：
+1. **按需选择** - 根据复杂度选择合适的方案
+2. **类型安全** - 使用 TypeScript 确保状态类型正确
+3. **可预测性** - 状态变化清晰可追踪
+4. **性能优化** - 避免不必要的重渲染
+
+---
+
+## 状态分类
+
+### 1. 组件本地状态（Local State）
+
+**定义**：仅在单个组件内使用的状态
+
+**适用场景**：
+- 表单输入值
+- UI 切换状态（展开/折叠）
+- 临时加载状态
+
+**技术选择**：React `useState`
+
+**示例**：
+```typescript
+const LoginForm = () => {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [showPassword, setShowPassword] = useState(false);
+
+  return (
+    <form>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+      />
+      <input
+        type={showPassword ? 'text' : 'password'}
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+      />
+      <button onClick={() => setShowPassword(!showPassword)}>
+        {showPassword ? '隐藏' : '显示'}密码
+      </button>
+    </form>
+  );
+};
+```
+
+---
+
+### 2. 跨组件状态（Shared State）
+
+**定义**：多个组件共享的状态
+
+**适用场景**：
+- 用户认证状态
+- 主题设置（暗色/亮色模式）
+- 语言设置
+
+**技术选择**：React Context + `useContext`
+
+**示例**：
+```typescript
+// src/contexts/AuthContext.tsx
+import { createContext, useContext, useState, ReactNode } from 'react';
+import type { User } from '@/types/user';
+
+interface AuthContextType {
+  user: User | null;
+  login: (user: User, token: string) => void;
+  logout: () => void;
+}
+
+const AuthContext = createContext<AuthContextType | undefined>(undefined);
+
+export const AuthProvider = ({ children }: { children: ReactNode }) => {
+  const [user, setUser] = useState<User | null>(null);
+
+  const login = (user: User, token: string) => {
+    setUser(user);
+    localStorage.setItem('auth_token', token);
+  };
+
+  const logout = () => {
+    setUser(null);
+    localStorage.removeItem('auth_token');
+  };
+
+  return (
+    <AuthContext.Provider value={{ user, login, logout }}>
+      {children}
+    </AuthContext.Provider>
+  );
+};
+
+export const useAuth = () => {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error('useAuth must be used within AuthProvider');
+  }
+  return context;
+};
+```
+
+**使用方式**：
+```typescript
+// App.tsx
+<AuthProvider>
+  <App />
+</AuthProvider>
+
+// LoginPage.tsx
+import { useAuth } from '@/contexts/AuthContext';
+
+const LoginPage = () => {
+  const { login } = useAuth();
+
+  const handleSubmit = async (email: string, password: string) => {
+    const { user, token } = await loginAPI(email, password);
+    login(user, token);
+  };
+
+  // ...
+};
+
+// Header.tsx
+import { useAuth } from '@/contexts/AuthContext';
+
+const Header = () => {
+  const { user, logout } = useAuth();
+
+  return (
+    <div>
+      {user && (
+        <>
+          <span>{user.name}</span>
+          <button onClick={logout}>登出</button>
+        </>
+      )}
+    </div>
+  );
+};
+```
+
+---
+
+### 3. 全局复杂状态（Global Complex State）
+
+**定义**：跨多个页面、需要复杂操作的状态
+
+**适用场景**：
+- 购物车状态
+- 消息通知队列
+- 应用配置
+
+**技术选择**：Zustand（推荐）或 Redux Toolkit
+
+---
+
+## Zustand 使用指南
+
+### 1. 安装
+
+```bash
+npm install zustand
+```
+
+### 2. 创建 Store
+
+```typescript
+// src/stores/cartStore.ts
+import { create } from 'zustand';
+import type { Product } from '@/types/product';
+
+interface CartItem {
+  product: Product;
+  quantity: number;
+}
+
+interface CartStore {
+  items: CartItem[];
+  addItem: (product: Product, quantity: number) => void;
+  removeItem: (productId: string) => void;
+  updateQuantity: (productId: string, quantity: number) => void;
+  clearCart: () => void;
+  total: () => number;
+}
+
+export const useCartStore = create<CartStore>((set, get) => ({
+  items: [],
+
+  addItem: (product, quantity) => {
+    set((state) => {
+      const existingItem = state.items.find(
+        (item) => item.product.id === product.id
+      );
+
+      if (existingItem) {
+        return {
+          items: state.items.map((item) =>
+            item.product.id === product.id
+              ? { ...item, quantity: item.quantity + quantity }
+              : item
+          ),
+        };
+      }
+
+      return {
+        items: [...state.items, { product, quantity }],
+      };
+    });
+  },
+
+  removeItem: (productId) => {
+    set((state) => ({
+      items: state.items.filter((item) => item.product.id !== productId),
+    }));
+  },
+
+  updateQuantity: (productId, quantity) => {
+    set((state) => ({
+      items: state.items.map((item) =>
+        item.product.id === productId ? { ...item, quantity } : item
+      ),
+    }));
+  },
+
+  clearCart: () => {
+    set({ items: [] });
+  },
+
+  total: () => {
+    const { items } = get();
+    return items.reduce(
+      (sum, item) => sum + item.product.price * item.quantity,
+      0
+    );
+  },
+}));
+```
+
+### 3. 使用 Store
+
+```typescript
+// 组件中使用
+import { useCartStore } from '@/stores/cartStore';
+
+const CartPage = () => {
+  const items = useCartStore((state) => state.items);
+  const total = useCartStore((state) => state.total());
+  const removeItem = useCartStore((state) => state.removeItem);
+
+  return (
+    <div>
+      <h1>购物车</h1>
+      {items.map((item) => (
+        <div key={item.product.id}>
+          <span>{item.product.name}</span>
+          <span>数量: {item.quantity}</span>
+          <button onClick={() => removeItem(item.product.id)}>删除</button>
+        </div>
+      ))}
+      <p>总计: ¥{total}</p>
+    </div>
+  );
+};
+```
+
+### 4. Zustand 持久化
+
+```typescript
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+export const useCartStore = create<CartStore>()(
+  persist(
+    (set, get) => ({
+      items: [],
+      addItem: (product, quantity) => {
+        // ...
+      },
+      // ...
+    }),
+    {
+      name: 'cart-storage', // localStorage key
+      getStorage: () => localStorage,
+    }
+  )
+);
+```
+
+---
+
+## Redux Toolkit 使用指南
+
+### 1. 安装
+
+```bash
+npm install @reduxjs/toolkit react-redux
+```
+
+### 2. 创建 Slice
+
+```typescript
+// src/store/slices/cartSlice.ts
+import { createSlice, PayloadAction } from '@reduxjs/toolkit';
+import type { Product } from '@/types/product';
+
+interface CartItem {
+  product: Product;
+  quantity: number;
+}
+
+interface CartState {
+  items: CartItem[];
+}
+
+const initialState: CartState = {
+  items: [],
+};
+
+const cartSlice = createSlice({
+  name: 'cart',
+  initialState,
+  reducers: {
+    addItem: (state, action: PayloadAction<{ product: Product; quantity: number }>) => {
+      const { product, quantity } = action.payload;
+      const existingItem = state.items.find(
+        (item) => item.product.id === product.id
+      );
+
+      if (existingItem) {
+        existingItem.quantity += quantity;
+      } else {
+        state.items.push({ product, quantity });
+      }
+    },
+    removeItem: (state, action: PayloadAction<string>) => {
+      state.items = state.items.filter(
+        (item) => item.product.id !== action.payload
+      );
+    },
+    updateQuantity: (
+      state,
+      action: PayloadAction<{ productId: string; quantity: number }>
+    ) => {
+      const item = state.items.find(
+        (item) => item.product.id === action.payload.productId
+      );
+      if (item) {
+        item.quantity = action.payload.quantity;
+      }
+    },
+    clearCart: (state) => {
+      state.items = [];
+    },
+  },
+});
+
+export const { addItem, removeItem, updateQuantity, clearCart } = cartSlice.actions;
+export default cartSlice.reducer;
+```
+
+### 3. 配置 Store
+
+```typescript
+// src/store/index.ts
+import { configureStore } from '@reduxjs/toolkit';
+import cartReducer from './slices/cartSlice';
+
+export const store = configureStore({
+  reducer: {
+    cart: cartReducer,
+  },
+});
+
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
+```
+
+### 4. 使用 Store
+
+```typescript
+// App.tsx
+import { Provider } from 'react-redux';
+import { store } from './store';
+
+<Provider store={store}>
+  <App />
+</Provider>
+
+// 组件中使用
+import { useSelector, useDispatch } from 'react-redux';
+import { addItem, removeItem } from '@/store/slices/cartSlice';
+import type { RootState } from '@/store';
+
+const CartPage = () => {
+  const items = useSelector((state: RootState) => state.cart.items);
+  const dispatch = useDispatch();
+
+  const handleRemove = (productId: string) => {
+    dispatch(removeItem(productId));
+  };
+
+  return (
+    // ...
+  );
+};
+```
+
+---
+
+## 服务器状态管理
+
+### 使用 React Query（推荐）
+
+**定义**：从服务器获取的数据（用户列表、产品详情等）
+
+**技术选择**：React Query（TanStack Query）
+
+**安装**：
+```bash
+npm install @tanstack/react-query
+```
+
+**配置**：
+```typescript
+// src/App.tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60000, // 1分钟内数据不过期
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+<QueryClientProvider client={queryClient}>
+  <App />
+</QueryClientProvider>
+```
+
+**使用示例**：
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { getUsers, deleteUser } from '@/lib/api/user';
+
+const UserList = () => {
+  const queryClient = useQueryClient();
+
+  // 查询用户列表
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: getUsers,
+  });
+
+  // 删除用户 mutation
+  const deleteMutation = useMutation({
+    mutationFn: deleteUser,
+    onSuccess: () => {
+      // 刷新用户列表
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+    },
+  });
+
+  if (isLoading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      {data?.items.map((user) => (
+        <div key={user.id}>
+          <span>{user.name}</span>
+          <button onClick={() => deleteMutation.mutate(user.id)}>
+            删除
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+---
+
+## 状态管理方案选择
+
+| 状态类型 | 复杂度 | 推荐方案 | 示例场景 |
+|---------|--------|---------|---------|
+| **本地状态** | 简单 | `useState` | 表单输入、UI切换 |
+| **跨组件状态** | 中等 | Context + `useContext` | 用户认证、主题设置 |
+| **全局复杂状态** | 复杂 | Zustand | 购物车、通知队列 |
+| **超大型应用** | 极复杂 | Redux Toolkit | 企业级应用 |
+| **服务器状态** | - | React Query | API数据缓存 |
+
+---
+
+## 性能优化
+
+### 1. 避免不必要的重渲染
+
+**使用 selector 精确订阅**：
+```typescript
+// ❌ 避免：订阅整个 store
+const store = useCartStore();
+
+// ✅ 推荐：只订阅需要的状态
+const items = useCartStore((state) => state.items);
+const total = useCartStore((state) => state.total());
+```
+
+### 2. 使用 memo 优化组件
+
+```typescript
+import { memo } from 'react';
+
+const CartItem = memo(({ item, onRemove }: CartItemProps) => {
+  return (
+    <div>
+      <span>{item.product.name}</span>
+      <button onClick={() => onRemove(item.product.id)}>删除</button>
+    </div>
+  );
+});
+```
+
+### 3. 使用 useMemo 缓存计算结果
+
+```typescript
+const CartSummary = () => {
+  const items = useCartStore((state) => state.items);
+
+  const total = useMemo(() => {
+    return items.reduce(
+      (sum, item) => sum + item.product.price * item.quantity,
+      0
+    );
+  }, [items]);
+
+  return <div>总计: ¥{total}</div>;
+};
+```
+
+---
+
+## 检查清单
+
+状态管理实现完成前，确保：
+
+- [ ] 本地状态使用 `useState`
+- [ ] 跨组件状态使用 Context 或 Zustand
+- [ ] 服务器状态使用 React Query
+- [ ] 所有状态有类型定义
+- [ ] 避免不必要的重渲染（使用 selector）
+- [ ] 复杂计算使用 `useMemo` 缓存
+- [ ] 状态更新逻辑清晰可追踪
+
+---
+
+## 常见问题
+
+### Q: 什么时候使用 Context，什么时候使用 Zustand？
+A:
+- **Context**：简单跨组件状态（用户认证、主题设置）
+- **Zustand**：复杂状态操作、需要频繁更新（购物车、通知）
+
+### Q: Redux 和 Zustand 如何选择？
+A:
+- **Zustand**：中小型应用，API 简单，性能好
+- **Redux**：大型企业应用，需要严格的状态管理规范
+
+### Q: 如何处理状态持久化？
+A:
+- **localStorage**：Zustand persist 中间件
+- **sessionStorage**：配置 `getStorage: () => sessionStorage`
+
+### Q: React Query 和 Zustand 如何配合？
+A:
+- **React Query**：管理服务器状态（API 数据）
+- **Zustand**：管理客户端状态（购物车、UI设置）
+
+---
+
+## 相关文档
+
+- [API 集成指南](./api-integration.md)
+- [Frontend 工作规范](./index.md)
+- [React Query 官方文档](https://tanstack.com/query/latest)
+- [Zustand 官方文档](https://zustand-demo.pmnd.rs/)

package/dist/templates/trellis/spec/roles/pm/index.md

@@ -0,0 +1,112 @@
+# PM (Product Manager) 工作规范
+
+> 产品经理在三角色协作中的职责、标准和工作流程
+
+---
+
+## 角色定位
+
+**产品经理（PM）** 是三角色协作流水线的**第一环**：
+- 负责需求分析和产品定义
+- 输出 PRD（Product Requirements Document）和用户故事
+- 产出物进入 `requirements` 池，供 Designer 消费
+
+---
+
+## 工作流程
+
+### 1. 创建任务
+```bash
+python3 .trellis/scripts/task.py create "功能标题" --slug feature-name
+python3 .trellis/scripts/task.py set-role <task-dir> pm
+```
+
+### 2. 编写PRD
+在任务目录创建 `prd.md`，参考模板：`.trellis/spec/roles/pm/prd-template.md`
+
+### 3. 完成并交接
+```bash
+# AI会自动生成 HANDOFF.md
+/trellis:handoff
+```
+
+产出自动进入 `deliverables/requirements/{task-id}/`
+
+---
+
+## PRD标准
+
+### 必需章节
+1. **功能概述** - 一句话说明这是什么功能
+2. **用户故事** - As a [角色], I want [功能], So that [价值]
+3. **功能需求** - 详细功能点列表
+4. **验收标准** - 如何判断功能完成
+5. **非功能需求** - 性能、安全、兼容性等
+
+### 推荐章节
+- 竞品分析
+- 数据埋点需求
+- 上线计划
+
+### 禁止内容
+- ❌ 技术实现细节（由Designer和Frontend决定）
+- ❌ UI设计细节（在PRD中仅描述布局要求，具体设计由Designer完成）
+
+---
+
+## HANDOFF文档要点
+
+AI生成的 `HANDOFF.md` 应包含：
+
+### 核心需求总结
+- 2-3段文字提炼PRD核心要点
+- 突出重点功能和优先级
+
+### 关键设计要点
+- Designer需要重点关注的UI/交互需求
+- 特殊布局要求
+- 品牌规范要求
+
+### 特别注意事项
+- 已知的技术限制（如兼容性要求）
+- 外部依赖（如第三方SDK）
+- 时间节点要求
+
+### 相关资源
+- 设计稿链接（如已有）
+- API文档链接
+- 参考资料链接
+
+---
+
+## 质量检查清单
+
+在执行 `/trellis:handoff` 前，确保：
+
+- [ ] PRD包含所有必需章节
+- [ ] 用户故事清晰完整
+- [ ] 验收标准可测试
+- [ ] 非功能需求已明确
+- [ ] 相关资源链接有效
+- [ ] 没有遗漏关键业务逻辑
+
+---
+
+## 常见问题
+
+### Q: PRD应该写多详细？
+A: 足够Designer理解要做什么，但不要限制实现方式。描述"什么"和"为什么"，不描述"怎么做"。
+
+### Q: 需要提供UI设计稿吗？
+A: 如果有现成设计稿，在HANDOFF中提供链接。如果没有，Designer会根据PRD创建原型。
+
+### Q: 如何处理需求变更？
+A: 小变更直接更新PRD和HANDOFF；大变更建议创建新任务，标注基于原任务。
+
+---
+
+## 参考资料
+
+- [PRD模板](./prd-template.md)
+- [用户故事编写指南](./user-story-guide.md)
+- [需求检查清单](./requirement-checklist.md)