ai-contract-platform/project-docs/V2-notification-center-2026-06-25.md

AI 合同平台 V2 - 通知中心闭环记录

日期：2026-06-25

背景

对照《AI 合同平台 V2 重构版开发方案》Phase 5 企业协作闭环，本轮实现通知中心功能，为审批通知、审查完成通知和履约提醒提供统一入口。

目标

• 实现通知中心后端 API。
• 实现通知中心前端页面。
• 审批状态变更时自动创建通知。
• 支持通知筛选和标记已读。

已完成内容

后端 API

文件：

• yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/contracts.py
• yuqei-contract-platform/services/contract-api/src/yuqei_contract_api/main.py

新增模型：

• NotificationType: approval_pending, approval_approved, approval_rejected, review_completed, review_failed, obligation_due
• Notification: id, notification_type, title, summary, contract_id, contract_title, is_read, created_at
• NotificationPage: items, page, page_size, total, unread_count

新增接口：

• GET /api/v1/notifications: 通知列表，支持 type 和 is_read 筛选
• PATCH /api/v1/notifications/{id}/read: 标记单条已读
• POST /api/v1/notifications/mark-all-read: 全部标记已读

自动通知创建：

• 提交审批 → approval_pending
• 审批通过 → approval_approved
• 审批退回 → approval_rejected
• 退回后重新提交 → approval_pending

前端页面

文件：

• yuqei-contract-platform/apps/contract-web/src/app/notifications/page.tsx
• yuqei-contract-platform/apps/contract-web/src/services/contracts.ts
• yuqei-contract-platform/apps/contract-web/src/components/app-shell.tsx
• yuqei-contract-platform/apps/contract-web/src/app/globals.css

新增路由：

• /notifications: 通知中心列表页

新增 API 代理：

• /api/contract-platform/notifications
• /api/contract-platform/notifications/[id]/read
• /api/contract-platform/notifications/mark-all-read

功能点：

• 通知列表展示，区分已读/未读
• 按类型筛选（审批、审查、履约）
• 按状态筛选（全部、未读、已读）
• 未读数量统计
• 一键全部已读
• 从通知直达关联合同详情
• 侧边栏增加通知中心入口

视觉设计：

• 不同通知类型采用不同颜色图标
• 未读通知带高亮标识
• 通知卡片展示：类型标签、标题、摘要、时间、关联链接

验证结果

后端测试：

python -m pytest yuqei-contract-platform/services/contract-api/tests -q

结果：25 passed

前端构建：

npm --prefix yuqei-contract-platform/apps/contract-web run typecheck
npm --prefix yuqei-contract-platform/apps/contract-web run build

结果：通过，新增 /notifications 路由

当前闭环

现在通知流程为：

1. 业务用户提交审批 → 系统创建"待审批"通知。
2. 审批人打开通知中心看到新通知。
3. 审批人点击通知进入合同详情处理审批。
4. 审批通过/退回 → 系统创建结果通知。
5. 业务用户在通知中心看到审批结果。
6. 用户可标记已读或一键全部已读。

这符合 V2 方案中"通知中心统一入口"的目标。

后续建议

1. 履约提醒真实数据: 当前履约提醒仅有通知类型定义，需要真实的履约任务模型和定时任务。
2. 实时推送: 当前通知需要刷新页面查看，可考虑 WebSocket 或轮询实现实时推送。
3. 通知偏好设置: 允许用户选择接收哪些类型的通知。