@jahanxu/trellis 0.4.2 → 0.5.1

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

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