eryao/.trellis/workspace/zl-q/journal-1.md

Journal - zl-q (Part 1)

AI development session journal Started: 2026-04-10

---

Session 1: 实现站内通知系统

Date: 2026-04-10 Task: 实现站内通知系统

Summary

(Add summary)

Main Changes

完成内容

模块	描述
协议文档	docs/protocols/notification/notification-inbox-protocol.md 及 http-error-codes.md 新增 NOTIFICATION_NOT_FOUND
数据库迁移	notifications + user_notifications 两张表, RLS 策略, 索引
后端 ORM	Notification(TimestampMixin, SoftDeleteMixin, Base) + UserNotification(TimestampMixin, Base)
后端 API	schema/repository/service/router 全套, 4 个端点 (列表/未读数/单条已读/全部已读)
后端测试	19 个单元测试覆盖: 列表权限隔离, 未读数统计, 幂等已读, 越权拒绝, 撤销/删除过滤, payload 解析
Flutter models	NotificationPayload sealed class (none/open_route/open_url) + NotificationItem + NotificationListResult
Flutter API	NotificationApi (list/unreadCount/markRead/markAllRead)
Flutter Repository	抽象接口 + NotificationRepositoryImpl
Flutter Bloc	NotificationBloc (ChangeNotifier) 含 Realtime 事件处理
Flutter UI	NotificationCenterScreen + NotificationListItem + 首页 badge 集成
Flutter 测试	14 个测试: payload 解析 6 个 + bloc 状态管理 8 个

验收标准对照

• 能为指定用户写入一条站内通知 (ORM + migration 就绪)
• 用户能看到自己的通知列表 (GET /notifications)
• 用户点击通知后可标记为已读 (PATCH /notifications/{id}/read)
• "全部已读"后未读数归零 (PATCH /notifications/mark-all-read)
• 用户 A 不能读取或修改用户 B 的通知 (service 层 user_id 来自 JWT, 测试覆盖)
• 已读接口重复调用不会报错 (幂等实现, 测试覆盖)
• 首页 badge 会随未读数自动更新 (NotificationBloc + ListenableBuilder)
• 撤销或统一删除主通知后, 用户侧列表不再展示 (repository 过滤 status+deleted_at)

Git Commits

Hash	Message
3f3d613	(see git log)

Testing

• [OK] (Add test results)

Status

[OK] Completed

Next Steps

• None - task complete

Session 2: 静态通知同步 + 积分审计 bug 修复

Date: 2026-04-10 Task: 静态通知同步 + 积分审计 bug 修复

Summary

(Add summary)

Main Changes

完成内容

功能	说明
静态通知 Pydantic Schema	static_schema.py — 含 deleted 字段支持显式软删除
静态通知同步逻辑	static_sync.py — 创建、更新、撤销、软删除、prune、reconcile-targets
CLI 命令	sync-notifications 支持 --path/--source-key/--dry-run/--prune/--reconcile-targets
数据库迁移	新增 source/source_key/source_version/content_hash 字段
示例通知	welcome_points.yaml
触发脚本	infra/scripts/register-notifications.sh
协议文档	static-notification-sync-protocol.md
Bug 修复	AuditLedgerMetadata 未序列化直接写 JSONB → .model_dump(mode="json")
单测	28 passed（test_static_notification_sync.py、test_notification_service.py）
冒烟验证	注册→通知→未读数→reconcile-targets→prune 全链路通过

未完成:

• notification_updated Realtime 事件链路
• Flutter 端通知中心页面、badge、Realtime 订阅

新增文件:

• backend/src/core/config/notification/__init__.py
• backend/src/core/config/notification/static_schema.py
• backend/src/core/config/notification/static_sync.py
• backend/src/core/config/static/notification/notifications/welcome_points.yaml
• backend/alembic/versions/20260411_0005_add_notification_static_sync_fields.py
• backend/tests/unit/test_static_notification_sync.py
• docs/protocols/notification/static-notification-sync-protocol.md
• infra/scripts/register-notifications.sh

修改文件:

• backend/src/core/runtime/cli.py
• backend/src/models/notification.py
• backend/src/v1/points/repository.py
• docs/plans/static-notification-sync-plan.md

Git Commits

Hash	Message
3f3d613	(see git log)

Testing

• [OK] (Add test results)

Status

[OK] Completed

Next Steps

• None - task complete