docs: 添加中文文档，新增前端和后端代码
- 新增 README_CN.md 中文文档 - 新增 frontend/ Vue 3 前端项目 - 新增 web/ FastAPI 后端项目 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
223
frontend/README.md
Normal file
223
frontend/README.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# bttoxin_webserver
|
||||
|
||||
BtToxin 毒素数据库 Web 前端项目，基于 Vue 3 + TypeScript + Vite 构建。
|
||||
|
||||
## 快速启动
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 启动开发服务器
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
启动后访问 http://localhost:5173/ 查看前端页面。
|
||||
|
||||
### 主要页面
|
||||
|
||||
| 路由 | 页面 | 功能 |
|
||||
|------|------|------|
|
||||
| `/` | 任务提交页 | 上传 .fna 文件并提交分析任务 |
|
||||
| `/:sessionId` | 任务监控页 | 实时查看任务执行状态和日志 |
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
bttoxin_webserver/
|
||||
├── public/ # 静态资源
|
||||
│ └── favicon.ico
|
||||
├── src/
|
||||
│ ├── api/ # API 请求层
|
||||
│ │ ├── http.ts # axios 实例、拦截器、错误规范
|
||||
│ │ ├── types.ts # API 类型定义
|
||||
│ │ ├── bttoxin.ts # 毒素接口：list/detail/download
|
||||
│ │ └── task.ts # 任务接口：createTask/getTaskState/downloadResult
|
||||
│ ├── components/
|
||||
│ │ └── task/ # 任务监控组件
|
||||
│ │ ├── TaskFlowPanel.vue # 工作流步骤可视化
|
||||
│ │ ├── TaskStatusBar.vue # 任务状态概览栏
|
||||
│ │ ├── TaskStepLogDrawer.vue # 步骤日志抽屉
|
||||
│ │ └── TaskSubmitForm.vue # 任务提交表单
|
||||
│ ├── composables/ # 组合式函数
|
||||
│ │ ├── useAsync.ts # 通用异步状态封装
|
||||
│ │ ├── useMotiaStreams.ts # Motia Streams 订阅
|
||||
│ │ └── useTaskState.ts # 任务状态管理
|
||||
│ ├── router/ # 路由配置
|
||||
│ │ └── index.ts
|
||||
│ ├── stores/ # Pinia 状态管理
|
||||
│ │ ├── counter.ts # 示例 store
|
||||
│ │ └── toxin.ts # 毒素业务 store
|
||||
│ ├── types/ # TypeScript 类型定义
|
||||
│ │ └── task.ts # 任务相关类型
|
||||
│ ├── utils/ # 工具函数
|
||||
│ │ ├── error.ts # 错误格式化、文件下载
|
||||
│ │ └── task.ts # 任务工具函数
|
||||
│ ├── views/ # 页面视图
|
||||
│ │ ├── TaskSubmitView.vue # 任务提交页
|
||||
│ │ └── TaskMonitorView.vue# 任务监控页
|
||||
│ ├── __tests__/ # 单元测试
|
||||
│ │ └── App.spec.ts
|
||||
│ ├── App.vue # 根组件
|
||||
│ └── main.ts # 入口文件
|
||||
├── .env.development # 开发环境变量
|
||||
├── .env.production # 生产环境变量
|
||||
├── index.html
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── vite.config.ts
|
||||
└── vitest.config.ts
|
||||
```
|
||||
|
||||
## 环境配置
|
||||
|
||||
开发环境 `.env.development`:
|
||||
```
|
||||
VITE_API_BASE_URL=http://127.0.0.1:8000
|
||||
```
|
||||
|
||||
生产环境 `.env.production`:
|
||||
```
|
||||
VITE_API_BASE_URL=https://your.domain/api
|
||||
```
|
||||
|
||||
## API 请求使用方式
|
||||
|
||||
### 1. 直接调用 API 函数
|
||||
|
||||
```ts
|
||||
import { listToxins, getToxinDetail } from '@/api/bttoxin'
|
||||
|
||||
// 获取列表
|
||||
const data = await listToxins({ q: 'Cry', page: 1, pageSize: 20 })
|
||||
console.log(data.items, data.total)
|
||||
|
||||
// 获取详情
|
||||
const detail = await getToxinDetail('toxin-id')
|
||||
```
|
||||
|
||||
### 2. 通过 Pinia Store 调用（推荐）
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { onMounted } from 'vue'
|
||||
import { useToxinStore } from '@/stores/toxin'
|
||||
|
||||
const store = useToxinStore()
|
||||
|
||||
onMounted(() => {
|
||||
store.fetchList()
|
||||
})
|
||||
|
||||
// 更新筛选条件
|
||||
function onSearch(keyword: string) {
|
||||
store.updateQuery({ q: keyword })
|
||||
}
|
||||
|
||||
// 翻页
|
||||
function onPageChange(page: number) {
|
||||
store.goToPage(page)
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div v-if="store.loading">加载中...</div>
|
||||
<div v-else-if="store.error">{{ store.error.message }}</div>
|
||||
<ul v-else>
|
||||
<li v-for="item in store.items" :key="item.id">
|
||||
{{ item.name }}
|
||||
</li>
|
||||
</ul>
|
||||
</template>
|
||||
```
|
||||
|
||||
### 3. 使用 useAsync 组合式函数
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { useAsync } from '@/composables/useAsync'
|
||||
import { getToxinDetail } from '@/api/bttoxin'
|
||||
|
||||
const { loading, error, data, execute } = useAsync(getToxinDetail)
|
||||
|
||||
// 调用
|
||||
execute('toxin-id')
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div v-if="loading">加载中...</div>
|
||||
<div v-else-if="error">{{ error.message }}</div>
|
||||
<div v-else>{{ data?.name }}</div>
|
||||
</template>
|
||||
```
|
||||
|
||||
### 4. 文件下载
|
||||
|
||||
```ts
|
||||
import { downloadFasta, downloadCsv } from '@/api/bttoxin'
|
||||
import { downloadBlob } from '@/utils/error'
|
||||
|
||||
// 下载单个 FASTA
|
||||
const blob = await downloadFasta('toxin-id')
|
||||
downloadBlob(blob, 'toxin.fasta')
|
||||
|
||||
// 下载 CSV
|
||||
const csvBlob = await downloadCsv({ family: 'Cry' })
|
||||
downloadBlob(csvBlob, 'toxins.csv')
|
||||
```
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 启动开发服务器
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
访问 http://localhost:5173/ 查看前端页面。
|
||||
|
||||
### 构建生产版本
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### 预览生产构建
|
||||
|
||||
```bash
|
||||
pnpm preview
|
||||
```
|
||||
|
||||
### 运行单元测试
|
||||
|
||||
```bash
|
||||
pnpm test:unit
|
||||
```
|
||||
|
||||
### 类型检查
|
||||
|
||||
```bash
|
||||
pnpm type-check
|
||||
```
|
||||
|
||||
### 代码检查
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
```
|
||||
|
||||
## 推荐 IDE 配置
|
||||
|
||||
[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar)
|
||||
|
||||
## 浏览器插件
|
||||
|
||||
- Chrome: [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
|
||||
- Firefox: [Vue.js devtools
|
||||
](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
|
||||
Reference in New Issue
Block a user