2
This commit is contained in:
@@ -1,59 +1,28 @@
|
||||
# 管理端开发文档
|
||||
## 管理端开发说明（当前实现）
|
||||
|
||||
本文档用于同步当前管理端（admin/）前端与数据库的开发状态与下一步计划。
|
||||
### 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()` 处理相对路径。
|
||||
|
||||
## 一、前端（admin/）
|
||||
- 技术栈：Vue3 + Vite + Element Plus
|
||||
- 主题：深色尊贵风格，数据展示面板/卡片/表格采用深蓝背景；Tag 颜色整体降亮。
|
||||
- 路由与页面：
|
||||
- `/vip-review`：VIP审核（默认页，卡片式，一卡一申请）
|
||||
- `/vip`：VIP管理（是否VIP、到期时间、启用/停用）
|
||||
- `/users`：用户管理（拉黑/恢复，状态文案“正常/黑名单”）
|
||||
- `/parts`：用户配件管理（拉黑/恢复）
|
||||
- `/consult`：咨询回复（回复/标记解决，标记后行内即时显示“已解决”）
|
||||
- Mock 数据：
|
||||
- 开启：`VITE_USE_MOCK=true`；使用 `public/mock/*.json`
|
||||
- 覆盖：`admin_vips.json`、`admin_vips_reviews.json`、`admin_users.json`、`admin_parts.json`、`admin_consults.json`
|
||||
- 状态：
|
||||
- 页面与交互：已完成
|
||||
- 主题色与降亮：已完成
|
||||
- Mock：已完成
|
||||
### 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，可在本地存储或环境变量覆盖），以匹配租户范围。
|
||||
|
||||
## 二、数据库（DB）
|
||||
- 已有与复用
|
||||
- `users.status`：1=正常、0=黑名单（供用户管理拉黑/恢复）
|
||||
- `global_skus`：公共SKU库（供未来配件审核通过后发布使用）
|
||||
- 新增表
|
||||
- `vip_users`：管理VIP（is_vip/status/expire_at/reviewer_id/reviewed_at/remark）
|
||||
- `consults`、`consult_replies`：咨询与回复
|
||||
- 字段与索引改动
|
||||
- `products.is_blacklisted TINYINT(1) NOT NULL DEFAULT 0`（黑名单标记）
|
||||
- 索引：`idx_products_shop_blacklist (shop_id, is_blacklisted)`
|
||||
- 文档：`doc/database_documentation.md` 已同步
|
||||
### 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 去重）。
|
||||
|
||||
## 三、API 规范（OpenAPI）
|
||||
- 已补充
|
||||
- 管理端VIP：`/api/admin/vips` 列表/创建/更新/审核通过/驳回（标注“❌ Partially Implemented”）
|
||||
- 待补充
|
||||
- 管理端用户：列表（kw）、更新（status 拉黑/恢复）
|
||||
- 管理端用户配件：列表（kw/status）、黑名单/恢复（更新 `products.is_blacklisted`）
|
||||
- 管理端咨询：列表（status/kw）、回复、标记解决
|
||||
|
||||
## 四、落地与联调建议
|
||||
- 后端接口：按上述待补充接口实现，完成后将 OpenAPI 的相应条目更新为“✅ Fully Implemented”。
|
||||
- 前台/小程序：默认过滤 `products.is_blacklisted=0`，防止黑名单配件外显。
|
||||
- 安全收口：后端增加 JWT 校验，从 Token 注入 `shopId/userId`，避免完全信任请求头。
|
||||
|
||||
## 五、环境与运行
|
||||
- 开发：
|
||||
```powershell
|
||||
cd admin; npm i; $env:VITE_APP_API_BASE_URL="http://127.0.0.1:8080"; $env:VITE_APP_SHOP_ID="1"; npm run dev
|
||||
```
|
||||
- Mock：
|
||||
```powershell
|
||||
cd admin; npm i; $env:VITE_USE_MOCK="true"; npm run dev
|
||||
```
|
||||
- 构建/预览：
|
||||
```powershell
|
||||
npm run build; npm run preview
|
||||
```
|
||||
### 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。
|
||||
|
||||
Reference in New Issue
Block a user