第 01 章
快速开始与系统架构
环境要求、部署步骤、环境变量清单、分层架构与三大核心业务调用链。
1.1 环境要求
| 依赖 | 版本 / 要求 | 用途 | 是否必需 |
|---|---|---|---|
JDK | 21 | 运行时 | 必需 |
Maven | 3.8+ | 构建 | 必需 |
MySQL | 8.x（utf8mb4） | 业务库 translation，15+ 张表 | 必需 |
Redis | 6.x+ | 登录 Token、翻译缓存、验证码 | 必需 |
MinIO | 任意近期版本 | 文档原文 / 译文对象存储 | 使用文档翻译时必需 |
RocketMQ | 4.9+ | 订单超时自动取消 | 可选（APP_MQ_ENABLED=false 可关闭） |
Elasticsearch | — | 预留搜索能力 | 可选，代码层未强依赖 |
| 通义千问 API Key | DashScope | LLM 翻译 / 客服 / 润色 / 质量评估 | 使用 QWEN 引擎时必需 |
| 阿里云翻译 AK | alimt 服务 | 机器翻译引擎与语种检测 | 使用 ALIBABA_CLOUD 引擎时必需 |
| 支付宝 / 微信支付商户参数 | — | 扫码支付 | 使用支付功能时必需 |
未配置外部服务会怎样？
系统不会因此不可用：翻译引擎未配置或调用失败时自动降级到内置 Mock 演示引擎（返回演示译文并自动退回点数）； RocketMQ 未启用时订单不会自动取消（可手动取消或管理端处理）；MinIO 未配置时文档翻译链路不可用，其余功能正常。
1.2 部署步骤
- 初始化数据库
创建数据库
translation（utf8mb4），执行database/translation_init_*.sql完整初始化快照（建表 + 初始数据）。 - 准备中间件
启动 MySQL / Redis / MinIO（可选 RocketMQ），将
application.yml或环境变量中的连接地址指向实际实例。 - 配置密钥环境变量
按 1.3 节清单配置通义千问、阿里云翻译、支付渠道等密钥（生产环境务必注入
JWT_SECRET）。 - 构建并启动
见下方命令，应用监听
8090端口。 - 验证
访问
http://localhost:8090/进入首页；GET /actuator/health应返回UP；GET /api/translation/health返回服务版本。
# 开发模式启动 mvn clean spring-boot:run # 或打包运行 mvn clean package -DskipTests java -jar target/ai-translation-assistant-1.0.0.jar
1.3 环境变量清单
| 变量 | 用途 | 默认 / 占位 |
|---|---|---|
QWEN_WEATHER_API_KEY | 通义千问 DashScope API Key | your_qwen_api_key_here |
ALIYUN_ACCESS_KEY_ID | 阿里云翻译 AccessKey ID | your-access-key-id |
ALIYUN_ACCESS_KEY_SECRET | 阿里云翻译 AccessKey Secret | your-access-key-secret |
JWT_SECRET | JWT 签名密钥（≥32 字节，生产必须覆盖默认值） | 配置文件默认值 |
APP_BASE_URL | 支付扫码回调主机地址 | http://localhost:8090 |
APP_MQ_ENABLED | 是否启用 RocketMQ 消费者（订单超时取消） | false |
PAY_ALIPAY_SANDBOX | 支付宝沙箱开关 | true |
PAY_ALIPAY_APP_ID / _PRIVATE_KEY / _PUBLIC_KEY / _NOTIFY_URL | 支付宝应用参数与回调地址 | 空 / 默认回调 /api/payment/notify/alipay |
PAY_WECHAT_APP_ID / _MCHID / _SERIAL_NO / _API_V3_KEY / _PRIVATE_KEY_PATH / _NOTIFY_URL | 微信支付商户参数 | 空 |
1.4 系统分层架构
代码包根为 com.terry.xu.translation，自上而下分为六层，依赖方向单向向下：
| 层 | 包 | 职责 |
|---|---|---|
| Web 接入层 | application/controller | REST 控制器 + 页面控制器（PageController），参数校验、用户上下文注入 |
| 安全 | application/security | AuthTokenInterceptor 拦截鉴权、JwtUtil 令牌签发校验、UserContext 当前用户 |
| 异常 / 响应 | application/handler、facade | GlobalExceptionHandler 全局异常矩阵；ApiResponse / PagedResponse 统一契约 |
| 业务逻辑层 | business/service | 翻译编排、RAG 检索、SSE 流式推送、文档策略工厂、订单支付、术语、质量、润色 |
| 支付通道 | payment | PaymentChannelService 接口 + Registry + 支付宝 / 微信 / 银联三渠道实现 |
| 领域 / 持久层 | domain、persistent/mapper | 实体、枚举、DTO；MyBatis-Plus Mapper |
横向组件
- ApiResponseAdvice：自动将控制器返回值包装为统一响应结构（SSE / 二进制 / 已包装体除外）。
- RequestLoggingFilter：请求日志过滤器，记录出入参摘要。
- OrderCancelProducer / Listener：RocketMQ 延时消息生产与消费（订单超时取消）。
- 线程池：
document.translation.executor（文档异步翻译，4 核心 / 8 最大 / 50 队列）与chat.sse.executor（SSE 推送，8 核心 / 20 最大 / 500 队列，前缀chat-sse-）。
1.5 三大核心业务调用链
① 文本翻译（POST /api/translation/translate）
- 参数与语言对校验Bean Validation 校验请求体，校验语言对是否受支持（auto 源语言合法）。
- 查翻译缓存命中
@Cacheable("translationCache")直接返回，不扣点。 - 扣点点数优先、会员额度补足；不足抛
InsufficientPointsException→ HTTP 402。 - RAG 增强检索术语库与历史翻译，Embedding 向量相似度重排，注入引擎提示词上下文。
- 引擎路由
ALIBABA_CLOUD→ 阿里云 TranslateGeneral；QWEN→ 通义千问；其他 → Mock。 - 落缓存与存档写入翻译缓存，保存
TranslationRecord记录，返回带计费信息的响应。
② 文档翻译（POST /api/document/upload → start → progress）
- 上传文件校验（8 种格式 / 50MB）后存入 MinIO，落库
document_translations。 - 启动异步任务
POST /start/{id}按页数预扣点数，提交document.translation.executor线程池。 - 策略解析与翻译按扩展名选择解析器（PDFBox / POI / 纯文本），提取文本行批量翻译，失败重试，仍失败保留原文。
- 回写与上传译文回写文档字节，上传 MinIO，更新进度与状态（COMPLETED / FAILED）。
- 下载
GET /download-url/{id}生成 600 秒预签名下载链接。
③ 会员订单与支付
- 下单
POST /api/membership/order创建 PENDING 订单（49/139/299 元），订单号MO+毫秒时间戳，30 分钟有效期。 - 延时取消发送 RocketMQ 延时消息（delayLevel=16 ≈ 30 分钟），超时未支付自动置 CANCELLED。
- 预下单
POST /api/payment/prepay走支付宝当面付 / 微信 Native 生成二维码串。 - 支付确认支付宝异步回调验签置 PAID；或测试流程
POST /api/payment/confirm主动确认。 - 权益生效开通会员（按月数授予月度额度），赠送点数入账。