makemd/docs/blueprints/frontend-architecture.md

# 🎨 Frontend Architecture Blueprint (V2.0 - Console)

## 1. 架构定位 (Positioning)

Console 是 Crawlful Hub 的"运营控制台"。它作为业务操作的统一入口，负责订单管理、商品管理、财务对账、数据报表等核心功能的呈现与交互。

## 2. 核心模式 (Core Patterns)

### 2.1 建议-审核工作流 (Suggestion-Approval Workflow)

所有的核心业务操作（调价、下单、退款）在前端必须遵循以下组件模式：
- **SuggestionCard**: 展示建议详情、依据说明
- **CausalChainView**: 展示决策背后的业务逻辑链
- **ActionGroup**: [忽略] | [修正] | [核准执行]

### 2.2 全链路溯源 (Full-Traceability)
- 每一笔操作必须绑定 `traceId`
- 联动 `TraceController`，支持在 UI 上查看操作日志

### 2.3 多租户隔离 (Tenant Isolation)
- 前端请求必须在 Header 中携带 `x-tenant-id`
- UI 适配：根据租户配额（Quota）动态置灰或隐藏未授权功能

## 3. 技术栈 (Tech Stack)

- **框架**: UmiJS 4.x
- **UI 组件库**: Ant Design 5.x
- **状态管理**: **Zustand** + TanStack Query
- **可视化**: AntV G2/G6 (用于经营报表与供应链拓扑展示)
- **HTTP 客户端**: Axios / Umirequest
- **表单管理**: React Hook Form + Zod

### 3.1 目录结构规范
```
src/
├── components/          # 公共组件
│   ├── Business/        # 业务组件
│   └── Basic/           # 基础组件
├── pages/              # 页面组件
├── stores/              # Zustand 状态管理
├── services/            # API 服务层 (TanStack Query)
├── utils/               # 工具函数
├── hooks/               # 自定义 Hooks
├── types/               # TypeScript 类型定义
└── assets/             # 静态资源
```

### 3.2 状态管理策略
| 状态类型 | 管理方案 | 适用场景 |
|---------|---------|---------|
| 全局状态 | **Zustand** | 用户信息、租户配置 |
| 服务端状态 | **TanStack Query** | API 数据缓存、同步 |
| 页面状态 | React Hook Form | 表单数据、列表筛选 |
| 表单验证 | Zod | 复杂表单验证 |

### 3.3 Zustand 使用示例
```typescript
// stores/userStore.ts
import { create } from 'zustand';

interface UserState {
  user: User | null;
  tenant: Tenant | null;
  setUser: (user: User) => void;
  setTenant: (tenant: Tenant) => void;
}

export const useUserStore = create<UserState>((set) => ({
  user: null,
  tenant: null,
  setUser: (user) => set({ user }),
  setTenant: (tenant) => set({ tenant }),
}));
```

### 3.4 TanStack Query 使用示例
```typescript
// services/orderService.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { request } from 'umi';

export const useOrders = (params: OrderQueryParams) => {
  return useQuery({
    queryKey: ['orders', params],
    queryFn: () => request('/api/v1/orders', { params }),
  });
};

export const useCreateOrder = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data: CreateOrderDTO) => 
      request('/api/v1/orders', { method: 'POST', data }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['orders'] });
    },
  });
};
```

## 4. 严禁事项 (Red Lines)
- **严禁 Mock 数据 (Zero-Mock)**：除 Storybook 演示外，生产代码禁止硬编码模拟 API
- **严禁越权修改**：前端禁止绕过审核流程直接调用后端 Mutation 接口
- **严禁敏感数据暴露**：前端禁止在 URL 或日志中暴露敏感信息

## 5. 交互规范

### 5.1 建议展示
- 凡是系统生成的建议内容必须带有标签说明来源
- 异常提示需展示根因分析，而非模糊的"系统错误"

### 5.2 加载状态
- 异步操作需展示 Loading 状态
- 长时操作需展示进度

### 5.3 错误处理
- 4xx 错误：展示具体错误原因，引导用户修正
- 5xx 错误：展示友好提示，记录日志便于排查

## 6. API 设计规范

### 6.1 RESTful API 标准
| 方法 | 用途 | 示例 |
|-----|-----|-----|
| GET | 查询 | GET /api/v1/orders |
| POST | 创建 | POST /api/v1/orders |
| PUT | 完整更新 | PUT /api/v1/orders/:id |
| PATCH | 部分更新 | PATCH /api/v1/orders/:id |
| DELETE | 删除 | DELETE /api/v1/orders/:id |

### 6.2 响应结构
```typescript
// 成功响应
{
  "success": true,
  "data": { ... },
  "pagination": { "page": 1, "pageSize": 20, "total": 100 }
}

// 错误响应
{
  "success": false,
  "error": { "code": "ORDER_NOT_FOUND", "message": "订单不存在", "details": {} }
}
```

### 6.3 错误码规范
| 错误类别 | 错误码前缀 | 说明 |
|---------|-----------|-----|
| 4xx | CLIENT_ERROR_ | 客户端错误（参数、权限） |
| 5xx | SERVER_ERROR_ | 服务端错误（数据库、外部服务） |
| 业务 | BIZ_ | 业务规则错误 |
| 认证 | AUTH_ | 认证授权错误 |

## 7. 开发环境与工具链

### 7.1 环境要求
| 环境 | 配置要求 |
|-----|---------|
| 开发环境 | Node.js 20.x, MySQL 8.0, Redis 6.0 |
| 测试环境 | Docker 容器化部署 |
| 生产环境 | 阿里云 ECS + RDS + Redis |

### 7.2 开发工具
| 工具 | 用途 |
|-----|-----|
| ESLint | 代码检查 |
| Prettier | 代码格式化 |
| TypeScript | 类型检查 |
| Husky | Git Hooks |

### 7.3 环境变量
```
.env                  # 本地开发
.env.development      # 开发环境
.env.staging          # 预发布环境
.env.production       # 生产环境
```

## 8. 质量保障

### 8.1 测试分层
| 测试类型 | 覆盖目标 | 工具 |
|---------|---------|-----|
| 单元测试 | 业务逻辑、工具函数 | Vitest |
| 组件测试 | UI 组件渲染 | Testing Library |
| E2E 测试 | 关键用户路径 | Playwright |

### 8.2 性能优化
| 优化点 | 方案 | 预期收益 |
|-------|-----|---------|
| 首屏加载 | Code Splitting, Lazy Loading | 减少 30% 首屏时间 |
| 请求优化 | TanStack Query 缓存 | 减少 50% 请求数 |
| 图片优化 | WebP, 懒加载 | 减少 40% 带宽 |
| 渲染优化 | React.memo, useMemo | 减少重渲染开销 |

---

## 9. 附录

### 9.1 技术栈总览
| 层级 | 技术方案 | 版本 |
|-----|---------|-----|
| 框架 | UmiJS | 4.x |
| UI 组件 | Ant Design | 5.x |
| 状态管理 | Zustand | 4.x |
| 服务端状态 | TanStack Query | 5.x |
| 表单验证 | React Hook Form + Zod | 最新 |
| 可视化 | AntV G2/G6 | 5.x |

### 9.2 相关文档
- [global-business-blueprint.md](./global-business-blueprint.md)
- [arch-overview-v30.md](./arch-overview-v30.md)

---

**文档维护者**：Crawlful Hub 架构团队 | **版本**：V2.0