@jahanxu/trellis 0.4.2 → 0.5.1

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

@@ -1,429 +0,0 @@
-# 原型代码开发指南
-
-> 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)