1
2
3
4
5
6
7
8
9

第0步：意图与愿景     → 为什么做（Purpose）
第1步：产品需求       → 做什么（What）
第2步：系统设计       → 怎么做（How - 架构层面）
第3步：定义文档       → 如何验证（Specification）
第4步：代码实现       → 精确表达（Implementation）

横切关注点：
  - 推演验证：每层都要进行"如果...那么..."推演
  - 质疑机制：主动挑战隐含假设和薄弱环节

1

[例如：为数据分析师构建的实时数据处理平台]

1
2
3
4

[描述当前的问题、痛苦、低效]
例如：
团队每天手工处理100+份Excel报表，耗时3小时，错误率15%，
导致决策延迟，且无法追溯历史数据。

1
2
3
4
5
6

[描述做完这个项目后的理想状态]
例如：
- 报表处理从3小时降到5分钟
- 错误率降到<1%
- 所有处理记录可追溯
- 数据可视化，支持实时决策

1
2
3
4
5

[如果不做这个项目会怎样]
例如：
- 团队效率持续低下，人员流失
- 数据错误导致重大决策失误
- 竞争对手已经在用自动化工具

1
2
3

- [如：报表处理时间从180分钟 → 5分钟]
- [如：用户满意度 > 8/10]
- [如：3个月内全员使用]

1
2
3

- [如：API响应时间 < 500ms (P95)]
- [如：系统可用性 > 99%]
- [如：核心功能测试覆盖率 > 80%]

1
2

- [如：上线后一周内关键bug < 3个]
- [如：代码review通过率 > 95%]

1
2
3
4

- 时间：[如：必须在Q2前上线]
- 预算：[如：云服务成本 < $500/月]
- 合规：[如：符合GDPR，数据不出境]
- 技术：[如：必须兼容现有的LDAP认证系统]

1
2
3

- [如：第一版不做移动端]
- [如：不支持实时协作编辑（后续版本）]
- [如：不处理超过100MB的单个文件]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

假设1: 用户愿意改变现有的工作习惯
  - 验证方式：[前期用户访谈，试点测试]
  
假设2: 现有的Excel文件格式相对标准化
  - 验证方式：[收集100份样本文件分析]
  
假设3: 现有服务器资源足够支撑
  - 验证方式：[压力测试，容量规划]

假设4: [你的假设]
  - 验证方式：[如何验证]

1
2
3
4
5
6
7
8
9

角色1: 数据分析师（张三）
  - 背景：每天处理大量报表，Excel熟练但不懂编程
  - 痛点：重复劳动多，经常出错，无法处理大数据量
  - 期望：一键上传自动处理，有问题能及时知道
  
角色2: [角色名]
  - 背景：
  - 痛点：
  - 期望：

1
2
3
4
5
6
7
8

1. 作为数据分析师，我希望可以拖拽上传Excel文件，
   以便快速开始数据处理（不用学习复杂的命令）
   
2. 作为数据分析师，我希望看到实时的处理进度，
   以便知道何时可以查看结果（不用一直等待）
   
3. 作为[角色]，我希望[功能]，
   以便[价值/目的]

1

1. 作为[角色]，我希望[功能]，以便[价值]

1

1. 作为[角色]，我希望[功能]，以便[价值]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

✅ 包含：
  - 支持CSV、Excel (.xlsx)
  - 自动数据清洗（去重、格式化）
  - 基础统计分析
  
❌ 不包含：
  - 不支持.xls旧格式（引导用户升级）
  - 不做复杂的数据建模
  - 不集成机器学习功能
  
⏰ 暂不考虑：
  - 多人协作（后续版本）
  - 自定义数据处理脚本

1
2
3

- 用户熟悉Excel基本操作
- 用户理解数据表格结构（行、列、表头）
- 用户不需要编程能力

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

[用文字或ASCII图描述，应清晰展示：模块、服务、通信方式、数据流向]

例如：
┌─────────────┐
│  浏览器客户端  │
│   (React)    │
└──────┬───────┘
       │ HTTPS
       ↓
┌─────────────────────────────────┐
│      Nginx (反向代理 + SSL)       │
└──────┬──────────────────┬───────┘
       │                  │
       ↓ REST API         ↓ WebSocket
┌─────────────┐    ┌──────────────┐
│   FastAPI   │←──→│    Redis     │
│  (业务逻辑)   │    │  (消息队列)   │
└──────┬──────┘    └──────┬───────┘
       │                  │
       ↓                  ↓
┌─────────────┐    ┌──────────────┐
│ PostgreSQL  │    │    Celery    │
│  (持久化)    │    │  (异步任务)   │
└─────────────┘    └──────────────┘

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

[详细步骤，包括正常流程和异常处理]

正常流程：
1. 用户在前端选择文件
2. 前端验证：文件类型、大小（< 10MB）
3. 前端发起上传请求（POST /api/uploads）
4. 后端接收文件，保存到临时目录（/tmp/uploads/{uuid}.xlsx）
5. 后端创建Task记录（status=pending），返回task_id
6. 后端异步：Celery worker开始处理文件
7. Worker解析文件 → 数据清洗 → 存入数据库
8. 处理过程中，通过WebSocket推送进度（0% → 100%）
9. 完成后，更新Task.status = completed
10. 前端收到完成通知，跳转到结果页面

异常处理：
- 步骤2失败 → 前端提示错误，不发请求
- 步骤4失败（网络中断） → 前端重试3次，超时提示
- 步骤7失败（格式错误） → Task.status = failed，返回错误详情
- Worker崩溃 → Celery自动重试，超过3次标记失败

1

[步骤描述]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

User（用户）
  - id: UUID (PK)
  - username: string (unique)
  - email: string
  - role: enum(admin, analyst)
  - created_at: timestamp

Dataset（数据集）
  - id: UUID (PK)
  - name: string
  - owner_id: UUID (FK → User.id)
  - file_path: string (原始文件路径)
  - row_count: integer
  - status: enum(pending, processing, completed, failed)
  - error_message: text?
  - created_at: timestamp
  - completed_at: timestamp?

ProcessingTask（处理任务）
  - id: UUID (PK)
  - dataset_id: UUID (FK → Dataset.id)
  - task_type: enum(parse, clean, analyze)
  - status: enum(pending, running, completed, failed)
  - progress: integer (0-100)
  - result_summary: json?
  - created_at: timestamp

1
2

User 1 ──< N Dataset (一个用户可以上传多个数据集)
Dataset 1 ──< N ProcessingTask (一个数据集可能有多个处理任务)

1
2
3
4

1. 创建：用户上传 → 文件存储 → Dataset记录（status=pending）
2. 处理：Worker启动 → Task记录（status=running） → 逐行解析
3. 完成：数据入库 → Dataset.status=completed → 通知用户
4. 清理：30天后，原始文件从临时目录删除（保留元数据）

1
2
3
4

- API响应时间：< 500ms (P95)
- 文件处理速度：1000行/秒
- 并发处理能力：10个任务同时运行
- 前端首屏加载：< 2s

1
2
3

- 系统可用性：99%（允许每月7小时维护）
- 数据持久性：99.9%（数据库主从备份）
- 任务失败重试：最多3次，指数退避

1
2
3
4

- 认证：JWT token，30分钟过期
- 授权：用户只能访问自己的数据
- 文件隔离：每个用户独立目录
- 敏感信息：密码bcrypt加密，不记录日志

1
2
3

- 水平扩展：Celery worker可增加到10个
- 数据库：单表行数 < 1000万（分表策略预留）
- 存储：支持S3替代本地文件系统

1
2
3
4
5

[列出你最不确定的设计点，让AI重点挑战]
例如：
1. Celery是否过重？轮询数据库状态是否更简单？
2. WebSocket是否必要？服务端推送的价值是否值得复杂度？
3. 文件存储在本地是否可靠？应该直接用S3吗？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

端点：POST /api/v1/datasets/upload
认证：Bearer Token (必需)

请求头：
  Content-Type: multipart/form-data
  Authorization: Bearer {jwt_token}

请求体：
  file: binary (必需, max: 10MB)
  name: string (可选, default: 原文件名)
  description: string (可选, max: 500字符)

成功响应 (201 Created)：
{
  "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "销售数据_2024Q1.xlsx",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z",
  "estimated_time": 30  // 预估处理时间（秒）
}

错误响应：
400 Bad Request - 文件格式不支持
  {"error": "unsupported_format", "message": "仅支持 .csv 和 .xlsx 文件"}
  
401 Unauthorized - Token无效或过期
  {"error": "invalid_token", "message": "请重新登录"}
  
413 Payload Too Large - 文件过大
  {"error": "file_too_large", "message": "文件大小不能超过 10MB"}
  
500 Internal Server Error - 服务器错误
  {"error": "internal_error", "message": "文件上传失败，请稍后重试"}

业务规则：
  - 文件名会自动去除特殊字符
  - 同名文件会自动加序号（如：data.xlsx → data(1).xlsx）
  - 上传后立即返回，异步处理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

端点：GET /api/v1/datasets/{dataset_id}
认证：Bearer Token (必需)

路径参数：
  dataset_id: UUID (必需)

成功响应 (200 OK)：
{
  "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "销售数据_2024Q1.xlsx",
  "status": "processing",  // pending | processing | completed | failed
  "progress": 45,  // 0-100
  "row_count": 1523,  // 已处理行数
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": null,
  "error_message": null
}

错误响应：
404 Not Found - 数据集不存在或无权访问
  {"error": "not_found", "message": "数据集不存在"}

1

[接口定义]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

端点：WS /api/v1/ws/progress
认证：URL参数 ?token={jwt_token}

连接后发送：
{
  "action": "subscribe",
  "dataset_id": "550e8400-e29b-41d4-a716-446655440000"
}

服务器推送消息：
{
  "type": "progress",
  "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
  "progress": 45,
  "message": "正在处理第 1500/3000 行"
}

完成消息：
{
  "type": "completed",
  "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
  "result_summary": {
    "total_rows": 3000,
    "valid_rows": 2987,
    "error_rows": 13
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  username VARCHAR(50) NOT NULL UNIQUE,
  email VARCHAR(255) NOT NULL UNIQUE,
  password_hash VARCHAR(255) NOT NULL,  -- bcrypt hash
  role VARCHAR(20) NOT NULL DEFAULT 'analyst' CHECK (role IN ('admin', 'analyst')),
  is_active BOOLEAN NOT NULL DEFAULT true,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  last_login_at TIMESTAMP,
  
  -- 索引
  INDEX idx_username (username),
  INDEX idx_email (email),
  INDEX idx_role (role)
);

-- 数据示例
-- id: 550e8400-e29b-41d4-a716-446655440000
-- username: zhangsan
-- email: zhangsan@company.com
-- role: analyst

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

CREATE TABLE datasets (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  owner_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  name VARCHAR(255) NOT NULL,
  description TEXT,
  file_path TEXT NOT NULL,  -- 例如：/data/uploads/550e8400.../data.xlsx
  file_size BIGINT NOT NULL,  -- 字节
  mime_type VARCHAR(100) NOT NULL,  -- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  status VARCHAR(20) NOT NULL DEFAULT 'pending' 
    CHECK (status IN ('pending', 'processing', 'completed', 'failed')),
  progress INTEGER NOT NULL DEFAULT 0 CHECK (progress >= 0 AND progress <= 100),
  row_count INTEGER DEFAULT 0,
  error_message TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  completed_at TIMESTAMP,
  
  -- 索引
  INDEX idx_owner_id (owner_id),
  INDEX idx_status (status),
  INDEX idx_created_at (created_at DESC),
  INDEX idx_owner_status (owner_id, status)  -- 复合索引，用于"我的数据集"查询
);

-- 触发器：更新 updated_at
CREATE TRIGGER update_datasets_updated_at
BEFORE UPDATE ON datasets
FOR EACH ROW
EXECUTE FUNCTION update_updated_at_column();

1

[表结构]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// 路径：src/components/FileUploader.tsx

interface FileUploaderProps {
  onUploadSuccess: (datasetId: string) => void;
  onUploadError: (error: Error) => void;
  maxFileSize?: number;  // 字节，默认 10MB
  acceptedFormats?: string[];  // 默认 ['.csv', '.xlsx']
}

interface FileUploaderState {
  file: File | null;
  uploading: boolean;
  progress: number;  // 0-100
  error: string | null;
}

// 主要职责：
// 1. 文件拖拽/选择
// 2. 前端格式验证
// 3. 上传进度显示
// 4. 错误处理和重试

// 使用示例：
<FileUploader
  maxFileSize={10 * 1024 * 1024}
  onUploadSuccess={(id) => navigate(`/dataset/${id}`)}
  onUploadError={(err) => toast.error(err.message)}
/>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// 路径：src/components/ProcessingStatus.tsx

interface ProcessingStatusProps {
  datasetId: string;
  onCompleted?: (dataset: Dataset) => void;
}

// 主要职责：
// 1. 轮询或WebSocket监听状态
// 2. 展示进度条和当前状态
// 3. 处理完成后的跳转

// 状态机：
// pending → processing → completed
//                    ↘ failed

1

[组件定义]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# 伪代码

def parse_and_clean_file(file_path: str, dataset_id: UUID) -> ParseResult:
    """
    解析Excel/CSV文件并进行数据清洗
    
    输入：文件路径
    输出：ParseResult(row_count, error_rows, cleaned_data)
    副作用：更新 datasets.progress，推送WebSocket消息
    """
    
    # 1. 检测文件格式
    if file_path.endswith('.csv'):
        df = read_csv(file_path, encoding='utf-8-sig')  # 处理BOM
    elif file_path.endswith('.xlsx'):
        df = read_excel(file_path, engine='openpyxl')
    else:
        raise UnsupportedFormat()
    
    # 2. 验证基本结构
    if df.empty:
        raise EmptyFileError("文件没有数据")
    
    if len(df.columns) > 50:
        raise TooManyColumnsError("列数不能超过50")
    
    # 3. 数据清洗（逐行处理，更新进度）
    total_rows = len(df)
    error_rows = []
    cleaned_rows = []
    
    for idx, row in df.iterrows():
        try:
            # 3.1 去除空白
            cleaned_row = {k: str(v).strip() for k, v in row.items()}
            
            # 3.2 类型推断和转换
            cleaned_row = infer_and_convert_types(cleaned_row)
            
            # 3.3 业务规则验证
            validate_business_rules(cleaned_row)
            
            cleaned_rows.append(cleaned_row)
            
        except ValidationError as e:
            error_rows.append({
                "row": idx + 2,  # Excel行号（跳过表头）
                "error": str(e)
            })
        
        # 4. 更新进度（每100行）
        if idx % 100 == 0:
            progress = int((idx / total_rows) * 100)
            update_progress(dataset_id, progress)
            push_websocket_message(dataset_id, progress)
    
    # 5. 返回结果
    return ParseResult(
        row_count=len(cleaned_rows),
        error_rows=error_rows,
        cleaned_data=cleaned_rows
    )

# 复杂度：O(n)，n为行数
# 内存：O(n)，未来可改为流式处理降到O(1)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

1. 文件层面：
   - 大小 < 10MB
   - 格式为 CSV 或 XLSX
   - 编码为 UTF-8（CSV自动检测）
   
2. 结构层面：
   - 必须有表头（第一行）
   - 列数 <= 50
   - 行数 <= 10万（超过需要分批上传）
   - 列名不能重复
   
3. 数据层面：
   - 空值比例 < 30%（否则警告）
   - 日期格式自动识别（支持 YYYY-MM-DD, MM/DD/YYYY 等）
   - 数字格式自动识别（处理千分位、货币符号）
   
4. 业务层面：
   - [根据业务定义的特殊规则]
   例如：金额字段不能为负数

1

[规则描述]

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106

project-root/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py              # FastAPI应用入口
│   │   ├── config.py            # 配置管理
│   │   ├── dependencies.py      # 依赖注入
│   │   │
│   │   ├── api/                 # API路由层
│   │   │   ├── __init__.py
│   │   │   ├── v1/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── auth.py      # 认证相关
│   │   │   │   ├── datasets.py  # 数据集CRUD
│   │   │   │   └── websocket.py # WebSocket
│   │   │   └── deps.py          # API依赖（如：get_current_user）
│   │   │
│   │   ├── models/              # 数据模型（SQLAlchemy）
│   │   │   ├── __init__.py
│   │   │   ├── user.py
│   │   │   ├── dataset.py
│   │   │   └── base.py          # 基类
│   │   │
│   │   ├── schemas/             # Pydantic schemas（数据验证）
│   │   │   ├── __init__.py
│   │   │   ├── user.py
│   │   │   ├── dataset.py
│   │   │   └── common.py        # 通用类型
│   │   │
│   │   ├── services/            # 业务逻辑层
│   │   │   ├── __init__.py
│   │   │   ├── auth_service.py
│   │   │   ├── dataset_service.py
│   │   │   └── parser_service.py
│   │   │
│   │   ├── tasks/               # Celery异步任务
│   │   │   ├── __init__.py
│   │   │   ├── celery_app.py    # Celery配置
│   │   │   └── processing.py    # 文件处理任务
│   │   │
│   │   ├── core/                # 核心工具
│   │   │   ├── __init__.py
│   │   │   ├── security.py      # JWT、密码加密
│   │   │   ├── exceptions.py    # 自定义异常
│   │   │   └── logging.py       # 日志配置
│   │   │
│   │   └── utils/               # 通用工具
│   │       ├── __init__.py
│   │       ├── file.py          # 文件操作
│   │       └── validators.py    # 验证器
│   │
│   ├── tests/                   # 测试
│   │   ├── unit/
│   │   ├── integration/
│   │   └── conftest.py
│   │
│   ├── alembic/                 # 数据库迁移
│   │   ├── versions/
│   │   └── env.py
│   │
│   ├── requirements.txt
│   ├── pytest.ini
│   └── .env.example
│
├── frontend/
│   ├── src/
│   │   ├── components/          # UI组件
│   │   │   ├── FileUploader.tsx
│   │   │   ├── ProcessingStatus.tsx
│   │   │   └── common/          # 通用组件
│   │   │
│   │   ├── pages/               # 页面
│   │   │   ├── Dashboard.tsx
│   │   │   ├── DatasetDetail.tsx
│   │   │   └── Login.tsx
│   │   │
│   │   ├── services/            # API调用
│   │   │   ├── api.ts           # axios配置
│   │   │   ├── authService.ts
│   │   │   └── datasetService.ts
│   │   │
│   │   ├── hooks/               # 自定义hooks
│   │   │   ├── useAuth.ts
│   │   │   ├── useWebSocket.ts
│   │   │   └── useDataset.ts
│   │   │
│   │   ├── types/               # TypeScript类型
│   │   │   ├── user.ts
│   │   │   ├── dataset.ts
│   │   │   └── api.ts
│   │   │
│   │   ├── utils/               # 工具函数
│   │   │   ├── format.ts
│   │   │   └── validators.ts
│   │   │
│   │   ├── App.tsx
│   │   └── main.tsx
│   │
│   ├── public/
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
│
├── docker-compose.yml
├── .gitignore
└── README.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# 命名约定
- 变量、函数：snake_case (例: user_id, get_dataset)
- 类：PascalCase (例: UserModel, DatasetService)
- 常量：UPPER_SNAKE_CASE (例: MAX_FILE_SIZE)
- 私有成员：_leading_underscore (例: _validate)

# 类型标注（必须）
def create_dataset(
    file: UploadFile,
    name: str,
    owner_id: UUID,
    db: Session
) -> Dataset:
    """创建数据集
    
    Args:
        file: 上传的文件对象
        name: 数据集名称
        owner_id: 所有者ID
        db: 数据库会话
    
    Returns:
        Dataset: 创建的数据集对象
    
    Raises:
        UnsupportedFormatError: 文件格式不支持
        FileTooLargeError: 文件过大
    """
    pass

# Docstring格式：Google Style

# 导入顺序：
# 1. 标准库
# 2. 第三方库
# 3. 本地模块

# 行长度：最大 100 字符
# 工具：black, isort, mypy, pylint

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// 命名约定
- 变量、函数：camelCase (例: userId, getDataset)
- 类、接口、类型：PascalCase (例: User, DatasetProps)
- 常量：UPPER_SNAKE_CASE (例: MAX_FILE_SIZE)
- 私有成员：#leading_hash (例: #validate) 或 _underscore

// 类型定义（必须，避免any）
interface Dataset {
  id: string;
  name: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  createdAt: Date;
}

function uploadFile(file: File, name: string): Promise<Dataset> {
  // 实现
}

// 组件Props必须定义interface
interface FileUploaderProps {
  onSuccess: (id: string) => void;
  maxSize?: number;
}

// 优先使用函数组件 + Hooks
// 工具：ESLint, Prettier, TypeScript strict mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# Web框架
fastapi==0.109.0
uvicorn[standard]==0.27.0
pydantic==2.5.0
pydantic-settings==2.1.0

# 数据库
sqlalchemy==2.0.25
alembic==1.13.1
psycopg2-binary==2.9.9

# 异步任务
celery==5.3.4
redis==5.0.1

# 认证
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
python-multipart==0.0.6

# 文件处理
pandas==2.1.4
openpyxl==3.1.2

# 工具
python-dotenv==1.0.0

# 测试
pytest==7.4.4
pytest-asyncio==0.23.3
httpx==0.26.0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.21.0",
    "axios": "^1.6.5",
    "zustand": "^4.4.7",
    "@tanstack/react-query": "^5.17.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.48",
    "@types/react-dom": "^18.2.18",
    "typescript": "^5.3.3",
    "vite": "^5.0.11",
    "eslint": "^8.56.0",
    "prettier": "^3.1.1"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 数据库
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Redis
REDIS_URL=redis://localhost:6379/0

# JWT
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# 文件存储
UPLOAD_DIR=/data/uploads
MAX_FILE_SIZE=10485760  # 10MB

# Celery
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

# 日志
LOG_LEVEL=INFO

# 前端（.env）
VITE_API_BASE_URL=http://localhost:8000/api/v1
VITE_WS_URL=ws://localhost:8000/ws

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# core/exceptions.py
class AppException(Exception):
    """应用基础异常"""
    def __init__(self, message: str, code: str):
        self.message = message
        self.code = code
        super().__init__(self.message)

class UnsupportedFormatError(AppException):
    def __init__(self):
        super().__init__(
            message="仅支持 .csv 和 .xlsx 文件",
            code="unsupported_format"
        )

# main.py 全局异常处理器
@app.exception_handler(AppException)
async def app_exception_handler(request: Request, exc: AppException):
    return JSONResponse(
        status_code=400,
        content={"error": exc.code, "message": exc.message}
    )

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// services/api.ts
axios.interceptors.response.use(
  response => response,
  error => {
    if (error.response?.status === 401) {
      // Token过期，跳转登录
      navigate('/login');
    }
    
    const apiError = {
      code: error.response?.data?.error || 'unknown_error',
      message: error.response?.data?.message || '请求失败'
    };
    
    // 统一toast提示
    toast.error(apiError.message);
    
    return Promise.reject(apiError);
  }
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# 日志级别使用
DEBUG: 详细的调试信息（生产环境关闭）
INFO: 关键业务流程（如：用户登录、文件上传开始）
WARNING: 异常但可恢复的情况（如：重试成功）
ERROR: 错误但不影响整体服务（如：单个任务失败）
CRITICAL: 严重错误，服务不可用

# 示例
logger.info(
    "Dataset created",
    extra={
        "dataset_id": str(dataset.id),
        "owner_id": str(owner.id),
        "file_size": file.size
    }
)

# 敏感信息不记录
logger.info(f"User {user.username} logged in")  # ✅
logger.info(f"Password: {password}")  # ❌ 绝对禁止

1
2
3
4
5
6
7

方法：用户访谈 + 原型测试
时间：开发前1周
验证点：
  - [ ] 用户故事是否覆盖真实场景
  - [ ] 产品边界是否被用户接受
  - [ ] UI/UX是否直观易用
产出：用户反馈报告，需求调整清单

1
2
3
4
5
6
7

方法：架构评审 + 性能推演
时间：编码前
验证点：
  - [ ] 架构是否支撑非功能性需求（性能、可靠性）
  - [ ] 是否存在单点故障
  - [ ] 扩展性是否足够
产出：架构评审报告，风险清单

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

方法：单元测试 + 集成测试 + E2E测试
覆盖率目标：
  - 核心业务逻辑：> 80%
  - API接口：100%（所有端点和错误码）
  - 前端组件：> 60%
关键测试场景：
  1. 正常流程：上传 → 处理 → 查看结果
  2. 异常流程：格式错误、超大文件、网络中断、并发冲突
  3. 性能测试：1000行文件处理时间、10并发上传
产出：测试报告，bug清单

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

方法：灰度发布 + 监控
阶段：
  1. 内部测试（1天）：团队成员使用
  2. 小范围试点（3天）：5-10个真实用户
  3. 全量发布
监控指标：
  - 错误率 < 1%
  - API响应时间 P95 < 500ms
  - 用户反馈 NPS > 7
回滚策略：如果错误率 > 5%，立即回滚

1
2
3
4
5
6
7
8

[描述你脑海中已经完整的设计]
例如：
1. 文件上传采用分块上传（前端实现），支持大文件和断点续传
2. 异步处理使用Celery，worker数量根据队列长度自动伸缩
3. 进度推送优先使用WebSocket，降级方案是轮询（每2秒）
4. 数据库索引策略：owner_id + status 复合索引，覆盖"我的数据集"查询
5. 前端状态管理用Zustand，避免Redux的繁琐
6. ...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

[需要AI帮助深入思考的设计点]
例如：
1. 文件解析失败后的重试策略：
   - 是否需要自动重试？重试几次？
   - 失败的中间数据如何处理？
   
2. 并发控制：
   - 如果用户快速上传10个文件，如何排队？
   - 是否需要限制单用户的并发任务数？
   
3. 缓存策略：
   - 数据集列表是否需要缓存？缓存多久？
   - 如何保证缓存一致性？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

[希望AI重点挑战的设计决策]
例如：
1. WebSocket的必要性：
   - 实时推送的价值是否值得复杂度？
   - 轮询（每2秒）的用户体验差多少？
   - WebSocket连接管理、断线重连的成本如何？
   
2. Celery的复杂度：
   - 对于MVP，是否可以用FastAPI的BackgroundTasks？
   - 什么时候才真正需要Celery？
   
3. 数据存储策略：
   - 原始文件是否需要长期保留？
   - 是否应该只保留解析后的结构化数据？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

工作量：2小时
内容：
  - 创建目录结构
  - 配置开发环境（Python venv, Node.js）
  - 安装核心依赖
  - 配置 docker-compose（PostgreSQL, Redis）
验收标准：
  - 前后端都能启动
  - 数据库连接成功
  - API返回"Hello World"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

工作量：4小时
内容：
  - User模型和数据库表
  - 注册、登录API
  - JWT token生成和验证
  - 前端登录页面和token管理
验收标准：
  - 可以注册新用户
  - 登录后获得token
  - 受保护的API需要token访问

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

工作量：6小时
内容：
  - Dataset模型和表
  - 上传API（接收文件，保存到本地）
  - Celery配置和测试任务
  - 前端FileUploader组件
验收标准：
  - 可以上传CSV/Excel文件
  - 文件保存成功，返回dataset_id
  - Celery worker正常运行

1
2
3
4

- 实现文件解析和数据清洗
- WebSocket实时进度推送
- 数据集列表和详情页面
- ...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

1. 我提供设计（或填写模板）
   ↓
2. 你复述理解 + 推演验证 + 提出质疑
   ↓
3. 我们讨论并达成共识
   ↓
4. 你高效实现（此时才开始写代码）
   ↓
5. 完成后，我们回顾是否符合设计
   ↓
6. 发现偏差 → 调整实现（而非修改设计）

1
2
3
4
5
6
7
8

阅读上面我填写的所有内容，然后：

1. 用一段话总结你对项目的理解（意图、目标、架构）
2. 列出你发现的3-5个潜在问题或风险
3. 针对"需要你质疑的部分"，给出你的分析
4. 确认第一阶段的任务清单，询问是否可以开始

只有得到我的明确确认后，才开始写第一行代码。