admin/Xboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(admin-frontend): 补齐用户节点与订单运营工作台

Browse Source 
新增用户高级筛选、批量操作与更多行级动作，支持邮件、
CSV、封禁恢复、订单分配、邀请查看、流量记录与重置流量

增强节点管理页的分页、父子筛选、跨页勾选、批量修改与
单节点置顶，并补齐后端批量更新 host、group_ids、rate

修复订单佣金状态误判问题，新增真实佣金筛选与行级确认，
同时优化仪表盘排行悬浮详情展示

补充 admin-frontend 独立 Dockerfile、Caddy 配置与 GHCR
发布工作流，支持通过独立镜像部署管理前端
This commit is contained in:
yinjianm
2026-04-24 23:15:48 +08:00
parent e393b11b61
commit d4168720ac
65 changed files with 4114 additions and 438 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.helloagents/archive/2026-04/202604242217_admin-frontend-orders-commission-confirmation/.status.json
+11
View File
@@ -0,0 +1,11 @@
{
"status": "completed",
"completed": 5,
"failed": 0,
"pending": 0,
"total": 5,
"done": 5,
"percent": 100,
"current": "订单页佣金状态修复、真实待确认筛选与单行确认菜单已完成",
"updated_at": "2026-04-24 22:26:00"
}
.helloagents/archive/2026-04/202604242217_admin-frontend-orders-commission-confirmation/proposal.md
+179
View File
@@ -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、菜单展开和状态更新后的即时消息反馈，不引入额外炫技动画
- **氛围**: 继续使用纯白工作台、轻阴影容器和圆角胶囊控件，让新增能力自然融入当前后台节奏
### 技术约束
- **可访问性**: 菜单项与操作按钮保持可聚焦、文案明确，不只靠颜色传达佣金状态
- **响应式**: 延续当前订单页在窄屏下工具栏换行与表格横向滚动策略，不额外引入新断点
.helloagents/archive/2026-04/202604242217_admin-frontend-orders-commission-confirmation/tasks.md
+50
View File
@@ -0,0 +1,50 @@
# 任务清单: admin-frontend-orders-commission-confirmation
> **@status:** completed | 2026-04-24 22:29
```yaml
@feature: admin-frontend-orders-commission-confirmation
@created: 2026-04-24
@status: completed
@mode: R2
```
## 进度概览
| 完成 | 失败 | 跳过 | 总数 |
|------|------|------|------|
| 5 | 0 | 0 | 5 |
---
## 任务列表
### 1. 佣金状态判定与页面交互
- [√] 1.1 在 `admin-frontend/src/utils/orders.ts` 中统一真实佣金判定与状态映射，修复无佣金订单误显示为“待确认” | depends_on: []
- [√] 1.2 在 `admin-frontend/src/views/subscriptions/OrdersView.vue` 中接入真实佣金筛选状态，新增“确认佣金”菜单并在列表请求中透传 `is_commission` | depends_on: [1.1]
- [√] 1.3 在 `admin-frontend/src/views/subscriptions/OrdersView.vue` 与 `OrdersView.scss` 中增加行级操作列，为真实待确认订单提供“确认佣金”快捷操作与状态提示 | depends_on: [1.2]
### 2. 一致性与验收
- [√] 2.1 在 `admin-frontend/src/views/subscriptions/OrderDetailDrawer.vue` 中同步佣金状态文案与可编辑条件，确保列表与详情一致 | depends_on: [1.1]
- [√] 2.2 执行 `admin-frontend` 构建验证，并同步 `.helloagents` 记录与变更说明 | depends_on: [1.3, 2.1]
---
## 执行日志
| 时间 | 任务 | 状态 | 备注 |
|------|------|------|------|
| 2026-04-24 22:17 | 方案设计 | completed | 已确认采用“列表页确认佣金菜单 + 单行快捷确认 + 保留详情抽屉”方案 |
| 2026-04-24 22:20 | 佣金判定修复 | completed | `orders.ts` 新增真实佣金判定，列表/详情统一改为无佣金不再显示待确认 |
| 2026-04-24 22:22 | 订单页交互增强 | completed | 订单工具栏新增“确认佣金”菜单，佣金状态筛选自动透传 `is_commission=true` |
| 2026-04-24 22:24 | 行级确认接入 | completed | 列表新增操作列，可对真实待确认订单直接确认为“发放中” |
| 2026-04-24 22:26 | 构建与文档同步 | completed | `npm run build` 通过，准备归档方案包并更新知识库记录 |
---
## 执行备注
- 当前后端已具备 `GET /order/fetch?is_commission=true` 与 `POST /order/update` 能力，本轮优先复用现有接口，不新增后端 API。
- 若本地构建外存在后端联调缺口，需以 `admin-frontend` 构建结果作为本轮最低验证证据，并在交付中明确说明。