create-react-admin-template 0.0.0-stage → 0.1.0

package/template/deploy/README.md

@@ -0,0 +1,132 @@
+# 部署模板
+
+仓库内置单容器静态站点部署模板。Vite 产物由 Nginx 提供，宿主机反向代理负责
+TLS、域名和 `/api/` 上游。模板中的域名、端口和 API 地址都是示例，初始化项目时必须
+按环境替换。
+
+## 流量结构
+
+```text
+https://admin.example.com
+├── /api/* -> 127.0.0.1:18085 -> backend
+└── /*     -> 127.0.0.1:8084  -> enterprise-react-admin:80
+```
+
+容器内的 [`nginx.conf`](nginx.conf) 只负责 SPA fallback、静态资源缓存和通用安全头。
+宿主机路由片段位于 `host-nginx/`，不包含 `server {}`，由平台统一的 HTTPS Server
+引入。CSP 允许源、响应头变更和依赖审计流程见
+[`../docs/browser-security.md`](../docs/browser-security.md)。
+
+## 不可变产物流
+
+流水线只产生一次前端代码：
+
+```text
+verify
+  pnpm verify
+  └── dist
+      └── release:prepare → .artifacts/release
+                               ├── site/
+                               ├── artifact-manifest.sha256
+                               └── artifact-metadata.json
+                                      │
+package                               ▼
+  校验 Commit 与文件摘要 → 仅封装 Nginx 镜像 → 推送 GitLab Registry
+                                                  │
+deploy                                            ▼
+  按 sha256 镜像摘要拉取 → 校验 Commit Label → 候选探活 → 正式容器
+```
+
+`verify` Job 是唯一允许安装前端依赖、执行测试和运行 Vite Build 的阶段。`package` Job 只
+消费它上传的 `.artifacts/release`，Dockerfile 不包含 Node、pnpm、源码或重新构建步骤；
+`deploy` Job 只接受 Registry 返回的 `RELEASE_IMAGE_DIGEST`，不按可变 Tag 部署。候选容器
+注入目标环境的 Runtime Config 后，使用真实 Chromium 打开 `/sign-in`；只有配置通过应用
+自己的 Zod 契约、React 完成启动并渲染登录表单，才允许进入正式晋级。晋级期间旧容器会
+改名并停止但不会删除；新容器创建、启动或公网探活失败时，Trap 会删除失败版本并恢复旧
+容器。只有公网探活通过后才删除回滚容器。
+
+发布清单记录每个静态文件的 SHA-256，元数据记录 Schema、应用版本、Git Commit、清单摘要
+以及 `strRuntimeConfig: external`。任意文件缺失、增加、内容变化或 Commit 不匹配都会阻断
+封装和部署。
+
+`runtime-config.json` 有意不进入不可变静态目录。它属于部署环境，在候选和正式容器启动前
+通过 GitLab File Variable 注入；因此同一镜像摘要可以晋级到多个环境，而无需重新编译。
+生产平台仍需独立版本化 Runtime Config，并保证其 Schema Version 与目标镜像兼容。
+
+## CI 变量
+
+| 变量                            | 类型            | 说明                       |
+| ------------------------------- | --------------- | -------------------------- |
+| `ADMIN_PUBLIC_URL`              | Variable        | 应用公网 HTTPS 地址        |
+| `ADMIN_RUNTIME_CONFIG_FILE`     | File variable   | 生产运行时配置 JSON        |
+| `ADMIN_WEB_HOST_PORT`           | Variable        | 宿主机应用端口，默认 8084  |
+| `ENABLE_PRODUCTION_DEPLOY`      | Variable        | 显式设为 `true` 才允许部署 |
+| `VITE_HANDSONTABLE_LICENSE_KEY` | Masked variable | Handsontable 商业许可证    |
+
+GitLab 内建的 `CI_REGISTRY`、`CI_REGISTRY_IMAGE`、`CI_REGISTRY_USER` 和
+`CI_REGISTRY_PASSWORD` 用于推送和拉取镜像。Registry 必须启用；部署身份应只拥有当前项目
+镜像的最小读写权限。
+
+## 宿主机示例
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name admin.example.com;
+
+    ssl_certificate /etc/nginx/certs/admin.example.com/fullchain.pem;
+    ssl_certificate_key /etc/nginx/certs/admin.example.com/privkey.pem;
+
+    include /etc/nginx/react-admin-locations/*.conf;
+}
+```
+
+生产部署默认关闭。仅当 main 分支的 `ENABLE_PRODUCTION_DEPLOY=true` 时显示手动部署
+任务；任务拒绝非 HTTPS 地址、`example.com` 示例域名、无效宿主机端口以及缺失或无效 JSON
+的 `ADMIN_RUNTIME_CONFIG_FILE`。该变量使用 GitLab File 类型，内容遵循
+`public/runtime-config.json` 契约；生产应设置 `app.strMode=connected` 和
+`auth.strSessionStorage=memory`。接入正式监控 Adapter 后，再设置
+`observability.bEnabled=true` 和稳定的 `observability.strEnvironment`；运行时 JSON
+不能写入任何密钥。
+
+启用生产部署后，main 流水线自动封装并推送 Commit Tag，同时保存 Registry Digest；手动
+`deploy` Job 只能消费该 Digest。候选容器的 Chromium 冒烟通过后才替换正式容器，正式
+公网探活通过前始终保留可恢复的上一版。运行时配置响应禁止缓存。浏览器 DOM 不包含登录表单时，
+流水线会以 `DEPLOY_BROWSER_SMOKE_APP_NOT_READY` 失败，并保留候选容器供当前 Job 清理。
+
+`deploy/host-nginx/` 是平台基础设施示例，不由应用发布任务覆盖。交付平台应在首次接入或
+端口/API 上游变化时单独评审、安装并执行 `nginx -t`；这样应用版本回滚不会夹带宿主机
+配置变更。`ADMIN_WEB_HOST_PORT` 必须与平台已安装的 Web upstream 保持一致。
+
+回滚时重新运行目标历史流水线的手动部署 Job，或由交付平台选择其保存的
+`release-image.txt` Digest；禁止对旧 Commit 重新构建一个“同名”镜像冒充原产物。镜像、
+流水线 Artifact 和 Registry 保留期应按项目恢复时间目标设置，模板中的 7/30 天只是最低
+示例。
+
+本地验证发布目录和运行时镜像：
+
+```bash
+pnpm verify
+pnpm release:prepare
+pnpm release:verify --commit "$(git rev-parse HEAD)"
+docker build --build-arg APP_COMMIT_SHA="$(git rev-parse HEAD)" -t react-admin:local .
+docker run --rm -d --name react-admin-candidate -p 127.0.0.1:8084:80 react-admin:local
+docker cp public/runtime-config.json react-admin-candidate:/usr/share/nginx/html/runtime-config.json
+pnpm deployment:smoke http://127.0.0.1:8084/sign-in
+docker rm -f react-admin-candidate
+```
+
+Dockerfile 的基础 Nginx 镜像使用 Digest 固定。升级 Nginx 时必须显式更新 Digest、重新执行
+镜像构建和安全检查，不能只把浮动 Tag 当作已验证依赖。
+
+## 验证
+
+```bash
+docker ps --filter name=enterprise-react-admin
+cat release-image.txt
+curl -I https://admin.example.com/sign-in
+curl -I https://admin.example.com/runtime-config.json
+curl -I https://admin.example.com/api/health
+```
+
+刷新任意前端路由应返回 SPA；API 请求应到达真实后端且不会落入 `index.html`。

package/template/deploy/host-nginx/react-admin-api.conf

@@ -0,0 +1,14 @@
+location /api/ {
+  proxy_pass http://127.0.0.1:18085;
+  proxy_http_version 1.1;
+  proxy_set_header Host $host;
+  proxy_set_header X-Real-IP $remote_addr;
+  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+  proxy_set_header X-Forwarded-Host $host;
+  proxy_set_header X-Forwarded-Port $server_port;
+  proxy_set_header X-Forwarded-Proto $scheme;
+  proxy_set_header Connection "";
+  proxy_buffering off;
+  proxy_cache off;
+  proxy_read_timeout 3600s;
+}

package/template/deploy/host-nginx/react-admin-web.conf

@@ -0,0 +1,8 @@
+location / {
+  proxy_pass http://127.0.0.1:8084;
+  proxy_http_version 1.1;
+  proxy_set_header Host $host;
+  proxy_set_header X-Real-IP $remote_addr;
+  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+  proxy_set_header X-Forwarded-Proto $scheme;
+}

package/template/deploy/nginx.conf

@@ -0,0 +1,38 @@
+map $uri $str_runtime_config_cache_control {
+  default "";
+  /runtime-config.json "no-store, no-cache, must-revalidate";
+}
+
+server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  add_header Content-Security-Policy "default-src 'self'; base-uri 'self'; connect-src 'self'; font-src 'self' data:; form-action 'self'; frame-ancestors 'none'; frame-src 'self' blob: https:; img-src 'self' blob: data: https:; object-src 'none'; script-src 'self'; script-src-attr 'none'; style-src 'self' 'unsafe-inline'" always;
+  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+  add_header Cross-Origin-Opener-Policy "same-origin" always;
+  add_header Cross-Origin-Resource-Policy "same-origin" always;
+  add_header Permissions-Policy "camera=(), geolocation=(), microphone=(), payment=(), usb=()" always;
+  add_header X-Frame-Options "DENY" always;
+  add_header X-Content-Type-Options "nosniff" always;
+  add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+  add_header Cache-Control $str_runtime_config_cache_control always;
+
+  gzip on;
+  gzip_min_length 1024;
+  gzip_types text/css application/javascript application/json image/svg+xml;
+
+  location /assets/ {
+    try_files $uri =404;
+    expires 1y;
+  }
+
+  location = /index.html {
+    expires -1;
+  }
+
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}

package/template/docs/activity-status.md

@@ -0,0 +1,217 @@
+# 通知与任务状态接口
+
+这套能力为企业项目提供一个供应商无关的“活动摘要 + 实时更新”基础设施：统一未读数量、
+近期后台任务状态、轮询/SSE/WebSocket 连接和断线恢复。它不提供通知中心、待办页面、
+业务消息模板或任务详情；这些仍由具体项目 Feature 使用生成客户端实现。
+
+公共入口统一从 `@/api/activity` 导入。这是按需能力，默认 `Application` 不装配
+`ActivityProvider`；项目应在确实展示通知或任务状态的认证布局或 Feature 边界挂载它。
+
+## 数据所有权
+
+| 数据或状态                   | 唯一所有者                      | 说明                                   |
+| ---------------------------- | ------------------------------- | -------------------------------------- |
+| 未读数、近期任务状态         | TanStack Query 活动快照         | 按用户、会话、租户、工作空间和语言隔离 |
+| 通知列表、待办列表、任务详情 | 所属 Feature 的 Query           | 不复制进活动快照或 Zustand             |
+| 连接、重连轮次、最后事件 ID  | `fnStartActivitySubscription()` | 仅为浏览器连接生命周期，不是服务端数据 |
+| Token、权限和最终任务状态    | 认证会话与后端                  | 前端展示和预检不能替代服务端授权       |
+
+活动快照最多保存 100 条近期任务，只包含稳定任务 ID、通用状态、更新时间和可选进度。通知
+标题、正文、发送人和业务跳转不进入全局摘要，避免把完整通知中心变成第二份全局缓存。
+
+## 快照与事件契约
+
+快照包含：
+
+- `nUnreadCount`：后端确认的未读总数。
+- `arrTaskStatuses`：近期任务的 `queued/running/succeeded/failed/cancelled` 状态。
+- `strVersion`：完整快照版本。
+- `strLastEventId`：快照已经包含的最后事件，用于断线续传。
+
+实时传输只支持四类幂等事件：
+
+| `strType`              | 行为                                           |
+| ---------------------- | ---------------------------------------------- |
+| `snapshot-replaced`    | 使用完整后端快照替换当前活动缓存               |
+| `unread-count-changed` | 设置最新未读总数，不传增量                     |
+| `task-status-changed`  | 按任务 ID 和更新时间合并，旧事件不能覆盖新状态 |
+| `snapshot-invalidated` | 失效当前 Query，并通过快照接口重新确认         |
+
+所有快照和事件在进入缓存前都会校验稳定 ID、非负未读数、任务状态、0–100 进度和 ISO 8601
+时间。传输事件采用“至少一次”友好的设置值语义；不要发送 `unread + 1` 一类依赖客户端旧值
+的指令。
+
+## 使用生成客户端加载快照
+
+项目 Adapter 负责把 Swagger DTO 映射为脚手架契约，不在基础设施中写死端点：
+
+```ts
+const objActivitySource = fnCreateActivitySource(
+  async ({ objScope, objSignal }) => {
+    const objResponse = await objGeneratedApi.api.activitySummaryList(
+      {
+        tenantId: objScope.strTenantId,
+        workspaceId: objScope.strWorkspaceId,
+      },
+      { signal: objSignal }
+    )
+
+    return {
+      nUnreadCount: objResponse.data.unreadCount,
+      arrTaskStatuses: objResponse.data.tasks.map(fnMapTaskStatus),
+      strLastEventId: objResponse.data.lastEventId,
+      strVersion: objResponse.data.version,
+    }
+  }
+)
+```
+
+标记已读、取消任务或重新执行任务属于业务 Mutation。成功后调用
+`fnInvalidateActivitySnapshot(objQueryClient, objScope)`，让服务端重新确认摘要；不要直接
+修改 Zustand 未读数。
+
+## 选择传输方式
+
+优先选择满足需求的最小能力：
+
+| 方式      | 适用场景                                     | 主要代价                                   |
+| --------- | -------------------------------------------- | ------------------------------------------ |
+| 轮询      | 更新频率低、后端没有流式基础设施             | 请求数量更多，后台标签页计时器可能被节流   |
+| SSE       | 服务器单向推送通知和任务状态                 | 原生 EventSource 不能设置 Authorization 头 |
+| WebSocket | 已有双向实时网关或后续确实需要客户端上行消息 | 网关、鉴权、心跳和运维复杂度最高           |
+
+### 轮询
+
+轮询顺序执行，请求不会重叠；成功后等待固定间隔，失败交给统一指数退避控制器：
+
+```ts
+const objActivityTransport = fnCreatePollingActivityTransport({
+  nIntervalMs: 30_000,
+  fnPoll: async ({ objScope, objSignal, strLastEventId }) => {
+    const objResponse = await objGeneratedApi.api.activityEventsList(
+      {
+        afterEventId: strLastEventId,
+        tenantId: objScope.strTenantId,
+        workspaceId: objScope.strWorkspaceId,
+      },
+      { signal: objSignal }
+    )
+    return objResponse.data.events.map(fnMapActivityEvent)
+  },
+})
+```
+
+### SSE
+
+浏览器原生 `EventSource` 不能附加 Bearer Token。不得把 Access Token、Refresh Token 或长期
+凭据放进 URL。推荐同源 HttpOnly Cookie；或者先通过生成客户端获取一次性短期连接票据，
+再异步创建 EventSource。若项目使用 Fetch 流式响应，可以包装成 `IActivityEventSourceLike`：
+
+```ts
+const objActivityTransport = fnCreateSseActivityTransport({
+  fnCreateEventSource: async ({ objScope, objSignal }) => {
+    const objTicket = await objGeneratedApi.api.activityTicketCreate(
+      { tenantId: objScope.strTenantId },
+      { signal: objSignal }
+    )
+    return new EventSource(
+      `/api/v1/activity/stream?ticket=${encodeURIComponent(objTicket.data.ticket)}`
+    )
+  },
+  fnParseMessage: (strData) => fnMapActivityEvent(JSON.parse(strData)),
+})
+```
+
+票据必须单次使用、短时过期、绑定用户和作用域，并避免进入访问日志。更推荐 Cookie 或
+Fetch Header 方案；示例票据不是允许把会话 Token 写入查询字符串。
+
+### WebSocket
+
+浏览器 WebSocket 同样不能自行设置认证 Header。使用同源安全 Cookie或由生成客户端获取的
+一次性连接票据，始终使用 `wss:`：
+
+```ts
+const objActivityTransport = fnCreateWebSocketActivityTransport({
+  fnCreateWebSocket: async ({ objScope, objSignal, strLastEventId }) => {
+    const objTicket = await objGeneratedApi.api.activityTicketCreate(
+      { tenantId: objScope.strTenantId },
+      { signal: objSignal }
+    )
+    return new WebSocket(
+      `wss://example.test/activity?ticket=${encodeURIComponent(
+        objTicket.data.ticket
+      )}&after=${encodeURIComponent(strLastEventId ?? '')}`
+    )
+  },
+  fnParseMessage: (strData) => fnMapActivityEvent(JSON.parse(strData)),
+})
+```
+
+基础设施只接受 UTF-8 文本帧。二进制协议、应用心跳、Ack 和客户端上行命令由确实需要
+WebSocket 的项目 Adapter 负责，不能为了展示未读数默认引入。
+
+## 应用和 React 使用
+
+在 `Application` 内部的认证布局或拥有该能力的 Feature 边界注入快照和可选传输。该位置
+已经具备 QueryClient、Locale 和租户/工作空间上下文：
+
+```tsx
+<ActivityProvider
+  bIsEnabled={bIsAuthenticated}
+  objSource={objActivitySource}
+  objTransport={objActivityTransport}
+  objReconnectPolicy={{
+    nInitialDelayMs: 1_000,
+    nMaxDelayMs: 30_000,
+    nMultiplier: 2,
+    nJitterRatio: 0.2,
+  }}
+>
+  {objChildren}
+</ActivityProvider>
+```
+
+普通组件读取摘要；任务入口按稳定 ID 订阅单条状态：
+
+```tsx
+const {
+  nUnreadCount,
+  objConnectionState,
+  fnReconnect,
+  fnRetry,
+} = useActivity()
+const objExportTask = useActivityTaskStatus(strExportTaskId)
+```
+
+`objConnectionState` 是 `idle/connecting/connected/reconnecting/error` 可判别联合。页面可以
+在最终 `error` 状态提供 `fnReconnect()`，快照请求失败则调用 `fnRetry()`。连接错误不隐藏
+应用子树；未读数和任务状态继续展示最后一次成功快照，并明确连接已降级。
+
+## React 外使用
+
+- `fnEnsureActivitySnapshot()`：Loader 或启动阶段确保快照存在。
+- `fnGetCachedActivitySnapshot()`：同步读取 QueryClient 中的当前快照。
+- `fnGetActivityTaskStatus()`：按稳定任务 ID 读取状态。
+- `fnApplyActivityEvent()`：项目自有宿主把已映射事件写入统一 Query 缓存。
+- `fnStartActivitySubscription()`：在 React 外启动同一重连控制器，调用方负责 `fnStop()`。
+
+身份、租户、工作空间、会话版本或语言变化会产生新的活动 Query Key，并由 Provider 关闭
+旧连接、取消旧请求、加载新快照后再连接。退出登录时，拥有该能力的认证布局应卸载 Provider
+或把 `bIsEnabled` 设为 `false`。
+
+## 断线与后端职责
+
+- 自动重连使用带抖动的指数退避，默认 1 秒起步、30 秒封顶；可配置连续失败上限。
+- 用户手动重连会清零连续失败轮次，并携带最后已应用事件 ID。
+- 新连接建立后，旧连接的迟到事件会被忽略。
+- 服务端应支持按事件 ID 续传；事件历史过期时发送 `snapshot-invalidated` 或完整快照。
+- 服务端负责成员关系、权限、未读事实、任务执行、事件顺序和事件保留窗口。
+- 前端不得因为实时连接成功就跳过普通 REST/Query 接口的权限校验。
+
+## 不支持范围
+
+- 不内置通知中心、待办/已办、任务详情、业务跳转或消息模板。
+- 不提供跨标签页 Leader Election、Service Worker 后台推送或系统级桌面通知。
+- 不把完整通知列表或任务列表持久化到 Local Storage。
+- 不自动选择供应商、消息中间件、网关协议、心跳格式或 WebSocket SDK。
+- 不用实时事件替代服务端最终状态、审计、幂等和权限判断。

package/template/docs/audit-logs.md

@@ -0,0 +1,158 @@
+# 审计日志接入
+
+`src/auditLogs` 提供审计列表、详情和导出的前端安全边界。它负责校验后端返回的
+展示模型、复用统一 Query 作用域、协调取消与异步导出；不负责在浏览器
+生成、保存或证明审计事实。
+
+## 权威边界
+
+| 层级            | 必须负责                                                          | 不能交给前端                              |
+| --------------- | ----------------------------------------------------------------- | ----------------------------------------- |
+| 业务后端        | 在权威事务附近生成事实，记录操作者、动作、目标、结果和请求关联 ID | 让浏览器上报“操作成功”作为事实            |
+| 审计服务        | 授权查询、租户隔离、字段脱敏、留存、完整性、防篡改、检索和导出    | 依赖隐藏按钮保护日志                      |
+| Swagger Adapter | 调用生成客户端并映射列表、详情和任务结果                          | 直接使用 `fetch`、拼接地址或返回管理密钥  |
+| `src/auditLogs` | 运行时校验、缓存隔离、取消、任务生命周期                          | 保存原始请求体、Token、Cookie 或任意 JSON |
+| 审计 Feature    | URL 筛选、AppTable 列、详情展示、错误与空状态                     | 自行判断跨租户数据是否有权查看            |
+
+前端不会提供 `fnCreateAuditEvent` 一类写入接口。登录、审批、删除、权限变更、导出
+等审计事实必须由实际执行操作的后端产生；普通埋点、可观测性事件和控制台日志都
+不能替代审计日志。
+
+## 数据模型
+
+列表项 `IAuditLogEntry` 只包含稳定 ID、时间、操作码、操作者/目标安全名称、执行
+结果、请求关联 ID、安全摘要和后端已遮罩的 IP 地址。
+
+详情不接受原始请求体或任意元数据对象，只接受两类有界字段：
+
+- `IAuditLogChange`：字段 Key、纯文本名称、前后安全展示值和展示级别。
+- `IAuditLogContextField`：受限上下文 Key、名称、安全展示值和展示级别。
+
+展示级别为 `plain`、`masked` 或 `redacted`。`plain` 不代表前端可以自行解除脱敏，
+它只表示后端已根据当前查看者权限确认该值可显示。所有内容仍应通过 React 普通
+文本节点渲染，不得进入 `dangerouslySetInnerHTML`。
+
+## Swagger 数据源
+
+项目使用 `fnCreateAuditLogSource` 连接生成客户端。下面的方法和 DTO 名称仅表示映射
+位置，以实际 OpenAPI 产物为准：
+
+```ts
+import { fnCreateAuditLogSource } from '@/auditLogs'
+import { objGeneratedApi } from '@/api/generated/project'
+
+export const objAuditLogSource = fnCreateAuditLogSource({
+  async fnList({ objFilter, objSignal }) {
+    const objResponse = await objGeneratedApi.auditLogs.list(objFilter, {
+      signal: objSignal,
+    })
+    return {
+      arrEntries: objResponse.data.items.map(fnMapAuditLogEntry),
+      bHasMore: objResponse.data.hasMore,
+      nTotal: objResponse.data.total,
+      strNextCursor: objResponse.data.nextCursor,
+    }
+  },
+  async fnGetDetail({ objSignal, strAuditLogId }) {
+    const objResponse = await objGeneratedApi.auditLogs.detail(strAuditLogId, {
+      signal: objSignal,
+    })
+    return fnMapAuditLogDetail(objResponse.data)
+  },
+})
+```
+
+`objScope` 包含当前用户、会话版本、租户、工作空间和语言，可用于生成客户端需要的
+非敏感请求参数或诊断，但不能替代服务端从认证会话重新确认身份。Adapter 必须把
+`objSignal` 透传给生成客户端。
+
+## 列表与详情
+
+```tsx
+import { useAuditLogDetail, useAuditLogList } from '@/auditLogs'
+
+const objListQuery = useAuditLogList({
+  objFilter: {
+    strAction: 'order.approve',
+    strStartedAt: '2026-08-01T00:00:00.000Z',
+    strEndedAt: '2026-08-31T23:59:59.999Z',
+  },
+  objSource: objAuditLogSource,
+})
+
+const objDetailQuery = useAuditLogDetail({
+  bIsEnabled: Boolean(strSelectedAuditLogId),
+  objSource: objAuditLogSource,
+  strAuditLogId: strSelectedAuditLogId,
+})
+```
+
+列表采用后端不透明游标，默认 50 条、最大 100 条。支持操作者、操作码、结果、时间
+范围、请求关联 ID、业务对象及服务器重新授权的租户/工作空间筛选。返回列表会拒绝
+重复 ID，并固定为时间倒序；详情返回的 ID 必须与请求完全一致。
+
+需要刷新、分享和浏览器前进后退的筛选由审计 Feature 的路由 Schema 读写，游标只代表
+当前分页过程，不应写入个人默认。Query 缓存按用户、会话版本、租户、工作空间、语言和
+完整筛选隔离，不复制到 Zustand 或持久化存储。
+
+## 安全导出
+
+审计导出复用 `useFileTask`，支持同步完成或后台任务。结果只包含导出 ID、受保护下载
+接口使用的文件 ID 和清理后的文件名，不允许 Adapter 返回任意外部 URL。
+
+```tsx
+const objExportTask = useAuditLogExport({
+  objSource: {
+    async fnStartExport({ objRequest, objSignal }) {
+      const objResponse = await objGeneratedApi.auditExports.create(
+        objRequest,
+        { signal: objSignal }
+      )
+      return objResponse.data.completed
+        ? {
+            strMode: 'completed',
+            objResult: {
+              strExportId: objResponse.data.exportId,
+              strFileId: objResponse.data.fileId,
+              strFileName: objResponse.data.fileName,
+            },
+          }
+        : {
+            strMode: 'background',
+            strTaskId: objResponse.data.taskId,
+          }
+    },
+    async fnPollExport({ objSignal, strTaskId }) {
+      const objResponse = await objGeneratedApi.auditExports.detail(
+        strTaskId,
+        { signal: objSignal }
+      )
+      return fnMapAuditExportTask(objResponse.data)
+    },
+  },
+})
+```
+
+任务成功后再使用 `fnDownloadFile` 和生成客户端按 `strFileId` 下载。后端必须重新鉴权
+文件归属和有效期，并限制时间范围、最大行数、允许字段和并发任务。CSV/XLSX 内容由
+后端生成时必须防止公式注入；前端文件名清理和隐藏导出按钮都不能代替
+这些控制。
+
+## 服务端验收要求
+
+- 审计写入与业务事务的失败语义明确，不能由浏览器伪造成功事实。
+- 以服务端身份、租户和资源权限授权每次列表、详情、导出和文件下载。
+- Token、Cookie、密码、密钥、完整请求体和敏感原值默认拒绝进入审计载荷。
+- IP、手机号、邮箱、证件号等个人数据按角色、用途和保留期脱敏。
+- 定义可信时钟、事件唯一 ID、不可变存储、完整性验证、归档和删除策略。
+- 请求关联 ID 可从统一 API 错误追溯到审计事实，但不能包含凭据。
+- 导出操作本身必须产生审计事实，并受行数、频率和数据字段限制。
+
+## 前端验收范围
+
+- 筛选、游标、时间戳、条数、列表重复 ID 和详情 ID 均经过运行时校验。
+- 详情只能携带有界纯文本展示字段，不存在任意 JSON 或原始请求体入口。
+- 后端 `401/403` 通过统一错误契约反馈，入口显隐不承担最终授权。
+- Query Key 隔离身份和全部筛选，请求取消信号可到达 Swagger Adapter。
+- 导出复用统一任务状态，任务 ID、文件 ID 和文件名经过校验。
+- 不增加默认审计页面、路由、菜单、供应商 SDK 或首屏依赖。