# 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 个 |

## 验收标准对照

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


## Session 3: 积分重注册余额恢复验证

**Date**: 2026-04-13
**Task**: 积分重注册余额恢复验证

### Summary

完成 register_bonus_claims 快照方案的本地迁移与集成测试验证，确认删除账号后重注册可恢复删除前积分余额。

### Main Changes

| Feature | Description |
|---------|-------------|
| DB Migration | 通过 `dev-migrate.sh migrate` 应用 `20260413_0004_register_bonus_claims_snapshot`，新增 `first_user_id_snapshot` 与 `balance_snapshot`，移除 `first_user_id`。 |
| Restore Logic | 注册流程优先读取 `balance_snapshot` 恢复余额；删除账号前写入当前余额快照。 |
| Integration Tests | 新增未消费删号重注册恢复场景，并更新已有消费后删号重注册断言。 |

**Updated Files**:
- `backend/alembic/versions/20260413_0004_register_bonus_claims_snapshot.py`
- `backend/src/models/register_bonus_claims.py`
- `backend/src/v1/points/repository.py`
- `backend/src/v1/points/service.py`
- `backend/src/v1/users/service.py`
- `backend/tests/integration/test_register_run_delete_reregister.py`
- `backend/tests/unit/test_points_service_audit.py`
- `docs/protocols/common/user-points-chat-data-protocol.md`

**Verification**:
- `uv run pytest backend/tests/unit/test_points_service_audit.py` -> 5 passed
- `uv run pytest backend/tests/integration/test_register_run_delete_reregister.py` -> 2 passed
- Supabase MCP 查询确认 `register_bonus_claims.balance_snapshot` 已写入并与测试行为一致。


### Git Commits

(No commits - planning session)

### Testing

- [OK] (Add test results)

### Status

[OK] **Completed**

### Next Steps

- None - task complete


## Session 4: 绑定积分重注册余额恢复提交

**Date**: 2026-04-13
**Task**: 绑定积分重注册余额恢复提交

### Summary

将删除账号后重注册积分余额恢复 feature 的代码提交与 session 记录绑定。

### Main Changes

| Item | Details |
|------|---------|
| Feature Commit | `c55be6d` |
| Scope | register_bonus_claims 快照字段、删号前余额快照、重注册余额恢复、相关测试与协议更新 |

**Validation**:
- pre-commit hooks passed during commit
- integration: `backend/tests/integration/test_register_run_delete_reregister.py` passed (`2 passed`)


### Git Commits

| Hash | Message |
|------|---------|
| `c55be6d` | (see git log) |

### Testing

- [OK] (Add test results)

### Status

[OK] **Completed**

### Next Steps

- None - task complete


## Session 5: feat: 邀请码显示功能 - 后端API + 前端对接

**Date**: 2026-04-13
**Task**: feat: 邀请码显示功能 - 后端API + 前端对接

### Summary

(Add summary)

### Main Changes

## Backend 新增 (src/v1/invite/)

| 文件 | 描述 |
|------|------|
| schemas.py | `MyInviteCodeResponse` (code, used_count) |
| repository.py | `InviteCodeRepository.get_by_owner_id()` |
| service.py | `InviteCodeService.get_my_invite_code()` |
| dependencies.py | 依赖注入 |
| router.py | `GET /api/v1/invite/me` |

修改: `src/v1/router.py` - 注册 invite_router

## Frontend 新增/修改 (apps/lib/features/settings/)

新增:
- `data/models/my_invite_code.dart` - `MyInviteCode` 数据模型
- `data/apis/invite_api.dart` - API 调用
- `data/repositories/invite_repository.dart` - Repository 封装

修改:
- `invite_screen.dart` - 移除 mock 数据，改为调用真实 API，增加 loading/error 状态
- `settings_screen.dart` - 接收 `InviteRepository` 参数
- `home_screen.dart` - 创建并传递 `InviteRepository` 实例

**验证**: ruff check ✅ / flutter analyze ✅


### Git Commits

(No commits - planning session)

### Testing

- [OK] (Add test results)

### Status

[OK] **Completed**

### Next Steps

- None - task complete