PartsInquiry/后端使用文档.md at 8885fb766ab174cd5d2c6a9bc96c02161686c2c5

TONASPACE/PartsInquiry

Fork 0

Files

Wdp-ab ed26244cdb 2

2025-09-27 22:57:59 +08:00

5.2 KiB

Raw Blame History

https://icons8.com/

后端使用文档（简版）

本文件用于指导在新电脑上启动 Spring Boot 后端，并直接连接远程 MySQL 数据库。

环境要求

操作系统: Windows 10/11（PowerShell）
JDK: 17 及以上（java -version 应显示 17+）
网络: 可访问 mysql.tonaspace.com:3306
构建工具: 无需单独安装 Maven（项目已提供 mvnw.cmd）

快速启动（默认连接远程库）

打开 PowerShell，进入项目后端目录：

cd backend

启动后端（使用默认远程数据库配置）：

.\mvnw.cmd spring-boot:run -DskipTests

说明：application.properties 已内置远程库默认值（DB_URL/DB_USER/DB_PASSWORD）。除非你的终端已设置了同名环境变量并想覆盖，否则无需再配置。

启动 Python 条码识别服务（可选）

本项目提供 Python 条码识别服务（FastAPI，目录 backend/txm），可与 Java 同时启动或独立启动。

独立启动（推荐先验证）：

cd .\backend\txm; python -m pip install -r requirements.txt; python -m app.server.main

随 Java 一并启动（通过环境变量启用；默认关闭）：

$env:PY_BARCODE_ENABLED="true"; $env:PY_BARCODE_WORKDIR=".\txm"; $env:PY_BARCODE_PYTHON="python"; .\mvnw.cmd spring-boot:run -DskipTests

可覆盖的相关配置键（同名环境变量可覆盖，括号为默认值）：

python.barcode.enabled=${PY_BARCODE_ENABLED:false}
python.barcode.working-dir=${PY_BARCODE_WORKDIR:./txm}
python.barcode.python=${PY_BARCODE_PYTHON:python}
python.barcode.app-module=${PY_BARCODE_APP_MODULE:app.server.main}
python.barcode.use-module-main=${PY_BARCODE_USE_MODULE:true}
python.barcode.host=${PY_BARCODE_HOST:127.0.0.1}
python.barcode.port=${PY_BARCODE_PORT:8000}
python.barcode.health-path=${PY_BARCODE_HEALTH:/openapi.json}
python.barcode.startup-timeout-sec=${PY_BARCODE_TIMEOUT:20}
python.barcode.log-file=${PY_BARCODE_LOG:}

Java 侧代理接口：POST /api/barcode/scan（表单字段名：file）。返回：

{
  success: true,
  barcodeType: 'EAN13' | 'CODE128' | 'QRCODE' | ...,
  barcode: '字符串',
  others: [{ type, code }, ...]  // 可能为空
}

说明：优先 EAN-13，否则返回任意码制的第一个结果，并同时返回 others。

可选：显式指定远程数据库（避免被旧环境变量覆盖）

如需显式声明一次连接信息（建议在怀疑本机已有旧变量时使用）：

$env:DB_URL="jdbc:mysql://mysql.tonaspace.com:3306/partsinquiry?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=utf8mb4&connectionCollation=utf8mb4_0900_ai_ci"; $env:DB_USER="root"; $env:DB_PASSWORD="TONA1234"
.\mvnw.cmd spring-boot:run -DskipTests

启动验证

浏览器访问：http://localhost:8080/api/dashboard/overview
- 返回概览数据即表示服务与数据库连接正常

按用户ID登录（用户端快速登录通道）

仅在调试或特定场景启用。默认关闭。

启用开关（临时）：

$env:AUTH_ID_LOGIN_ENABLED="true"; .\mvnw.cmd spring-boot:run -DskipTests

请求示例：

POST http://localhost:8080/api/auth/login-by-id
Content-Type: application/json

{ "userId": 2 }

成功返回：{ token, expiresIn, user:{ userId, shopId, phone? } }
之后在调用业务接口时携带：Authorization: Bearer <token>

常见问题

端口被占用：更换启动端口

.\mvnw.cmd spring-boot:run -DskipTests -Dserver.port=8081

远程库连不通：检查网络是否放行 mysql.tonaspace.com:3306；如在公司网络，确认代理/防火墙策略已放通。
Java 未安装或版本不符：安装 JDK 17，并在新开终端内确认 java -version。

可选设置

占位图（非必需）：若需启用 /api/attachments/placeholder

$env:ATTACHMENTS_PLACEHOLDER_IMAGE="C:\Users\Public\Pictures\placeholder.png"

前端联调 CORS（按需）：

$env:CORS_ALLOWED_ORIGINS="http://localhost:5173"

可选：打包为可执行 JAR

cd backend; .\mvnw.cmd clean package -DskipTests; java -jar .\target\demo-0.0.1-SNAPSHOT.jar

SMTP 邮件配置（Windows PowerShell）

请在启动后端前设置以下环境变量（QQ 邮箱）：

$env:MAIL_HOST="smtp.qq.com"; $env:MAIL_PORT="465"; $env:MAIL_PROTOCOL="smtps"; $env:MAIL_USERNAME="sdssds@163.com"; $env:MAIL_PASSWORD="NQLihrab8vGiAjiE"; $env:MAIL_FROM="sdssds@163.com"; $env:MAIL_SUBJECT_PREFIX="[配件查询]"

说明：

MAIL_USERNAME/MAIL_FROM：发件邮箱地址
MAIL_PASSWORD：SMTP 授权码
采用 465 + SMTPS + SSL；若使用 587，请改为 MAIL_PORT=587 并设置 spring.mail.properties.mail.smtp.starttls.enable=true。

邮箱验证码接口

POST /api/auth/email/send：请求体 { email, scene? }，成功返回 { ok, cooldownSec }
POST /api/auth/email/login：请求体 { email, code }，成功返回 { token, expiresIn, user }

返回的 JWT 通过 Authorization: Bearer <token> 使用，解析后包含 userId/shopId/email/provider 等声明。

以上即为在新电脑上启动后端并连接远程数据库的最小步骤。

5.2 KiB Raw Blame History Unescape Escape