公开 API 权限与可见性矩阵

网页和 API 使用同一套账号范围。文档中的“接口存在”不代表每个账号都可以调用；客户端应把权限不足、入口隐藏、空数据和网络失败分开处理。

账号范围

账号范围	通常可见	通常不可见或需额外授权
未登录	公共文档和登录入口	账号数据、缓存、写入
普通用户	个人配方、记录、成绩、相片、缓存	机台控制、机台聚合、审核
机台账号	机台配方、健康、订单、查卡和允许的用户数据	不属于该账号范围的机台
内容/审核账号	成绩互动、反馈状态和授权审核入口	未授权的凭据和内部实现
测试账号	页面明确开放的测试内容	未开放的生产内容和其它账号数据

实际范围以当前页面和服务响应为准。不要通过猜测参数、修改前端显示或拼接路径绕过隐藏入口。

页面隐藏的四种原因

看不到功能时至少考虑：

1. 未登录；
2. 账号类型不匹配；
3. 当前账号没有目标机台/内容授权；
4. 当前版本暂时隐藏或功能已退役。

这些情况都不等价于服务故障。反馈时说明页面是否显示入口、账号类型和时间，不要只说接口返回 404。

公开端点的权限判断

会话

获取 Token、验证、绑定密码和退出只作用于当前登录输入。客户端不能使用一个账号的 Token 操作另一个账号的本地条目。

访问码

访问码生成属于当前账号。绑定网页登录时还要检查页面是否显示目标机台和验证码。普通用户不要自行填入机台标识。

配方

读取和修改只针对当前账号能看到的配置。机台账号额外字段需要目标机台授权；用户账号不应尝试添加机台参数。

相片、缓存和上传缓存

这些数据属于当前账号。文件名和快照索引必须来自当前账号的列表，不能跨账号复用名称。

记录、成绩和互动

用户只能读取当前账号可见数据。评论删除、反馈撤回和审核决定需要更细的对象权限；失败时应显示权限提示，不要把目标对象编号换掉继续尝试。

查卡、地区和统计

查卡通常需要机台目标授权；地区和服务统计可能只返回聚合结果。聚合接口不应被客户端扩展成用户级列表。

权限失败的正确显示

情况	UI 建议
未登录	显示登录/账号选择入口
Token 失效	停止请求并要求重新登录
账号无权限	显示权限不足和当前账号类型
目标不存在	显示目标已不可见或检查标识
空数据	显示范围、账号和空状态
网络错误	显示重试/反馈入口

不要把权限不足显示成空列表，也不要把空列表显示成数据已删除。

账号切换边界

账号切换时：

1. 停止当前账号轮询；
2. 取消未完成请求；
3. 清理当前页面数据；
4. 更新会话和账号类型；
5. 重新读取主页和权限；
6. 不复用上一个账号的缓存。

多个标签页要测试切换竞争：旧账号响应不能覆盖新账号页面，旧 Token 失效不能注销新账号。

机台多目标边界

机台账号可能绑定多个目标。目标选择器应：

• 显示脱敏名称和标识尾部；
• 默认选择明确的当前目标；
• 保存/控制前再次显示目标；
• 多目标统计保留来源；
• 删除绑定前确认不是当前目标；
• 不把多个目标的状态写回单个目标。

测试内容权限

测试内容入口可能只对获得计划授权的账号显示。申请成功、列表出现、内容发布和机台可见是不同状态。客户端不要用隐藏入口推断申请失败，应显示当前账号没有可见内容或联系渠道。

下载测试文件前确认目标环境。下载并不等于获得公开分发许可；客户端不应自动把下载内容上传到其它服务。

审核权限

普通用户可以提交反馈或评论，但不一定可以读取审核备注、处理队列或决定内容可见性。审核页面要隔离内部字段，普通客户端也要忽略未知审核字段而不是展示。

权限排障模板

账号别名：<脱敏>
账号类型：用户 / 机台 / 其它授权
页面：<页面名称>
目标：<脱敏名称>
入口是否显示：是 / 否
请求结果：空 / 权限不足 / 网络错误 / 其它
发生时间：<含时区>
最后一次成功动作：<动作>

不要附带完整 Token、目标完整编号、原始响应、私钥或完整配置。

权限安全测试

• [ ] 未登录访问受保护页面不会泄露上一个账号的数据；
• [ ] 普通账号看不到机台控制入口；
• [ ] 账号 A 不能读取账号 B 的文件名；
• [ ] 机台 A 不能读取机台 B 的统计；
• [ ] 审核字段不出现在普通用户页面；
• [ ] Token 失效后轮询停止；
• [ ] 账号切换不会复用旧缓存；
• [ ] 404、403、空列表和网络错误显示不同文案。