目录
文档是企业智能知识库系统的核心功能之一,今天这篇文章,主要给大家介绍一下文档的生命周期和审核闭环。
1. 一条完整链路走完发生了什么
在进入细节之前,先看一个完整的审核闭环:

这条链路涉及 2 个微服务(kb-document、kb-foundation)、1 种消息中间件(RabbitMQ)、1 种实时通信协议(WebSocket STOMP),以及 4 张数据库表(kb_document、tb_document_review、kb_notification、kb_system_config)。
下面逐层拆解。
2. 文档状态机:4 种状态与 3 次关键转换
2.1 状态定义
文档存在 4 种生命周期状态,定义在 DocumentStatus 枚举中:
// kb-common/src/main/java/com/knowledge/base/common/enums/DocumentStatus.java
public enum DocumentStatus {
DRAFT(0, "草稿"),
PUBLISHED(1, "已发布"),
ARCHIVED(2, "已归档"),
PENDING_REVIEW(3, "待审核");
}关键设计点:Document 实体的 Javadoc 注释写的是 0-草稿, 1-已发布, 2-已归档,未提及状态 3。这是因为 PENDING_REVIEW(3) 是审核流程引入后才加入的枚举值,实体注释未同步更新。代码中 submitForReview() 和 updateDocument() 都完整支持状态 3 的写入和判断。
2.2 状态转换图

3 次关键转换:
| 转换 | 触发方法 | 前置状态 | 后置状态 | 副作用 |
|---|---|---|---|---|
| 提交审核 | submitForReview() | DRAFT(0) 或 PUBLISHED(1) | PENDING\_REVIEW(3) | 创建审核记录、发送 SUBMITTED 事件 |
| 审核通过 | approveReview() | PENDING\_REVIEW(3) | PUBLISHED(1) | 同步 RAG 索引、KAG 图谱、ES 搜索索引 |
| 审核驳回 | rejectReview() | PENDING\_REVIEW(3) | DRAFT(0) | 记录驳回原因、通知作者 |
被拒绝进入的状态:从 PENDING_REVIEW 可以直接回到 PUBLISHED,也可以直接进入 ARCHIVED(归档)——但这不是审核流程的一部分,而是独立的管理操作。
3. 提交审核:不做"先斩后奏"的审核流程
3.1 入口:两条路径汇聚到同一个方法
提交审核有两条入口路径,最终都汇聚到 DocumentReviewServiceImpl.submitForReview():
路径 1 — 显式提审接口:
POST /api/document/review/submit/{documentId}
→ DocumentReviewController.submitForReview()
→ DocumentReviewServiceImpl.submitForReview()路径 2 — 编辑时直接提审:
PUT /api/document/documents/{id}
→ DocumentServiceImpl.updateDocument()
→ 检测到 status 变为 PENDING_REVIEW(3)
→ DocumentReviewServiceImpl.submitForReview()两条路径的权限要求不同:显式接口需要 document:edit 或 document:review;编辑提审需要 document:edit。
3.2 submitForReview 完整执行流程

源码参考:
kb-document/src/main/java/com/knowledge/base/document/service/impl/DocumentReviewServiceImpl.java:83-160
3.3 审核开关:一键关闭审核流程
系统通过 Redis 缓存中的 system.requireApproval 配置项控制是否启用审核流程:
// DocumentReviewServiceImpl.java:617-620
private boolean checkRequireApproval() {
String value = systemConfigCache.getConfig("system.requireApproval");
return !"false".equals(value);
}当值为 "false" 时,submitForReview() 直接调用 directPublishDocument(),跳过审核流程:
// directPublishDocument:跳过审核,直接发布
document.setStatus(DocumentStatus.PUBLISHED.getCode()); // status = 1
document.setPublishTime(LocalDateTime.now());
documentMapper.updateById(document);
// 异步触发 RAG 索引、KAG 图谱构建、ES 同步这个设计的实际价值:在内部测试环境或非正式部署场景下,可以关闭审核流程降低操作成本。配置存储在 kb_system_config 表,通过 SystemConfigCache 读取 Redis Hash kb:system:config,默认为 "true"。
4. 审核执行:单条与批量的统一处理路径
4.1 审核执行流程

4.2 审核通过的关键副作用
审核通过后的副作用不仅限于状态变更,还包括 3 个异步索引操作:
| 操作 | 目标 | 说明 |
|---|---|---|
| RAG 索引同步 | Elasticsearch | 对文档内容重新分块、Embedding 向量化,更新向量索引 |
| KAG 图谱构建 | Neo4j | 提取文档中的实体和关系,更新知识图谱 |
| ES 搜索索引同步 | Elasticsearch | 更新全文检索索引,使新文档可被搜索 |
这三个操作是异步执行的,失败不会回滚审核状态——这是有意为之的设计取舍:审核通过是"人的决策",不应因机器索引失败而撤销。
4.3 驳回必须填写原因
驳回时 reviewComment 为必填项,这是业务约束而非数据库约束:
// DocumentReviewServiceImpl.java:237-250
if (dto.getReviewComment() == null || dto.getReviewComment().trim().isEmpty()) {
throw new BusinessException("驳回时必须填写审核意见");
}驳回后文档状态还原为 DRAFT(0),作者可在"我的文档 → 不通过"标签页中查看驳回原因并修改后重新提交。
4.4 批量审核
批量审核通过 POST /review/tasks/batch-review 接口实现:
// DocumentReviewServiceImpl.java:469-488
public void batchReview(List<Long> taskIds, String status, String comment) {
for (Long taskId : taskIds) {
DocumentReviewDTO dto = new DocumentReviewDTO();
dto.setReviewId(taskId);
dto.setReviewResult("approved".equalsIgnoreCase(status) ? 1 : 2);
dto.setReviewComment(comment);
if ("approved".equalsIgnoreCase(status)) {
approveReview(dto);
} else {
rejectReview(dto);
}
}
}注意:批量审核是循环单条执行,没有使用批量 SQL 或事务包裹。这意味着:如果第 5 条失败,前 4 条已经生效且不会回滚。这是一个可以接受的简化——实际业务中批量审核失败的概率很低,且每条都有独立的幂等性保护(检查 reviewResult == null)。
4.5 审核任务查询
审核员通过 GET /review/tasks 获取审核任务列表,支持多维度筛选:
// DocumentReviewController.java:54-66
@GetMapping("/tasks")
@PreAuthorize("hasAnyAuthority(..., T(...).DOCUMENT_REVIEW, T(...).DOCUMENT_LIST)")
public Result<PageResult<DocumentReviewVO>> getReviewTasks(
@RequestParam(required = false) String status, // pending/approved/rejected
@RequestParam(required = false, defaultValue = "1") Integer page,
@RequestParam(required = false, defaultValue = "10") Integer pageSize,
@RequestParam(required = false) String keyword, // 文档标题模糊搜索
@RequestParam(required = false) Long authorId) // 按作者筛选状态映射在 Controller 层完成:pending → 0, approved → 1, rejected → 2。
源码参考:
kb-document/src/main/java/com/knowledge/base/document/controller/DocumentReviewController.javakb-document/src/main/java/com/knowledge/base/document/service/impl/DocumentReviewServiceImpl.java:162-309
5. 事件驱动通知闭环:从 RabbitMQ 到 WebSocket 的完整链路
5.1 事件模型
审核通知使用 ReviewEventDTO 在 kb-document(事件生产者)和 kb-foundation(事件消费者)之间传递:
// kb-common/src/main/java/com/knowledge/base/common/event/ReviewEventDTO.java
@Data @Builder
public class ReviewEventDTO implements Serializable {
private String eventType; // SUBMITTED / APPROVED / REJECTED
private Long documentId;
private String documentTitle;
private Long authorId;
private String authorName;
private Long reviewerId;
private String reviewerName;
private Integer reviewRound;
private Integer reviewLevel;
private String reviewComment; // 驳回时必填
private LocalDateTime timestamp;
}三种事件类型对应不同的通知目标:
| eventType | 触发时机 | 通知对象 | 通知内容 |
|---|---|---|---|
SUBMITTED | 提交审核 | 所有 ROLE\_REVIEWER 用户 | "有新文档待审核:{标题}" |
APPROVED | 审核通过 | 文档作者 | "文档审核通过:{标题}" |
REJECTED | 审核驳回 | 文档作者 | "文档审核驳回:{标题},原因:{comment}" |
5.2 完整事件流

5.3 消费者:ReviewNotificationListener
消费者在 kb-foundation 中,监听队列 kb.notification.review.queue:
// kb-foundation/src/main/java/com/knowledge/base/foundation/mq/ReviewNotificationListener.java
@RabbitListener(queues = "kb.notification.review.queue")
public void handleReviewEvent(ReviewEventDTO event) {
switch (event.getEventType()) {
case "SUBMITTED" -> handleSubmitted(event);
case "APPROVED" -> handleApproved(event);
case "REJECTED" -> handleRejected(event);
}
}SUBMITTED 处理的核心逻辑——审核员查找与降级:
// 查询所有 ROLE_REVIEWER 角色用户
Result<List<Long>> result = userAuthFeignClient.getUserIdsByRole("ROLE_REVIEWER");
List<Long> reviewerIds = (result != null && result.isSuccess()) ? result.getData() : Collections.emptyList();
// 降级:无审核员时通知管理员
if (reviewerIds == null || reviewerIds.isEmpty()) {
Result<List<Long>> adminResult = userAuthFeignClient.getUserIdsByRole("ROLE_ADMIN");
reviewerIds = (adminResult != null && adminResult.isSuccess()) ? adminResult.getData() : Collections.emptyList();
}
// 逐个推送 + 广播
for (Long reviewerId : reviewerIds) {
persistAndPush(reviewerId, "review", "新文档待审核",
"文档《" + event.getDocumentTitle() + "》已提交审核",
"/review/documents/" + event.getDocumentId(), event.getDocumentId());
}
// 广播到审核员公共频道
messagingTemplate.convertAndSend("/topic/reviewers", payload);5.4 持久化 + 实时推送双通道
每条通知都走 persistAndPush() 方法,确保 **DB 持久化** 和 **WebSocket 实时推送** 双通道送达:
private void persistAndPush(Long userId, String type, String title,
String content, String link, Long documentId) {
// 1. DB 持久化(离线用户也能在登录后看到)
NotificationDTO dto = new NotificationDTO();
dto.setUserId(userId);
dto.setNotificationType(type);
dto.setTitle(title);
dto.setContent(content);
dto.setLink(link);
dto.setRelatedType("document");
dto.setRelatedId(documentId);
notificationService.sendNotification(dto);
// 2. WebSocket 实时推送(在线用户即时收到)
if (!isWebSocketEnabled()) return;
Map<String, Object> payload = new LinkedHashMap<>();
payload.put("notificationType", type);
payload.put("title", title);
payload.put("content", content);
payload.put("link", link);
payload.put("documentId", documentId);
messagingTemplate.convertAndSendToUser(
String.valueOf(userId), "/queue/notifications", payload);
}WebSocket 可配置关闭:通过 systemConfigCache.getConfig("websocket.enabled") 控制,当值不为 "true" 时只持久化 DB 不推送 WebSocket。
5.5 WebSocket 基础设施
WebSocket 基于 STOMP over SockJS,端点 /ws/notification:
WebSocket 连接流程:
1. 客户端发起 SockJS 连接 → /ws/notification?token=<jwt>
2. WebSocketHandshakeInterceptor 从 query param 提取 JWT 并验证
3. CustomHandshakeHandler 将 Principal 设置到 WebSocket Session
4. 客户端发送 STOMP CONNECT 帧(带 Authorization: Bearer <token> header)
5. WebSocketAuthInterceptor 拦截 CONNECT 帧,二次验证 JWT
6. 客户端订阅:
- /user/queue/notifications (个人通知,点对点)
- /topic/reviewers (审核员广播,公共频道)双重鉴权:握手阶段(URL token)和 STOMP CONNECT 阶段(Header token)都进行 JWT 验证,确保 WebSocket 连接的安全性。
源码参考:
kb-foundation/src/main/java/com/knowledge/base/foundation/websocket/WebSocketConfig.javakb-foundation/src/main/java/com/knowledge/base/foundation/websocket/WebSocketHandshakeInterceptor.javakb-foundation/src/main/java/com/knowledge/base/foundation/websocket/WebSocketAuthInterceptor.javakb-foundation/src/main/java/com/knowledge/base/foundation/mq/ReviewNotificationListener.java
6. 审核轮次机制:驳回后重提的设计
6.1 review\_round 自增逻辑
每次提交审核时,review_round 在当前文档的历史最大值基础上 +1:
// DocumentReviewServiceImpl.java:124-126
Integer maxRound = documentReviewMapper.selectMaxReviewRound(documentId);
int nextRound = (maxRound != null ? maxRound : 0) + 1;
review.setReviewRound(nextRound);对应的 SQL:
-- DocumentReviewMapper.xml
SELECT COALESCE(MAX(review_round), 0) FROM tb_document_review WHERE document_id = #{documentId}6.2 审核历史

beforeStatus 字段保存每次提交前的文档状态快照,用于驳回时还原:
review.setBeforeStatus(document.getStatus()); // 记录提交前的状态审核历史通过 GET /review/documents/{documentId}/history 查询,按 created_at 倒序返回该文档的所有审核记录。
6.3 reviewLevel 扩展预留
reviewLevel 字段当前固定为 1,注释为"一级审核"。这是为多级审核(如:一级审核员初审 → 二级管理员终审)预留的扩展点。当前系统只有一级审核,该字段暂时不影响任何业务逻辑。
7. 容错与自愈:孤立文档修复与配置降级
7.1 孤立 PENDING\_REVIEW 文档自动修复
这是一个值得注意的工程细节:getPendingReviews() 在每次查询审核任务前,会先执行 syncOrphanedPendingDocuments():
// DocumentReviewServiceImpl.java:315-359
private void syncOrphanedPendingDocuments() {
// 查询所有 status=PENDING_REVIEW 但没有对应审核记录的文档
List<Document> orphanedDocs = documentMapper.selectOrphanedPendingDocuments();
for (Document doc : orphanedDocs) {
// 自动创建审核记录
DocumentReview review = new DocumentReview();
review.setDocumentId(doc.getId());
review.setBeforeStatus(DocumentStatus.DRAFT.getCode());
review.setReviewRound(1);
review.setReviewLevel(1);
review.setReviewComment("系统自动修复:检测到文档状态为待审核但缺少审核记录");
documentReviewMapper.insert(review);
log.warn("修复孤立审核文档:documentId={}", doc.getId());
}
}触发场景:
- 数据库直接修改文档状态为 PENDING\_REVIEW,但未创建审核记录
- 审核记录被误删除
- 旧数据迁移后状态不一致
这个自愈机制确保审核任务列表不会"漏掉"任何待审核的文档。
7.2 审核员查找失败降级
当 ROLE_REVIEWER 角色下没有任何用户时,降级通知 ROLE_ADMIN:
if (reviewerIds == null || reviewerIds.isEmpty()) {
log.warn("未找到审核员角色用户,降级通知管理员");
reviewerIds = userAuthFeignClient.getUserIdsByRole("ROLE_ADMIN");
}7.3 Feign 调用熔断
UserAuthFeignClient 配置了 FallbackFactory,当 kb-user-auth 服务不可用时返回空列表,通知流程不会因 Feign 调用失败而抛出异常:
// kb-foundation/.../feign/UserAuthFeignFallbackFactory.java
public UserAuthFeignClient create(Throwable cause) {
return new UserAuthFeignClient() {
public Result<List<Long>> getUserIdsByRole(String roleCode) {
return Result.success(Collections.emptyList());
}
};
}7.4 审核开关配置降级
system.requireApproval 的查找走 SystemConfigCache,Cache 从 Redis Hash 读取。如果 Redis 不可用,Cache 层的默认值 "true" 确保审核流程不会被意外跳过。
8. 前端交互:从提审到审核的完整体验
8.1 作者端:提审入口
作者从三个页面可以提交审核:
| 页面 | 入口 | 交互方式 |
|---|---|---|
CreateDocumentPage | 新建文档后 | 保存选项切换为"提交审核",调用 reviewService.submitForReview() |
EditDocumentPage | 编辑已有文档后 | 同上 |
DraftsPage | 草稿箱 | 点击"提交审核"按钮,Popconfirm 二次确认后调用 documentService.publishDocument() |
// CreateDocumentPage.tsx - 创建并提审
const [saveOption, setSaveOption] = useState<'submit_review' | 'draft'>('submit_review');
// 保存后
await reviewService.submitForReview(result.id);
message.success('文档已提交审核!');// DraftsPage.tsx - 草稿箱提审
const handlePublish = async (draftId: string) => {
await documentService.publishDocument(draftId);
message.success('已提交审核');
};8.2 审核员端:通知 + 工作台
审核员通过两种方式获知新审核任务:
- WebSocket 实时通知:前端订阅
/user/queue/notifications(个人)和/topic/reviewers(广播),审核事件触发时即时弹窗 - "待审核"侧边栏入口:链接到
/admin/review,仅对审核员可见
// MainLayout.tsx - 审核通知类型映射
{
'review-submitted': { icon: <ClockCircleOutlined />, color: '#d97706' },
'review-approved': { icon: <CheckCircleOutlined />, color: '#059669' },
'review-rejected': { icon: <CloseCircleOutlined />, color: '#dc2626' },
}点击通知后跳转到 DocumentReviewWorkspacePage(/review/documents/:documentId),在新标签页中打开审核工作台。
8.3 审核工作台
DocumentReviewWorkspacePage 是审核员操作的核心页面,布局为左右分栏:
- 左栏:文档内容(
ReactMarkdown渲染完整 Markdown)+ 文档元信息(作者、分类、状态、更新时间) - 右栏:当前审核任务信息(轮次、提交时间)+ 审核操作按钮(通过/驳回)+ 审核历史时间线
驳回时弹出模态框,要求填写驳回原因(限制 500 字,实时显示字符数)。
// DocumentReviewWorkspacePage.tsx - 审核操作
const submitReview = async (status: 'approved' | 'rejected', comment?: string) => {
await reviewService.reviewDocument(pendingTask.id, { status, comment });
message.success(status === 'approved' ? '审核已通过' : '已驳回该文档');
};8.4 前端权限控制
审核相关操作的前端权限检查:
// 审核工作台 — 基于角色判断
const canReviewByRoles = (roles: string[]) =>
roles.some(role => {
const upperRole = role.toUpperCase();
return upperRole.includes('REVIEWER') || upperRole.includes('ADMIN');
});
// 路由守卫 — 基于权限码
<ProtectedRoute requireAdmin requiredPermissions={[PERMISSIONS.documentReview]}>前端权限码 document:review 对应后端的 DOCUMENT_REVIEW = "document:review" 常量。
源码参考:
src/pages/CreateDocumentPage.tsxsrc/pages/DraftsPage.tsxsrc/pages/DocumentReviewWorkspacePage.tsxsrc/pages/admin/ReviewPage.tsxsrc/services/review.service.tssrc/services/websocket.service.tssrc/utils/permission.ts
总结
- 事件驱动的审核通知闭环:
kb-document只负责发事件,kb-foundation负责消费和推送。两个服务的数据库和代码完全解耦,审核逻辑不感知通知的实现细节。 - DB + WebSocket 双通道通知:
persistAndPush()的设计确保通知不会丢失——在线用户即时收到 WebSocket 推送,离线用户登录后从数据库读取历史通知。 - 自愈机制:
syncOrphanedPendingDocuments()是典型的"宁可事后修复,不让用户感知异常"思路。这种防御性编程在微服务架构中尤为重要。 - 审核开关设计:
system.requireApproval配置项让审核流程可以在不停服的情况下开启/关闭,方便测试环境和非审核场景的使用。 - 审核轮次追踪:
review_round+beforeStatus快照提供了完整的审核历史追溯能力,满足企业级审计需求。 - 审核员降级策略:当系统中没有
ROLE_REVIEWER角色的用户时,自动降级通知管理员,避免审核任务无人处理。