2

doc/后端使用文档.md

@@ -21,6 +21,49 @@ cd backend
 ```
 > 说明：`application.properties` 已内置远程库默认值（`DB_URL/DB_USER/DB_PASSWORD`）。除非你的终端已设置了同名环境变量并想覆盖，否则无需再配置。
 
+### 启动 Python 条码识别服务（可选）
+
+本项目提供 Python 条码识别服务（FastAPI，目录 `backend/txm`），可与 Java 同时启动或独立启动。
+
+- 独立启动（推荐先验证）：
+```powershell
+cd .\backend\txm; python -m pip install -r requirements.txt; python -m app.server.main
+```
+
+- 随 Java 一并启动（通过环境变量启用；默认关闭）：
+```powershell
+$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。
+
 ### 可选：显式指定远程数据库（避免被旧环境变量覆盖）
 如需显式声明一次连接信息（建议在怀疑本机已有旧变量时使用）：
 ```powershell
@@ -72,6 +115,25 @@ $env:CORS_ALLOWED_ORIGINS="http://localhost:5173"
 cd backend; .\mvnw.cmd clean package -DskipTests; java -jar .\target\demo-0.0.1-SNAPSHOT.jar
 ```
 
+### SMTP 邮件配置（Windows PowerShell）
+
+请在启动后端前设置以下环境变量（QQ 邮箱）：
+
+```powershell
+$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` 等声明。
+
 以上即为在新电脑上启动后端并连接远程数据库的最小步骤。