3 Commits
3 changed files with 364 additions and 0 deletions

No files matched your search

+91
View File
@@ -0,0 +1,91 @@
# 2026-10-17 K7 首页轮播图 + 站内信通知
## 一、目标与边界
本批只完成 Flutter 客户端两项能力:
- K7-A:增强现有 `CoverCarousel`,继续使用 `feed.banners` 和 3D 翻转风格,
增加自动轮播、交互暂停、指示器、失败占位和语义。
- K7-B:新增匿名站内信分页页,接入 `GET /app/notices`,在我的页增加通知入口。
- K7-C:补轮播/通知/响应式与 locale 时间测试。
不做已读未读、红点、FCM、通知设置、`/app/config noticeEnabled`、首页铃铛、
新 banner 接口、后端、Web 或 specs 修改。
## 二、契约口径
### Banner
- 数据源:`GET /app/home/feed` / `GET /app/discover/feed` 的 `banners[]`。
- 无独立接口;空列表继续 `SizedBox.shrink()`。
- 点击继续沿用 `linkType=DRAMA` + `linkValue` 的现有 `onOpen`。
### Notices
- `GET /app/notices?pageIndex=1&pageSize=20`,匿名。
- 响应:`{total, list:[{id,title,content,type,publishAt,expireAt}]}`。
- ID 全部按字符串;`total` 是数字。
- `list.length` 用于判断当前页是否有数据;是否加载更多按
“已加载数量 < total”判断。
- `type` 原样展示,不建立客户端枚举映射。
## 三、预计影响文件
轮播:
- `lib/pages/discover/widgets/cover_carousel.dart`
- `lib/pages/discover/discover_view.dart`
- `lib/core/widgets/remote_image.dart`(可选失败图标参数)
- `test/discover/cover_carousel_test.dart`
通知:
- `lib/core/data/models/notice.dart`
- `lib/core/data/remote/notice_api.dart`
- `lib/core/data/repositories/notice_repository.dart`
- `lib/core/data/services/notices_controller.dart`
- `lib/pages/notices/notices_page.dart`
- `lib/pages/mine/mine_view.dart`
- `lib/app.dart`(NoticeRepository Provider)
- `test/notice/**`
- `lib/l10n/app_{en,zh,id}.arb` 与生成文件
## 四、实现口径
### 轮播
- `Timer.periodic` 4.5s;单张不创建定时器;`dispose` 取消。
- 使用 `TickerMode.of(context)`/`Visibility` 语义监听页面可见性;
不可见时取消,恢复时重新启动。
- pointer down 暂停,up/cancel 恢复;拖拽时沿用现有 3D 翻转。
- 指示器采用底部圆点,使用 `AppColors.onPrimary` + `muted` 低透明度。
- 语义标签进入三语 arb。
- 图片失败使用现有 `RemoteImage` 并显示图标占位。
### 通知
- `NoticesController` 管理首屏、分页、加载更多、刷新、错误。
- `NoticesPage` 深色页,保留 K5/K6 主题与 Haptics 不触发滑动振动。
- 列表项标题/类型/时间/两行摘要;点击打开详情 Dialog。
- 详情 `content` 用可滚动 `Text` 保留 `\n`,长内容不溢出。
- `publishAt` / `expireAt` 使用现有 `formatLocalizedDateTime`。
- 我的页 `_menuCard` 增加通知入口,匿名可进入。
## 五、TDD 顺序
1. 轮播:自动切页、单张无 Timer、指示器、触摸暂停、点击回调、失败占位。
2. 通知 API/model:分页字段、字符串 ID、时间解析。
3. Controller:首屏、追加、加载更多条件、空/失败/刷新。
4. NoticesPage:三态、列表、分页、详情、长内容、小屏。
5. 我的页入口与三语文案。
6. 门禁:`dart analyze lib test`、`flutter test`、
`flutter build apk --debug`。
## 六、风险与待确认
- 自动轮播 Timer 与 3D AnimationController 并存,需避免 dispose 后 setState。
- 页面用 `IndexedStack` 保持状态,需通过 `TickerMode` 判断真实可见性。
- `total` 可能在分页期间变化,以本次响应 total 与已加载数量比较。
- 详情长内容必须可滚动,避免小屏 overflow。
- `noticeEnabled` 属 `/app/config`,本批不接;通知入口暂时常驻,已登记后续。
- 无独立 banner 接口和已读接口,不自行扩展契约。
+200
View File
@@ -20,6 +20,206 @@
---
## [已处理·待用户验收] 2026-10-17 | K7 首页轮播图 + 站内信通知
**用户指令(2026-10-17)**:「现在做首页轮播图及站内信通知」。
> **依赖 K5/K6**:轮播与通知页的配色、控件、震动反馈沿用 K5 主题与 K6 `Haptics`。
> 接口只认 `FruitServer/docs/api-phase1.md` §1.3 / §1.9,**契约里没有的接口一律不许自造**。
### 〇、开工前必读
1. `AGENTS.md`、`CODING_STANDARDS.md`、`GIT_WORKFLOW.md`
2. `FruitServer/docs/api-phase1.md` §1.3(feed banners)/ §1.9.2(notices)
3. K5 主题 token、K6 `Haptics` 封装
4. 本 INBOX 条目
### 一、PM 已勘察的现状(实测)
- **轮播图已有基础实现**:发现页 `lib/pages/discover/discover_view.dart` 的 `_carousel` 使用 `lib/pages/discover/widgets/cover_carousel.dart`(3D 翻转风格,手动滑动)。
- 数据来自 `GET /app/discover/feed` 的 `banners[]`;**契约无独立 banner 接口**。
- 现状缺口:无自动轮播、无页码/圆点指示器、单张时无特殊处理、图片失败无占位。
- **站内信完全未接**:客户端没有 `notice_api` / 通知页;`GET /app/notices` 契约已实现。
- 契约:`GET /app/notices?pageIndex=1&pageSize=20`(匿名),返回 `{total, list:[{id,title,content,type,publishAt,expireAt}]}`,`pageSize` 最大 50,空数据返回 `total=0,list=[]`。
- 契约**没有已读/未读接口**,本批不做未读红点。
- 我的页菜单 `lib/pages/mine/mine_view.dart` 的 `_menuCard` 已有「观看历史 / 我的收藏 / 下载 / 设置」列表,可新增「通知」入口。
- 客户端尚未接 `GET /app/config`,本批**不接** `noticeEnabled` 开关(登记为后续项)。
### 二、本批范围(2 块 + 测试验收,按顺序做)
#### K7-A 首页轮播图增强
- 数据源保持不变:`feed.banners`,不新增接口、不改后端。
- 在现有 `CoverCarousel` 上做最小增强,**保留 3D 翻转风格**:
- 自动轮播:间隔 4.5s;用户拖拽/触摸期间暂停,松手后恢复;`items.length <= 1` 时不启动定时器;
- 页面不可见/组件 dispose 时取消定时器(避免后台耗电与 `setState after dispose`);
- 指示器:底部圆点或 `当前/总数`(二选一,克制);颜色用 K5 主题 token,未选中用 `muted` 低透明度;
- 图片加载失败显示占位底色 + 图标(复用 `RemoteImage` 的错误处理,不白屏);
- 点击行为沿用现有 `onOpen`(跳详情),不改变跳转逻辑;
- 无障碍:指示器与轮播容器提供语义标签(走 l10n)。
- `items` 为空时保持现状 `SizedBox.shrink()`,不占位。
#### K7-B 站内信通知
- 新增数据层:`notice.dart`(model)、`notice_api.dart`、`notice_repository.dart`、`notices_controller.dart`,ID 按字符串解析。
- 新增独立页 `lib/pages/notices/notices_page.dart`:
- 分页:首屏 `pageSize=20`,`list.length < total` 时展示「加载更多」并用 `pageIndex+1` 续拉;
- 三态:加载 / 空(「暂无通知」)/ 失败(可重试);支持下拉刷新;
- 列表项:标题、类型(`type` 原样展示或统一「公告」,不自造枚举映射)、`publishAt` 按 locale 格式化、内容摘要(最多 2 行);
- 点击打开详情弹窗(标题 + 发布时间 + 完整 `content`,保留换行);关闭按钮无障碍标签走 l10n。
- 入口:我的页 `_menuCard` 新增「通知」ListTile(图标 `notifications_none_rounded`,主题色),点击打开 `NoticesPage`;不新增首页铃铛,避免改首页信息架构。
- 匿名可访问,不要求登录;不做未读态、不做通知设置。
- 文案全部进 en/zh/id 三份 arb。
#### K7-C 测试与验收
- 轮播:`pump` 时间推进后自动切页、单张不启动定时器、指示器数量与当前页、触摸暂停、点击回调。
- 通知:首屏加载、分页追加、空态、失败重试、详情展示、时间格式化(id locale)。
- 深色主题、小屏、长标题/长内容不溢出。
- 真机验收由用户执行:轮播自动切换与指示器、通知列表/详情、三态与下拉刷新。
### 三、明确不做
- 不新增 banner 接口、不改 `/app/notices` 契约、不改后端/Web/specs。
- 不做已读/未读、通知红点、推送(FCM)、通知设置。
- 不接 `/app/config` 的 `noticeEnabled`(登记后续)。
- 不新增首页铃铛入口、不改首页信息架构。
### 四、规范约束
- 颜色只用 K5 token;震动仅用于关键操作(K6 `Haptics`),轮播滑动不加震动。
- 新增文案三语齐全;新文件首行 `// Author: fruit.com.cn`;public 类/方法文档注释;无 AI 痕迹。
- 代码规模红线:函数 ≤50 行、参数 ≤5、类 ≤300 行、单文件 ≤500 行、嵌套 ≤4 层、圈复杂度 ≤10。
### 五、门禁
1. `dart analyze lib test` 零告警;`flutter test` 全过。
2. `flutter build apk --debug` 通过。
3. 新增测试必须真红后绿;不得删改既有测试来「变绿」。
4. 真机/设备侧验证由用户执行(红线 7、10),回执给「用户可照做步骤 + 每步预期」。
### 六、Git 与留痕
- 从当前干净 `develop` 拉 `feature/flutter-k7-carousel-notices`;完成后 `git merge --no-ff` 回 `develop` 并 push;不动 `main`。
- 先写 `FruitServer/docs/plans/2026-10-17-K7.md`(范围、影响文件、契约缺口、风险、待确认)。
- 每步「叙述 + 命令 + 原始输出 + 解读」追加到 `docs/plans/PROGRESS.md`;完成后停住写回执。
- 提交作者与提交者统一 `Zhou Weidong <502333560@qq.com>`。
### 七、K7 完成回执(2026-10-17)
**结论**:K7-A 轮播增强、K7-B 站内通知、K7-C 测试验收均完成并停止。
未新增接口,未改后端/Web/specs。
#### 7.1 首页轮播
- 保持 `feed.banners` 数据源和 `CoverCarousel` 3D 翻转风格。
- 4.5s 自动轮播;单张不启动 Timer。
- 触摸/拖拽期间暂停,松手恢复。
- `active=false` 或 `TickerMode` 不可见时暂停;dispose 取消 Timer。
- 底部圆点指示器使用 `onPrimary` / `muted` K5 token,带三语语义标签。
- 图片失败复用 `RemoteImage` 并显示图标占位。
- 点击继续调用原有 `onOpen`。
#### 7.2 站内通知
- 新增 `notice.dart`、`notice_api.dart`、`notice_repository.dart`、
`notices_controller.dart` 和 `NoticesPage`。
- `GET /app/notices?pageIndex&pageSize=20`,匿名访问。
- ID 按字符串解析,`total` 按数字解析。
- 首屏、加载更多、空态、失败重试、下拉刷新均已接入;
已加载数量 `< total` 时才展示加载更多。
- 列表展示标题、原始 `type`、locale 时间、两行摘要。
- 详情弹窗展示完整 `content`,保留换行并支持长内容滚动。
- 我的页新增“通知”入口;匿名可进入,无登录闸。
- `noticeEnabled` 属 `/app/config`,本批未接,登记后续。
真实 8081 匿名接口验证:
```
$ curl -sS 'http://127.0.0.1:8081/app/notices?pageIndex=1&pageSize=20'
{"code":0,"message":"ok","data":{"total":0,"list":[]}}
```
#### 7.3 门禁原始结果
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test test/discover/cover_carousel_test.dart test/notice
All tests passed!
$ flutter test
00:14 +284 ~1: All tests passed!
$ flutter build apk --debug
Running Gradle task 'assembleDebug'... 6.9s
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
`~1` 是既有 live watch 用例在 8081 未启动时按机制跳过。
新增覆盖:
- 自动轮播、单张无 Timer、交互暂停、active/TickerMode、圆点、图片占位、onOpen。
- 通知 API 字符串 ID、controller 分页/空/失败/刷新。
- NoticesPage 首屏、加载更多、加载/空/失败三态、详情换行、印尼时间。
- 320×568 长标题/长内容不溢出;我的页匿名通知入口。
#### 7.4 Git
- 功能提交:`b870956665f5268070c691533cc2a334f2aa7f59`
`feat(flutter): 增加轮播自动播放与站内通知`
- `--no-ff` 合并:`3e8703b`,已推送
`b7b1c50..3e8703b develop -> develop`
- author/committer 均为 `Zhou Weidong <502333560@qq.com>`;未操作 `main`。
#### 7.5 用户真机验证步骤与预期
1. 打开发现页顶部轮播,等待 4.5 秒。
预期:自动翻到下一张,圆点同步变化;单张 banner 不会自动循环。
2. 按住/拖动轮播超过 4.5 秒后松手。
预期:按住期间不自动翻页;松手后恢复自动轮播;拖拽仍保持 3D 翻转。
3. 暂时断开图片源或使用失败封面。
预期:显示深色占位和图片失败图标,不白屏。
4. 点击当前 banner。
预期:按原有 DRAMA 跳转逻辑进入详情。
5. 进入“我的 → 通知”,未登录也可访问。
预期:显示通知列表;空数据时显示“暂无通知”;断网时显示失败及重试。
6. 有超过 20 条通知时点击“加载更多”。
预期:下一页追加到列表,无重复;已加载数量达到 total 后按钮消失。
7. 下拉刷新,再点击一条长通知。
预期:刷新后列表回到第一页;详情显示标题、发布时间和完整正文;
正文换行保留且长内容可滚动。
8. 切换 Bahasa Indonesia 查看通知时间。
预期:时间按印尼 Material 格式显示。
设备侧截图与真机结果由用户执行。
#### 7.6 已知边界
- 无已读/未读、红点、FCM、通知设置。
- 不接 `/app/config noticeEnabled`,通知入口当前常驻。
- 无独立 banner 接口,未新增首页铃铛。
---
## [已处理·待用户验收] 2026-10-17 | K6 客户端 UI:登录页 + 底部导航优化
**用户指令(2026-10-17)**:「接下来优化登录页面 UI 及底部导航 UI」。
+73
View File
@@ -2028,3 +2028,76 @@ ac706a4..b7b1c50 develop -> develop
```
解读:修复已合并推送;用户设备特定 error 仍需设备日志确认。
---
## 2026-10-17 K7 首页轮播与站内通知(【Codex】)
### 21.1 K7 计划与首次红灯
叙述:先写 `docs/plans/2026-10-17-K7.md`,从干净 `develop b7b1c50`
创建 `feature/flutter-k7-carousel-notices`。
首次轮播/通知测试:
```
No named parameter with the name 'active'
Error when reading 'lib/core/data/models/notice.dart': No such file or directory
Error when reading 'lib/core/data/remote/notice_api.dart': No such file or directory
00:00 +0 -3: Some tests failed.
```
解读:轮播增强、通知数据层和页面尚不存在,红灯符合预期。
### 21.2 轮播绿灯
实现 Timer、交互暂停、active/TickerMode、圆点、失败占位与语义后:
```
$ flutter test test/discover/cover_carousel_test.dart
00:00 +7: All tests passed!
```
### 21.3 通知实现与定向绿灯
实现 Notice model/API/repository/controller/Page、我的页入口和三语文案后,
真实匿名接口返回:
```
$ curl -sS 'http://127.0.0.1:8081/app/notices?pageIndex=1&pageSize=20'
{"code":0,"message":"ok","data":{"total":0,"list":[]}}
```
通知与轮播定向测试:
```
$ flutter test test/discover/cover_carousel_test.dart test/notice
All tests passed!
```
期间修正 320px 下类型/时间同一行 3.5px 溢出,改为双 Flexible。
### 21.4 K7 最终门禁
```
$ dart analyze lib test
Analyzing lib, test...
No issues found!
$ flutter test
00:14 +284 ~1: All tests passed!
$ flutter build apk --debug
✓ Built build/app/outputs/flutter-apk/app-debug.apk
```
### 21.5 Git
```
b870956665f5268070c691533cc2a334f2aa7f59
feat(flutter): 增加轮播自动播放与站内通知
b7b1c50..3e8703b develop -> develop
```
解读:K7 已合并推送;author/committer 均为 Zhou Weidong。