2

doc/admin_requirements.md

@@ -1,59 +1,26 @@
-# 管理端需求说明（配件管家）
+# 管理端需求文档
 
-本文件描述管理端前端与后端的需求要点，遵循“默认同意，管理端可拉黑/恢复”的运营策略；所有可配置值放置在配置或数据库，不允许硬编码。
+## 1. 页面结构
+- **VIP 系统**：含价格配置、充值记录与会员列表三块；价格修改需立即生效并同步到前端 `VIP_PRICE` 显示；列表支持手机号模糊检索。
+- **公告管理**：支持公告的新增、编辑、发布、下线、置顶，字段包括标题、内容、标签、有效期、生效状态。
+- **咨询回复**：列出店铺咨询，管理员可单次回复并标记已解决。
+- **用户管理**：展示用户基本信息，支持编辑、启停（黑名单）。
+- **用户配件管理**：适配用户提交的配件数据，允许管理员编辑品牌/型号/规格与图片链接。
+- **供应商管理**：列表检索、创建、编辑供应商信息，含欠款字段展示。
+- **主数据字典**：主单位、主类别维护入口，仅平台管理员可用。
 
-## 1. 运营策略
-- 用户与用户配件（投稿/商品）默认允许展示与使用。
-- 管理端具备拉黑与恢复能力：
-  - 拉黑后：对应对象在前台/小程序/客户侧不可见或被限制。
-  - 恢复后：恢复正常可用状态。
+## 2. 认证约束
+- 所有接口通过 `AdminAuthInterceptor` 鉴权：优先 Bearer Token，其次 `X-Admin-Id`/`X-User-Id`。
+- 请求必须携带 `X-Shop-Id`，缺省取 1；多租户数据严格隔离。
+- 登录功能正在开发中，当前临时通过本地存储写入管理员 ID。
 
-## 2. 数据模型
-### 2.1 用户黑名单
-- 复用 `users.status` 字段：`1=正常`，`0=黑名单`。
-- 管理端动作：
-  - 拉黑用户 → `PUT /api/admin/users/{id}` body `{ status: 0 }`
-  - 恢复用户 → `PUT /api/admin/users/{id}` body `{ status: 1 }`
+## 3. 功能约束
+- 禁止硬编码配置值，价格、库存等需从后端接口读取。
+- 上传图片统一调用 `/api/attachments`，返回的 `url` 需落库或直接引用。
+- 所有列表接口支持分页（默认 `page=1&size=20`）；前端需预留分页扩展点。
+- 删除功能未启用，均以启停或逻辑状态位代替。
 
-### 2.2 用户配件黑名单
-- 建议在承载表中增加状态位供管理端控制：
-  - 若使用 `products` 承载：新增 `products.is_blacklisted TINYINT(1) NOT NULL DEFAULT 0`（黑名单标记）。
-  - 若使用专表（如未来 `part_submissions`/`user_parts`）：同样增加 `is_blacklisted`。
-- 索引建议：`KEY idx_products_shop_blacklist (shop_id, is_blacklisted)`，便于后台筛选。
-- 管理端动作：
-  - 拉黑配件 → `PUT /api/admin/parts/{id}/blacklist`
-  - 恢复配件 → `PUT /api/admin/parts/{id}/restore`
-
-## 3. 前端（admin/）
-- 路由：
-  - 用户管理：列表提供“拉黑/恢复”按钮，状态显示“正常/黑名单”。
-  - 用户配件管理：列表提供“拉黑/恢复”按钮，状态显示“正常/黑名单”。
-- Mock：
-  - 开启 `VITE_USE_MOCK=true` 使用 `public/mock/*.json`。
-
-## 4. 后端接口（OpenAPI 标注）
-- 用户：
-  - `GET /api/admin/users?kw=` → 列表（分页）
-  - `PUT /api/admin/users/{id}` → 修改 `status`/`name`/`phone`/`role`
-- 用户配件：
-  - `GET /api/admin/parts?kw=&status=` → 列表（分页，支持按 `is_blacklisted` 过滤）
-  - `PUT /api/admin/parts/{id}/blacklist` → 标记黑名单
-  - `PUT /api/admin/parts/{id}/restore` → 取消黑名单
-- 咨询服务：
-  - `GET /api/admin/consults?status=&kw=` → 列表
-  - `POST /api/admin/consults/{id}/reply` → 回复
-  - `PUT /api/admin/consults/{id}/resolve` → 标记解决（前端需即时将该行状态改为 resolved）
-
-说明：OpenAPI 需更新到 `doc/openapi.yaml` 并在 summary 中标注“❌ Partially Implemented”。
-
-## 5. 前台/小程序侧行为
-- 用户被拉黑：登录受限或仅保留最低权限（由业务规则定义）；其数据不可见或只读。
-- 配件被拉黑：前台与小程序配件列表/搜索/选择均需基于 `is_blacklisted=0` 过滤。
-
-## 6. 审计与可观测性
-- 建议记录操作日志（操作者、对象、操作、时间），便于追责与回溯。
-- 建议在管理端提供简单的筛选/导出功能。
-
-## 7. 迁移计划
-- 若使用 `products`：新增字段 `is_blacklisted` 并补齐索引；前台/小程序查询添加过滤条件。
-- 若采用专表方案：保持同名字段与相同行为，编写同步脚本将历史数据初始化为非黑名单。
+## 4. 未完成功能
+- 管理端登录页与权限粒度控制尚未上线。
+- 配件审核流仅完成基础编辑，驳回/通过流程待接入。
+- 公告板目前缺少多语言与富文本支持。