feat(admin-frontend): 补齐用户节点与订单运营工作台
新增用户高级筛选、批量操作与更多行级动作，支持邮件、 CSV、封禁恢复、订单分配、邀请查看、流量记录与重置流量 增强节点管理页的分页、父子筛选、跨页勾选、批量修改与 单节点置顶，并补齐后端批量更新 host、group_ids、rate 修复订单佣金状态误判问题，新增真实佣金筛选与行级确认， 同时优化仪表盘排行悬浮详情展示 补充 admin-frontend 独立 Dockerfile、Caddy 配置与 GHCR 发布工作流，支持通过独立镜像部署管理前端
This commit is contained in:
yinjianm
+179
@@ -0,0 +1,179 @@
|
||||
# 变更提案: admin-frontend-orders-commission-confirmation
|
||||
|
||||
## 元信息
|
||||
```yaml
|
||||
类型: 缺陷修复
|
||||
方案类型: implementation
|
||||
优先级: P1
|
||||
状态: 已完成
|
||||
创建: 2026-04-24
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 需求
|
||||
|
||||
### 背景
|
||||
`admin-frontend` 的 `#/subscriptions/orders` 订单管理页目前直接按 `commission_status` 渲染佣金状态。由于后端很多“无佣金订单”默认也会带 `commission_status = 0`，页面把这些订单一并显示成“待确认”，造成运营误判。同时，列表页缺少直接面向“真实待确认佣金订单”的筛选与快捷确认入口，只能进入详情抽屉手动改状态，效率较低。
|
||||
|
||||
### 目标
|
||||
- 修复无佣金订单被误显示为“待确认”的问题，让列表与详情抽屉的佣金状态表达与真实业务一致。
|
||||
- 在订单页增加“确认佣金”菜单，能一键筛出真实待确认的佣金订单。
|
||||
- 在列表行级菜单中加入“确认佣金”快捷操作，把真实待确认订单手动确认到“发放中”。
|
||||
- 保留详情抽屉内现有佣金状态维护能力，确保列表与详情行为一致。
|
||||
|
||||
### 约束条件
|
||||
```yaml
|
||||
时间约束: 本轮只处理 admin 订单页佣金可视化与确认流程，不扩展到返佣任务或提现模块
|
||||
性能约束: 继续复用现有 order/fetch 与 order/update 接口，不新增重型列表查询
|
||||
兼容性约束: 保持现有订单详情抽屉、佣金状态枚举与 Apple 风格后台视觉一致
|
||||
业务约束: “真实待确认”必须排除无佣金订单；列表快捷确认仅把状态改为 1（发放中），不直接标记为已发放
|
||||
验证约束: 优先执行 admin-frontend 的 Vite 构建验证；本地不依赖额外后端联调环境
|
||||
```
|
||||
|
||||
### 验收标准
|
||||
- [ ] 无佣金订单在列表和详情中不再显示为“待确认”，而是明确显示“无佣金”
|
||||
- [ ] 点击“确认佣金”菜单后，可筛出真实待确认的佣金订单，不再混入无佣金订单
|
||||
- [ ] 列表行级菜单可直接对真实待确认订单执行“确认佣金”，并把状态更新为“发放中”
|
||||
- [ ] 详情抽屉中的佣金状态展示与可编辑条件和列表保持一致
|
||||
- [ ] `admin-frontend` 构建通过
|
||||
- [ ] `.helloagents` 文档与变更记录已同步
|
||||
|
||||
---
|
||||
|
||||
## 2. 方案
|
||||
|
||||
### 技术方案
|
||||
1. 在 `admin-frontend/src/utils/orders.ts` 中抽出“是否存在真实佣金”的统一判定逻辑，优先根据 `commission_balance` / `actual_commission_balance` 和已进入发放链路的状态综合判断，而不是单看默认的 `commission_status`。
|
||||
2. 调整佣金状态标签生成逻辑：无真实佣金的订单统一返回“无佣金”，佣金状态筛选仍保留原有枚举，但当前端进入佣金筛选场景时，自动附加后端已有的 `is_commission=true` 参数，利用服务端过滤能力排除无佣金订单。
|
||||
3. 在订单页工具栏增加“确认佣金”菜单，提供“真实待确认订单 / 全部佣金订单 / 清空佣金筛选”三个快捷入口，帮助运营快速切换到真实佣金工作流。
|
||||
4. 在列表新增行级操作列，保留“查看详情”，并对真实待确认订单提供“确认佣金”快捷项；执行时复用现有 `/order/update` 接口，把 `commission_status` 更新为 `1`。
|
||||
5. 同步更新订单详情抽屉的佣金状态文案与操作判定，确保列表页和详情页对“无佣金 / 待确认 / 发放中 / 已发放 / 无效”的解释一致。
|
||||
|
||||
### 影响范围
|
||||
```yaml
|
||||
涉及模块:
|
||||
- admin-frontend/src/utils/orders.ts: 统一佣金状态判定、筛选标签与可编辑条件
|
||||
- admin-frontend/src/views/subscriptions/OrdersView.vue: 增加确认佣金菜单、真实佣金筛选与行级快捷确认
|
||||
- admin-frontend/src/views/subscriptions/OrdersView.scss: 补充菜单/操作列样式
|
||||
- admin-frontend/src/views/subscriptions/OrderDetailDrawer.vue: 同步佣金状态文案与操作可见性
|
||||
预计变更文件: 4
|
||||
```
|
||||
|
||||
### 风险评估
|
||||
| 风险 | 等级 | 应对 |
|
||||
|------|------|------|
|
||||
| 历史订单存在 `commission_balance = 0` 但已进入发放链路 | 中 | 真实佣金判定同时纳入 `actual_commission_balance` 与已发放/无效状态，避免误判为无佣金 |
|
||||
| 列表快捷确认与详情抽屉状态维护不一致 | 中 | 两处统一复用 `orders.ts` 的判定与状态 meta，更新后统一刷新列表/详情 |
|
||||
| 佣金筛选逻辑过于隐蔽导致运营不易理解 | 低 | 工具栏新增显式“确认佣金”菜单，并在激活时显示提示文案，说明当前只展示真实佣金订单 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 技术设计（可选）
|
||||
|
||||
> 本轮不新增接口与数据结构，复用现有后端能力，保留该节用于说明前后端数据流。
|
||||
|
||||
### 架构设计
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[OrdersView 工具栏菜单] --> B[fetchOrders is_commission=true]
|
||||
A --> C[行级操作菜单]
|
||||
C --> D[/order/update commission_status=1]
|
||||
B --> E[订单表格]
|
||||
E --> F[OrderDetailDrawer]
|
||||
F --> D
|
||||
```
|
||||
|
||||
### API设计
|
||||
#### GET /order/fetch
|
||||
- **请求**: 现有分页参数 + `filter` + `is_commission?: true`
|
||||
- **响应**: 订单列表；当前端处于佣金工作流时，由后端过滤掉无邀请人、待支付/已取消、佣金金额为 0 的记录
|
||||
|
||||
#### POST /order/update
|
||||
- **请求**: `{ trade_no: string, commission_status: 1 }`
|
||||
- **响应**: `ApiResponse<boolean>`
|
||||
|
||||
### 数据模型
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| commission_balance | number | 应付佣金额；大于 0 时优先认定为真实佣金订单 |
|
||||
| actual_commission_balance | number \| null | 已实际发放佣金；用于兜底识别已进入发放链路的历史订单 |
|
||||
| commission_status | number \| null | 0 待确认 / 1 发放中 / 2 已发放 / 3 无效 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 核心场景
|
||||
|
||||
> 执行完成后同步到对应模块文档
|
||||
|
||||
### 场景: 运营筛出真实待确认佣金订单
|
||||
**模块**: admin-frontend / subscriptions / orders
|
||||
**条件**: 订单列表页已加载，存在部分真实佣金待确认订单
|
||||
**行为**: 用户点击“确认佣金”菜单中的“真实待确认订单”
|
||||
**结果**: 列表切换为仅展示 `commission_status = 0` 且真实存在佣金的订单
|
||||
|
||||
### 场景: 运营在列表中手动确认佣金
|
||||
**模块**: admin-frontend / subscriptions / orders
|
||||
**条件**: 某条订单属于真实待确认佣金订单
|
||||
**行为**: 用户在该行操作菜单点击“确认佣金”
|
||||
**结果**: 调用 `/order/update` 把佣金状态更新为“发放中”，列表状态即时刷新
|
||||
|
||||
### 场景: 无佣金订单被正确标记
|
||||
**模块**: admin-frontend / subscriptions / orders
|
||||
**条件**: 订单的 `commission_balance = 0`，且未进入发放链路
|
||||
**行为**: 用户查看列表或详情抽屉中的佣金状态
|
||||
**结果**: 页面明确显示“无佣金”，不再误导为“待确认”
|
||||
|
||||
---
|
||||
|
||||
## 5. 技术决策
|
||||
|
||||
> 本方案涉及的技术决策，归档后成为决策的唯一完整记录
|
||||
|
||||
### admin-frontend-orders-commission-confirmation#D001: 真实佣金判定以金额和发放链路为准，不再单看默认 commission_status
|
||||
**日期**: 2026-04-24
|
||||
**状态**: ✅采纳
|
||||
**背景**: 当前无佣金订单也可能落在 `commission_status = 0`，如果前端只按状态展示，会把“默认值”误渲染成“待确认”。
|
||||
**选项分析**:
|
||||
| 选项 | 优点 | 缺点 |
|
||||
|------|------|------|
|
||||
| A: 继续只看 commission_status | 改动最小 | 会持续把无佣金订单误判成待确认 |
|
||||
| B: 以佣金金额/实际发放金额/已进入发放链路状态综合判断 | 业务语义更准确 | 需要统一封装前端判定逻辑 |
|
||||
**决策**: 选择方案 B
|
||||
**理由**: 能同时覆盖无佣金订单、已发放历史订单和无效佣金订单，最符合真实业务语义。
|
||||
**影响**: `orders.ts` 的状态映射、订单列表渲染、详情抽屉可编辑条件
|
||||
|
||||
### admin-frontend-orders-commission-confirmation#D002: 列表页新增“确认佣金”快捷菜单与单行确认，而不是只依赖详情抽屉
|
||||
**日期**: 2026-04-24
|
||||
**状态**: ✅采纳
|
||||
**背景**: 用户明确要求在当前页面把真实待确认佣金筛出来并能手动确认，同时在上一轮选择了“列表页新增单行快捷确认，并保留详情抽屉”。
|
||||
**选项分析**:
|
||||
| 选项 | 优点 | 缺点 |
|
||||
|------|------|------|
|
||||
| A: 只保留详情抽屉确认 | 实现最少 | 无法满足当前页快速筛选与快捷确认诉求 |
|
||||
| B: 列表页加快捷菜单与行级确认，详情抽屉保留完整状态维护 | 符合运营工作流，效率更高 | 需要补充操作列与筛选状态管理 |
|
||||
**决策**: 选择方案 B
|
||||
**理由**: 与用户确认选项一致，且能把“筛选 + 确认”闭环留在一个工作台内完成。
|
||||
**影响**: `OrdersView.vue` / `OrdersView.scss` 需要新增工具栏菜单、操作列和交互反馈
|
||||
|
||||
---
|
||||
|
||||
## 6. 成果设计
|
||||
|
||||
> 含视觉产出的任务由 DESIGN Phase2 填充。非视觉任务整节标注"N/A"。
|
||||
|
||||
### 设计方向
|
||||
- **美学基调**: Apple 风格的高密度运营工作台 —— 黑色静默首屏、白色精密工作区、蓝色交互信号，新增能力保持“像系统功能自然长出来”的克制感
|
||||
- **记忆点**: 订单页工具栏里新增一颗明确的“确认佣金”工作流胶囊按钮，进入后列表与行级操作形成连续确认闭环
|
||||
- **参考**: `apple/DESIGN.md`、`.helloagents/DESIGN.md`、当前订单页截图
|
||||
|
||||
### 视觉要素
|
||||
- **配色**: 延续现有 `#000000 / #f5f5f7 / #ffffff` 主场与 `#0071e3` 交互强调色；无佣金状态使用中性灰，不与真实待确认的橙色混淆
|
||||
- **字体**: 继续遵循项目既有 Apple 化系统字体栈，不引入新字体，只通过字重与字距维持信息层级
|
||||
- **布局**: 保持现有单层工具栏结构，在筛选胶囊群中补入“确认佣金”菜单；表格右侧新增轻量操作列，不打断订单号点击查看详情的主路径
|
||||
- **动效**: 仅保留按钮 hover、菜单展开和状态更新后的即时消息反馈，不引入额外炫技动画
|
||||
- **氛围**: 继续使用纯白工作台、轻阴影容器和圆角胶囊控件，让新增能力自然融入当前后台节奏
|
||||
|
||||
### 技术约束
|
||||
- **可访问性**: 菜单项与操作按钮保持可聚焦、文案明确，不只靠颜色传达佣金状态
|
||||
- **响应式**: 延续当前订单页在窄屏下工具栏换行与表格横向滚动策略，不额外引入新断点
|
||||
Reference in New Issue
Block a user