FEATURE-BEHAVIOR.md

功能行为与通知规则

本文档记录用户可感知的行为约定。新增功能或修改推送逻辑时，先更新本文档，再同步代码，避免本地通知、邮件提醒和页面展示出现不一致。

1. UI / UX 基准

没有明确同济业务差异时，前端 UI / UX 默认对齐 DanXi iOS App：

• 信息密度克制，优先展示用户当前真正需要的信息
• 列表行、卡片标题、图标和内容基线保持一致
• 空状态、加载态、错误态和刷新行为统一
• 不在本人专用页面重复展示卡号、账号等低价值敏感信息
• 页面正文、附件区和底部 Tab Bar 必须正确避让，禁止遮挡

参考仓库 ../DanXi-swift/ 只读，不得直接修改或复制整段源码。

2. 校园页刷新

校园服务页支持下拉刷新。刷新时会触发已接入服务的数据同步，包括：

• 教务通知
• 卓越星
• 校园卡
• 考试安排
• 课程成绩
• 图书馆座位

耗时较长的链路应复用 single-flight 任务，避免多个卡片或页面同时发起重复请求。

校园卡采用快速优先策略：

1. 先同步余额和第 1 页消费记录，尽快更新首屏
2. 后台继续补齐历史消费记录
3. 非强制刷新在短时间内优先使用缓存

3. 教务通知

教务通知页面提供：

• 摘要列表
• 详情正文
• 附件按需下载
• Quick Look 预览或系统分享

认证状态从续期中恢复为有效后，外层校园卡片应清除旧错误并重新加载，不依赖用户进入详情页再返回。

附件区域与正文分别滚动，附件面板必须停在底部 Tab Bar 上方；附件过多时限制最大高度并允许面板内部滚动。

4. 考试安排

考试安排同步后会同时服务于：

• 校园服务中的考试安排页面
• 日程页对应周的"本周考试"
• 系统日历导出

系统日历导出规则：

• 只导出具有明确日期、开始时间和结束时间的考试
• 默认提醒为考前 15 分钟和 30 分钟
• 无明确时间的考察、论文、汇报等条目只在 App 内展示

5. 课程成绩

课程成绩页面展示：

• 总平均绩点
• 实修学分
• 不及格学分
• 不及格门数
• 分学期课程列表
• 课程详情

课程类别保留一系统中的领域名，并把括号编号翻译成标签短名。例如：

科学探索与生命关怀[2]
-> 科学探索与生命关怀 · 精品类（核心）

SJ 等一系统内部代码不对用户展示。缓存中的旧类别会在下一次成功下拉刷新后重写。

6. 校园卡

校园卡详情页展示：

• 当前余额
• 更新时间
• 最近 7 天每日消费曲线
• 精简后的最近消费记录

消费记录标题优先展示真实地点或业务名称，例如食堂名称、充值来源。机位号、电子账户消费、消费等重复泛化字段不作为主标题堆叠展示。

低余额提醒阈值默认 50 元，用户可在设置中修改。本地通知与邮件提醒使用相同规则：

1. 首次检测只建立基线，不补发历史
2. 上次余额高于阈值，本次余额低于或等于阈值时提醒一次
3. 持续低余额期间不重复提醒
4. 余额恢复到阈值以上后，再次跌破才重新提醒

7. 卓越星提醒

卓越星活动提醒遵循"变化触发，不补发历史"：

• 首次检测只建立基线
• 新出现且符合用户关注星星类别的活动可触发提醒
• 已关注活动从未开始报名变为开始报名时可触发提醒
• 同一个活动、同一种状态变化只提醒一次
• 已经处于报名中的历史活动不会在首次建立基线时批量补发

本地通知和邮件提醒应使用同一套判断逻辑，避免用户收到两套语义不一致的提醒。

8. 图书馆座位

图书馆座位功能首版为只读状态面板，不提交预约、取消预约或签到。

页面展示范围：

• 四平路校区图书馆
• 德文图书馆
• 东区图书馆
• 嘉定校区图书馆
• 其他空间只显示折叠概览

人数概览遵循双口径原则：

1. 若后续发现真实门禁 / 入馆人数接口，优先展示真实人数
2. 当前协议只提供 total_num 与 free_num，因此 UI 必须标注为“座位占用口径”
3. 不得把座位占用率直接命名为入馆人数

座位展示规则：

• 区域页使用学校返回坐标绘制平面图，不展示几千条座位列表
• 座位状态筛选只影响图上显示 / 高亮，不触发预约
• 学校标签与本地标签可以一起筛选
• 本地 单人单座 标签按以下规则命中：
  • 四平路二楼：113-128、191-214
  • 四平路 6 / 8 / 10 楼南北：001-007、032-040、073-081
  • 东区二楼：57-69
  • 东区三楼：65-79
• 不确定的区域不误标，宁可不显示本地标签

研习室展示规则：

• 按今天、明天、后天三天展示
• 每个研习室显示人数限制和 08:00-22:00 时间轴
• 空闲段来自学校接口返回的可约区间
• 当前没有研习室数据的图书馆显示空状态

9. 邮件推送与敏感信息

邮件推送服务域名：

https://tjpush.mikezhuang.cn

用户只有在 App 内明确开启离线邮件推送并同意风险说明后，才会向服务端提交必要的一系统账号凭据。服务端必须：

• 加密保存凭据
• 支持用户随时删除订阅、凭据和检测状态
• 日志脱敏
• 使用低频、带随机抖动、夜间降频的轮询
• 遇到 MFA、验证码或风控时暂停该订阅并提示用户重新确认
• 不伪造人类行为，不绕过验证码或风控

SMTP 密码、服务端加密主密钥、Cookie、Token、真实账号密码不得进入 Git。

App 端通知开关与邮件订阅必须保持一致：

• 用户拒绝 iOS 系统通知权限，视为关闭通知；App 需要关闭本地通知，并请求服务端删除邮件订阅和凭据
• 用户关闭“启用邮件推送”，必须请求服务端删除订阅和凭据，不能只改本地 mailPushEnabled
• 用户修改教务通知、卓越星、校园卡低余额等偏好时，如果邮件推送已开启，需要自动同步到后端
• 用户离开通知设置页时，如果邮件推送仍开启，需要兜底同步邮箱、阈值和偏好，避免本地与后端状态漂移

10. APNs 后续计划

注册 Apple Developer Program 后，可增加 APNs 远程推送：

• 开启 Push Notifications capability
• 配置 aps-environment
• 在服务器安全保存 APNs Auth Key (.p8)
• 保持 APNs 与邮件提醒复用同一套事件去重规则

APNs 尚未接入时，邮件提醒是离线远程通知的替代方案；App 内本地通知不依赖 APNs。