前端对接：兑换码/优惠券权限与登录日志

日期：2026-10-21。本文对应当前本地后端改动，尚未完成编译、发布及在线联调。接口均为应用路径，不含网关 /api 等前缀，沿用现有 baseURL 和后台鉴权请求配置。

1. 发布前准备

后端/运维执行：

docs/sql/20261021-coupon-exchange-permissions.sql：补齐 9 个权限，默认仅授权 root。父菜单无法自动识别时按脚本填写父菜单 id。已有权限不重复添加。
docs/sql/20261021-login-audit.sql：创建登录日志表。
在角色管理中显式授权所需权限，重新保存角色刷新权限缓存，再重新登录。

前端不直接操作权限表。后台登录返回的 AdminInfo 已有 permissions 和 roles，可沿用现有登录流程：/manage/admin/get/loginInfo 或 /manage/user/get/loginInfo。 /manage/menu/get/self/menu 只返回非 button 菜单，不能从这里推断完整按钮权限。

2. 兑换码页面（优先接入）

入口	显示/请求条件	后端接口
兑换码页、查询按钮、首次列表加载、翻页	exchangeCode:view	GET /manage/exchange/code/get
生成兑换码按钮及提交	同时有 exchangeCode:add 和 exchangeCode:export	GET /manage/exchange/code/createAndExport
导出按钮及提交	exchangeCode:export	GET /manage/exchange/code/export

没有 view 时不请求列表、不渲染码明文及复制按钮，展示无权限提示。权限异步加载完成后才决定是否首次请求；退出登录/切换账号清空列表、表单和已缓存码。路由守卫、按钮和点击处理函数都检查权限，不能只隐藏按钮。后端仍为最终授权边界。不要仅凭 root 字样在前端忽略权限码；应使用项目现有、与后端一致的权限匹配逻辑。

// 概念示例，接到项目现有权限工具，不另造登录或 token 存储。
const canView = hasPermission('exchangeCode:view');
const canGenerate = hasPermission('exchangeCode:add') && hasPermission('exchangeCode:export');
const canExport = hasPermission('exchangeCode:export');

2.1 查询/导出参数白名单

参数	类型/规则
goodsId	商品 Long，可选
skuId	规格 Long，可选
code	完整兑换码，精确匹配，不再模糊查询
userId	用户 Long，可选
useStatus	true/false 或 1/0；全部时省略，未使用必须显式传 false
codeType	1 兑换码、2 兑换链接；全部时省略
start	从 1 开始的页码，默认 1
limit	1–100，默认 10

只发送上述字段。不要传 condition、operator、字段 -op、逻辑分组或动态排序。不再支持透传其他历史 BeanSearcher 参数；若现有页面依赖，请列清单再联调，不恢复通用参数透传。兑换链接筛选先解析 URL 的 code 查询参数，再传完整码本身；不要把整个 URL 直接作为 code。查询列表返回 Result<SearchResult<ExchangeCodeView>>，沿用现有 BeanSearcher 列表解析。导出为 xlsx，最多 10000 条，不按分页截断；超限提示缩小筛选范围。非 root 只能查当前创建人范围；历史创建人昵称为空或重名时后端会拒绝，前端显示后端提示。

2.2 生成参数

沿用 GET 查询参数（兼容现有页面，后续联合迁移 POST，不要预加载或自动重试该请求）：

skuIds=[823]
number=10
type=0
codeType=1

skuIds 是 JSON 数组字符串，包含 1–100 个有效规格 ID，不传 goodsIds/operator。
number：1–500 的整数；提交期间禁用按钮，超时后先查询核实，避免重复生成。
type：0 平台（默认）、1 抽奖；codeType：1 兑换码（默认）、2 链接。
当前后端 number > 1 才返回 Excel；number = 1 生成后无文件响应，应刷新列表确认，不能把“无下载文件”当成失败并重试。
外层请求检查权限失败、参数异常时仍可能返回 JSON，不能全部保存成 Excel 文件。

2.3 文件与错误处理

查询沿用 Result：code、msg、flag、data，成功以现有统一拦截器判断。不要只依据 HTTP 200 判定业务成功。二进制下载先区分 Content-Type 是否为 JSON， JSON 错误解析后展示 msg，不生成错误 Excel。鉴权失效走现有重新登录流程；无权限展示提示，不自动重试，不降级到 external 接口。

3. 优惠券页面

行为	权限
查询券、分类、发放记录及统计	coupon:view
POST /manage/coupon 新增券	coupon:add
PUT /manage/coupon 及推荐、推广码、分类、活动等配置	coupon:edit
删除券、分类、推荐、活动等记录	coupon:delete
POST /manage/coupon/send 或 /corp/send	coupon:send

其他新增配置 POST（例如分类、弹窗）目前归 coupon:edit，不是 coupon:add。所有 /manage/coupon 接口都要求后台身份，不能用前台用户 token。普通用户领券继续使用 /applet/coupon/**，不要改调后台接口。新增券请求剔除 id；编辑使用 PUT 且带 id。折扣 0 < discount <= 1，立减金额 > 0，金额沿用后端原有“分”单位，表单显示“元”时做好转换。

4. 登录日志页面（新增）

只允许 roles 精确包含 root 的后台账号访问；不包含则隐藏入口且禁止发请求。当前后端使用 root 角色限制，不需要新增 loginAudit:view 权限码。

GET /manage/login/audit/get?start=1&limit=20
GET /manage/login/audit/get?loginType=user&loginId=1533797&start=1&limit=20

筛选：loginType、loginId、account、result、loginMethod、ip、from、to；空值省略。 start 从 1 开始，limit 1–100（默认 20）；from/to 为 URL 编码后的 yyyy-MM-dd HH:mm:ss。时间沿用应用环境时区，不擅自转换两次。

注意：登录日志分页不是 BeanSearcher。 返回 Result<Page<LoginAudit>>，列表读 data.records，总数读 data.total，当前页 data.current，页大小 data.size。

建议列表列：时间、身份类型、用户 ID、账号、登录方式、结果、连接 IP、浏览器、系统、耗时。详情抽屉：remoteIp、forwardedFor、realIp、userAgent、device、requestPath、httpMethod、reason。

字段	展示说明
loginType	user 普通用户；login 默认后台；其他值原样显示
loginMethod	sms_code 短信、email_code 邮箱、google、wechat、mini_program 小程序
其他方式	password_check 后台密码预检查、admin_impersonation 管理员代登录、account_switch 切换账号、phone_or_email_code 未细分、other/unknown
result	SUCCESS 会话创建成功；FAILURE 处理异常；CHECK_SUCCESS 凭据预检查通过，不能标成已登录
account/loginId	可以为空，空值展示 —，不能据此断言异常或伪造身份
remoteIp	socket 对端，经过代理时可能是网关地址
forwardedFor/realIp	未验证代理头，可能被伪造，界面明确标“代理头（未验证）”
durationMs	到登录事件发生时耗时，毫秒，不是完整 HTTP 请求耗时

ip 筛选目前只精确匹配 remoteIp 或 realIp，不查询 forwardedFor 链。日志从部署后开始记录，不能回溯历史；未抛异常的业务失败不保证计入 FAILURE。不提供删除、编辑或导出日志接口。敏感字段仅按文本渲染，不使用 v-html/innerHTML。

5. 外部接口兼容变化

GET /external/app/get/mirror：后台 root + exchangeCode:view。
PUT /external/app/refund/{id}：后台 root + exchangeCode:refund。
普通后台角色即使有上述权限也不能调用；无第三方签名方案前不恢复匿名访问。
这些不是前台列表/退款的替代接口，前端不得用它们绕过管理接口权限。
不把后台 root token 嵌入公开页面或第三方客户端；需要服务间调用请另行对接专用鉴权。

6. 联调验收清单

无 view：进页面、翻页、搜索均不请求；已加载列表清空，码与复制控件不可见。
只有 view：能看列表，生成/导出不可用；手动请求写接口仍被后端拒绝。
只有 add 无 export：不能生成兼导出；有 add + export 时正常提交。
false 筛选未使用正常生效，全部时无 useStatus 字段；分页最多 100。
超过 500 个生成/超过 10000 条导出有明确错误提示；不误下载 JSON。
root 登录日志列表可筛选、翻页、查看详情；其他角色/前台身份拒绝。
退出/切换账号不残留明文兑换码；所有 UA/账号等字段以文本展示。
新增优惠券不传 id；密码预检查通过与实际登录成功在日志界面清晰区分。

上述为待执行验收项，不表示线上已经通过；后端当前编译被既有腾讯云 SDK 依赖缺失阻断。

用户余额与权限管理补充

PUT /manage/user/add/balance：userBalance:add。
PUT /manage/user/sub/balance：userBalance:deduct。
GET /manage/user/get/user/balance/sys/operate/record：userBalance:view。
增减请求保持 userId、deductBalance、remark；用户 ID 必须为正数，金额单位仍为分，必须为正整数且最多 10 位；备注必填且最多 255 字符。禁止连点提交，超时后先查账，不要自动重试增加余额。
SQL 脚本的 @balance_parent_override 必须设置为真实用户管理菜单 ID，执行后检查 12 个权限全部为 OK；未配置不会默认开放。
角色、菜单和后台账号新增/修改/删除，以及后台账号停启用、重置密码，只允许精确 root 角色。普通角色隐藏对应写按钮；只读列表仍沿用原入口。登录入口不受 root 限制。
优惠券编辑忽略客户端创建时间和删除状态，保留数据库原值；优惠券及规格关联在事务内更新。
现有余额流水与操作日志继续保留。当前增额接口没有业务幂等键；拥有权限的操作员多次提交仍可能重复加款，前端禁连点不能替代后端幂等。

上线验收（在测试库进行）

匿名、前台用户 token、无对应权限后台账号均不能增减余额、生成/查看/导出兑换码、创建/修改优惠券；核对数据库无变化。
已授权后台账号可以执行对应动作；停用账号不得增减余额。
无 root 角色不能修改角色权限、菜单权限、后台账号或重置管理员密码。
余额金额为 0、负数、小数、超过 10 位或备注为空时拒绝；合法请求金额和流水一致，余额竞争更新失败时不产生流水。
修改优惠券同时提交伪造 createdTime，确认原创建时间不变。
执行 SQL、部署后重新登录刷新权限；历史异常优惠券/兑换码不会因部署自动作废，需要单独核查处理。

登录日志菜单权限（2026-10-21 更新）

入口改为系统管理下的登录日志，移除顶部快捷按钮。
路由 /setting/loginAudit，旧地址 /security/login-audit 保留别名。
查询接口 GET /manage/login/audit/get 由 root 限制改为登录且持有 loginAudit:view；响应格式不变。
前端路由、页面和请求拦截同步校验该权限。该权限可查询全部登录日志，应仅授权可信审计人员。
执行 docs/sql/20261021-login-audit-menu.sql，核对系统管理父菜单 ID；仅默认授权 root，其他角色手工勾选菜单并刷新权限、重新登录。
验收：授权角色可查询；无权限角色无法进入且直接调用接口被拒绝；未登录拒绝；旧地址同样受控。

frontend-security-integration.md 12 KB History Raw