218 lines
6.5 KiB
Markdown
218 lines
6.5 KiB
Markdown
# 🎨 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
|