@jahanxu/trellis 0.4.2 → 0.5.1

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

@@ -1,599 +0,0 @@
-# 状态管理规范
-
-> 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

@@ -1,112 +0,0 @@
-# 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)