Files

bruce 90144c42ac chore(feishu): 提交飞书接入文档和本地配置

2026-06-07 22:36:04 +08:00

19 KiB

Raw Blame History

飞书通知与问答接入详细设计

文档信息

项目	内容
需求分析文档	docs/1.需求分析/4.飞书通知与问答接入.md
功能设计文档	docs/2.功能设计/4.飞书通知与问答接入.md
数据库设计文档	docs/4.数据库设计/4.飞书通知与问答接入.md
所属模块	审核智能体 review_agent
设计日期	2026-06-07
设计版本	V1.0

一、实现目标

首期实现一个统一飞书通知能力，使自动汇总、法规核查、自动填表三个工作流在完成、部分成功或失败时，通过飞书官方智能体/应用机器人消息 API 向指定个人账号发送富文本私聊通知。通知失败不阻断主流程，发送结果落库并在批次详情页展示。

同时预留飞书私聊问答所需的用户映射、查询服务、权限过滤和问答日志模型，但不实现飞书事件订阅回调。

二、推荐文件结构

文件	类型	责任
`review_agent/models.py`	修改	新增 `FeishuUserMapping`、`WorkflowNotificationRecord`、`FeishuQuestionLog`
`review_agent/admin.py`	修改/新增	注册飞书用户映射和通知记录后台
`review_agent/notifications/__init__.py`	新增	通知模块包
`review_agent/notifications/context.py`	新增	定义统一通知上下文 dataclass
`review_agent/notifications/recipient.py`	新增	解析首期指定个人接收人；后续扩展为按系统用户映射解析
`review_agent/notifications/message_builder.py`	新增	构造飞书富文本 payload 和摘要
`review_agent/notifications/feishu_token.py`	新增	使用 App ID/App Secret 获取并缓存 tenant_access_token
`review_agent/notifications/feishu_message_api.py`	新增	调用飞书发送消息 API、处理响应解析
`review_agent/notifications/records.py`	新增	判重和通知记录落库
`review_agent/notifications/dispatcher.py`	新增	对外统一发送入口
`review_agent/notifications/workflow_adapters.py`	新增	三个工作流批次到通知上下文的适配
`review_agent/feishu_questions/query.py`	新增	后续问答预留：批次摘要查询
`review_agent/feishu_questions/permissions.py`	新增	后续问答预留：权限过滤
`tests/test_feishu_notification.py`	新增	飞书通知单元测试
`tests/test_feishu_question_reserved.py`	新增	问答预留服务测试

三、数据结构设计

3.1 NotificationContext

from dataclasses import dataclass, field
from typing import Any


@dataclass(frozen=True)
class NotificationContext:
    workflow_type: str
    workflow_batch_id: int
    workflow_batch_no: str
    workflow_status: str
    title: str
    trigger_user_id: int
    trigger_username: str
    result_url: str
    summary_lines: list[str] = field(default_factory=list)
    next_action: str = ""
    metadata: dict[str, Any] = field(default_factory=dict)

    @property
    def dedupe_key(self) -> str:
        return f"{self.workflow_type}:{self.workflow_batch_id}:{self.workflow_status}"

3.2 ResolvedFeishuTarget

from dataclasses import dataclass


@dataclass(frozen=True)
class ResolvedFeishuTarget:
    mapping_id: int | None
    display_name: str
    identifier_type: str
    identifier_value: str
    masked_identifier: str
    missing: bool = False

identifier_type 取值：

值	说明
open_id	使用飞书 open_id
user_id	使用飞书 user_id
mobile	使用手机号，后续按发起人私聊时使用
missing	未配置映射

四、模型详细设计

4.1 FeishuUserMapping

字段见数据库设计。模型需提供方法：

def preferred_identifier(self) -> tuple[str, str]:
    if self.feishu_open_id:
        return "open_id", self.feishu_open_id
    if self.feishu_user_id:
        return "user_id", self.feishu_user_id
    if self.feishu_mobile:
        return "mobile", self.feishu_mobile
    return "missing", ""

clean() 校验：

def clean(self):
    if not (self.feishu_open_id or self.feishu_user_id or self.feishu_mobile):
        raise ValidationError("feishu_open_id、feishu_user_id、feishu_mobile 至少填写一个")

4.2 WorkflowNotificationRecord

字段见数据库设计。建议方法：

@classmethod
def already_sent(cls, dedupe_key: str) -> bool:
    return cls.objects.filter(dedupe_key=dedupe_key, send_status=cls.SendStatus.SUCCESS).exists()

注意：若使用唯一约束限制 dedupe_key，重复触发时可以直接返回已有记录；若希望保留 skipped_duplicate 记录，则不能对 dedupe_key 做全局唯一，只能用查询判重。本项目需求是“只发一次”，更推荐保留唯一成功意图，重复触发返回已有记录或创建 skipped 记录需在实现计划中二选一。为了 SQLite 简化，首期建议不创建 skipped 记录，直接返回已有成功记录。

五、核心服务详细设计

5.1 workflow_adapters.py

职责：把不同批次对象转换为 NotificationContext。

函数：

def build_file_summary_context(batch: FileSummaryBatch) -> NotificationContext: ...
def build_regulatory_review_context(batch: RegulatoryReviewBatch) -> NotificationContext: ...
def build_application_form_fill_context(batch: ApplicationFormFillBatch) -> NotificationContext: ...

自动汇总摘要：

字段	计算方式
文件总数	`batch.items.count()`
成功解析数	解析状态为 success 的 item 数
异常数	failed、skipped、unsupported 等状态数量
导出文件数	`ExportedSummaryFile` 中 workflow_type=file_summary 或 batch 关联文件数

法规核查摘要：

字段	计算方式
风险总数	`batch.issues.count()`
阻断项	severity=blocking
高风险	severity=high
中风险	severity=medium

自动填表摘要：

字段	计算方式
模板数	`len(batch.selected_templates)`
导出文件数	对应 `ExportedSummaryFile` 数量
冲突字段数	`len(batch.conflict_summary or [])`
失败原因	`batch.error_message` 或节点错误摘要

5.2 recipient.py

职责：首期根据环境变量解析指定个人接收人；后续可扩展为根据系统用户解析飞书目标。

伪代码：

def resolve_feishu_target(user: User) -> ResolvedFeishuTarget:
    if settings.FEISHU_DEFAULT_USER_OPEN_ID:
        return ResolvedFeishuTarget(
            mapping_id=None,
            display_name=getattr(settings, "FEISHU_DEFAULT_TARGET_NAME", "指定个人账号"),
            identifier_type="open_id",
            identifier_value=settings.FEISHU_DEFAULT_USER_OPEN_ID,
            masked_identifier=mask_identifier(settings.FEISHU_DEFAULT_USER_OPEN_ID),
            missing=False,
        )
    if settings.FEISHU_DEFAULT_USER_ID:
        return ResolvedFeishuTarget(
            mapping_id=None,
            display_name=getattr(settings, "FEISHU_DEFAULT_TARGET_NAME", "指定个人账号"),
            identifier_type="user_id",
            identifier_value=settings.FEISHU_DEFAULT_USER_ID,
            masked_identifier=mask_identifier(settings.FEISHU_DEFAULT_USER_ID),
            missing=False,
        )
    return ResolvedFeishuTarget(
        mapping_id=None,
        display_name=user.get_username(),
        identifier_type="missing",
        identifier_value="",
        masked_identifier="",
        missing=True,
    )


def resolve_feishu_target_by_user_mapping(user: User) -> ResolvedFeishuTarget:
    mapping = (
        FeishuUserMapping.objects
        .filter(system_user=user, is_active=True)
        .first()
    )
    if mapping is None:
        return ResolvedFeishuTarget(
            mapping_id=None,
            display_name=user.get_username(),
            identifier_type="missing",
            identifier_value="",
            masked_identifier="",
            missing=True,
        )
    identifier_type, identifier_value = mapping.preferred_identifier()
    return ResolvedFeishuTarget(
        mapping_id=mapping.pk,
        display_name=mapping.feishu_display_name or user.get_username(),
        identifier_type=identifier_type,
        identifier_value=identifier_value,
        masked_identifier=mask_identifier(identifier_value),
        missing=identifier_type == "missing",
    )

脱敏规则：

类型	规则
mobile	保留前三位和后四位，如 `138****1234`
open_id/user_id	保留前 6 位和后 4 位
missing	空字符串

首期调度器使用 resolve_feishu_target()。resolve_feishu_target_by_user_mapping() 作为后续“按发起人私聊”能力预留。

5.3 message_builder.py

职责：构造富文本 payload 和入库摘要。

函数：

def build_feishu_post_message(
    context: NotificationContext,
    target: ResolvedFeishuTarget,
) -> dict: ...

def build_message_summary(
    context: NotificationContext,
    target: ResolvedFeishuTarget,
) -> str: ...

富文本规则：

场景	规则
有映射	加入 `at` 标签
无映射	不加入 `at` 标签，增加映射缺失提示
失败状态	标题和下一步动作突出失败原因摘要
摘要过长	每条摘要最多 120 字，总摘要最多 800 字
链接	使用本地地址拼接，后续再切换域名配置

5.4 feishu_token.py

职责：使用 App ID/App Secret 获取并缓存 tenant_access_token。

函数：

def get_tenant_access_token() -> FeishuTokenResult: ...
def refresh_tenant_access_token() -> FeishuTokenResult: ...

结果结构：

@dataclass(frozen=True)
class FeishuTokenResult:
    ok: bool
    tenant_access_token: str
    expire_seconds: int
    code: str
    message: str

处理规则：

场景	处理
App ID/App Secret 缺失	返回 failed，错误码 config_missing
缓存 token 未过期	直接返回缓存 token
token 过期或不存在	调用飞书 token API 重新获取
token API 返回失败	返回 failed，记录 code/message
HTTP 超时	返回 failed，错误码 timeout

5.5 feishu_message_api.py

职责：调用飞书发送消息 API。

函数：

def send_personal_message(
    *,
    tenant_access_token: str,
    receive_id_type: str,
    receive_id: str,
    payload: dict,
) -> FeishuMessageApiResult: ...

结果结构：

@dataclass(frozen=True)
class FeishuMessageApiResult:
    ok: bool
    status_code: int | None
    code: str
    message: str
    duration_ms: int
    message_id: str = ""

异常处理：

异常	处理
指定接收人缺失	返回 failed，错误码 recipient_missing
tenant_access_token 缺失	返回 failed，错误码 token_missing
HTTP 超时	返回 failed，错误码 timeout
非 2xx	返回 failed，记录 status_code
飞书返回 code 非 0	返回 failed，记录 code/message
token 失效	刷新 token 后允许同步重试一次消息 API

5.6 records.py

职责：判重和落库。

流程：

输入 NotificationContext
-> 查询 dedupe_key 是否已有 success
-> 若有，返回已有记录，不发送
-> 若未启用真实飞书，创建 disabled/mock 记录
-> 若发送成功，创建 success 记录
-> 若发送失败，创建 failed 记录

字段写入规则：

字段	来源
workflow_type	context.workflow_type
workflow_batch_id	context.workflow_batch_id
workflow_batch_no	context.workflow_batch_no
workflow_status	context.workflow_status
dedupe_key	context.dedupe_key
trigger_user_id	context.trigger_user_id
feishu_mapping_id	target.mapping_id
at_identifier_type	target.identifier_type
at_identifier_masked	target.masked_identifier
message_summary	`build_message_summary()`

5.7 dispatcher.py

对外入口：

def dispatch_workflow_notification(context: NotificationContext) -> WorkflowNotificationRecord:
    if WorkflowNotificationRecord.already_sent(context.dedupe_key):
        return WorkflowNotificationRecord.objects.get(
            dedupe_key=context.dedupe_key,
            send_status=WorkflowNotificationRecord.SendStatus.SUCCESS,
        )

    user = User.objects.get(pk=context.trigger_user_id)
    target = resolve_feishu_target(user)
    message = build_feishu_post_message(context, target)
    summary = build_message_summary(context, target)

    if not settings.FEISHU_NOTIFY_ENABLED:
        return create_disabled_record(context, target, summary)

    token_result = get_tenant_access_token()
    if not token_result.ok:
        return create_failed_record(context, target, summary, token_result)

    result = send_personal_message(
        tenant_access_token=token_result.tenant_access_token,
        receive_id_type=target.identifier_type,
        receive_id=target.identifier_value,
        payload=message,
    )
    if result.ok:
        return create_success_record(context, target, summary, result)
    return create_failed_record(context, target, summary, result)

六、工作流接入点

工作流	推荐接入位置
自动汇总	文件汇总批次状态写为 success/partial_success/failed 后
法规核查	报告导出和风险项保存后；替换或并行现有 `create_mock_notifications`
自动填表	`notify` 节点中替换或扩展现有 `notify_completion`

接入原则：

原则	说明
通知异常捕获	工作流调用通知服务时捕获异常并记录 non_blocking_errors
不回滚业务结果	通知失败不修改业务批次成功状态
单点适配	工作流只负责生成或传入批次，摘要由 adapter 负责

七、批次详情展示设计

7.1 后端上下文

为批次详情页提供：

def get_notification_records(workflow_type: str, batch_id: int) -> QuerySet:
    return WorkflowNotificationRecord.objects.filter(
        workflow_type=workflow_type,
        workflow_batch_id=batch_id,
    ).order_by("-created_at")

7.2 页面展示规则

状态	展示
success	“飞书通知已发送”，展示 sent_at
failed	“飞书通知失败”，展示 error_message
disabled	“飞书通知未启用”
无记录	“暂无通知记录”

三个工作流结果页可复用同一 partial 模板或上下文字段。

八、问答预留详细设计

8.1 批次摘要查询服务

预留函数：

def query_batch_summary(
    user: User,
    *,
    workflow_type: str | None = None,
    batch_no: str | None = None,
    latest: bool = False,
) -> dict:
    ...

权限规则：

用户	可查范围
管理员	全部批次
普通用户	`batch.user == user` 的批次
未绑定用户	不可查

查询对象：

类型	说明
明确批次号	精确匹配 batch_no
最近/最新	在有权限范围内按 created_at/finished_at 倒序取第一条
工作流类型	file_summary、regulatory_review、application_form_fill

8.2 问答日志服务