未来洞派单系统 · 交接文档 & 开发需求

版本 v1.1.0 · 编制 2026-09-16 · 端口 env.js 配置 · 本系统由乌鱼子开发·设计·文档提出 · 测试端服务器及接口函数由乌鱼子提供编写

当前项目概况

端口

env.js 读 PORT，默认 3789

域名

onlygay.cn

数据

/opt/dispatch/data/

账号

admin / admin123

后端

Express 5.2

数据库

SQLite

前端

原生 HTML/JS

认证

JWT 12h

备份

每4h

角色

客服 / 管理 / 审核 / 打手

目录结构

/opt/dispatch/
├── server/
│   ├── src/
│   │   ├── index.js          ← 入口
│   │   ├── env.js            ← 环境变量
│   │   ├── db.js             ← 数据库（建表/迁移/种子/备份）
│   │   ├── logger.js         ← 日志（按天）
│   │   ├── utils.js          ← 核心算法（粘贴解析/佣金/保底）
│   │   ├── middleware/
│   │   │   └── auth.js      ← JWT 认证
│   │   └── routes/          ← 12 个路由模块
│   │       ├── auth.js      ← 登录/登出/改密
│   │       ├── orders.js    ← ⭐ 订单核心（680行）
│   │       ├── users.js     ← 用户管理
│   │       ├── config.js    ← 系统配置
│   │       ├── stats.js     ← 统计
│   │       ├── calls.js     ← 呼叫
│   │       ├── chat.js      ← 聊天记录
│   │       ├── chatroom.js  ← 聊天室
│   │       ├── handovers.js ← 交接班
│   │       ├── announcements.js ← 公告
│   │       ├── export.js    ← 导出
│   │       ├── logs.js      ← 日志
│   │       └── reserved.js  ← 预留(501)
│   ├── package.json
│   └── 生产.env.example
├── client/public/
│   ├── index.html        ← 主页面
│   ├── app.js            ← 主逻辑（3145行）
│   ├── styles.css        ← 样式（5套主题）
│   ├── detail.* / handover.* / chatroom.*
│   ├── assets/           ← logo/favicon
│   └── downloads/        ← Electron 安装包
└── data/               ← 运行时自动生成
    ├── dispatch.db       ← 数据库
    ├── uploads/          ← 上传文件
    ├── backups/          ← 自动备份
    └── logs/             ← 日志

技能包

技能包	用途
`ui-ux-pro-max-skill`	主题/UI（5套主题配色）
`canvas`	文档渲染
`data-analysis`	数据分析
`excel-xlsx`	CSV 生成
`pdf-generator`	PDF（预留）

数据库（13 张表）

表	用途	关键字段
`users`	用户	username, role, password_hash
`cs_accounts`	客服账号	account_name, type
`login_records`	登录记录	user_id, cs_account_id
`orders`	⭐ 订单	40+字段，7个 is_*
`order_status_history`	状态历史	field, value, changed_by
`call_records`	呼叫	call_type, is_read
`announcements`	公告	is_pinned, is_active
`team_chat`	聊天室	content, kind
`handovers`	交接	priority, status
`chat_records`	聊天	record_type, content
`operation_logs`	日志	action, details
`user_settings`	设置	theme, density
`configs`	配置	config_key, config_value

订单表结构

CREATE TABLE orders (
    id                  INTEGER PRIMARY KEY,
    order_number        TEXT UNIQUE,             -- 订单编号
    store_amount        REAL,                    -- 门店金额
    purchase_item       TEXT,                    -- 购买项目
    client_type         TEXT,                    -- PC/手游
    character_name      TEXT,                    -- 角色名
    player_name         TEXT,                    -- 打手
    team_code           TEXT,                    -- 组队码
    studio_name         TEXT,                    -- 工作室
    channel             TEXT,                    -- 渠道
    player_count        INTEGER DEFAULT 2,       -- 人数
    commission_rate     REAL,                    -- 抽成比例
    commission_amount   REAL,                    -- 抽成金额
    player_each_income  REAL,                    -- 到手/人
    dailiantong_order   TEXT,                    -- 代练通单号
    map_name            TEXT,                    -- 地图
    guarantee_target    REAL,                    -- 保底目标
    notes               TEXT,                    -- 备注
    paste_raw           TEXT,                    -- 粘贴原文
    -- 状态标志
    primary_status      TEXT DEFAULT '待派出',
    is_dispatched_group     INTEGER DEFAULT 0,
    is_dispatched_system    INTEGER DEFAULT 0,
    is_accepted             INTEGER DEFAULT 0,
    is_stored               INTEGER DEFAULT 0,
    is_refunded             INTEGER DEFAULT 0,
    is_aftersale            INTEGER DEFAULT 0,
    is_dailiantong          INTEGER DEFAULT 0,
    is_voided               INTEGER DEFAULT 0,
    -- 存单/退款
    store_reason        TEXT,
    remaining_guarantee REAL,
    per_round_amounts   TEXT,
    refund_amount       REAL,
    refund_reason       TEXT,
    -- 关联/时间
    created_by          INTEGER,
    assigned_to         INTEGER,
    created_at, updated_at, dispatched_at,
    accepted_at, stored_at, refunded_at,
    aftersale_at, voided_at, status_changed_at
);

API 接口（58 个）

所有接口前缀 /api · 需登录的接口 Header: Authorization: Bearer <token>

权限条件说明

🔓 公开 — 无需登录 🔒 管理 — 需登录 + role=admin

认证 · /api/auth

POST/api/auth/login登录▶

权限

🔓 公开 — 无需登录

参数

{ username: string, password: string, cs_account_id?: number }

处理逻辑

查 users 表找 username → bcrypt 验密码 → 写 login_records → 返回 { token, must_change_password, user }。首次登录 must_change_password=true 时前端强制弹改密框。

{ token: string, must_change_password: boolean, user: { id, username, name, role } }

POST/api/auth/logout登出▶

权限

处理逻辑

更新 login_records 的 logout_time 为当前时间（改最近一条未登出的记录）。

GET/api/auth/me当前用户信息▶

权限

{ user: { id, username, name, role, is_active, must_change_password }, cs_account: { id, account_name, account_type } }

POST/api/auth/change-password改密▶

权限

参数

{ old_password: string, new_password: string }

处理逻辑

验旧密码 → 新密码 ≥ 8 位 → 不能是 admin123 → bcrypt 哈希 → 更新 users → 清 must_change_password。

订单 · /api/orders

POST/api/orders/parse粘贴文本解析▶

权限

参数

{ text: string }

处理逻辑

调 parsePasted() 逐行扫描，匹配 30+ 中文标签（如 "门店金额" "金额" "总价" → store_amount）。自动识别 PC/手游、渠道、金额、保底。

{ parsed: { store_amount, order_number, character_name, ..., _missing: string[] }, commission: { commission_rate, commission_amount, player_each_income } }

POST/api/orders/calculate佣金试算▶

权限

参数

{ store_amount: number, channel?: string, product_type?: string, commission_rate?: number, player_count?: number }

处理逻辑

按渠道×产品类型匹配 commission_rules → 算 commission_amount = amount × rate% → player_total = amount - commission → player_each = total / count。

POST/api/orders/check-guarantee保底检查▶

权限

参数

{ map_name: string, extracted_amount: number }

处理逻辑

查 guarantee_rules 找地图阈值。带出 < 阈值时返回 need_add=true + add_amount。

POST/api/orders/calculate-store存单试算▶

权限

参数

{ guarantee_target: number, per_round_amounts: number[] }

{ guarantee_target, completed, remaining, rounds }

POST/api/orders创建订单▶

权限

参数

全部订单字段（order_number, store_amount, character_name, ...）

处理逻辑

查重（order_number 全表遍历）→ 算佣金 → 推导 primary_status → 写 orders + order_status_history + operation_logs。

GET/api/orders列表 / 搜索▶

权限

参数

?q=（13字段模糊） ?user_id= ?flag= ?status= ?include_voided=1 ?limit=100 ?offset=0

{ total: number, items: Order[] }

GET/api/orders/:id详情▶

权限

{ order: Order, history: StatusHistory[] }

PUT/api/orders/:id编辑▶

权限

处理逻辑

partial update，自动重算佣金、重推导主状态、写时间戳。

PUT/api/orders/:id/tags⭐ 改状态标签（核心）▶

权限

参数

{ tags: string[] } — 可选值：已派群聊 已派系统 已接单 已存单 已退款 已售后 代练通

处理逻辑

全量替换 7 个 is_* 标志（传了设 1，没传设 0）→ 推导 primary_status → 每个变更写 order_status_history + 对应时间戳（dispatched_at / accepted_at 等）。卡单不接受，是自动判定的。

POST/api/orders/:id/void作废▶

权限

🔒 管理 — role 必须是 admin

处理逻辑

is_voided=1，primary_status='已作废'，记录 reason。软删除，数据不丢。

POST/api/orders/:id/unvoid恢复▶

权限

🔒 管理 — role 必须是 admin

处理逻辑

is_voided=0，重新推导主状态。

GET/api/orders/:id/copy复制文本▶

权限

处理逻辑

返回格式化 "标签：值" 文本。可选 ?fields= 指定字段。

POST/api/orders/:id/audit审核（预留 501）▶

权限

🔒 管理

说明

审核功能。返回 501，预留。

POST/api/orders/:id/payment收付款（预留 501）▶

权限

🔒 管理

说明

收付款。返回 501，预留。

用户 · /api/users

GET/api/users/cs-accounts客服账号列表▶

权限

🔓 公开 — 无需登录，登录页下拉用

GET/api/users用户列表▶

权限

GET/api/users/cards用户卡片（含订单计数）▶

权限

每人附带 { open, stored, refunded, aftersale } 计数。

GET/api/users/settings个人设置▶

权限

PUT/api/users/settings保存设置▶

权限

POST/api/users创建用户▶

权限

🔒 管理 — role 必须是 admin

参数

{ username, name, role, password } — role: reception/dispatch/admin

PUT/api/users/:id编辑 / 重置密码▶

权限

🔒 管理 — role 必须是 admin

POST/api/users/cs-accounts创建客服账号▶

权限

🔒 管理

说明

创建客服账号。提交 {account_name, account_type}。type: wechat/douyin。

PUT/api/users/cs-accounts/:id编辑客服账号▶

权限

🔒 管理

说明

编辑客服账号。可改 account_name 和 is_active。

配置 · /api/config

GET/api/config/commission抽成规则▶

权限

🔒 管理（PUT 更新）

GET/api/config/guarantee保底规则▶

权限

🔒 管理（PUT 更新）

GET/api/config/status状态列表▶

权限

🔒 管理（PUT 更新）

GET/api/config/fields字段标签

GET/api/config/timeout超时分钟（GET 登录 / PUT 管理）

GET/api/config/meta元数据

统计 · /api/stats

GET/api/stats/activity今日活跃

POST/api/stats/activity上报活跃▶

权限

说明

GET: 今日活跃计数。POST: 上报增量 {mouse_clicks, key_presses}。

GET/api/stats/buckets工作桶（未派/派了/卡单/派完/存单）

GET/api/stats/summary全局汇总

GET/api/stats/dashboard仪表盘

呼叫 · /api/calls

GET/api/calls列表（管理全部，客服自己）

POST/api/calls发呼叫（5种类型）▶

权限

说明

GET: 列表（管理全部，客服自己，含未读）。POST: 发呼叫（5种类型）。

PUT/api/calls/:id/read标记已读▶

权限

🔒 管理

说明

标记单条已读。

POST/api/calls/read-all全部已读▶

权限

🔒 管理

说明

全部标记已读。

聊天 · /api/chat

GET/api/chat/order/:id获取聊天记录

POST/api/chat/order/:id上传文字▶

权限

说明

GET: 获取聊天记录。POST: 上传文字（限5000字）。

POST/api/chat/order/:id/image上传图片（5MB）▶

权限

说明

上传图片（仅图片格式，5MB 限）。文件名自动消毒+随机前缀。

DEL/api/chat/:id删除▶

权限

说明

删除聊天记录（连带删磁盘文件）。

聊天室 · /api/chatroom

GET/api/chatroom近4小时消息

POST/api/chatroom发消息（30字，5条/分）▶

权限

说明

GET: 近4小时消息。POST: 发消息（30字限，每分钟5条，超限429）。

POST/api/chatroom/boost"有打手"通报▶

权限

说明

"有打手"通报。kind=boost。

交接 · /api/handovers

GET/api/handovers列表

POST/api/handovers创建▶

权限

说明

GET: 列表（按状态+优先级排序）。POST: 创建（标题必填，优先级4级）。

PUT/api/handovers/:id编辑▶

权限

🔒 管理

说明

删除（创建者或管理员）。

POST/api/handovers/:id/done完成▶

权限

说明

标记完成。status=done。

POST/api/handovers/:id/reopen重开▶

权限

说明

重新打开。status=open。

DEL/api/handovers/:id删除

公告 · /api/announcements

GET/api/announcements列表

POST/api/announcements发布▶

权限

说明

GET: 列表（置顶优先）。POST: 发布（客服仅限"有手游/有端游"）。

PUT/api/announcements/:id编辑▶

权限

🔒 管理

说明

PUT: 编辑。DELETE: 下线（软删除 is_active=0）。

DEL/api/announcements/:id下线

导出 · /api/export

GET/api/export/orders导出订单 CSV

GET/api/export/refunds导出退款 CSV▶

权限

🔒 管理

说明

导出退款 CSV。

POST/api/export/refunds/preview退款导入预览▶

权限

🔒 管理

说明

退款导入预览（按订单号/角色名匹配）。

POST/api/export/refunds/apply退款批量导入▶

权限

🔒 管理

说明

退款批量导入（自动打标+写历史）。

日志 · /api/logs

GET/api/logs操作日志查询

预留端口（501）

GET/api/reserved预留端口列表▶

权限

说明

预留端口列表。

POST/api/reserved/audit审核▶

权限

🔓 公开

说明

审核功能。返回 501。

POST/api/reserved/douyin抖音接入▶

权限

🔓 公开

说明

抖音信息接入。返回 501。

POST/api/reserved/payment收付款▶

权限

🔓 公开

说明

收付款。返回 501。

权限矩阵（3 → 5 角色）

现在：admin / reception → 加：reviewer（审核）、player（打手）。派单 = 客服，同一角色。

操作	客服（含派单）	管理	审核（新）	打手（新）
看订单	自己录入/负责的	全部	全部	自己的 + 待审核/已驳回的（申诉用）
录订单	✅	✅	—	—
改信息	自己录入的	✅	—	—
改状态	❌ 禁止	✅ 都行	—	—
作废	—	✅	—	—
审核	—	✅	✅	—
抢单	—	—	—	✅
报单	—	—	—	✅

核心：客服不能改任何状态标签。状态变更只有管理员能操作。派单和客服是同一角色。打手可看自己的订单和待审核/已驳回订单（用于申诉）。

已有功能

模块	功能
订单	录入 / 粘贴解析(30+标签) / 查重 / 搜索 / 编辑 / 作废恢复 / 复制
状态	8个标签 + 卡单自动判定 + 超时闪红
佣金	按渠道抽成 + 按地图保底 + 存单试算
呼叫	5种类型 + 未读计数 + 关联订单
交接	创建/完成/重开 + 4级优先级
公告	发布/置顶/下线 + 快速通报
聊天室	30字 / 5条/分 / 4h窗口
统计	工作桶 + 仪表盘 + 活跃计数
用户	CRUD + 客服账号 + 5套主题
导出	订单CSV + 退款导入
备份	每4h VACUUM，保留48份

开发需求

6.1 架构改造升级 P0

项	现在	目标
后端	Express 裸写	NestJS 或 Express 三层
数据库	SQLite	PostgreSQL + Prisma
前端	原生	Vue 3 + TS + Vite + Pinia
实时	轮询	WebSocket
多租户	没有	club_id 贯穿所有表

6.2 权限体系新增 P0

新增 reviewer（审核）+ player（打手）。打手独立登录入口，只能抢单、报单、看自己订单。派单和客服合并为同一角色。

核心：客服不能改任何状态。

6.3 派单系统升级 P1

粘贴加英文标签
智能推荐打手
批量派单、倒计时
录入=全信息，识别仅展示

6.4 存单系统升级 P1

列表页一键存单
进度条、到期提醒、转结单

6.5 报单系统新增 P0

H5/小程序上报 + 截图 + 自动关联
作废只不结算，数据留着
不同游戏不同模板
驳回后二次申诉

6.6 抢单大厅新增 P1

发布→抢锁30s→超时释放
按游戏/地图/金额筛选

6.7 审核系统新增 P1

录入 → 审核队列 → 通过 → 派单
               → 驳回 → 二次申诉 → 重审 → 争议 → 管理员介入

6.8 平台对接新增 P0

平台	优先级
抖音	P0
代练通	P1
淘宝/天猫	P2
其他	P3

6.9 提醒 & 状态识别升级 P1

5min黄→10min橙→15min红→30min闪+声音。退款/结单自动识别。

6.10 打手/工作室新增 P1

独立ID + 档案
自营叫「未来洞电竞」

6.11 渠道/财务升级 P1

渠道自动识别。实付/退款/结单。已结算可扣打手账户退款。

6.12 看板/多游戏新增 P0

全源+单源+实时。每游戏独立报单模板。

下载

📦 源码包

后端+前端，排除 node_modules

⬇ 1.1MB

📋 需求规格书

Markdown

⬇ 21KB

未来洞 · 交接文档 · v1.1.0 · 2026-09-16
本系统由乌鱼子开发·设计·文档提出 · 测试端服务器及接口函数由乌鱼子提供编写

未来洞派单系统

未来洞派单系统 · 交接文档 & 开发需求

当前项目概况

目录结构

技能包

数据库（13 张表）

订单表结构 💬 反馈

API 接口（58 个）

认证 · /api/auth 💬 反馈

订单 · /api/orders 💬 反馈

用户 · /api/users 💬 反馈

配置 · /api/config 💬 反馈

统计 · /api/stats 💬 反馈

呼叫 · /api/calls 💬 反馈

聊天 · /api/chat 💬 反馈

聊天室 · /api/chatroom 💬 反馈

交接 · /api/handovers 💬 反馈

公告 · /api/announcements 💬 反馈

导出 · /api/export 💬 反馈

日志 · /api/logs 💬 反馈

预留端口（501） 💬 反馈

权限矩阵（3 → 5 角色）

已有功能

开发需求

6.1 架构改造 💬 反馈 升级 P0

6.2 权限体系 💬 反馈 新增 P0

6.3 派单系统 💬 反馈 升级 P1

6.4 存单系统 💬 反馈 升级 P1

6.5 报单系统 💬 反馈 新增 P0

6.6 抢单大厅 💬 反馈 新增 P1

6.7 审核系统 💬 反馈 新增 P1

6.8 平台对接 💬 反馈 新增 P0

6.9 提醒 & 状态识别 💬 反馈 升级 P1

6.10 打手/工作室 💬 反馈 新增 P1

6.11 渠道/财务 💬 反馈 升级 P1

6.12 看板/多游戏 💬 反馈 新增 P0

下载

📦 源码包

📋 需求规格书

💬 意见反馈

订单表结构

认证 · /api/auth

订单 · /api/orders

用户 · /api/users

配置 · /api/config

统计 · /api/stats

呼叫 · /api/calls

聊天 · /api/chat

聊天室 · /api/chatroom

交接 · /api/handovers

公告 · /api/announcements

导出 · /api/export

日志 · /api/logs

预留端口（501）

6.1 架构改造升级 P0

6.2 权限体系新增 P0

6.3 派单系统升级 P1

6.4 存单系统升级 P1

6.5 报单系统新增 P0

6.6 抢单大厅新增 P1

6.7 审核系统新增 P1

6.8 平台对接新增 P0

6.9 提醒 & 状态识别升级 P1

6.10 打手/工作室新增 P1

6.11 渠道/财务升级 P1

6.12 看板/多游戏新增 P0