SuperAPI AI 工具集

dates-streaks-and-statistics

编程与开发

查看项目

更新于 10-18 18:02

技能介绍

本技能用于在 React Native / Expo 应用中建立一套可靠的“日历日、连续天数与统计”逻辑,核心目标是在本地时区下正确表示“今天”,并让打卡、连续天数、倒计时和统计数据在跨午夜、夏令时(DST)、跨时区旅行以及系统时钟回拨等情况下保持一致。

用途 该技能面向需要处理以下场景的代码:读取或展示“今天”、计算到期日、每日打卡或每日挑战、连续天数展示、距离次日的倒计时、完成事件的记录,以及总计、成功/失败次数、连续成功次数和自定义计数器等统计。

主要能力与规则

  1. 日期以本地民用日键表示,格式为 YYYY-MM-DD,通过 src/core/dates/date-key.ts 提供的 addDays、daysBetween、isoWeekday 等函数做整数运算;禁止使用 toISOString().slice(0, 10)、getUTC*、new Date(key)、Date.parse(key),也禁止用毫秒数除以 86,400,000 来计算天数。
  2. 只有时钟适配器读取真实时钟,日、连续天数和统计代码通过 ClockPort(nowMs、today、msUntilNextLocalDay)接收时间值。
  3. “今天”在每次渲染时读取,useToday() 会在本地午夜和 App 回到前台时重新渲染;不得把 today() 缓存进 state、ref 或模块常量。
  4. 事件归属其开始时的本地日,并在所有折叠函数中传入,折叠函数不重新读取时钟。
  5. 连续天数遵循单一纯模型:当日首个事件标记该日;最后活跃日为今天或昨天时连续天数延续;间隔更长则重置为 1;保留最佳值;时钟回拨不会删除已完成日或重复计数。宽限、冻结和修复作为产品数据记录为天,而不是规则分支。
  6. 每个数字只有一个真实来源:从永久保留的行在读取时派生,或在明细会被裁剪时作为计数器存储,但两者不得同时保存。
  7. 完成事件在显示确认前,以一次事务更新记录行、连续天数和统计数据;练习类事件不记录;折叠函数不修改输入。
  8. 统计按固定规则折叠:总计、成功、失败和时间累加;失败重置连续成功并保留最长值;按日分桶覆盖从最新日往前计算的固定窗口;自定义计数器使用稳定的 kebab-case id,并按 sum 或 max 折叠最终已提交步骤。
  9. 界面只格式化纯摘要,buildStreakSummary / buildStatsSummary 生成所有数字、标记和标志;组件与 hook 不做日期运算,也不读取原始分桶;标签与数字来自 i18n 层。
  10. 距下一日的时间来自 msUntilNextLocalDay(),useNextDayCountdown() 以整分钟快照并通过纯函数 splitCountdown 向上取整。

使用方式 工作流程包括:按任务查阅 references 下的 calendar-days.md、streaks.md、statistics.md、checkers.md;确认 clock 端口、date-key.ts 和渲染辅助等前置条件;将 templates 中所需模块(hooks、core/countdown、core/streaks、core/stats、contracts/day-logic.json 等)复制到其首行标注的路径;在 feature 逻辑中定义一次合格规则;通过一次 repository 事务写入完成记录;用 model hook 读取 useToday()、选择器和 useNextDayCountdown() 构建摘要,再由组件渲染;规则变更先写测试;最后运行指定 jest 命令与 npm run typecheck,并执行两个检查脚本,直到输出 RESULT: PASS。

适用场景 适用于 Expo / React Native 应用中的每日打卡、连续天数卡片、周条、每日挑战、统计面板、完成记录和次日倒计时等功能的实现与校验。

限制 该技能依赖 architecture-and-boundaries 提供的 clock 端口、seeded-determinism-and-golden-vectors 提供的 date-key.ts 以及 unit-and-component-tests 提供的渲染辅助;模板中的 clock 与 date-key 文件为同步副本,仅在应用缺失时复制且不得在应用内编辑。不含连续天数或统计模块的应用会输出 NOT APPLICABLE。具体收费、平台支持范围等未在资料中提供。