玩家客服、坐席与平台协查

星途客服包含游戏内玩家入口、开发者客服工作台和平台客服工作台。玩家围绕同一条工单补充消息和图片；开发者处理授权游戏的问题，必要时升级平台协查。账号问题和访客请求由平台接待。

开发者控制台的 玩家客服 用于服务游戏玩家；平台支持 用于开发者向平台提交接入、账号与资料请求。两者的工单和处理接口独立。

先完成接待配置

1. 使用开发者所有者账号登录 开发者控制台，打开「玩家客服 → 设置与 FAQ」。
2. 选择已归属自己的游戏，配置客服名称、欢迎语、服务时间、时区和自动回复。服务时间为展示文本，不会自动排班或自动下线。
3. 添加玩家常见问题，可逐项启用，最多 30 条。工作台可将启用的 FAQ 回答填入回复草稿，由客服确认后发送。
4. 用测试玩家从该游戏打开客服并提交「游戏」或「其他」问题，核对开发者队列收到工单。支付问题关联订单时，服务端检查订单是否属于该玩家和游戏。
5. 确认能回复、补充图片、关闭、评价和重新打开，再安排正式接待。

关闭游戏客服接待后，新请求会进入平台队列；已有工单不会自动迁移。游戏未归属有效开发者、开发者被停用、账号类问题、访客请求及旧工单的兜底接待也由平台处理。当前支付类问题也先由平台接待，尚未按支付失败、游戏未到账或渠道争议细分责任。平台客服队列需要实际安排人员，开启界面不代表已有 24 小时人工服务。

客服团队与权限

每个开发者客服账号单独登录，按所属开发者及授权游戏双重隔离。客服坐席进入控制台后，只显示玩家客服和账号安全；不会读取应用密钥、开发者订单、财务或平台支持页面。

开发者角色	工单操作	设置与团队
所有者 owner	处理旗下授权范围内工单、认领、指派、协查	管理游戏客服设置、邀请主管或坐席、调整与停用成员
主管 manager	处理获授权游戏、认领与指派	管理获授权游戏设置；只能管理完整游戏权限位于自身范围内的普通坐席和只读成员
坐席 agent	处理未指派或分配给自己的工单；不能修改他人已认领工单	不管理接待配置或团队
只读 viewer	查看授权工单及附件、同步已读	不能回复、上传、备注、认领、指派或改状态

在「客服团队」填写名称、角色与游戏范围，生成 48 小时有效的邀请链接。受邀人设置独立的 help_ 开头账号和密码后加入。邀请只可接受一次，链接只在创建时展示；如创建结果因网络丢失，可撤销原邀请后重新生成。浏览器阻止存储时，邀请页会保留 URL 片段以便刷新恢复。

接受邀请后若网络中断、页面未收到成功结果，可先回到登录页，用刚设置的账号和密码登录，避免重复创建。成员角色、游戏授权或启用状态变化会撤销该成员旧会话，须重新登录。

平台管理后台也支持 owner / manager / agent / viewer 客服角色。所有者可在「平台客服与协查 → 客服团队」创建 support_ 账号、调整角色、停用及重置密码；主管可查看团队、分派工单和管理接待设置。其他客服角色仅进入客服工作台，开发者开户、商品、订单及系统配置仍限平台所有者。创建或重置时随机密码仅本次返回；请私下交付给对应人员，丢失时重新重置。

三栏工作台

左栏是工单队列，中间为对话和回复草稿，右栏展示游戏、玩家标识、关联订单、负责人、状态及玩家评价。

• 按游戏、状态、负责人筛选；搜索支持标题、工单号和订单号。工单每页 30 条，可继续加载。
• 顶部统计来自服务端的完整筛选结果，包含等待客服、未读、超时待办、平均首响及满意度，不只统计当前分页。超时待办指新工单或等待客服超过 24 小时未更新，不是商用 SLA 排班系统。
• 页面可见时约每 20 秒同步统计和当前对话。回复提交期间暂停轮询；已加载多个工单分页时保留队列，点击刷新可重新读取首页。
• 对话默认读取最近 100 条可见消息，可加载更早记录。内部备注在服务端过滤后再分页，玩家无法读取备注；开发者不能读取平台内部备注。
• 快捷回复只填入草稿，不自动发送。发送消息、修改状态或转交队列后，刷新当前筛选结果。

回复、协查与关闭

状态	含义与下一步
open	新工单，等待接待
waiting_support	玩家已补充，需要客服回应
waiting_player	客服已公开回复，等待玩家确认或补充
closed	已关闭；先重新打开后才能继续回复或添加备注

内部备注不改变等待方向。普通坐席不能抢占其他坐席已认领的工单；主管可重新分派给有游戏权限的有效坐席。只读成员不能被分配为负责人。

开发者提交平台协查时，说明问题、已核验信息和需要平台协助的事项。工单进入 escalated，负责人清空，开发者暂停公开回复及状态操作，但可补充文字内部备注。平台核验后可记录公开回复并退回原开发者队列；游戏归属不再有效时会拒绝退回。协查原因和退回原因会展示给玩家，请勿写入私密排查资料。

玩家可关闭工单，关闭后进行 1～5 分评价及补充意见；每次关闭只评价一次。关闭 7 天内可说明原因重新打开，重新打开会清除该次评价。玩家最多同时保留 5 条未关闭工单。

工单回复、关闭或协查仅改变客服记录，不会自动退款、发货、修改角色资产或变更账号资料。涉及这些操作时，应走对应业务流程并核验实际结果。

图片附件

每条消息最多附加 3 张图片，输入格式为静态 PNG、JPEG 或 WebP，单张不超过 2 MB，最多约 1600 万像素。服务端验证图片并转为不超过 2048 × 2048 的 WebP，同时移除元数据。工单附件总量及尚未发送的上传数量另有限制，达到限制会返回错误。

附件不是公开链接。上传和下载均要求与工单匹配的 Bearer 身份，已附到内部备注的图片遵循相同可见范围。工作台下载前再次校验当前账号和选中工单，退出后旧请求不会显示到新账号。

游戏内接入

游戏已完成登录时，用该玩家的平台会话调用 POST /api/support/launch，请求体为 { "requestId": "本次打开请求的唯一标识" }。响应提供短时打开凭证 ticket、客服页面 url 和 expiresAt。打开 url 即可进入客服，页面通过 POST /api/support/launch/exchange 兑换独立客服会话。

打开凭证只在 60 秒内有效且只能兑换一次，通过 URL 片段传递。不要把长期玩家令牌放到查询参数或浏览器历史中。若打开请求已处理但响应丢失，使用新的 requestId 重新打开。客服会话最多 8 小时且不超过原玩家会话有效期，原会话失效后需要从游戏重新进入。

未登录用户可通过访客客服入口创建独立会话，提交账号或其他问题。访客不能读取正常玩家工单，也不能凭填写玩家标识取得账号权限。访客会话 24 小时有效，创建频率受限。

各端打开入口的具体方法与宿主生命周期，参见 H5 参考、Android 参考、iOS 参考 和 Windows 接入。原生宿主仍需在对应设备验证浏览器或 WebView 导航、返回游戏和退出清理。

玩家也可以主动申请平台介入：仅限已登录的非访客、仍在游戏客服队列（queue=developer）且未关闭的本人工单。调用 POST /api/support/tickets/:id/escalate，提交 version / reason / requestId，原因 1～1000 字；每个工单累计最多 3 次，退回或重开不清零。成功后队列变为 escalated，保留公开协查进度；超限返回 429 PLAYER_ESCALATION_LIMIT。H5 / 原生及引擎桥均提供 escalateTicket（.NET 为 EscalateTicketAsync）。

接口与并发约定

开发者前缀为 /api/developer/support，平台后台为 /api/admin/support，已登录玩家为 /api/support，访客为 /api/support/guest。不同身份不能混用令牌。

方法 / 相对路径	用途
GET /tickets	返回 items / total / nextCursor；支持 limit / before / queue / status / gameId / assigned / q，权限由服务端约束
GET /tickets/:id	详情、当前 version、最近可见消息、messageCursor / messageCount
GET /tickets/:id/messages	limit=1～100，默认 50，before 使用上页消息游标；返回按时间正序的 items / total / nextCursor
POST /tickets/:id/messages	公开回复：content / attachmentIds / version / requestId
POST /tickets/:id/notes	客服内部备注，同上；必须携带当前 version
POST /tickets/:id/read	更新当前身份已读位置：version / requestId
POST /tickets/:id/claim	客服认领：version / requestId
POST /tickets/:id/assign	主管指派：assigneeId / version / requestId；null 取消指派
POST /tickets/:id/status	客服更新状态：status / version / requestId
POST /tickets/:id/escalate	开发者升级协查或玩家主动申请平台介入：reason / version / requestId（访客不支持）
POST /tickets/:id/return	平台退回：reason / version / requestId
POST /tickets/:id/attachments	URL 中提供 filename / requestId，正文为图片二进制，不使用 JSON 或 multipart
GET /tickets/:id/attachments/:attachmentId	鉴权下载已授权图片
GET /stats	客服完整筛选结果统计
GET /settings	客服读取游戏设置与可见游戏，支持 gameId
PUT /settings	所有者或主管保存设置，携带配置字段、version / requestId，不回传 updatedAt

玩家另有创建工单、close / reopen / rating 接口；账号与角色权限不支持由客户端自行声明。客服配置公开读取使用 GET /api/support/config?appId=...，只展示已启用 FAQ。

消息、状态、指派、设置和团队修改使用版本校验及幂等标识。网络超时重试应保留原 requestId 和原请求体，不能换标识重复执行。409 TICKET_VERSION_CONFLICT 或设置/成员版本冲突表示内容已变化，应重新读取并核对后再提交；不能自动用新版本覆盖其他客服处理结果。错误权限、停用、图片格式、频率限制应展示对应错误，不应假装成功。

验收与边界

上线前至少验证：跨开发者、跨游戏、访客与玩家工单隔离；只读角色不能写入；停用与改权撤销会话；两名客服同时认领或回复；超时重试不重复执行；图片不越权下载；超过 100 条消息仍可读历史；协查与退回后队列正确；刷新保留登录且退出不恢复旧会话。

当前提供工单式接待与定时同步，没有承诺 WebSocket 即时聊天、人工自动排班、外部 IM 通知、语音客服或自动退款。平台客服细角色不等同于完整通用运营 RBAC；MFA 与管理员自助改密需按实际发布能力另行确认。