时间胶囊

记录决策的最佳时机是做出决策的那一刻。其次，是为后来需要处理这些决策的人留下信息。

功能概述

你现在知道的信息，将来可能会被迫切需要——但你不知道将来是何时。时间胶囊让你能够在代码库中埋藏信息，当特定条件触发时，这些信息会自动浮现：

• - 当有人终于碰触那个两年无人问津的文件时
• 当某个模块的TODO数量超过阈值时
• 当特定依赖被升级时
• 当测试覆盖率低于某个百分比时
• 当新开发者提交首次代码时
• 在特定日期（嘿团队，API许可证下个月到期）

信息会在最相关的时刻送达——不会提前（那会成为噪音），也不会滞后（那会为时已晚）。

胶囊类型

欢迎胶囊

╔══════════════════════════════════════════════════════════════╗
║ ⏳ 时间胶囊已开启！ ║
║ 埋藏者：@jcooley 于 2025-06-15 ║
║ 触发条件：检测到新贡献者 ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ 亲爱的新团队成员， ║
║ ║
║ 欢迎！以下是我希望入职第一天就有人告诉我的事： ║
║ ║
║ 1. legacy文件夹并非遗留系统——它是计费引擎， ║
║ 每天处理200万美元交易。不要重命名任何东西。 ║
║ ║
║ 2. /integration中的测试很慢（40分钟）。先运行/unit测试。 ║
║ 只有在推送到主分支前才运行集成测试。 ║
║ ║
║ 3. 如果你在auth.ts中看到名为doTheThing()的函数—— ║
║ 是的，我们知道。不，暂时不要修复它。上面有个时间胶囊。 ║
║ 等它开启时你就会明白了。 ║
║ ║
║ 4. 真正的架构图在/docs/actual.png， ║
║ 而不是/docs/architecture.png（那是2023年的版本）。 ║
║ ║
║ 祝你好运。你会爱上这里的。 ║
║ — 团队，2025年6月 ║
╚══════════════════════════════════════════════════════════════╝

警告胶囊

╔══════════════════════════════════════════════════════════════╗
║ ⏳ 时间胶囊已开启！ ║
║ 埋藏者：@sarah 于 2025-09-22 ║
║ 触发条件：src/payments/reconciliation.ts 被修改 ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ 停。在修改任何内容之前请先阅读。 ║
║ ║
║ 此文件处理与Stripe的支付对账。 ║
║ 看起来简单。但绝不简单。以下是需要了解的内容： ║
║ ║
║ - 第47行的3秒延迟并非随意设置。 ║
║ Stripe的webhook投递存在竞态条件。 ║
║ 没有这个延迟，大约每500笔支付中会有1笔重复扣款。 ║
║ 我们付出了惨痛代价才学到这一点。工单：INC-2847。 ║
║ ║
║ - 第63行的Math.round()必须保留。 ║
║ 浮点数+货币=灾难。我们在发现这个问题前的3周内 ║
║ 损失了12,847美元。工单：INC-3012。 ║
║ ║
║ - 如果需要测试，请使用Stripe沙箱配合webhook重放工具。 ║
║ 不要用真实收费进行测试。 ║
║ （是的，有人干过。不，我们不想谈这事。） ║
║ ║
║ 如果你在重构：请保持以上三个不变条件。 ║
║ 如果你在修复bug：先查看INC-2847和INC-3012。 ║
║ ║
║ — Sarah，最后一个碰过这个文件的人 ║
╚══════════════════════════════════════════════════════════════╝

日期胶囊

╔══════════════════════════════════════════════════════════════╗
║ ⏳ 时间胶囊已开启！ ║
║ 埋藏者：@mike 于 2025-11-01 ║
║ 触发条件：到达日期：2026年3月1日 ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ 嘿团队， ║
║ ║
║ GeoLocation API许可证将于2026年3月31日到期。 ║
║ 续费费用为每年4,800美元。免费替代方案（OpenCage） ║
║ 存在但不支持批量查询。 ║
║ ║
║ 需要做出决定： ║
║ 1. 续费许可证（4,800美元） ║
║ 2. 迁移到OpenCage（预计3个开发日） ║
║ 3. 构建自己的地理编码缓存（预计2个开发周） ║
║ ║
║ 我提前4个月埋下这个胶囊，以便你们有时间做决定。 ║
║ 别像2024年的SSL证书那样让它意外过期。 ║
║ ║
║ — Mike ║
╚══════════════════════════════════════════════════════════════╝

阈值胶囊

╔══════════════════════════════════════════════════════════════╗
║ ⏳ 时间胶囊已开启！ ║
║ 埋藏者：@jcooley 于 2025-08-10 ║
║ 触发条件：src/checkout/ 测试覆盖率降至80%以下 ║
╠══════════════════════════════════════════════════════════════╣
║ ║
║ 覆盖率降至80%以下。我就知道这一天会来。 ║
║ ║
║ 2025年8月我编写结账测试时，覆盖率为94%。 ║
║ 我写下这个胶囊是因为我知道截止日期的压力会逐渐侵蚀它。 ║
║ 情况是这样的： ║
║ ║
║ 未测试的代码路径正是金钱相关的bug藏身之处。 ║
║ 具体来说：多币种、折扣叠加和部分退款。 ║
║ 如果覆盖率下降了，很可能是因为有人添加功能时没有添加测试。 ║
║ ║
║ 恢复计划： ║
║ 1. 运行：npm test -- --coverage checkout/ ║
║ 2. 红色行是没有测试的新代码 ║
║ 3. 优先级：任何涉及金钱的代码优先获得测试 ║
║ 4. 不要让这个数字低于70%。低于70%时， ║
║ 结账模块将变得无法在不恐惧的情况下修复。 ║
║ ║
║ 我在70%处埋了另一个胶囊。你不会想看到那个的。 ║
║ ║
║