1

doc/admin_requirements.md

@@ -0,0 +1,59 @@
+# 管理端需求说明（配件管家）
+
+本文件描述管理端前端与后端的需求要点，遵循“默认同意，管理端可拉黑/恢复”的运营策略；所有可配置值放置在配置或数据库，不允许硬编码。
+
+## 1. 运营策略
+- 用户与用户配件（投稿/商品）默认允许展示与使用。
+- 管理端具备拉黑与恢复能力：
+  - 拉黑后：对应对象在前台/小程序/客户侧不可见或被限制。
+  - 恢复后：恢复正常可用状态。
+
+## 2. 数据模型
+### 2.1 用户黑名单
+- 复用 `users.status` 字段：`1=正常`，`0=黑名单`。
+- 管理端动作：
+  - 拉黑用户 → `PUT /api/admin/users/{id}` body `{ status: 0 }`
+  - 恢复用户 → `PUT /api/admin/users/{id}` body `{ status: 1 }`
+
+### 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` 并补齐索引；前台/小程序查询添加过滤条件。
+- 若采用专表方案：保持同名字段与相同行为，编写同步脚本将历史数据初始化为非黑名单。