概述
ChangeLog 是共享的审计/活动时间线 UI。用 pluginName + reference.prefix + reference.number 限定范围。
- 从 @quan-erp/base-frontend 导入
- prefix — 实体种类（SO、EMP 等）
- number — 记录 id 字符串
- 后端需调用 ChangeLogService.addChangeLog
1. ChangeLog 组件
在详情页放置 <ChangeLog pluginName reference />。
- pluginName 必须与后端写入一致
- reference.number 使用 String(id)
TSXdetail page
1import { ChangeLog } from "@quan-erp/base-frontend";
2import metadata from "../../../module.metadata.json" with { type: "json" };
3
4export function SalesOrderDetail({ id }: { id: number }) {
5 return (
6 <ChangeLog
7 pluginName={metadata.name}
8 reference={{ prefix: "SO", number: String(id) }}
9 />
10 );
11}2. 查询与变更 hooks
Use these when you need a custom feed UI instead of the stock ChangeLog component.
- useChangeLogQuery — 分页列表
- useInfiniteChangeLog — 无限滚动
- useReactChangeLogQuery / useRemoveReactChangeLogQuery — 反应
- clearChangeLogCache — 缓存失效
TSXcustom query
1import {
2 useChangeLogQuery,
3 useReactChangeLogQuery,
4 clearChangeLogCache,
5} from "@quan-erp/base-frontend";
6
7const { data: logs = [] } = useChangeLogQuery({
8 pluginName: metadata.name,
9 referencePrefix: "SO",
10 referenceNumber: String(orderId),
11 currentPage: 1,
12 pageSize: 20,
13});
14
15const react = useReactChangeLogQuery();
16await react.mutateAsync({
17 reaction: "👍",
18 reactBy: currentUserId,
19 changeLogId: logs[0].id,
20});
21
22clearChangeLogCache({
23 pluginName: metadata.name,
24 reference: { prefix: "SO", number: String(orderId) },
25});3. 结果结构
GetChangeLogDto / ChangeLogReaction。
TSGetChangeLogDto (shape)
1interface GetChangeLogDto {
2 id: number;
3 message: string;
4 createdBy: UserDto;
5 isCreatedBySystem: boolean;
6 pluginName: string;
7 referencePrefix: string;
8 referenceNumber: string;
9 createDate: string;
10 reactions: ChangeLogReaction[];
11}
12
13interface ChangeLogReaction {
14 id: number;
15 reaction: string;
16 reactBy: UserDto;
17}4. 与后端对齐
UI 只显示 ChangeLogService 已写入的内容 — prefix/number/pluginName 必须一致。
- See Documentation → Backend → Builtin Services → ChangeLogService
- Mismatch in prefix/number/pluginName = empty feed
- After server-side writes from another client, clearChangeLogCache if you keep a long-lived view open
关键规则
- 从 @quan-erp/base-frontend 导入
- 前后端 reference 必须一致
- number 必须是字符串
- 标准时间线优先用 <ChangeLog />
检查清单
- Backend addChangeLog on the relevant mutations
- Detail page renders <ChangeLog pluginName reference />
- prefix/number match backend writes
- Optional: reactions via useReactChangeLogQuery
- Verify feed after create/update in the ERP UI
常见失败
- 空列表 — 未写入或 reference 不匹配
- 导入错误 — 从 shared-ui 查找
- 陈旧数据 — 未 clearChangeLogCache
- 反应失败 — DTO / 权限错误