日期库改造在回归矩阵一致后仍有最后一道工程关口：锁定的究竟是哪份包、安装时实际取到了哪些文件，以及出现异常后能否回到此前的业务结果。前三篇把日期语义、跨时区转换和双驱动回归契约逐步固定下来，本篇收束为可追溯的版本治理流程。目标不是追求永远使用某一个库，而是在依赖替换时保留日期计算的可解释性、发布记录与可回退路径。

日期规则工作台继续以2026-10-28和Asia/Shanghai为常规输入，保留纽约春季跳时、秋季重复小时作为关键地区用例。当前生效驱动记为candidate-A，准备替换的驱动记为candidate-B。这些名称只是业务配置槽位，并非第三方包的公开版本号。库的真实名称、版本、来源、许可信息和锁文件内容必须从工程实际安装清单读取，不用界面标签推测。

一、版本固化需要同时固定来源与内容

只把dependencies里的版本范围写成某个数字还不够。安装过程还受包仓库来源、可解析版本、锁文件、传递依赖与缓存影响。对于运行期日期驱动，应在实际使用的模块级oh-package.json5声明依赖，并把经过审核的锁文件纳入版本管理。华为开发者的依赖配置指南列明了远程包、本地模块、本地HAR/HSP等引入方式，也说明工程级与模块级依赖在构建期间的处理差异。升级时需要核对安装树，避免运行期库只被放在开发依赖配置中。

治理清单应包含包名、精确版本、来源地址、内容摘要、许可信息、业务接口版本以及回归矩阵标识。精确版本主要解决语义版本范围漂移，摘要解决同名文件内容不一致；两者并不互相替代。摘要可以由CI从实际取得的包内容计算，而不是手写一个看起来像校验码的值。若使用远程依赖，还需关注仓库镜像策略和锁文件记录的解析目标；若是本地HAR，则要固定相对路径背后产物的生成流程。

以下脚本使用Node.js计算内容SHA-256，并核对锁定记录与实际文件是否一致。输入使用一段示例包内容，展示哈希检查方法；真正接入工程时，输入应来自所选包产物的原始字节，随后将算法结果与可追溯的锁定信息比对。

const assert = require('node:assert/strict');
const { createHash } = require('node:crypto');
function sha256(buffer) {
  return createHash('sha256').update(buffer).digest('hex');
}
function verifyPackage(bytes, record) {
  if (!/^\d+\.\d+\.\d+$/.test(record.version)) throw new Error('VERSION_NOT_PINNED');
  if (!record.name || !record.source) throw new Error('SOURCE_MISSING');
  return { valid: sha256(bytes) === record.sha256, computed: sha256(bytes) };
}
const bytes = Buffer.from('calendar-adapter-build-A', 'utf8');
const record = { name: 'date-adapter', version: '1.0.0',
  source: 'local-reviewed-artifact', sha256: sha256(bytes) };
assert.equal(verifyPackage(bytes, record).valid, true);
assert.equal(verifyPackage(Buffer.from('modified'), record).valid, false);
assert.throws(() => verifyPackage(bytes, { ...record, version: '^1.0.0' }), /VERSION_NOT_PINNED/);
console.log({ name: record.name, digest: record.sha256.slice(0, 12) });

这里1.0.0是自定义适配器记录的样例版本，不对应特定开源包的实际发布情况。治理过程中应区别包完整性与来源可信性：SHA-256可以识别内容变化，但如果攻击者同时改变文件和记录，单靠哈希比较仍然不够。锁定记录需要来自可信变更流程，重要依赖可结合仓库凭据、产物签名和人工审阅材料进行确认。应用运行时不应反复计算整个包摘要，内容确认更适合放在构建交付流程中完成。

二、把替换决策拆成多项门禁

C-03回归矩阵给出的accepted只能说明业务结果达到契约比较要求，不能覆盖所有发布条件。实际替换还需要校对许可证、代码来源、模块导出、ArkTS类型适配、依赖安装树、时间地区测试、回滚快照和变更批准。不同项目对许可证接受范围可能不同，这类政策由组织配置，不应由日期解析器自动推断。任何必需项缺失，都应该将结果归类为暂缓切换，同时给出具体原因。

在界面上，门禁卡片可将“来源与摘要”“规则契约”“地区边界”“回滚快照”分开列出，并允许点开查看对应记录。需要人审的状态用review，未通过使用fail，通过使用pass。只有所有必需项均为pass才允许切换。即使单个失败项只影响罕见地区，也不适合在没有补偿措施的情况下自动覆盖旧驱动，因为该地区的用户仍可能持有已经约定的截止时间。

const assert = require('node:assert/strict');
const required = ['source', 'digest', 'license', 'contract', 'zoneCases', 'rollback'];
function releaseGate(checks) {
  const blocked = required.filter(key => checks[key] !== 'pass');
  return { action: blocked.length ? 'hold' : 'switch', blocked };
}
const healthy = Object.fromEntries(required.map(key => [key, 'pass']));
assert.deepEqual(releaseGate(healthy), { action: 'switch', blocked: [] });
const waiting = { ...healthy, zoneCases: 'review', rollback: 'fail' };
assert.deepEqual(releaseGate(waiting), {
  action: 'hold', blocked: ['zoneCases', 'rollback']
});
assert.equal(releaseGate({ ...healthy, digest: undefined }).action, 'hold');
console.log(releaseGate(waiting));

这种输出用于驱动发布流程，不直接替代人工审核机制。对于zoneCases=review，可以先保留生效版本，补充纽约重复小时的UTC候选顺序、额外的时区数据库样例，再重新计算门禁；对于rollback=fail，应先补齐可信的旧驱动产物和配置快照。把原因码固定下来，有助于在版本记录中对比“上次为何暂停”和“这次哪些项已修复”。门禁日志应记录版本与检查摘要，避免把完整的用户合同或预约数据写入开发输出。

三、替换时坚持原子切换与可回退

日期库适配器向上层只暴露稳定端口。实际的驱动实例可经工厂构造，在候选版本通过门禁后更新单一生效引用，页面组件不应该同时持有多个可变驱动。切换前保存旧驱动标识、规则配置版本和影响范围，切换后将未完成的旧请求按版本丢弃，避免异步计算结果越过版本边界进入新界面。对于尚未确认的纽约重复时刻，不能利用候选驱动的默认返回值悄悄补全用户选择。

回退不意味着重写已经确定的历史UTC瞬时值。存储层保留明确的epochMs、zoneId及原始钟面输入，回滚主要恢复未来计划的解释规则和应用解析入口。若替换失败，恢复旧驱动并重新读取业务快照；如果快照本身过旧，仍应按照迁移策略核对而不是覆盖新数据。下面的脚本通过接口校验、版本引用替换和异常回退展示这一边界。

const assert = require('node:assert/strict');
function makeDriver(id, parse) {
  return Object.freeze({ id, parse });
}
function createManager(initial) {
  let active = initial;
  return {
    current: () => active.id,
    parse: text => active.parse(text),
    replace(next, probe) {
      const previous = active;
      try {
        if (!probe(next)) throw new Error('CONTRACT_REJECTED');
        active = next;
        return { changed: true, from: previous.id, to: next.id };
      } catch (err) {
        active = previous;
        return { changed: false, reason: err.message };
      }
    }
  };
}
const old = makeDriver('candidate-A', text => ({ kind: 'calendar-day', value: text }));
const bad = makeDriver('candidate-B', text => ({ value: text }));
const good = makeDriver('candidate-C', text => ({ kind: 'calendar-day', value: text }));
const manager = createManager(old);
const probe = driver => driver.parse('2026-10-28').kind === 'calendar-day';
assert.equal(manager.replace(bad, probe).changed, false);
assert.equal(manager.current(), 'candidate-A');
assert.equal(manager.replace(good, probe).changed, true);
assert.equal(manager.current(), 'candidate-C');
console.log(manager.parse('2026-10-28'));

例子中的探针只检查一个契约字段，完整工程替换条件应使用上一节所有门禁和C-03全部固定用例。若驱动需要异步初始化，应先在隔离环境构造候选实例，确认插件加载与规则表就绪后再提交生效引用，不能一边初始化一边向用户开放新结果。生命周期结束时还应清理监听器、临时缓存与加载中的请求，回滚记录的保留期限则由具体业务审计要求决定。

四、用户界面与审计记录保持一致

页面可分为“当前锁定版本”“候选替换版本”“必需门禁”和“历史变更”四部分。生效版本卡片展示精确版本和摘要前缀，详情中保留完整摘要；候选卡片明确pending、review或ready，仅在所有必需项通过后开放提交。对于存在待复核项的候选，主操作应显示“暂缓切换”，其详情指出需补充哪组日期边界，而不是只给一个没有上下文的红色警告符号。这样的界面更便于开发和维护人员理解变更状态。

审计记录至少包含当前与候选依赖版本、包摘要、业务契约版本、回归矩阵标识、执行时间、处理动作和回滚目标。日志中避免记录完整私人预约数据；需要保存具体失败样本时，优先使用公开日期规则边界或脱敏的字段输入。由于审计记录独立于日期库实现，即使日后更换解析引擎，仍能读取历史决策，并明确当时采用哪个策略解释跳时与重复小时。

持续集成可以将依赖树核对、Node.js领域规则断言、ArkTS静态类型检查和工程构建拆成独立阶段。只有当相应阶段真正完成时，才写入该阶段的通过状态。华为开发者的ArkTS运行时与依赖管理文档可以用于核对工程配置和运行相关概念；第三方库的插件API与解析选项则参照各自项目文档。两类证据应分开记录，既能帮助排查问题，也不会把某一个脚本运行结果误用为整个工程的发布结论。

五、维护周期中的迁移与回滚策略

未来升级时先固定上一版锁文件与日期契约回归矩阵，再分析变更日志及传递依赖，按业务风险扩充测试用例。对所有用户共用的日期解析库，发布窗口应安排可撤销的灰度策略，及时观察INVALID_DATE、gap、overlap等错误类别分布是否异常；这里的观察指标应基于经授权采集的匿名统计，并具有明确保留策略。若候选驱动出现异常，保留原始输入和既定UTC数据，撤回新的解析入口，在稳定版本上重新处理未来规则。

值得避免的维护陷阱还有两类。一是将库版本直接写进业务数据键，造成每次依赖升级都触发无必要的数据迁移；二是在页面内散布对第三方库的直接引用，使得库替换必须修改大量组件。统一适配层、清晰的错误契约、版本锁定记录和跨时区回归矩阵共同解决这两个问题。日期库可以按需更新，业务日期含义则应持续稳定；这也是本系列从输入语义到依赖治理的完整工程主线。

参考资料

• 华为开发者：《添加依赖项》 https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/ide-hmos-hvigor-dependencies
• 华为开发者：《ArkTS运行时概述》 https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/arkts-runtime-overview
• Day.js：《严格解析校验》 https://day.js.org/docs/en/parse/is-valid
• Day.js：《UTC》 https://day.js.org/docs/en/plugin/utc
• Day.js：《Timezone》 https://day.js.org/docs/en/plugin/timezone