目录

文档是企业智能知识库系统的核心功能之一,今天这篇文章,主要给大家介绍一下文档的生命周期和审核闭环。

1. 一条完整链路走完发生了什么

在进入细节之前,先看一个完整的审核闭环:

图片.png

这条链路涉及 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 状态转换图

图片.png

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 完整执行流程

图片.png

源码参考:

  • 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 审核执行流程

图片.png

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.java
  • kb-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 完整事件流

图片.png

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.java
  • kb-foundation/src/main/java/com/knowledge/base/foundation/websocket/WebSocketHandshakeInterceptor.java
  • kb-foundation/src/main/java/com/knowledge/base/foundation/websocket/WebSocketAuthInterceptor.java
  • kb-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 审核历史

图片.png

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 审核员端:通知 + 工作台

审核员通过两种方式获知新审核任务:

  1. WebSocket 实时通知:前端订阅 /user/queue/notifications(个人)和 /topic/reviewers(广播),审核事件触发时即时弹窗
  2. "待审核"侧边栏入口:链接到 /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.tsx
  • src/pages/DraftsPage.tsx
  • src/pages/DocumentReviewWorkspacePage.tsx
  • src/pages/admin/ReviewPage.tsx
  • src/services/review.service.ts
  • src/services/websocket.service.ts
  • src/utils/permission.ts

总结

  1. 事件驱动的审核通知闭环:kb-document 只负责发事件,kb-foundation 负责消费和推送。两个服务的数据库和代码完全解耦,审核逻辑不感知通知的实现细节。
  2. DB + WebSocket 双通道通知:persistAndPush() 的设计确保通知不会丢失——在线用户即时收到 WebSocket 推送,离线用户登录后从数据库读取历史通知。
  3. 自愈机制:syncOrphanedPendingDocuments() 是典型的"宁可事后修复,不让用户感知异常"思路。这种防御性编程在微服务架构中尤为重要。
  4. 审核开关设计:system.requireApproval 配置项让审核流程可以在不停服的情况下开启/关闭,方便测试环境和非审核场景的使用。
  5. 审核轮次追踪:review_round + beforeStatus 快照提供了完整的审核历史追溯能力,满足企业级审计需求。
  6. 审核员降级策略:当系统中没有 ROLE_REVIEWER 角色的用户时,自动降级通知管理员,避免审核任务无人处理。
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏