docs: 新增V30.0版本相关设计文档与指南
新增服务器启动文档、设计说明书、风险清单等核心文档 补充前端集成蓝图、多租户实施清单、上线红线检查清单 添加质量保障文档与早期业务规格书
This commit is contained in:
Ansonai
217
docs/blueprints/frontend-architecture.md
Normal file
217
docs/blueprints/frontend-architecture.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# 🎨 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
|
||||
Reference in New Issue
Block a user