# 管理端需求说明（配件管家）

本文件描述管理端前端与后端的需求要点，遵循“默认同意，管理端可拉黑/恢复”的运营策略；所有可配置值放置在配置或数据库，不允许硬编码。

## 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` 并补齐索引；前台/小程序查询添加过滤条件。
- 若采用专表方案：保持同名字段与相同行为，编写同步脚本将历史数据初始化为非黑名单。