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 使用示例

// 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 使用示例

// 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 响应结构

// 成功响应
{
  "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
• arch-overview-v30.md

---

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