feat: add platform audit export

2026-06-30 05:41:30 +08:00
parent c74432ce98
commit b9957d18d5
13 changed files with 422 additions and 69 deletions
--- a/docs/refactor/taro-frontend-integration.md
+++ b/docs/refactor/taro-frontend-integration.md
@@ -2519,7 +2519,7 @@ src/services/ai.ts         AI 择校推荐生成、报告列表、报告详情
 src/services/pronunciation.ts H5/小程序单词发音适配
 src/services/tenantAdmin.ts 租户后台看板、权限矩阵、成员、学生创建/批量导入/分班/备注/跟进、内容、营销、设置、角色模板写操作、公共题库采纳/同步/单条和批量冲突处理、导入详情/复检、CRM 配置/队列、分佣规则/成员比例/订单/结算、优惠券规则/核销报表、积分任务/兑换配置和记录
 src/services/tenantFinance.ts 租户财务运营：退款状态机、官方账单任务、对账批次/明细、差错工单、异常订单和人工调整凭证
-src/services/platformAdmin.ts 平台后台租户、租户详情、账务资料、平台审计、套餐账单、订阅账单候选/dry-run/批量生成、自动计费生成结果查看、逾期预览/内部催缴记录、用量、公共题库授权
+src/services/platformAdmin.ts 平台后台租户、租户详情、账务资料、平台审计查询/CSV 导出、套餐账单、订阅账单候选/dry-run/批量生成、自动计费生成结果查看、逾期预览/内部催缴记录、用量、公共题库授权
 ```

 验证命令：
@@ -2533,6 +2533,69 @@ npm run build:taro:h5:platform

 已通过。构建仍有 Taro H5 入口体积 warning，属于当前 Taro 工程既有警告，不阻断联调。

+## 平台审计导出
+
+平台审计属于超级管理员后台能力，学生端和租户后台不要接。前端只能调用后端命令式接口，不允许直接读 Supabase 表或拼 SQL 导出审计。
+
+查询审计：
+
+```text
+GET /api/platform-admin/audit-logs?tenantId=<tenantId>&action=platform.tenant&limit=100
+```
+
+导出审计：
+
+```text
+GET /api/platform-admin/audit-logs/export?format=csv&limit=1000
+GET /api/platform-admin/audit-logs/export?format=json&tenantId=<tenantId>&startDate=2026-06-01&endDate=2026-06-30
+```
+
+可用筛选：
+
+```text
+tenantId
+action       前缀匹配，例如 platform.tenant
+targetType
+actorUserId
+q            匹配 action/targetType/targetId
+startDate    YYYY-MM-DD
+endDate      YYYY-MM-DD
+limit        查询最大 500，导出最大 5000
+format       csv | json
+```
+
+导出响应：
+
+```json
+{
+  "item": {
+    "filename": "platform-audit-20260630T120000Z.csv",
+    "format": "csv",
+    "mimeType": "text/csv",
+    "rowCount": 25,
+    "exportedAt": "2026-06-30T12:00:00.000Z",
+    "sha256": "<content-sha256>",
+    "sizeBytes": 4096,
+    "contentBase64": "<base64>",
+    "filters": {
+      "tenantId": "<tenantId>",
+      "action": "platform.tenant",
+      "startDate": "2026-06-01",
+      "endDate": "2026-06-30"
+    }
+  }
+}
+```
+
+前端处理规则：
+
+- 只允许平台管理员页面调用，普通学生或租户成员会返回 `PLATFORM_ADMIN_REQUIRED`。
+- 后端会把导出动作再次写入 `platform.audit.exported`，前端不需要额外记日志。
+- 导出内容中的 `details` 会递归脱敏 token、secret、password、key、authorization、cookie、session、cert、signature 等敏感字段。
+- H5 可用 `contentBase64` 生成 `data:<mimeType>;base64,...` 下载；下载后可以显示 `sha256` 方便人工校验。
+- 小程序端如果无法稳定写入文件系统，建议展示“已生成，请到 H5 平台后台下载”，不要把完整 base64 长文本复制到剪贴板。
+- 平台后台不要把 `contentBase64` 持久存入本地缓存、日志或埋点。
+
 ## 平台账务逾期催缴

 平台后台账务页只调用命令式 API，不直接改 `tenant_invoices.status`、`tenants.billing_status` 或 `tenant_invoice_reminders`。后端会做平台管理员鉴权、行锁、每日催缴去重和审计。
@@ -2590,7 +2653,7 @@ GET /api/platform-admin/invoices/reminders?tenantId=<tenantId>&invoiceId=<invoic

 - 学生端：地区选择、题目视频播放、题目反馈、错题/收藏专题页、模考交卷报告、收银台、订单详情、售后入口、题干/解析/知识手册 RichContent 安全渲染、逐题复盘、背单词卡片学习/发音/收藏练习、资料短签名水印预览/下载确认、个人中心消息中心、积分任务、积分兑换和积分明细第一版已接；下一批继续补独立消息中心增强、真正 KaTeX/小程序公式方案、私有题图签名资源映射、背单词更细统计、小程序支付容器和分享场景。
 - 租户后台：工作台已接权限驱动模块入口；学生运营页已接学生创建/更新、禁用/恢复、批量导入、批量分班、学生备注、跟进任务和完成跟进第一版；题库内容页已接公共题库采纳/同步、冲突查看、单条/批量采纳平台或保留本地、导入问题、模板预览/下载、异步任务轮询和导入后复检第一版；营销中心已接 CRM 配置保存、CRM 队列按状态查看、分佣默认规则、成员分佣比例、分佣订单明细、结算单生成、审核通过/驳回、标记线下打款、优惠券规则表单、筛选、核销明细、核销报表、积分任务/兑换操作台和用户通知查看第一版；财务运营页已接退款申请/审核/供应商提交与查询、官方账单任务、对账批次/异常明细、差错工单处理、人工调整凭证提交/复核和异常订单运营台第一版；租户设置页已接主题模板、草稿预览、发布、角色模板创建、编辑、停用、权限点、菜单、模块、字段、基础数据范围、成员搜索/新建、成员绑定模板、成员状态和额外权限覆盖第一版；下一批继续补更精细的学生导入模板体验、真实生产账单抽样验收、真实打款 provider、发票、更细数据范围 UI 和主题素材库。
- 平台后台：租户创建、租户详情、状态变更、账务资料维护、最近平台审计、订阅开通、账单生成、订阅账单候选预览、dry-run、批量生成、自动计费生成结果查看、人工收款确认、逾期预览、内部催缴生成、催缴记录查看、用量录入、公共题库授权编辑已接第一版；后端会跳过已开票订阅并记录 `platform.invoice.subscription_batch_created` 审计，`platform-billing` worker 会自动生成即将到期订阅账单并记录 `platform.invoice.subscription_auto_created` 审计，`platform-dunning` worker 会标记已过期未结清服务费账单、生成 `tenant_invoice_reminders` 并记录 `platform.invoice.overdue_processed` 审计；前端只展示候选、预览结果、跳过结果、逾期处理结果和生成后的账单/审计，不要直接更新账单状态或租户 `billing_status`；继续补租户基础资料编辑增强、平台审计报表导出/告警、外部催缴通知和平台在线收款。
+- 平台后台：租户创建、租户详情、状态变更、账务资料维护、最近平台审计查询/CSV 导出、订阅开通、账单生成、订阅账单候选预览、dry-run、批量生成、自动计费生成结果查看、人工收款确认、逾期预览、内部催缴生成、催缴记录查看、用量录入、公共题库授权编辑已接第一版；后端会跳过已开票订阅并记录 `platform.invoice.subscription_batch_created` 审计，`platform-billing` worker 会自动生成即将到期订阅账单并记录 `platform.invoice.subscription_auto_created` 审计，`platform-dunning` worker 会标记已过期未结清服务费账单、生成 `tenant_invoice_reminders` 并记录 `platform.invoice.overdue_processed` 审计；前端只展示候选、预览结果、跳过结果、逾期处理结果和生成后的账单/审计，不要直接更新账单状态或租户 `billing_status`；继续补租户基础资料编辑增强、平台审计告警、外部催缴通知和平台在线收款。
 - 小程序：验证 `Taro.login`、微信支付、分享 scene/referral、Supabase client 兼容性；如不稳定，保留 `apps/api/auth/*` 作为小程序登录适配层。

 ## AI 择校推荐接入