@jahanxu/trellis 0.4.1

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

@@ -0,0 +1,243 @@
+# Designer (交互设计师) 工作规范
+
+> 交互设计师在三角色协作中的职责、标准和工作流程
+
+---
+
+## 角色定位
+
+**交互设计师（Designer）** 是三角色协作流水线的**第二环**：
+- 从 `requirements` 池选择需求
+- 基于PRD创建可运行的前端原型（带Mock数据）
+- 产出物进入 `prototypes` 池，供 Frontend 消费
+
+---
+
+## 工作流程
+
+### 1. 选择需求
+```bash
+# 查看可用需求
+python3 .trellis/scripts/pool.py list requirements
+
+# 选择需求并创建任务
+/trellis:pick-task requirements <task-id>
+```
+
+系统会自动：
+- 创建任务目录
+- 设置 `source.json` 引用上游产出
+- 注入上游PRD和HANDOFF文档
+
+### 2. 创建原型
+
+参考上游的 `HANDOFF.md`，创建：
+- React/Vue组件（推荐使用项目技术栈）
+- Mock数据和Mock API
+- 基本交互逻辑
+
+### 3. 完成并交接
+```bash
+/trellis:handoff
+```
+
+产出自动进入 `deliverables/prototypes/{task-id}/`
+
+---
+
+## 原型代码标准
+
+### 必需要素
+
+#### 1. 可运行性
+- ✅ 原型可以直接 `npm run dev` 运行
+- ✅ 所有交互可以点击/操作
+- ✅ 使用Mock数据模拟真实数据流
+
+#### 2. Mock数据规范
+```typescript
+// Mock数据应该结构清晰，易于替换
+// ✅ 推荐：集中管理Mock
+// src/mocks/user.mock.ts
+export const mockUser = {
+  id: "mock-user-1",
+  name: "张三",
+  email: "zhangsan@example.com"
+};
+
+// ❌ 避免：硬编码分散各处
+const user = { name: "张三" };  // 不易查找和替换
+```
+
+#### 3. Mock API位置标注
+```typescript
+// ✅ 使用清晰的TODO注释
+const handleLogin = async (email: string, password: string) => {
+  // TODO: [Frontend] 替换为真实API调用 /api/auth/login
+  return new Promise(resolve => {
+    setTimeout(() => resolve(mockUser), 1000);
+  });
+};
+```
+
+### 组件结构规范
+
+**推荐分层**：
+```
+src/
+├── pages/           # 页面级组件
+│   └── LoginPage.tsx
+├── components/      # 复用组件
+│   ├── LoginForm.tsx
+│   └── SocialLoginButtons.tsx
+├── mocks/           # Mock数据
+│   └── auth.mock.ts
+└── types/           # TypeScript类型定义
+    └── user.ts
+```
+
+### 样式规范
+
+根据项目技术栈选择：
+- **Tailwind CSS** - 推荐用于快速原型
+- **CSS Modules** - 适合组件隔离
+- **Styled Components** - 适合复杂主题
+
+**原则**：样式应该**接近最终效果**，但不必完美实现所有细节。
+
+---
+
+## HANDOFF文档要点
+
+AI生成的 `HANDOFF.md` 应包含：
+
+### 设计说明
+- 整体布局思路
+- 主要组件设计理由
+- 交互流程说明
+
+### 组件结构
+```
+App
+├── LoginPage
+│   ├── LoginForm       （核心表单）
+│   │   ├── EmailInput
+│   │   └── PasswordInput
+│   └── SocialLoginButtons （第三方登录）
+```
+
+### Mock数据说明
+```typescript
+// 清楚标注每个Mock数据的位置和用途
+const mockUser = { ... };  // 位置：src/mocks/auth.mock.ts:10
+```
+
+### 需要Frontend补充的逻辑
+
+**明确列出**：
+1. **API集成点** - 哪些函数需要替换为真实API
+   - 文件：`LoginPage.tsx:45`
+   - Mock: `mockLogin()`
+   - 真实API: `POST /api/auth/login`
+
+2. **状态管理** - 需要接入全局状态的部分
+   - 用户登录状态
+   - Token存储和刷新
+
+3. **错误处理** - 需要完善的错误场景
+   - 网络超时
+   - 登录失败（密码错误、账号不存在）
+   - 表单验证错误
+
+### 特别注意事项
+
+**需要保留的设计**：
+- 特定的交互动画
+- 品牌色使用
+- 布局细节
+
+**可以优化的部分**：
+- 性能优化（lazy loading等）
+- 代码结构调整
+- 组件拆分
+
+---
+
+## 质量检查清单
+
+在执行 `/trellis:handoff` 前，确保：
+
+- [ ] 原型可运行（npm run dev 无报错）
+- [ ] 所有交互可操作（按钮、表单、链接）
+- [ ] Mock数据结构合理（接近真实API）
+- [ ] TODO注释清晰（标注需要替换的Mock）
+- [ ] 组件命名语义化
+- [ ] 已测试关键交互流程
+- [ ] HANDOFF文档包含所有关键信息
+
+---
+
+## Mock数据最佳实践
+
+### 1. 集中管理
+```typescript
+// src/mocks/index.ts
+export { mockUser, mockUserList } from './user.mock';
+export { mockProduct, mockProductList } from './product.mock';
+```
+
+### 2. 类型安全
+```typescript
+// src/types/user.ts
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+// src/mocks/user.mock.ts
+import type { User } from '../types/user';
+
+export const mockUser: User = {
+  id: "1",
+  name: "张三",
+  email: "zhangsan@example.com"
+};
+```
+
+### 3. 真实性
+```typescript
+// ✅ Mock数据应该接近真实场景
+export const mockUserList: User[] = [
+  { id: "1", name: "张三", email: "zhangsan@example.com" },
+  { id: "2", name: "李四", email: "lisi@example.com" },
+  // ... 10-20条数据，测试分页、滚动等
+];
+
+// ❌ 避免过于简化
+export const mockUserList = [{ id: "1", name: "test" }];
+```
+
+---
+
+## 常见问题
+
+### Q: 原型需要实现所有PRD功能吗？
+A: 实现核心流程即可。边缘场景可以用TODO注释标注，交给Frontend补充。
+
+### Q: Mock数据应该多详细？
+A: 结构完整、字段真实。数量上：列表型数据10-20条，单条数据包含所有字段。
+
+### Q: 需要实现响应式设计吗？
+A: 根据PRD要求。如果PRD要求多端适配，原型应体现主要断点。
+
+### Q: 如何处理复杂交互？
+A: 核心交互必须可操作，动画和过渡效果可简化。在HANDOFF中说明预期效果。
+
+---
+
+## 参考资料
+
+- [原型代码指南](./prototype-guidelines.md)
+- [Mock数据标准](./mock-data-standards.md)
+- [组件设计模式](./component-patterns.md)

package/dist/templates/trellis/spec/roles/designer/mock-data-standards.md

@@ -0,0 +1,481 @@
+# Mock 数据标准
+
+> Designer 角色创建和管理 Mock 数据的规范
+
+---
+
+## 核心原则
+
+Mock 数据应该：
+1. **结构完整** - 包含所有必需字段
+2. **类型安全** - 符合 TypeScript 类型定义
+3. **接近真实** - 数据内容符合真实场景
+4. **易于替换** - Frontend 可以快速找到并替换
+
+---
+
+## 数据组织规范
+
+### 目录结构
+
+```
+src/mocks/
+├── index.ts          # 统一导出
+├── auth.mock.ts      # 认证相关
+├── user.mock.ts      # 用户数据
+├── product.mock.ts   # 产品数据
+└── order.mock.ts     # 订单数据
+```
+
+### 统一导出
+
+```typescript
+// src/mocks/index.ts
+export * from './auth.mock';
+export * from './user.mock';
+export * from './product.mock';
+export * from './order.mock';
+```
+
+**使用方式**：
+```typescript
+import { mockUser, mockProductList } from '@/mocks';
+```
+
+---
+
+## 类型定义规范
+
+### 1. 类型优先
+
+先定义类型，再创建 Mock 数据：
+
+```typescript
+// src/types/user.ts
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+  avatar?: string;
+  role: 'admin' | 'user' | 'guest';
+  createdAt: string;
+  updatedAt: string;
+}
+
+// src/mocks/user.mock.ts
+import type { User } from '@/types/user';
+
+export const mockUser: User = {
+  id: "user-001",
+  name: "张三",
+  email: "zhangsan@example.com",
+  avatar: "https://i.pravatar.cc/150?img=1",
+  role: "user",
+  createdAt: "2026-01-01T00:00:00Z",
+  updatedAt: "2026-02-01T10:30:00Z"
+};
+```
+
+### 2. 可选字段处理
+
+对于可选字段，提供有值和无值两种 Mock：
+
+```typescript
+export const mockUserWithAvatar: User = {
+  id: "user-001",
+  name: "张三",
+  email: "zhangsan@example.com",
+  avatar: "https://i.pravatar.cc/150?img=1",
+  role: "user",
+  createdAt: "2026-01-01T00:00:00Z",
+  updatedAt: "2026-02-01T10:30:00Z"
+};
+
+export const mockUserWithoutAvatar: User = {
+  id: "user-002",
+  name: "李四",
+  email: "lisi@example.com",
+  // avatar: undefined (可选字段，不提供)
+  role: "user",
+  createdAt: "2026-01-02T00:00:00Z",
+  updatedAt: "2026-02-02T11:00:00Z"
+};
+```
+
+---
+
+## 数据真实性规范
+
+### 1. 字段内容要求
+
+| 字段类型 | Mock 数据要求 | 示例 |
+|---------|-------------|------|
+| **ID** | 语义化前缀 + 数字 | `user-001`, `prod-A123` |
+| **姓名** | 常见中文姓名 | 张三、李四、王五 |
+| **邮箱** | 真实邮箱格式 | `zhangsan@example.com` |
+| **URL** | 可访问的占位图 | `https://via.placeholder.com/150` |
+| **日期** | ISO 8601 格式 | `2026-01-01T00:00:00Z` |
+| **枚举** | 覆盖所有可能值 | `'pending' | 'approved' | 'rejected'` |
+
+### 2. 数量要求
+
+**单条数据**：包含所有字段
+
+```typescript
+export const mockProduct: Product = {
+  id: "prod-001",
+  name: "iPhone 15 Pro",
+  description: "苹果最新旗舰手机，搭载A17 Pro芯片",
+  price: 7999,
+  stock: 50,
+  category: "电子产品",
+  tags: ["手机", "苹果", "5G"],
+  images: [
+    "https://via.placeholder.com/400x300",
+    "https://via.placeholder.com/400x300"
+  ],
+  createdAt: "2026-01-15T10:30:00Z"
+};
+```
+
+**列表数据**：10-20 条，覆盖边缘场景
+
+```typescript
+export const mockProductList: Product[] = [
+  {
+    id: "prod-001",
+    name: "iPhone 15 Pro",
+    price: 7999,
+    stock: 50,
+    category: "电子产品",
+    // ...
+  },
+  {
+    id: "prod-002",
+    name: "MacBook Pro 16\"",
+    price: 19999,
+    stock: 20,
+    category: "电脑",
+    // ...
+  },
+  {
+    id: "prod-003",
+    name: "AirPods Pro 2",
+    price: 1899,
+    stock: 0, // ✅ 边缘场景：库存为0
+    category: "配件",
+    // ...
+  },
+  // ... 继续到 10-20 条
+];
+```
+
+### 3. 边缘场景覆盖
+
+Mock 数据应该包含边缘场景：
+
+```typescript
+export const mockOrderList: Order[] = [
+  {
+    id: "order-001",
+    status: "pending",    // 待支付
+    total: 7999,
+    // ...
+  },
+  {
+    id: "order-002",
+    status: "paid",       // 已支付
+    total: 19999,
+    // ...
+  },
+  {
+    id: "order-003",
+    status: "cancelled",  // 已取消
+    total: 1899,
+    // ...
+  },
+  {
+    id: "order-004",
+    status: "refunded",   // 已退款
+    total: 5999,
+    // ...
+  },
+];
+```
+
+---
+
+## API 响应格式规范
+
+### 1. 统一响应结构
+
+定义统一的 API 响应格式：
+
+```typescript
+// src/types/api.ts
+export interface ApiResponse<T> {
+  code: number;
+  message: string;
+  data: T;
+}
+
+export interface ApiListResponse<T> {
+  code: number;
+  message: string;
+  data: {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+  };
+}
+```
+
+### 2. Mock API 响应
+
+```typescript
+// src/mocks/auth.mock.ts
+import type { ApiResponse } from '@/types/api';
+import type { User } from '@/types/user';
+
+export const mockLoginResponse: ApiResponse<{ user: User; token: string }> = {
+  code: 200,
+  message: "登录成功",
+  data: {
+    user: mockUser,
+    token: "mock-jwt-token-xxx"
+  }
+};
+
+export const mockLoginErrorResponse: ApiResponse<null> = {
+  code: 401,
+  message: "邮箱或密码错误",
+  data: null
+};
+```
+
+### 3. 分页数据 Mock
+
+```typescript
+export const mockProductListResponse: ApiListResponse<Product> = {
+  code: 200,
+  message: "成功",
+  data: {
+    items: mockProductList.slice(0, 10), // 第一页
+    total: 50,
+    page: 1,
+    pageSize: 10
+  }
+};
+```
+
+---
+
+## Mock 函数规范
+
+### 1. Mock API 函数
+
+每个 API 端点对应一个 Mock 函数：
+
+```typescript
+// src/mocks/api/auth.mock.ts
+import type { User } from '@/types/user';
+import { mockUser, mockLoginErrorResponse } from '@/mocks/auth.mock';
+
+/**
+ * Mock 登录 API
+ * TODO: [Frontend] 替换为真实API调用 POST /api/auth/login
+ */
+export const mockLoginAPI = async (
+  email: string,
+  password: string
+): Promise<{ user: User; token: string }> => {
+  return new Promise((resolve, reject) => {
+    setTimeout(() => {
+      // 模拟登录失败
+      if (email === "fail@example.com") {
+        reject(new Error(mockLoginErrorResponse.message));
+      } else {
+        resolve({
+          user: mockUser,
+          token: "mock-jwt-token-xxx"
+        });
+      }
+    }, 1000); // 模拟网络延迟
+  });
+};
+```
+
+### 2. Mock 函数文档注释
+
+必须包含：
+- 功能说明
+- TODO 标记（指明需要 Frontend 替换）
+- 真实 API 路径
+
+```typescript
+/**
+ * Mock 获取用户列表 API
+ *
+ * TODO: [Frontend] 替换为真实API调用 GET /api/users?page=1&pageSize=10
+ *
+ * @param page 页码
+ * @param pageSize 每页数量
+ * @returns 用户列表响应
+ */
+export const mockGetUsersAPI = async (
+  page: number = 1,
+  pageSize: number = 10
+): Promise<ApiListResponse<User>> => {
+  // Mock 实现
+};
+```
+
+---
+
+## 占位资源规范
+
+### 1. 图片占位
+
+推荐使用的占位图服务：
+
+| 服务 | URL 格式 | 示例 |
+|------|---------|------|
+| **Placeholder.com** | `https://via.placeholder.com/{width}x{height}` | `https://via.placeholder.com/400x300` |
+| **Pravatar** | `https://i.pravatar.cc/{size}?img={id}` | `https://i.pravatar.cc/150?img=1` |
+| **Picsum** | `https://picsum.photos/{width}/{height}` | `https://picsum.photos/400/300` |
+
+**示例**：
+```typescript
+export const mockProduct: Product = {
+  id: "prod-001",
+  name: "iPhone 15 Pro",
+  images: [
+    "https://via.placeholder.com/400x300?text=iPhone+15+Pro",
+    "https://via.placeholder.com/400x300?text=Detail+View",
+  ],
+  // ...
+};
+```
+
+### 2. 头像占位
+
+```typescript
+export const mockUser: User = {
+  id: "user-001",
+  name: "张三",
+  avatar: "https://i.pravatar.cc/150?img=1", // 固定头像 ID
+  // ...
+};
+```
+
+---
+
+## Mock 数据维护规范
+
+### 1. 文件大小控制
+
+单个 Mock 文件不超过 **300 行**
+
+**✅ 推荐**：按功能拆分
+```
+src/mocks/
+├── user.mock.ts        # 用户相关
+├── product.mock.ts     # 产品相关
+└── order.mock.ts       # 订单相关
+```
+
+**❌ 避免**：所有 Mock 放在一个文件
+```
+src/mocks/
+└── data.mock.ts        # 1000+ 行，难以维护
+```
+
+### 2. 更新频率
+
+- **需求变更时**：同步更新 Mock 数据结构
+- **Frontend 反馈时**：补充缺失字段或场景
+
+### 3. 删除时机
+
+**不要删除 Mock 数据**！Frontend 需要用于测试。
+
+建议：
+- 保留在 `src/mocks/` 目录
+- Frontend 会将其移动到 `__tests__/mocks/` 用于测试
+
+---
+
+## 检查清单
+
+在交接给 Frontend 前，确保：
+
+- [ ] 所有 Mock 数据符合 TypeScript 类型定义
+- [ ] 列表数据包含 10-20 条记录
+- [ ] 覆盖主要边缘场景（空值、错误状态等）
+- [ ] Mock API 函数包含 TODO 注释
+- [ ] 占位图片 URL 可访问
+- [ ] 日期格式统一为 ISO 8601
+- [ ] 统一导出到 `src/mocks/index.ts`
+
+---
+
+## 常见问题
+
+### Q: Mock 数据量应该多大？
+A:
+- **单条数据**：完整包含所有字段
+- **列表数据**：10-20 条，覆盖边缘场景
+- **分页数据**：模拟 total 为 50-100，但只返回当前页
+
+### Q: 如何处理关联数据？
+A: 使用外键 ID 关联，但 Mock 数据中可以直接嵌套对象
+
+```typescript
+// ✅ 推荐：嵌套完整对象（原型阶段方便显示）
+export const mockOrder: Order = {
+  id: "order-001",
+  user: mockUser,  // 嵌套完整用户对象
+  products: mockProductList.slice(0, 2),
+  // ...
+};
+
+// Frontend 会改为：
+export const mockOrder: Order = {
+  id: "order-001",
+  userId: "user-001",  // 只保留 ID
+  productIds: ["prod-001", "prod-002"],
+  // ...
+};
+```
+
+### Q: Mock 数据需要模拟权限吗？
+A: 不需要。权限验证由 Frontend 实现。
+
+### Q: 如何模拟 API 错误？
+A: 提供特定输入触发错误
+
+```typescript
+export const mockLoginAPI = async (email: string, password: string) => {
+  // TODO: [Frontend] 替换为真实API调用
+  return new Promise((resolve, reject) => {
+    setTimeout(() => {
+      if (email === "error@example.com") {
+        reject(new Error("网络错误"));
+      } else if (password === "wrong") {
+        reject(new Error("密码错误"));
+      } else {
+        resolve({ user: mockUser, token: "xxx" });
+      }
+    }, 1000);
+  });
+};
+```
+
+---
+
+## 相关文档
+
+- [原型代码指南](./prototype-guidelines.md)
+- [Designer 工作规范](./index.md)
+- [TypeScript 类型规范](../../frontend/type-safety.md)