admin/Xboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
Xboard/.helloagents/archive/2026-04/202604242217_admin-frontend-orders-commission-confirmation/proposal.md
T
yinjianm d4168720ac feat(admin-frontend): 补齐用户节点与订单运营工作台 
新增用户高级筛选、批量操作与更多行级动作，支持邮件、
CSV、封禁恢复、订单分配、邀请查看、流量记录与重置流量

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

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

补充 admin-frontend 独立 Dockerfile、Caddy 配置与 GHCR
发布工作流，支持通过独立镜像部署管理前端
2026-04-24 23:15:48 +08:00

10 KiB
Raw Permalink Blame History

变更提案: admin-frontend-orders-commission-confirmation

元信息

类型: 缺陷修复
方案类型: implementation
优先级: P1
状态: 已完成
创建: 2026-04-24

1. 需求

背景

admin-frontend 的 #/subscriptions/orders 订单管理页目前直接按 commission_status 渲染佣金状态。由于后端很多“无佣金订单”默认也会带 commission_status = 0，页面把这些订单一并显示成“待确认”，造成运营误判。同时，列表页缺少直接面向“真实待确认佣金订单”的筛选与快捷确认入口，只能进入详情抽屉手动改状态，效率较低。

目标

  • 修复无佣金订单被误显示为“待确认”的问题，让列表与详情抽屉的佣金状态表达与真实业务一致。
  • 在订单页增加“确认佣金”菜单，能一键筛出真实待确认的佣金订单。
  • 在列表行级菜单中加入“确认佣金”快捷操作，把真实待确认订单手动确认到“发放中”。
  • 保留详情抽屉内现有佣金状态维护能力，确保列表与详情行为一致。

约束条件

时间约束: 本轮只处理 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. 同步更新订单详情抽屉的佣金状态文案与操作判定，确保列表页和详情页对“无佣金 / 待确认 / 发放中 / 已发放 / 无效”的解释一致。

影响范围

涉及模块:
  - 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. 技术设计（可选）

本轮不新增接口与数据结构，复用现有后端能力，保留该节用于说明前后端数据流。

架构设计

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 View Git Blame Copy Permalink