diff --git a/docs/plans/INBOX.md b/docs/plans/INBOX.md index bf27f1a..569dbcc 100644 --- a/docs/plans/INBOX.md +++ b/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」。