@qiqb/audit-domain

按需装配的 QIQB 操作审计前端领域包，提供 AuditLogViewer 日志页面、AuditOperationDetail 完整操作过程组件和 AuditPropertyChanges 递归属性展示。采用 React、Ant Design 与 Ant Design ProTable，通过 runtime 注入宿主请求和权限项目，不依赖 Umi、ProKeeper 或平台管理页面。

页面组织

列表使用标准 ProTable 的标题、查询、分页和列设置，按根操作分页。操作时间、名称、编码、操作者、来源、直接对象记录、执行结果、数据提交状态和耗时分列展示，技术字段可通过列设置选择。筛选命中子操作时仍返回整次操作，避免一个复杂业务被拆散在多个分页。

“查看过程”打开宽抽屉：

• 左侧显示业务操作树，支持展开多层操作和选择单个节点。
• 从左侧选择节点或“全部操作”，右侧按操作展示其直接归属的定位对象；父操作不重复展示子操作的变更。
• 列表使用标准 ProTable 默认尺寸；详情使用紧凑变更列表，直接展示“属性名：旧值 → 新值”。每条对象记录保留类型、稳定编号、变更时名称和所属关系，重复片段分别保留。
• 对象属性、集合及元素使用默认展开的层级分组，标量前后值在各自属性内成对展示。集合元素按稳定键标出新增、修改、删除或移动，元素内部可以继续包含对象和子集合；整体快照与子属性变化同时保留。
• null、属性不存在和未采集分别显示，长文本换行，JSON 可展开完整快照。删除对象及集合元素以快照展示，不依赖实时业务数据。
• 执行成功、失败与数据已提交、已回滚、提交状态未知分别呈现，嵌套关系不会被解释成事务关系。详情以对象和属性前后对比为主；操作人、技术编号、HTTP 上下文、Trace 和方法参数放在默认收起的“操作信息”中，需要时展开。属性修改和位置变化可以出现在同一个元素记录中，页面同时展示属性对比与前后索引。

操作树与数据属性树是不同维度：操作树表示业务因果，对象的所属关系和集合结构表示数据定位。

跨方法填写如何呈现

后端推荐外层用 bindObject 确定对象，内层业务方法在掌握旧值的位置调用静态 change。 绑定范围可以跨方法，它本身不会增加操作树节点；页面仍接收同一套结构化事实，不展示 Java 方法调用栈。

注解方法默认记录调用前的实参，详情通过 parametersJson 展示按参数顺序排列的 JSON 数组。[] 表示已采集但方法没有参数，null 或缺少字段表示未采集。参数用于查看调用输入，属性前后对比仍以业务实际填写的变更事实为准；参数不会自动转换为对象变更。

• 同一操作、同一绑定片段的不同属性累积到一条对象记录；重复同一属性路径或重新显式绑定时保留后续片段，展示实际发生的每一段前后变化。
• 子操作继承外层对象及集合路径，变化仍归子节点；不同操作的同对象记录不合并，也不复制回父节点。
• 显式有效绑定可以先记录空属性的对象身份、空字段的集合元素路径；空属性表示没有填写字段事实，不证明字段已改变或未改变。子操作仅继承且未显式绑定、填写时不复制父记录。
• defaultObject 复用已有对象和路径；缺少外层对象才用业务方法自己的默认身份。
• defaultOperation 复用已有操作时不增加节点；operation 建立子节点；rootOperation 则成为列表中的独立根，同项目仍使用外层对象或集合路径，字段事实只属于新根。需切换对象时显式 bindObject。
• item/createItem/deleteItem 可以跨方法绑定集合元素，内层静态填写仍展示为对象属性树中的集合；多层集合不会被当成业务操作节点。

全局 fallback 是后端入口模板。没有活动操作的业务范围可以据此建立短期根；页面不会因为使用同一模板而把不同请求合成一条日志。 页面统计的是对象、属性和集合元素的记录数：空绑定及同一路径的多次片段都保留，不代表唯一对象数，也不证明数据已提交。 完整调用与默认/强制覆盖规则见 跨方法审计使用手册。

运行时与路由

import { configureAuditDomainRuntime } from '@qiqb/audit-domain/runtime';

configureAuditDomainRuntime({
  request, // 复用宿主 Token、超时及鉴权策略
  apiPrefix: '/api/qiqb_platform/audit',
  projectCode: 'qiqb_platform',
});

默认列表接口为 GET /api/qiqb_platform/audit/logs。详情为 GET /api/qiqb_platform/audit/logs/{operationId}?projectCode=...，返回同一根操作下的扁平节点数组。详情只按 operationId 定位；id 仅标识存储记录。/api 是宿主网关前缀；后端通用端点为 /qiqb_platform/audit。

列表的 objectId 筛选匹配定位对象及归属对象的类型、编号子串，不搜索属性值或集合元素键。 筛选命中子节点时返回所属根，多项条件需要由同一节点满足。集合稳定键在详情内阅读。

列表服务处理当前宿主的 { items, total, page, size } 及 WebResp.data；详情处理当前宿主的直接节点数组及 WebResp.data。失败或非法响应在组件展示；请求使用 skipErrorHandler: true 避免宿主重复弹窗。默认 fetch 使用同源凭证，正式宿主应注入已有请求层。

import { auditRoutes, createAuditRoutes } from '@qiqb/audit-domain/routes';

const routes = auditRoutes; // /p/audit/operations
const custom = createAuditRoutes({ projectCode: 'custom_project', basePath: '/custom/audit' });

路由保持 AuditOperationPage 权限码，由宿主和后端校验项目权限；查询项目不能替代授权。routes 入口无 React 或运行时依赖，ESM/CJS 均可用于宿主构建配置。平台核心不隐式依赖、转导或装配审计页面。

组件嵌入与静态数据

import {
  AuditLogViewer,
  AuditOperationDetail,
  type AuditLogItem,
} from '@qiqb/audit-domain';

<AuditLogViewer
  projectCode="custom_project"
  request={queryRootOperations} // 返回 AuditLogPage
  detailRequest={queryOperationDetails} // 返回 AuditLogItem[]
  traceUrlBuilder={(traceId) => `/traces/${encodeURIComponent(traceId)}`}
/>;

// 只读组件也可直接展示静态方法填充后返回的记录，无需自己构建树。
<AuditOperationDetail items={operationRecords} />;

结构契约与后端一致：operationId 独立定位操作，parentOperationId 关联上级，rootOperationId 标识整次操作；objects[].properties 可递归包含 VALUE、OBJECT、COLLECTION。集合的 items[].key 为元素稳定键，properties 可继续递归；下标仅描述移动位置。值状态为 VALUE（允许 null）、ABSENT、UNKNOWN。

AuditExamplePage 是独立的订单静态示例组件。它不代表本仓库存在订单业务、库存规则或这些业务 API，只用于呈现审计结构。

示例操作树为“调整订单” → “调整订单明细” → “调整明细分批计划”，另包含“调整库存预留”“发送订单调整通知”和 JOB 来源的“复核订单汇总”。每项变化只记录在直接负责它的节点中：

• 根操作的 Order 记录订单备注及订单金额变化；附件集合另演示不修改内容的独立排序移动。
• 明细操作的 Order.details 以 detailId 定位，展示数量及单价修改、新增明细、删除明细完整快照。示例从 139.40 调整到 153.80：商品 A 的数量 2 → 4、单价 19.80 → 18.50，删除商品 B（数量 2、单价 49.90），新增商品 C（数量 3、单价 26.60）。
• 分批计划操作沿 Order.details[detailId].batches[batchId].allocations[allocationId] 展开三层集合，各层按稳定键定位，不使用数组下标识别元素。分批计划展示新增、删除和修改；修改批次时同时调整位置，页面在同一元素条目中展示属性对比和前后索引。独立排序移动由订单附件集合演示。
• 库存预留操作记录两个独立 StockReservation 对象，通过 owners 保存订单和明细的定位链；这些归属关系不会被显示为操作嵌套。
• 通知失败独立呈现执行失败与回滚；订单根操作仍可以执行成功。汇总任务的提交状态为未知，页面不会把执行成功当作数据已提交。

示例只读取本地数据，不访问真实 API，也不进入正式日志列表或注册正式路由。可用它检验列表 → 抽屉、操作树选择、对象筛选和集合展开。

构建与验证

cd frontend
pnpm --filter @qiqb/audit-domain lint
pnpm --filter @qiqb/audit-domain build
pnpm --filter @qiqb/audit-domain test:routes
pnpm --filter @qiqb/audit-domain test:runtime
pnpm --filter @qiqb/audit-domain test:display

# 从实际 React/Ant Design 组件生成无外部请求的自包含交互 HTML。
pnpm --filter @qiqb/audit-domain preview:example /absolute/path/audit-example.html
# 精简详情预览保留操作树、对象筛选、集合展开；不包含列表和抽屉。
pnpm --filter @qiqb/audit-domain preview:example /absolute/path/audit-detail.html --detail-only

预览复用 workspace 已安装的 esbuild，输出 SSR 首屏及同一真实组件的浏览器交互。test:display 检查树组装、异常关系保留、递归统计和真实组件 SSR 内容；它不代替浏览器中的交互与视觉检查。

构建输出 ESM JavaScript、TypeScript 声明、LESS 和独立路由 CJS；宿主使用已有 LESS loader。生产依赖由 React、React DOM、Ant Design 和 @ant-design/pro-components peerDependencies 提供；开发版本沿用消息及平台领域的 3.1.12-0。