## 管理端开发说明（当前实现）

### 1. 模块概览
- **VIP 系统**：`/vip/system` 管理统一售价与充值记录，`/vip/list` 维护店铺会员状态。价格管理页面引用 `/api/admin/vip/system/price`，充值列表读取 `/api/admin/vip/system/recharges`。
- **公告管理**：`/notice/list` 支持公告检索、创建、编辑、发布与下线，对应接口 `/api/admin/notices` 及其子路径。
- **咨询回复**：`/consult` 基于 `/api/admin/consults` 完成列表、单次回复、标记已解决。
- **用户/配件/供应商**：`/users`、`/parts`、`/supplier` 依次调用 `/api/admin/users`、`/api/admin/parts`、`/api/suppliers` 进行检索与维护。
- **附件与图片**：图片上传统一走 `/api/attachments`，列表页展示时需通过 `withBaseUrl()` 处理相对路径。

### 2. 认证与上下文
- 后端默认启用 `AdminAuthInterceptor`，优先校验 Bearer Token；未登录情况下回退到请求头 `X-Admin-Id` 与 `X-User-Id`。
- 管理端前端目前仍使用本地存储写入 `USER_ID`/`ADMIN_ID`（详见 `admin/src/api/http.ts`）；接入登录页时需改为在登录成功后写入 Token 并移除默认 ID。
- 所有请求必须附带 `X-Shop-Id`（默认 1，可在本地存储或环境变量覆盖），以匹配租户范围。

### 3. 接口要点
- **VIP 列表**：`GET /api/admin/vips` 已落地；`POST /api/admin/vips` 需要传入 `shopId` 与 `userId` 才能成功创建。
- **VIP 价格**：`GET/PUT /api/admin/vip/system/price` 会清空 `vip_price` 再写入单条记录，不允许并行修改；可考虑后续改为 `UPDATE` 语句。
- **VIP 充值**：`GET /api/admin/vip/system/recharges` 支持关键字（姓名/手机号）过滤，默认按创建时间倒序。
- **公告管理**：创建与更新均支持标签、置顶、时间窗，未填写时间默认为即时生效/长期有效。
- **附件上传**：上传成功返回 `url` 与元信息，若需要落库请在业务表维持引用；多次上传同一文件会复用记录（按 hash 去重）。

### 4. 条码识别接入
- 管理端不提供扫码入口，仅用户端调用 `/api/barcode/scan`。
- 后端代理服务会将图片转发至 Python TXM（FastAPI）并返回首个匹配条码，需保持 Java 与 Python 两侧的 `PY_BARCODE_MAX_UPLOAD_MB` 一致。
- 部署时应通过环境变量配置：
  - `PY_BARCODE_HOST`/`PY_BARCODE_PORT`：Python 服务地址，默认 `127.0.0.1:8000`。
  - `PY_BARCODE_MAX_UPLOAD_MB`：上传大小限制，默认 8MB。
- 小程序端调用扫码接口需将后端域名加入“request 合法域名”并启用 HTTPS。