2
This commit is contained in:
71
backend/txm/doc/API.md
Normal file
71
backend/txm/doc/API.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# 条形码识别 API 对接文档
|
||||
|
||||
本文档说明与 Java 后端对接的上传识别接口，返回 EAN‑13 结果；若无法识别返回明确错误提示。
|
||||
|
||||
## 基本信息
|
||||
- 接口地址：`/api/barcode/scan`
|
||||
- 请求方式：`POST multipart/form-data`
|
||||
- 参数：
|
||||
- `file`：图片文件（二进制）。
|
||||
- 成功响应（HTTP 200）：
|
||||
```json
|
||||
{ "success": true, "barcodeType": "EAN13", "barcode": "6901234567892" }
|
||||
```
|
||||
- 失败响应（HTTP 400）：
|
||||
```json
|
||||
{ "success": false, "message": "无法识别，请重新上传" }
|
||||
```
|
||||
|
||||
## 请求示例（PowerShell）
|
||||
```powershell
|
||||
Invoke-RestMethod -Uri http://127.0.0.1:8000/api/barcode/scan -Method Post -Form @{ file = Get-Item .\sample.jpg }
|
||||
```
|
||||
|
||||
## 请求示例（curl）
|
||||
```bash
|
||||
curl -F "file=@sample.jpg" http://127.0.0.1:8000/api/barcode/scan
|
||||
```
|
||||
|
||||
## Java 示例（Spring WebClient）
|
||||
```java
|
||||
WebClient client = WebClient.create("http://127.0.0.1:8000");
|
||||
MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
|
||||
body.add("file", new FileSystemResource(new File("sample.jpg")));
|
||||
|
||||
Map res = client.post()
|
||||
.uri("/api/barcode/scan")
|
||||
.contentType(MediaType.MULTIPART_FORM_DATA)
|
||||
.body(BodyInserters.fromMultipartData(body))
|
||||
.retrieve()
|
||||
.onStatus(s -> s.value() == 400, r -> r.bodyToMono(String.class).map(RuntimeException::new))
|
||||
.bodyToMono(Map.class)
|
||||
.block();
|
||||
|
||||
System.out.println(res);
|
||||
```
|
||||
|
||||
## Java 示例（Spring RestTemplate）
|
||||
```java
|
||||
RestTemplate rest = new RestTemplate();
|
||||
HttpHeaders headers = new HttpHeaders();
|
||||
headers.setContentType(MediaType.MULTIPART_FORM_DATA);
|
||||
MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
|
||||
body.add("file", new FileSystemResource("sample.jpg"));
|
||||
HttpEntity<MultiValueMap<String, Object>> req = new HttpEntity<>(body, headers);
|
||||
|
||||
ResponseEntity<String> resp = rest.postForEntity("http://127.0.0.1:8000/api/barcode/scan", req, String.class);
|
||||
System.out.println(resp.getStatusCode());
|
||||
System.out.println(resp.getBody());
|
||||
```
|
||||
|
||||
## 返回字段说明
|
||||
- `success`：是否识别成功。
|
||||
- `barcodeType`：条码类型（当前为 `EAN13`）。
|
||||
- `barcode`：条码数字串。
|
||||
- `message`：失败时的人类可读说明。
|
||||
|
||||
## 错误码
|
||||
- 400：文件为空、图片解析失败、或未识别；返回 `{ success:false, message:"无法识别，请重新上传" }`。
|
||||
- 413：文件过大（受 `config/config.yaml` 中 `app.server.max_upload_mb` 限制）。
|
||||
|
||||
|
||||
51
backend/txm/doc/README.md
Normal file
51
backend/txm/doc/README.md
Normal file
@@ -0,0 +1,51 @@
|
||||
使用说明
|
||||
|
||||
1. 安装依赖：
|
||||
```powershell
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
2. 启动 Tk 测试界面：
|
||||
```powershell
|
||||
python -m app.ui.tk_app
|
||||
```
|
||||
3. 在界面中点击“选择图片”，然后点击“识别 EAN-13”。
|
||||
|
||||
摄像头识别
|
||||
1. 在 Tk 界面点击“摄像头识别”，程序会打开默认摄像头（`config/config.yaml` 可配置 index、分辨率与轮询间隔）。
|
||||
2. 一旦识别到任意条码（优先 EAN‑13），会自动关闭摄像头并在界面显示结果。
|
||||
3. 再次点击“停止摄像头”可手动关闭。
|
||||
|
||||
HTTP 服务（上传识别）
|
||||
1. 启动服务：
|
||||
```powershell
|
||||
python -m app.server.main
|
||||
```
|
||||
2. PowerShell 上传示例：
|
||||
```powershell
|
||||
Invoke-RestMethod -Uri http://127.0.0.1:8000/recognize/ean13 -Method Post -Form @{ file = Get-Item .\sample.jpg }
|
||||
```
|
||||
3. 响应：
|
||||
```json
|
||||
{ "code": "6901234567892", "type": "EAN13", "others": [{ "type": "CODE128", "code": "..." }], "message": "ok" }
|
||||
```
|
||||
|
||||
配置说明
|
||||
- 编辑 `config/config.yaml` 可调整预处理、ROI 过滤、解码参数；字体路径已按系统自动选择。
|
||||
- `app.server` 中的 `host/port/max_upload_mb` 控制 HTTP 服务监听与上传大小限制。
|
||||
|
||||
注意事项
|
||||
- 该程序不会自动启动摄像头或后台任务，均需用户手动触发。
|
||||
- 若图片分辨率过低或条码倾斜严重，识别率会下降，可增大 `warp_target_height` 与 `sample_rows` 数量。
|
||||
|
||||
Pyzbar/ZBar 安装说明
|
||||
- Windows: 直接 `pip install pyzbar` 即可（已包含 zbar DLL）。
|
||||
- macOS: 安装 zbar 库后再安装 pyzbar：
|
||||
```bash
|
||||
brew install zbar; pip install pyzbar
|
||||
```
|
||||
- Linux (Debian/Ubuntu)：
|
||||
```bash
|
||||
sudo apt-get update; sudo apt-get install -y libzbar0; pip install pyzbar
|
||||
```
|
||||
|
||||
|
||||
94
backend/txm/doc/openapi.yaml
Normal file
94
backend/txm/doc/openapi.yaml
Normal file
@@ -0,0 +1,94 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: 条形码识别端口 API
|
||||
version: 1.0.0
|
||||
description: 本地视觉识别 EAN-13 的测试接口定义（示例）。
|
||||
servers:
|
||||
- url: http://localhost:8000
|
||||
paths:
|
||||
/recognize/ean13:
|
||||
post:
|
||||
summary: 识别 EAN-13（✅ 完全实现：Pyzbar+自研回退，UI 与服务端可用）
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
responses:
|
||||
"200":
|
||||
description: 成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
description: EAN-13 数字串（未识别为空字符串）
|
||||
message:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
description: 命中的主类型；未识别为空
|
||||
others:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
code:
|
||||
type: string
|
||||
"400":
|
||||
description: 参数错误
|
||||
"500":
|
||||
description: 服务器错误
|
||||
/api/barcode/scan:
|
||||
post:
|
||||
summary: 图片上传并识别 EAN-13（✅ 完全实现）
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
responses:
|
||||
"200":
|
||||
description: 成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
barcodeType:
|
||||
type: string
|
||||
example: EAN13
|
||||
barcode:
|
||||
type: string
|
||||
example: 6901234567892
|
||||
"400":
|
||||
description: 无法识别或参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: false
|
||||
message:
|
||||
type: string
|
||||
example: 无法识别，请重新上传
|
||||
|
||||
|
||||
77
backend/txm/doc/同步文档.md
Normal file
77
backend/txm/doc/同步文档.md
Normal file
@@ -0,0 +1,77 @@
|
||||
## 前后端数据库状态说明
|
||||
|
||||
**更新日期**: 2025-09-17
|
||||
|
||||
### 概要
|
||||
- 数据库已落地：已在远程 MySQL `mysql.tonaspace.com` 的 `partsinquiry` 库完成初始化（表结构与触发器已创建）。
|
||||
- 已生成根目录文档：`/doc/database_documentation.md` 已同步线上结构（字段、索引、外键、触发器）。
|
||||
- 后端代码仍未配置数据源依赖与连接，前端无本地结构化存储方案。
|
||||
|
||||
### 已建库与连接信息（用于部署/联调）
|
||||
- Address: `mysql.tonaspace.com`
|
||||
- Database: `partsinquiry`
|
||||
- User: `root`
|
||||
- 说明：所有结构变更均通过 MysqlMCP 执行并已落地到线上库。
|
||||
|
||||
### 角色与模拟数据策略（统一为店长）
|
||||
- 当前不进行角色划分，系统仅保留“店长”角色。
|
||||
- 已将所有用户记录统一为：`role='owner'`、`is_owner=1`。
|
||||
- 前端/后端权限逻辑暂未启用，后续若引入权限体系，再行扩展角色与边界。
|
||||
|
||||
### 小程序默认用户（可开关，默认关闭）
|
||||
- 目的：开发/演示阶段，便于免登录联调。
|
||||
- 机制：前端在请求头附加 `X-User-Id`（值为张老板 id=2），仅当开关开启时。
|
||||
- 开关：
|
||||
- 环境变量：`VITE_APP_ENABLE_DEFAULT_USER=true` 与 `VITE_APP_DEFAULT_USER_ID=2`
|
||||
- 或本地存储：`ENABLE_DEFAULT_USER=true` 与 `DEFAULT_USER_ID=2`
|
||||
- 关闭：不设置/置为 `false` 即可停用（生产环境默认关闭）。
|
||||
- 完全移除：删除 `frontend/common/config.js` 中默认用户配置与 `frontend/common/http.js` 中注入逻辑。
|
||||
|
||||
### 后端（Spring Boot）状态
|
||||
- 依赖：`pom.xml` 已包含 `spring-boot-starter-web`、`spring-boot-starter-data-jpa`、`mysql-connector-j`。
|
||||
- 配置：`application.properties` 使用环境变量注入数据源，已补充 Hikari/JPA；新增附件占位图配置：
|
||||
- `attachments.placeholder.image-path`（env: `ATTACHMENTS_PLACEHOLDER_IMAGE`）
|
||||
- `attachments.placeholder.url-path`（env: `ATTACHMENTS_PLACEHOLDER_URL`，默认 `/api/attachments/placeholder`）
|
||||
- 接口：新增附件相关接口（占位方案）：
|
||||
- POST `/api/attachments`：忽略内容，返回 `{ url: "/api/attachments/placeholder" }`
|
||||
- GET `/api/attachments/placeholder`：返回本地占位图二进制
|
||||
- 迁移：仍建议引入 Flyway/Liquibase；结构变更继续通过 MysqlMCP 并同步 `/doc/database_documentation.md`。
|
||||
|
||||
### 前端（uni-app）数据库状态
|
||||
- 数据持久化：未见 IndexedDB/WebSQL/SQLite/云数据库使用；页面数据为内置静态数据。
|
||||
- 本地存储：未见 `uni.setStorage`/`uni.getStorage` 的集中封装或结构化键空间设计。
|
||||
- 结论：前端当前不涉及本地数据库或结构化存储方案。
|
||||
|
||||
### 风险与影响
|
||||
- 后端未配置数据源与接口，应用无法读写远端库（虽已建表）。
|
||||
- 无接口契约，前后端仍无法联调涉及数据库的功能。
|
||||
|
||||
### 建议的后续行动（不自动执行）
|
||||
- 在后端引入依赖：`spring-boot-starter-web`、`spring-boot-starter-data-jpa`、`mysql-connector-j`。
|
||||
- 配置数据源：使用环境变量注入 `SPRING_DATASOURCE_URL`、`SPRING_DATASOURCE_USERNAME`、`SPRING_DATASOURCE_PASSWORD` 等，指向上述远程库。
|
||||
- 引入迁移工具（Flyway/Liquibase）管理 DDL；后续所有变更继续通过 MysqlMCP 执行，并同步 `/doc/database_documentation.md`。
|
||||
- 增加健康检查与基础 CRUD 接口；在 `/doc/openapi.yaml` 按规范登记并标注实现状态（❌/✅）。
|
||||
|
||||
### 前端默认连接策略
|
||||
- 默认后端地址：`http://127.0.0.1:8080`（可被环境变量/Storage 覆盖）
|
||||
- 多地址重试：按顺序尝试（去重处理）：`[ENV, Storage, 127.0.0.1:8080, localhost:8080]`
|
||||
- 默认用户：开启（可被环境变量/Storage 关闭），请求自动附带 `X-User-Id`（默认 `2`）。
|
||||
- 如需关闭：在 Storage 或构建环境中设置 `ENABLE_DEFAULT_USER=false`。
|
||||
|
||||
|
||||
### 占位图策略（当前阶段）
|
||||
- 说明：所有图片上传与展示均统一使用占位图，实际文件存储暂不开发。
|
||||
- 本地占位图：`C:\Users\21826\Desktop\Wj\PartsInquiry\backend\picture\屏幕截图 2025-08-14 134657.png`
|
||||
- 配置方式：
|
||||
- PowerShell（当前用户持久化）
|
||||
```powershell
|
||||
setx ATTACHMENTS_PLACEHOLDER_IMAGE "C:\\Users\\21826\\Desktop\\Wj\\PartsInquiry\\backend\\picture\\屏幕截图 2025-08-14 134657.png"
|
||||
setx ATTACHMENTS_PLACEHOLDER_URL "/api/attachments/placeholder"
|
||||
```
|
||||
- 应用重启后生效；也可在运行环境变量中注入。
|
||||
- 前端影响：
|
||||
- `components/ImageUploader.vue` 上传始终得到 `{ url: '/api/attachments/placeholder' }`
|
||||
- 商品列表/详情展示该占位图地址
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user