# BizTranslate

**Repository Path**: scj0708/BizTranslate

## Basic Information

- **Project Name**: BizTranslate
- **Description**: 浏览器翻译插件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BizTranslate 工作区

外贸场景 **Google Chrome** 翻译扩展（Manifest V3）与配套后端，任务清单见根目录《开发计划.md》。

## 仓库布局

| 路径 | 说明 |
|------|------|
| [BizTranslate-web](./BizTranslate-web) | 扩展前端（Manifest V3 + Vite + React + TypeScript） |
| [BizTranslate-service](./BizTranslate-service) | 后端 API（Java 17 + Spring Boot 3） |
| [开发计划.md](./开发计划.md) | 分阶段任务与打钩 |
| [CHANGELOG.md](./CHANGELOG.md) | 版本记录（与 CHK-DOC-001 对齐） |
| [详细设计-外贸Chrome翻译插件.md](./详细设计-外贸Chrome翻译插件.md) | 详细设计 v2 |

## 快速开始

### 扩展

```bash
cd BizTranslate-web
cp .env.example .env
pnpm install   # 若 pnpm 安装失败，可改用：npm install
pnpm dev       # 或：npm run dev
```

在 Chrome `chrome://extensions` 加载 `BizTranslate-web/dist` 目录。

### 后端

```bash
cd BizTranslate-service
mvn spring-boot:run
```

默认 `http://localhost:8080`，扩展 `.env` 中 `VITE_API_BASE=http://localhost:8080`。无后端时可设 `VITE_USE_MOCK=true`。

## 如何测试

### 1. 自动化（推荐每次改代码后跑一遍）

**扩展（BizTranslate-web）**

```bash
cd BizTranslate-web
npm install
npm run lint
npm run build
```

- `lint`：ESLint 检查 `src` 下 TS/TSX。  
- `build`：先 `tsc --noEmit` 再 `vite build`；通过表示类型与打包无报错，产物在 `dist/`。  
- 若本机 `pnpm install` 因镜像或 Node 版本报错，可改用 **`npm install`**（与上表一致）。

**后端（BizTranslate-service）**

```bash
cd BizTranslate-service
mvn test
```

- 跑单元 / 集成测试（如计费流程等）；通过表示当前后端契约与核心逻辑可回归。

**CI**（可选）：仓库根 `.github/workflows/ci.yml` 会对 web 与 service 做安装与构建/测试，与 PR 对齐。

---

### 2. 扩展手动测试（Chrome）

**准备**

1. 按上文完成 `npm run build`（开发调试也可用 `npm run dev`，按 [BizTranslate-web/README.md](./BizTranslate-web/README.md) 说明加载）。  
2. 打开 Chrome → `chrome://extensions` → 打开「开发者模式」→「加载已解压的扩展程序」→ 选择 **`BizTranslate-web/dist`** 目录。  
3. 配置 `BizTranslate-web/.env`：  
   - **只测扩展、不调本地 Java**：设 `VITE_USE_MOCK=true`（Service Worker 内 Mock 翻译/部分接口）。  
   - **联调本地后端**：设 `VITE_USE_MOCK=false` 且 `VITE_API_BASE=http://localhost:8080`，并先启动 `mvn spring-boot:run`。

**建议 smoke 路径（最小闭环）**

| 模块 | 操作入口 | 预期（摘要） |
|------|-----------|--------------|
| 划词 | 任意 https 页选中文本悬停约 300ms | 浮窗出现译文；可复制、发音（如已授权） |
| 开关 | 扩展 Popup 关闭「开启」 | 划词不再出现浮窗；工具栏图标变灰 |
| 历史 | Options「历史记录」 | 划词成功后产生记录；免费版最多约 30 条（见产品说明） |
| 全文 | Popup 或快捷键 / 右键「全文翻译」 | 页内顶栏、还原；超长有拦截提示 |
| 设置 | Options 各 Tab | 语言、隐私、会员（Mock 登录）、快捷键页可读 |
| 长文本 | Options → 长文本翻译 | TXT/DOCX 可载入（DOCX 为本地解析）；`VITE_USE_MOCK=true` 时可跑 Mock 分段任务 |

**详细用例表**

- MVP 划词/历史/开关等：见 [BizTranslate-web/docs/MVP-QA.md](./BizTranslate-web/docs/MVP-QA.md)。  
- P6 回归矩阵（登记式）：见 [BizTranslate-web/docs/P6-regression-matrix.md](./BizTranslate-web/docs/P6-regression-matrix.md)。

---

### 3. 后端手动测试

1. `cd BizTranslate-service && mvn spring-boot:run`。  
2. 浏览器或 curl 访问：`http://localhost:8080/privacy.html`（应 200，供商店隐私 URL 联调）。  
3. 扩展侧将 `VITE_API_BASE` 指向上述地址，`VITE_USE_MOCK=false`，在网页上走登录/翻译/支付沙箱等流程（具体路径见 `BizTranslate-service/docs` 与 web 下 `docs/api-*.md`）。

---

### 4. 常见问题

| 现象 | 处理 |
|------|------|
| 扩展加载后 Popup 白屏 | 打开 `chrome://extensions` → 该扩展「错误」；或 F12 对 Popup / Options 单独检查控制台 |
| 翻译一直 Mock | 检查 `.env` 是否 `VITE_USE_MOCK=true` |
| 跨域或 401 | 确认 `VITE_API_BASE` 与后端地址一致；后端 `SecurityConfig` 是否放行对应路径 |

## 分支约定

- `main`：稳定可发布  
- `develop`：日常集成（详见 [BizTranslate-web/CONTRIBUTING.md](./BizTranslate-web/CONTRIBUTING.md)）