@jahanxu/trellis 0.4.2 → 0.5.0

package/dist/templates/trellis/scripts/handoff_generator.py

@@ -1,380 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-HANDOFF Document Generator
-
-Generates role-specific handoff documents for three-role collaboration.
-
-Templates:
-- PM: Summarize PRD core requirements
-- Designer: Design rationale + Mock data locations
-- Frontend: Implementation details + API integration points
-"""
-
-import sys
-from datetime import datetime
-from pathlib import Path
-from typing import Optional
-
-# Add parent directory to path for imports
-sys.path.insert(0, str(Path(__file__).parent))
-
-from common.paths import get_developer, get_repo_root
-
-# =============================================================================
-# Template Functions
-# =============================================================================
-
-
-def generate_handoff_pm(task_dir: Path, task_data: dict) -> str:
-    """Generate HANDOFF.md for PM role."""
-    task_id = task_data.get("id", "unknown")
-    title = task_data.get("title", "未命名任务")
-    developer = get_developer(get_repo_root()) or "unknown"
-    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-
-    # Read PRD content
-    prd_file = task_dir / "prd.md"
-    prd_content = ""
-    if prd_file.exists():
-        prd_content = prd_file.read_text(encoding="utf-8")
-
-    template = f"""# {title} - 需求交接文档
-
-## 📋 任务信息
-- **功能ID**: {task_id}
-- **功能名称**: {title}
-- **完成人**: {developer}
-- **完成时间**: {now}
-
-## 🎯 核心需求
-
-**请AI根据PRD总结核心要点（2-3段）**
-
-PRD位置：`{task_dir.name}/prd.md`
-
-## 📄 产出文件
-
-- `prd.md` - 产品需求文档
-- `user-stories.md` - 用户故事（如有）
-- 其他补充文档（如有）
-
-## 🔑 关键设计要点
-
-**请Designer重点关注**：
-
-1. [TODO: AI填写关键功能点1]
-2. [TODO: AI填写关键功能点2]
-3. [TODO: AI填写关键功能点3]
-
-## ⚠️ 特别注意事项
-
-**设计实现时需要注意**：
-
-- [TODO: AI填写注意事项1 - 如UI布局要求]
-- [TODO: AI填写注意事项2 - 如交互特殊要求]
-- [TODO: AI填写注意事项3 - 如性能要求]
-
-## 🔗 相关资源
-
-- 设计稿: [TODO: 填写Figma链接]
-- API文档: [TODO: 填写API文档链接]
-- 参考资料: [TODO: 填写其他资源]
-
-## 📞 联系方式
-
-如有疑问，请联系 {developer}
-
----
-
-## 附录：PRD内容摘要
-
-```
-{prd_content[:500]}...
-```
-
-> 完整PRD请查看 `{task_dir.name}/prd.md`
-"""
-
-    return template
-
-
-def generate_handoff_designer(task_dir: Path, task_data: dict, source_data: Optional[dict] = None) -> str:
-    """Generate HANDOFF.md for Designer role."""
-    task_id = task_data.get("id", "unknown")
-    title = task_data.get("title", "未命名任务")
-    developer = get_developer(get_repo_root()) or "unknown"
-    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-
-    # Get upstream info
-    based_on = "N/A"
-    if source_data and "based_on" in source_data:
-        based_on = f"{source_data['based_on']['type']}/{source_data['based_on']['id']}"
-
-    template = f"""# {title} - 原型交接文档
-
-## 📋 任务信息
-- **功能ID**: {task_id}
-- **基于需求**: {based_on}
-- **完成人**: {developer}
-- **完成时间**: {now}
-
-## 🎨 设计说明
-
-**请AI总结设计思路（2-3段）**：
-
-- 整体布局思路
-- 主要组件设计
-- 交互流程设计
-
-## 📄 产出文件
-
-**请列出所有组件文件**：
-
-- `[ComponentName].tsx` - 组件说明
-- `[ComponentName].tsx` - 组件说明
-- ...
-
-## 🧩 组件结构
-
-```
-[TODO: AI绘制组件树]
-App
-├── LoginPage
-│   ├── LoginForm
-│   │   ├── EmailInput
-│   │   └── PasswordInput
-│   └── SocialLoginButtons
-└── ...
-```
-
-## 💾 Mock数据说明
-
-**当前使用的Mock数据**：
-
-```typescript
-// [TODO: AI填写Mock数据示例]
-const mockUser = {{
-  id: "1",
-  email: "test@example.com",
-  name: "Test User"
-}};
-
-// Mock登录逻辑位置：[TODO: 文件名:行号]
-const handleLogin = async () => {{
-  // TODO: 替换为真实API调用
-  setTimeout(() => setUser(mockUser), 1000);
-}};
-```
-
-## 🔄 需要Frontend补充的逻辑
-
-**请Frontend开发重点处理**：
-
-1. **API集成** - 替换Mock为真实API调用
-   - 位置: [TODO: 文件名:行号]
-   - 需要调用: [TODO: API端点]
-
-2. **错误处理** - 添加网络错误和业务错误处理
-   - 网络超时
-   - 登录失败提示
-   - 表单验证错误
-
-3. **状态管理** - 添加全局状态管理（如需要）
-   - 用户登录状态
-   - Token存储
-
-4. **持久化** - 实现"记住我"功能
-   - localStorage/Cookie
-   - Token刷新逻辑
-
-## ⚠️ 特别注意事项
-
-**保留以下设计**：
-
-- [TODO: 需要保留的交互细节]
-- [TODO: 需要保留的UI元素]
-- [TODO: 需要保留的样式]
-
-**可以优化的部分**：
-
-- [TODO: 可以优化的性能点]
-- [TODO: 可以调整的代码结构]
-
-## 📞 联系方式
-
-如有疑问，请联系 {developer}
-"""
-
-    return template
-
-
-def generate_handoff_frontend(task_dir: Path, task_data: dict, source_data: Optional[dict] = None) -> str:
-    """Generate HANDOFF.md for Frontend role."""
-    task_id = task_data.get("id", "unknown")
-    title = task_data.get("title", "未命名任务")
-    developer = get_developer(get_repo_root()) or "unknown"
-    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-
-    # Get upstream info
-    based_on = "N/A"
-    if source_data and "based_on" in source_data:
-        based_on = f"{source_data['based_on']['type']}/{source_data['based_on']['id']}"
-
-    template = f"""# {title} - 生产代码交接文档
-
-## 📋 任务信息
-- **功能ID**: {task_id}
-- **基于原型**: {based_on}
-- **完成人**: {developer}
-- **完成时间**: {now}
-
-## 🎯 实现总结
-
-**请AI总结实现要点（2-3段）**：
-
-- 主要功能实现
-- API集成情况
-- 状态管理方案
-
-## 📄 产出文件
-
-**请列出修改的文件**：
-
-- `[FileName].tsx` - 修改说明
-- `[FileName].ts` - 修改说明
-- ...
-
-## 🔌 API集成
-
-**已集成的API**：
-
-| 端点 | 方法 | 用途 | 位置 |
-|------|------|------|------|
-| [TODO] | POST | [TODO] | [TODO:文件:行号] |
-
-## 🧪 测试说明
-
-**已添加的测试**：
-
-- [ ] 单元测试: [TODO: 测试文件]
-- [ ] 集成测试: [TODO: 测试文件]
-- [ ] E2E测试: [TODO: 测试文件]
-
-**测试覆盖率**: [TODO: X%]
-
-## 🐛 已知问题
-
-**遗留问题**（如有）：
-
-1. [TODO: 问题描述]
-   - 影响: [TODO]
-   - 计划修复时间: [TODO]
-
-## ⚠️ 部署注意事项
-
-**环境变量**：
-
-```bash
-# [TODO: 列出需要的环境变量]
-VITE_API_BASE_URL=https://api.example.com
-```
-
-**依赖项**：
-
-- [TODO: 新增的npm包]
-
-**数据库迁移**（如需要）：
-
-- [TODO: 迁移脚本]
-
-## 📞 联系方式
-
-如有疑问，请联系 {developer}
-"""
-
-    return template
-
-
-# =============================================================================
-# Main Function
-# =============================================================================
-
-
-def generate_handoff(task_dir: Path, role: str, task_data: dict, source_data: Optional[dict] = None) -> str:
-    """Generate HANDOFF.md based on role.
-
-    Args:
-        task_dir: Task directory path
-        role: Role type (pm, designer, frontend)
-        task_data: Task metadata from task.json
-        source_data: Source reference from source.json (optional)
-
-    Returns:
-        HANDOFF.md content
-    """
-    generators = {
-        "pm": generate_handoff_pm,
-        "designer": generate_handoff_designer,
-        "frontend": generate_handoff_frontend,
-    }
-
-    if role not in generators:
-        raise ValueError(f"Invalid role: {role}. Must be one of {list(generators.keys())}")
-
-    # Designer and Frontend can use source_data
-    if role in ("designer", "frontend"):
-        return generators[role](task_dir, task_data, source_data)
-    else:
-        return generators[role](task_dir, task_data)
-
-
-# =============================================================================
-# CLI Entry Point
-# =============================================================================
-
-
-def main() -> int:
-    """CLI entry point for testing."""
-    import argparse
-    import json
-
-    parser = argparse.ArgumentParser(description="HANDOFF Document Generator")
-    parser.add_argument("task_dir", help="Task directory path")
-    parser.add_argument("role", choices=["pm", "designer", "frontend"], help="Role type")
-    parser.add_argument("--output", "-o", help="Output file path (default: HANDOFF.md in task dir)")
-
-    args = parser.parse_args()
-
-    task_dir = Path(args.task_dir)
-    if not task_dir.exists():
-        print(f"Error: Task directory not found: {task_dir}", file=sys.stderr)
-        return 1
-
-    # Read task.json
-    task_json = task_dir / "task.json"
-    if not task_json.exists():
-        print(f"Error: task.json not found in {task_dir}", file=sys.stderr)
-        return 1
-
-    task_data = json.loads(task_json.read_text(encoding="utf-8"))
-
-    # Read source.json (optional)
-    source_json = task_dir / "source.json"
-    source_data = None
-    if source_json.exists():
-        source_data = json.loads(source_json.read_text(encoding="utf-8"))
-
-    # Generate HANDOFF
-    handoff_content = generate_handoff(task_dir, args.role, task_data, source_data)
-
-    # Output
-    output_file = Path(args.output) if args.output else task_dir / "HANDOFF.md"
-    output_file.write_text(handoff_content, encoding="utf-8")
-
-    print(f"✓ Generated HANDOFF.md: {output_file}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

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

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