@jahanxu/trellis 0.4.1

package/dist/templates/trellis/spec/roles/designer/prototype-guidelines.md

@@ -0,0 +1,429 @@
+# 原型代码开发指南
+
+> Designer 角色创建可运行原型的详细指南
+
+---
+
+## 核心原则
+
+原型代码的目标是：
+1. **可运行** - Frontend 可以直接启动并看到效果
+2. **易替换** - Mock 数据和 API 位置清晰，Frontend 可以快速替换
+3. **接近真实** - 布局、交互、数据结构接近最终产品
+
+---
+
+## 原型结构规范
+
+### 推荐目录结构
+
+```
+task-dir/
+├── src/
+│   ├── pages/              # 页面组件
+│   │   └── LoginPage.tsx
+│   ├── components/         # 复用组件
+│   │   ├── LoginForm.tsx
+│   │   └── SocialLoginButtons.tsx
+│   ├── mocks/              # Mock数据（集中管理）
+│   │   └── auth.mock.ts
+│   └── types/              # TypeScript类型定义
+│       └── user.ts
+├── package.json
+├── tsconfig.json
+└── README.md               # 原型说明文档
+```
+
+### 文件命名规范
+
+- **组件文件**：大驼峰命名 `LoginForm.tsx`
+- **Mock 文件**：`*.mock.ts` 或 `*.mock.tsx`
+- **类型文件**：小驼峰或大驼峰 `user.ts` 或 `User.ts`
+
+---
+
+## Mock 数据规范
+
+### 1. 集中管理
+
+**✅ 推荐**：所有 Mock 数据放在 `src/mocks/` 目录
+
+```typescript
+// src/mocks/auth.mock.ts
+import type { User } from '../types/user';
+
+export const mockUser: User = {
+  id: "mock-user-1",
+  name: "张三",
+  email: "zhangsan@example.com",
+  avatar: "https://via.placeholder.com/150",
+  createdAt: "2026-01-01T00:00:00Z"
+};
+
+export const mockUserList: User[] = [
+  mockUser,
+  {
+    id: "mock-user-2",
+    name: "李四",
+    email: "lisi@example.com",
+    avatar: "https://via.placeholder.com/150",
+    createdAt: "2026-01-02T00:00:00Z"
+  },
+  // ... 10-20 条数据，模拟真实场景
+];
+```
+
+**❌ 避免**：在组件中硬编码 Mock 数据
+
+```typescript
+// ❌ 不推荐
+const LoginPage = () => {
+  const [user, setUser] = useState({ name: "测试用户" });
+  // ...
+};
+```
+
+### 2. 类型安全
+
+所有 Mock 数据必须符合类型定义：
+
+```typescript
+// src/types/user.ts
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+  avatar?: string;
+  createdAt: string;
+}
+
+// src/mocks/auth.mock.ts
+import type { User } from '../types/user';
+
+// ✅ TypeScript 会检查类型
+export const mockUser: User = {
+  id: "1",
+  name: "张三",
+  email: "zhangsan@example.com",
+  createdAt: "2026-01-01T00:00:00Z"
+};
+```
+
+### 3. 真实性原则
+
+Mock 数据应该接近真实场景：
+
+**✅ 推荐**：
+```typescript
+export const mockProductList = [
+  {
+    id: "prod-001",
+    name: "iPhone 15 Pro",
+    price: 7999,
+    stock: 50,
+    category: "电子产品",
+    tags: ["手机", "苹果", "5G"],
+    createdAt: "2026-01-15T10:30:00Z"
+  },
+  // ... 10-20 条，覆盖各种场景
+];
+```
+
+**❌ 避免**：
+```typescript
+export const mockProductList = [
+  { id: "1", name: "test", price: 100 }
+];
+```
+
+---
+
+## Mock API 规范
+
+### 1. API 位置标注
+
+使用清晰的 TODO 注释标注需要替换的位置：
+
+```typescript
+// ✅ 推荐格式
+const handleLogin = async (email: string, password: string) => {
+  // TODO: [Frontend] 替换为真实API调用 POST /api/auth/login
+  return new Promise<User>((resolve) => {
+    setTimeout(() => resolve(mockUser), 1000);
+  });
+};
+```
+
+**TODO 注释格式**：
+- `[Frontend]` - 标明需要 Frontend 角色处理
+- API 方法和路径 - `POST /api/auth/login`
+- 文件位置 - 自动通过 grep 查找
+
+### 2. API 响应模拟
+
+Mock API 应该模拟真实 API 的行为：
+
+```typescript
+// ✅ 推荐：模拟延迟、成功/失败场景
+const mockLoginAPI = async (email: string, password: string): Promise<User> => {
+  // TODO: [Frontend] 替换为真实API调用 POST /api/auth/login
+  return new Promise((resolve, reject) => {
+    setTimeout(() => {
+      // 模拟登录失败
+      if (email === "fail@example.com") {
+        reject(new Error("邮箱或密码错误"));
+      } else {
+        resolve(mockUser);
+      }
+    }, 1000); // 模拟网络延迟
+  });
+};
+```
+
+### 3. 状态管理
+
+简单的原型可以使用 React 内置状态：
+
+```typescript
+// ✅ 推荐：简单原型使用 useState
+const LoginPage = () => {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleLogin = async (email: string, password: string) => {
+    setLoading(true);
+    setError(null);
+    try {
+      const user = await mockLoginAPI(email, password);
+      setUser(user);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    // ... JSX
+  );
+};
+```
+
+**注意**：复杂状态（全局用户状态、购物车等）在原型阶段可以简化，Frontend 会补充完整的状态管理方案。
+
+---
+
+## 组件设计规范
+
+### 1. 组件拆分原则
+
+**按功能拆分**：
+```
+LoginPage                 （页面组件）
+├── LoginForm            （表单逻辑）
+│   ├── EmailInput       （输入组件）
+│   └── PasswordInput    （输入组件）
+└── SocialLoginButtons   （第三方登录）
+```
+
+**拆分标准**：
+- 单一职责：每个组件只负责一个功能
+- 可复用性：通用组件（如 Button、Input）可以被多个页面使用
+- 复杂度控制：组件文件不超过 200 行
+
+### 2. Props 接口定义
+
+使用 TypeScript 定义清晰的 Props 接口：
+
+```typescript
+interface LoginFormProps {
+  onSubmit: (email: string, password: string) => void;
+  loading?: boolean;
+  error?: string;
+}
+
+const LoginForm: React.FC<LoginFormProps> = ({ onSubmit, loading, error }) => {
+  // ...
+};
+```
+
+### 3. 组件命名规范
+
+- 页面组件：`XxxPage.tsx` （如 `LoginPage.tsx`）
+- 功能组件：`XxxForm.tsx`、`XxxList.tsx`
+- UI 组件：`Button.tsx`、`Input.tsx`
+
+---
+
+## 样式规范
+
+### 推荐技术栈
+
+根据项目选择：
+
+| 技术栈 | 适用场景 | 优点 |
+|--------|---------|------|
+| **Tailwind CSS** | 快速原型 | 无需写 CSS 文件，开发快 |
+| **CSS Modules** | 组件隔离 | 样式作用域明确 |
+| **Styled Components** | 复杂主题 | 动态样式、主题切换 |
+
+### Tailwind CSS 示例
+
+```tsx
+// ✅ 推荐：使用 Tailwind
+const LoginButton = () => (
+  <button className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
+    登录
+  </button>
+);
+```
+
+### 样式原则
+
+1. **接近最终效果**：布局、颜色、字体应该接近 PRD 要求
+2. **响应式可选**：根据 PRD 要求决定是否实现响应式
+3. **细节可简化**：动画、过渡效果可以简化，在 HANDOFF 中说明预期效果
+
+---
+
+## 交互实现规范
+
+### 必须实现的交互
+
+- [ ] **表单输入**：所有输入框可以输入
+- [ ] **按钮点击**：所有按钮有点击事件
+- [ ] **链接跳转**：所有链接可以跳转（或模拟跳转）
+- [ ] **加载状态**：提交表单时显示加载状态
+- [ ] **错误提示**：模拟错误场景并显示错误信息
+
+### 可以简化的交互
+
+- **复杂动画**：可以用简单过渡替代
+- **拖拽排序**：可以用点击上下移动替代
+- **实时搜索**：可以用按钮触发搜索替代
+
+### 交互示例
+
+```tsx
+const LoginPage = () => {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError(null);
+
+    try {
+      await mockLoginAPI(email, password);
+      // 跳转到首页（原型阶段可以 alert 或 console.log）
+      alert('登录成功！');
+    } catch (err) {
+      setError('登录失败，请检查邮箱和密码');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="邮箱"
+        disabled={loading}
+      />
+      <input
+        type="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        placeholder="密码"
+        disabled={loading}
+      />
+      {error && <p className="text-red-500">{error}</p>}
+      <button type="submit" disabled={loading}>
+        {loading ? '登录中...' : '登录'}
+      </button>
+    </form>
+  );
+};
+```
+
+---
+
+## 原型文档要求
+
+### README.md 必须包含
+
+```markdown
+# [功能名称] 原型
+
+## 功能说明
+简要描述此原型实现的功能
+
+## 启动方式
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Mock 数据位置
+- 用户数据：src/mocks/user.mock.ts
+- 产品数据：src/mocks/product.mock.ts
+
+## 需要 Frontend 补充的功能
+1. 替换 Mock API 为真实 API（位置：src/pages/LoginPage.tsx:45）
+2. 接入全局用户状态管理
+3. 完善错误处理（网络超时、权限验证）
+
+## 技术栈
+- React 18
+- TypeScript 5
+- Tailwind CSS 3
+- Vite 5
+```
+
+---
+
+## 检查清单
+
+在完成原型前，确保：
+
+- [ ] 项目可以正常启动（`npm run dev` 无报错）
+- [ ] 所有交互可以操作（按钮、输入框、链接）
+- [ ] Mock 数据结构合理（符合类型定义）
+- [ ] Mock API 位置已用 TODO 注释标注
+- [ ] 组件命名语义化
+- [ ] README.md 包含必要信息
+- [ ] 已测试关键交互流程（登录、提交、错误处理）
+
+---
+
+## 常见问题
+
+### Q: 原型需要实现所有 PRD 功能吗？
+A: 实现**核心流程**即可。边缘场景可以用 TODO 注释标注，交给 Frontend 补充。
+
+### Q: 原型需要完美像素级还原设计稿吗？
+A: 不需要。布局结构正确、颜色接近即可。细节由 Frontend 优化。
+
+### Q: 如何处理复杂状态管理（Redux/Zustand）？
+A: 原型阶段可以简化为 `useState` 或 `useContext`。在 HANDOFF 中说明需要 Frontend 接入全局状态。
+
+### Q: 原型需要写单元测试吗？
+A: 不需要。测试由 Frontend 补充。
+
+### Q: 原型需要处理所有错误场景吗？
+A: 只需要处理**主要错误场景**（如登录失败、网络错误）。边缘场景交给 Frontend。
+
+---
+
+## 相关文档
+
+- [Designer 工作规范](./index.md)
+- [Mock 数据标准](./mock-data-standards.md)
+- [前端组件规范](../frontend/component-guidelines.md)