PartsInquiry/doc/admin_requirements.md

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

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

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