docs(plans): 下发 K7 轮播图与站内信任务

docs/plans/INBOX.md

@@ -20,6 +20,93 @@
 
 ---
 
+## [待处理] 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>`。
+
+---
+
 ## [已处理·待用户验收] 2026-10-17 | K6 客户端 UI：登录页 + 底部导航优化
 
 **用户指令（2026-10-17）**：「接下来优化登录页面 UI 及底部导航 UI」。