施工进度时间轴有一组非常稳定的业务字段：活动编号、施工区域、计划开始日、计划结束日以及完成比例。前面几篇围绕周视图、可见区、增量更新和离线状态做了治理，到了日期服务准备复用时，新的问题反而暴露出来：不同页面各自解析日期字符串，遇到跨月、日期非法或时区转换时，结果可能互相矛盾。同一个ACT-02在列表里显示十月二十八日至三十日，在接口返回的时间戳被截取后却可能错成前一天。此时继续给每个页面补判断，修复成本会越来越高。

我的处理方式是把自然日计算集中到一个日期业务端口。施工日历的2026-10-29指的是项目约定的一个日历日，它不是一段毫秒数，也没有附带某个设备的时区。日志中的2026-10-29T10:20:00Z才是一个可比较的绝对时刻。两种类型从字段命名、解析函数到存储契约都需要区分。否则一旦页面换到另一类终端，常见的new Date(value)与本地格式化组合便可能改变显示日期。

从施工任务反推日期接口

时间轴里有四条持续使用的活动数据：ACT-01基础准备在十月二十七日，ACT-02混凝土浇筑从十月二十八日至三十日，ACT-03钢筋安装从十月二十九日至三十一日，ACT-04隐蔽验收定在十月三十一日。它们需要的公共日期功能其实很少：严格读取YYYY-MM-DD、计算周一日期、按自然日增减、判断闭区间是否相交，以及输出稳定的日期文本。页面关心的是这些功能的业务结果，不需要知道底层用了哪套第三方工具。

选型时我把三个关注点分开检查。一是库是否支持严格格式解析，错误日期会不会被宽松归一；二是日期对象修改后是否保持原值，避免同一对象被多个视图共享时发生副作用；三是安装形态、类型声明、插件和锁定文件是否与项目构建链路相容。Day.js具有轻量、对象操作返回新实例的设计，并提供CustomParseFormat插件，适合进入候选范围。不过它在Node.js业务层的使用方式与ArkTS设备侧包集成是两项不同的适配工作，必须分别检查。

在工程结构中，entry/src/main/ets/pages/PlanPage.ets负责展示，业务层的DatePort负责接收严格字符串并返回严格字符串。Node.js批处理工具可以采用Day.js候选实现；HarmonyOS应用接入时，再根据目标包的类型约束和打包结果决定是否直接复用。端口不暴露Day.js对象，跨模块传递的始终是字符串、整数和清楚命名的结果对象，这样第三方库替换时不会牵动页面状态。

严格解析与周起点计算

要解决的问题是把解析失败停在入口。Day.js默认解析容易接受某些可归一的输入，因此启用CustomParseFormat后还需要显式传递严格模式。下面的Node.js业务模块依赖安装好的dayjs，使用的是该库文档列出的插件和公开方法。

const dayjs = require('dayjs');
const customParseFormat = require('dayjs/plugin/customParseFormat');
dayjs.extend(customParseFormat);

const FORMAT = 'YYYY-MM-DD';
function createDatePort(engine = dayjs) {
  function parseDay(value) {
    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
      throw new RangeError('日期格式必须为YYYY-MM-DD');
    }
    const parsed = engine(value, FORMAT, true);
    if (!parsed.isValid()) throw new RangeError('不存在的施工日期');
    return parsed;
  }
  return {
    normalize: value => parseDay(value).format(FORMAT),
    addDays: (value, count) => {
      if (!Number.isInteger(count)) throw new RangeError('天数必须为整数');
      return parseDay(value).add(count, 'day').format(FORMAT);
    },
    monday: value => {
      const date = parseDay(value);
      return date.subtract((date.day() + 6) % 7, 'day').format(FORMAT);
    }
  };
}
module.exports = { createDatePort };

将第一段业务代码保存为DatePort.cjs后，后面的活动规范化代码即可通过require使用它。这里的date.day()以星期日作为零，经过(day+6)%7换算，就能从任意一天退回本周星期一。传入2026-10-29得到2026-10-26；传入十月三十一日后，仍落在十月二十六日至十一月一日这一周。业务代码没有把输入字符串先拼接T00:00:00，因此不会让系统本地时区决定施工自然日的含义。

失败路径同样属于接口契约。2026-02-29不是有效日期，2024-02-29有效；2026-2-9虽容易辨认，但不符合接口约定，应由导入映射流程处理后再交给日期端口。宁可让错误在进入数据库前显式暴露，也不要在周图绘制完成后再寻找凭空多出的三月第一天。

将第三方对象隔离在业务边界

施工任务不能只检查一个日期是否合法，开始日与结束日之间还需要业务关系。ACT-04是单日里程碑，闭区间可以允许首尾相等；如果ACT-03被填成结束日期早于开始日期，就应该拒绝入库。活动编号和修订号仍由之前连载的增量同步逻辑管理，日期端口不承担记录主键或审计历史的职责。

const { createDatePort } = require('./DatePort.cjs');
function normalizeActivity(input, datePort) {
  const id = String(input.id || '').trim();
  if (!/^ACT-\d{2,}$/.test(id)) throw new Error('活动编号无效');
  const start = datePort.normalize(input.start);
  const end = datePort.normalize(input.end);
  if (start > end) throw new RangeError('结束日早于开始日');
  const progress = Number(input.progress);
  if (!Number.isFinite(progress) || progress < 0 || progress > 100) {
    throw new RangeError('进度范围应为0至100');
  }
  return {
    id, name: String(input.name).trim(), start, end,
    progress, revision: Number(input.revision || 0)
  };
}

const tasks = [
  { id: 'ACT-02', name: '混凝土浇筑', start: '2026-10-28',
    end: '2026-10-30', progress: 50, revision: 9 }
];
const normalized = tasks.map(item => normalizeActivity(item, createDatePort()));
console.log(normalized[0].start, normalized[0].end);

这段代码输入与输出都是普通数据，不要求ArkUI页面理解第三方库的解析对象。若页面使用列表、甘特图或小屏卡片，统一读取start与end即可。十月二十八日到三十日仍然是三个计划自然日，完成率来自进度业务事件，不通过日期计算推导。revision:9与前一篇增量合并后的ACT-02状态保持衔接，避免文章中的业务快照倒退。

版本选择不能等到发布时才讨论

选择候选版本时，既要保留软件物料清单，也要保留可复现的安装记录。Node.js业务服务可以在独立包中将Day.js固定到团队评审通过的明确版本，例如通过npm install dayjs@1.11.13 --save-exact记录一个候选版本；该数字是版本固定方法的具体例子，并非要求始终使用这一版本。后续升级需要重新跑输入契约与边界样本。HarmonyOS的模块依赖则由oh-package.json5等配置管理，锁文件oh-package-lock.json5记录实际解析的依赖树，应随仓库提交并由ohpm维护。

这里有一个容易误判的环节：Node端的npm锁定结果不能自动等同于HarmonyOS端ohpm的可用依赖。它们的仓库来源、打包格式、TypeScript特性与ArkTS约束可能不同。为了防止错误宣传“已适配”，我倾向于先确认目标模块能否解析导出、类型是否可静态检查，再按项目依赖机制记录版本；Node.js日期服务在构建服务器上执行时则沿用自己的依赖锁定链路。

下面的业务脚本不解析锁文件内部节点，而是记录候选输入包的整体摘要；提交记录能够对应到具体文件内容，便于后续追查发生变化的环节。摘要只是文件身份信息，依赖安全与兼容问题还需要单独处理。

const fs = require('node:fs');
const crypto = require('node:crypto');
function fileSha256(filename) {
  const bytes = fs.readFileSync(filename);
  return crypto.createHash('sha256').update(bytes).digest('hex');
}
function compareDependencyFiles(before, after) {
  return {
    changed: fileSha256(before) !== fileSha256(after),
    previousHash: fileSha256(before),
    currentHash: fileSha256(after)
  };
}
module.exports = { fileSha256, compareDependencyFiles };

不要把一切日期能力都交给插件。遇到不合法的月份、负的任务时长、变更版本不匹配等情况，业务校验依然要明确负责；插件处理日期计算而不是决定项目业务的合法性。日期输出建议保持无时区的YYYY-MM-DD，时间戳则带偏移量或使用UTC形式，后台日志再单独记录时刻。这样同一条活动在手机、平板和后台批处理间传递时，字段意义始终一致。

生命周期、排查和后续升级

日期适配层虽然没有长期持有窗口引用，但页面对它的调用仍可能夹在异步数据请求内。页面退出时应该中止相关请求或标记请求代际，结果返回时核对当前活动ID；这与此前工单双栏连载的处理路径一致。日期对象不应被保存在全局可变单例中，业务端口保存无状态的计算函数即可，列表移除时由页面按自身生命周期清理订阅与计时器。

我通常先从最小输入集定位日期问题：十月二十九日应归属于十月二十六日那一周；十一月一日仍是同一周的最后一天；二月二十九日只允许在闰年出现；所有正常业务日期都要能够严格往返格式化。再比较页面拿到的原始字符串与适配器返回的结果。如果后端返回时间戳，应走时间戳转换入口，不要直接交给parseDay。

上线迭代最怕的是库升级后“看上去还是同一个日期”，周起点却整体偏移。封装端口以后，输入格式、闭区间语义、周一约定和版本变更都能形成稳定的回归契约。接下来重点处理的便是时区差异、月末与闰日这样的边界问题，让工地计划不会因为设备所在时区或者第三方库的默认解析策略而改变。

参考资料

• 华为开发者：oh-package.json5与依赖锁文件
• 华为开发者：添加依赖项
• 华为开发者：ArkTS运行时概述
• Day.js：CustomParseFormat严格解析