企业官网建设流程全解析

1. 工期到底怎么算：先把口径定死

排期这件事，最怕的不是算不出来，而是两个人算出来的结果不一样，还都觉得自己对。我见过太多次这样的场面：一方说"30 个工作日的活儿，9 月 27 号开工，10 月底肯定交"，另一方翻着日历说"不对，10 月中旬就该交了"。争到最后发现，两个人的差别不在算术，而在于一个按自然日算、一个按工作日算，一个把开工当天算进去、一个不算。工期计算器（也常被叫做工期日历计算器、在线工期计算工具）本质上不是算数工具，而是一个"口径统一器"——它把项目里那些含糊其辞的"多少天"翻译成唯一确定的日期，让双方在同一个坐标上对话。

我用这类工具的场景大概有三类：一是施工、装修、设备安装这类有明确合同工期的项目，合同上写的是日历天，现场排产靠的是工作日，两套口径来回换；二是软件交付、活动筹备这类按工作日推进的活儿，要避开假期；三是招投标阶段快速评估"这个交付节点我们扛不扛得住"。所以这篇东西写给三类人看：需要跟甲方对工期的项目负责人、需要把排期落到日历上的执行同学、以及想自己做一个内部小工具的技术同学。哪怕你只是想知道"从下周一往后数 20 个工作日是哪天"，看到第 3 节就能直接拿走用。

1.1 三种计时口径：日历天、工作日、有效工作日

所有工期计算的混乱，八成来自三个词被混用。**日历天（自然日）**就是一天不多一天不少，从 3 月 1 日到 3 月 31 日是 31 天，中间下雨、过年、周六周日全都算在里头。工程合同、租赁合同、质保期基本都用这个口径，因为它不需要解释，也不需要维护任何日历表，谁都赖不掉。工作日是剔除周末（以及法定节假日）之后的日子，它回答的是"我们真正能干活的天数有多少"。软件排期、行政审批、财务流程常用这个口径。有效工作日则更细一层，它还要再扣掉内部明确不排产的日期，比如公司年会那天、季度盘点那天、某个团队固定不开工的时间段，这些既不是法定假期也不是周末。

这三个口径必须在使用前就写清楚，写在排期表抬头或者需求文档第一行。我的习惯是：凡是跨部门、跨公司的约定，一律先落到日历天上，因为它是唯一不需要维护数据的口径；内部排产再往下折算成工作日。之所以这么定，是因为日历天是绝对量，不随任何人维护的节假日表变化。你今天按工作日算出来 10 月 20 日交，明天人家把某个补班日改成了休息日，你的交付日期就往后挪了，但合同上的日历天不会动。这一点在跨年项目里尤其明显——节假日安排每年公布一次，跨年项目的后半段永远是在用一份还没最终确定的日历做计算。

注意：别指望一个数字同时满足两个口径。要么在两个口径之间做明确的换算并写明换算依据，要么就老老实实算两遍，把两个日期都列在表里。

1.2 含不含起算日，这一个开关能差出一整天

这是个看起来极小的细节，但它制造的错误比所有算法 bug 加起来都多。"开工当天算不算第一天"，在计算上就是"含起算日"与"不含起算日"两个分支，结果常常差一天，而这一天的误差在验收、结算、违约金计算里都是实打实的钱。

常见的约定是这样的：施工类项目讲"工期 30 日历天"，多数按含起算日、含收工日处理，也就是 3 月 1 日开工、工期 30 天，那么 3 月 30 日就是最后一天；而软件项目讲"这个需求要 5 个工作日"，多数人的直觉是不含起算日——今天开始算，5 个工作日之后也就是下周一交付。这两种约定都没有对错，但必须选定一个并且在工具里显式暴露成一个开关，而不是藏在代码里靠一个+1或者-1蒙混过去。

我在实际项目里踩过的坑是：同一个团队的两拨人，用同一个计算器，一个人开着"含起算日"、一个人关着，算出来的日期差一天，然后各自拿着截图去跟客户确认。后来我干脆在工具的结果区把两个日期都打出来——"含起算日：3 月 30 日 / 不含起算日：3 月 31 日"，并标注当前使用的是哪一种。这个小改动把扯皮次数直接压到接近零。凡是存在两种合理解释的地方，就不要替用户做选择，而要让他看见选择。

1.3 为什么非要做成在线工具

有人会问，Excel 里NETWORKDAYS不是已经能算工作日了吗，为什么还要单独做一个在线工具。原因是这类计算一旦嵌进表格，就会出现三个很难治的毛病。第一，节假日表散落在每个人的本地文件里，张三的表更新了、李四的没有，两个人算出两个结果，还都不知道对方的表是旧的。在线工具的价值在于日历数据是集中一份，改一次全员生效，而且能打上版本号。第二，表格里的公式是隐形的，谁都能改一笔，改完还看不出来，而工期这种直接影响对外的数字，越透明越好，输入项、口径、日历版本必须一眼可见。第三，手机上看不了、分享不了，现场核对工期的时候大家手里拿的是手机，不是笔记本，一个能直接发链接、结果能截图的口径说明，比一个.xlsx附件有用得多。

顺带说一句，在线工具还有一个隐性价值：它逼你把规则写下来。做表格的时候，你不太会去想"我们的周末到底是双休还是大小周""春节那段到底算几天"，但做工具的时候你必须把这些填进配置里，填的过程本身就是一次规则梳理。我见过好几个团队，是在做这个小工具的过程中，才第一次把"我们的工作日到底指什么"讨论清楚。

2. 日历数据才是这类工具的命门

很多教程把工期计算器讲成一个纯粹的日期算法问题，仿佛把周末判断写对了就完事了。实际做下来，算法部分可能只占两成工作量，剩下八成全在日历数据的建模和维护上。因为这个工具的输出不是"距离今天多少天"，而是"哪一天交付"，这个日期必须建立在与使用者完全一致的日历认知上。日历认知一旦对不上，算法再漂亮也是错的。所以这一节先把数据说清楚，第 3 节再讲算法。

2.1 周末规则不是全球统一：双休、单休、大小周

"周末就是周六周日"，这句话对大部分人成立，但对着工期工具来讲是不够的。至少有这么几种情况必须支持：双休（周六日休息）是最常见的一种；单休（只休周日）在部分生产、零售、服务场景里仍然存在；大小周（一周单休、一周双休交替）在不少团队里实行过；还有轮班制，休息日与星期几完全无关，是按排班表走的。如果你的工具有一天要给这些场景用，就必须把"哪几天算休息"做成可配置的，而不是硬编码成day === 0 || day === 6。

我的做法是把周末规则抽象成"一周七位的休息掩码"，用[日, 一, 二, 三, 四, 五, 六]的顺序存七个布尔值，双休是[1,0,0,0,0,0,1]，单休是[1,0,0,0,0,0,0]。大小周则不能用一个固定掩码表示，需要额外挂一个"周序号奇偶"的规则，或者更通用的做法——直接退化成"按日期区间声明休息"，把未来一年的休息日全部铺开成一张表。后者看起来笨，但它能同时覆盖单休、大小周、轮班，扩展成本最低，我后来基本只用这一种。

实际经验里，大小周是最容易算错的，因为它的周期是两周，而月份长度不是 14 的倍数，所以每个月的休息日分布都在变。如果你用"每月休息 X 天"这种近似口径去算，短短几个月就会累计出明显误差。要么老老实实铺表，要么就在工具里明确声明不支持，不要给出一个似是而非的结果。

2.2 节假日与补班表：维护成本比算法高

休息日分两种：一种是周期性休息（周末），靠规则就能推出来；另一种是一次性休息（节假日），只能靠人工录入。更麻烦的是还有反向的补班日——本来该休息的日子被标记成工作日。所以完整的日历数据不是一张"假期表"，而是两张表：休息日表和补班日表，而且补班日的优先级高于休息日，因为它是对默认规则的一次显式覆盖。

判断逻辑的顺序必须是固定的，我一般写成这样：先查补班表，命中就是工作日；再查休息日表，命中就是休息日；两边都没有，才回落到周期性规则。顺序不能乱，一旦先查周末规则再查补班表，补班就永远不生效，这是新手最常犯的一个错。

关于数据来源，我的建议是：工具不要内置一份"写死"的节假日数据，而是内置一份可编辑的示例数据，并且明确标注这是示例、实际使用时按官方公布的安排自行维护。原因很现实——节假日安排每年公布一次，且存在调休，如果工具把某一年的数据硬编码进去，第二年所有用过的人都会得到错误结果，而他们不会意识到是数据过期了，只会觉得这个工具"不准"。我在一个内部工具上就吃过这个亏，第一年用得挺好，第二年春节后陆续有人反馈算错，排查了半天才发现是数据表没更新，而不是代码有问题。

注意：节假日表至少要提前一年准备。做跨年项目的时候，如果下一年的安排还没出来，工具应该明确提示"该日期超出当前日历覆盖范围"，而不是默默按周末规则算一个结果出来。

2.3 给日历打版本号，解决"历史项目复算"问题

这一条是被很多人忽略的。假设你的工具一直在线，日历数据一直在更新，那么半年前算出来的一个交付日期，今天用同样的输入再算一遍，结果可能不一样了——因为中间某个日期被调整过。这时候如果有人拿旧截图来对账，你没办解释清楚，因为你连"当时用的是哪一版日历"都说不出来。

解决办法很朴素：给日历表打版本号，并把版本号写进计算结果的输出里。每次日历数据变更，递增一个版本号，或者干脆用日期做版本标识（比如calendar-2024.11.01）。计算结果旁边永远跟着一行小字：按calendar-2024.11.01计算，含起算日，周末规则为双休。这样半年后有人来对账，你能立刻定位到当时的算法口径，甚至可以把旧版本日历找出来复现一遍。

这个设计的额外好处是，它逼你把日历数据做成不可变快照而不是"随时可改的一坨数据"。每次修改不是覆盖，而是新增一个版本。存储成本几乎为零（一年也就几百个日期），但它带来的可追溯性价值极高。我在做第二个版本的时候就改成了这个模式，之后再没出现过"两个日期对不上但说不清为什么"的情况。

3. 核心算法拆解与代码实现

数据说完了，聊算法。这一块其实不复杂，但有几个点如果不提前想清楚，代码写出来会又长又容易错。我的整体思路是：把日期统一降维成"日序号"这个整数，所有加减都在整数上做，只在展示的时候转回年月日。这样做的好处是，时区、夏令时、闰年、月末天数这些麻烦事全都被挡在转换层之外，核心循环里只剩下纯整数运算，逻辑一眼能看明白。

3.1 日期都用"日序号"表示，绕开时区与夏令时

如果用Date对象直接做+1 天的运算，就会碰上两个讨厌的问题：一是夏令时切换那天，某些时区的一天不是 24 小时，简单地加86400000毫秒可能落到前一天或后一天；二是本地时区与 UTC 混用的时候，日期字符串转换容易出现偏移，尤其在东八区，new Date('2024-03-01')解析成 UTC 零点，本地显示会变成 2 月 29 日。

我的处理方式是：全程使用 UTC 时间戳，且只用它的"日"维度。具体讲，就是把2024-03-01解析成Date.UTC(2024, 2, 1)，之后所有加减都是+ 86400000，因为 UTC 没有夏令时，一天的毫秒数恒定为 86400000。展示的时候用getUTCFullYear / getUTCMonth / getUTCDate取回年月日。这样就彻底绕开了时区问题，代码在任何地区的浏览器里跑出来的结果都一样。

另一种更彻底的做法是直接用"儒略日序号"——把某个固定日期（比如 1970-01-01）定为 0，之后每一天递增 1。这样日期就是一个纯整数n，加一天就是n+1，判断星期几就是n % 7。这个模型在工期计算里非常舒服，因为工期计算的本质就是整数加减。我现在的实现里，内部就是用这个整数做运算的，只有在输入输出时做一次转换。

3.2 正算：开始日期加工期

正算是最常用的场景：给定开工日和工期，求交付日。核心是一个循环：从起点开始，一天一天往后走，遇到工作日就计数加一，计数到工期就停。

这里有个关键细节——起点的计数方式取决于"含不含起算日"这个开关。如果含起算日，那么起点当天如果是工作日，就先记 1；如果不含起算日，起点当天不计数，从下一天开始找。这个逻辑如果写反了，结果会整整差一天，而且因为大部分输入下结果看起来"差不多对"，很难被发现。

另一个细节是：如果工期是 0 或负数怎么办。工具里必须处理这个边界，通常的做法是直接返回起点日期并给出提示，而不是让循环跑出奇怪的结果。我在第一版里没处理，结果有人输了个 0，页面直接卡住了——因为循环条件永远不满足。这类边界看起来低级，但它真的会发生。

关于性能，需要说明一下：逐日循环在工期几千天的量级下完全不需要优化。一年 365 天，5 年也才 1825 次迭代，现代浏览器跑这个用不了 1 毫秒。网上有些文章会教你用"总天数减去完整周数乘以每周休息天数"的数学公式来加速，那个公式确实更快，但它处理补班日的时候会变得非常绕，而且一旦算错，排查难度远高于循环。我的判断是：除非你的工期动辄几万天，否则老老实实用循环，可读性带来的维护收益远超那点性能。

3.3 反算：从交付日倒推最晚开工

反算的场景也很常见：客户给了交付日期，问"最晚什么时候必须开工"。逻辑上是正算的镜像——从交付日往前一天一天走，遇到工作日计数加一，计数到工期就停，得到的日期就是最晚开工日。

反算的坑比正算多，主要在两端。前端（交付日）：如果交付日当天是休息日，那么"最晚交付"其实是往前最近的一个工作日，还是说交付日必须是工作日？这两种理解在不同行业里都有人用。我一般默认"交付日必须落在工作日"，如果用户输入的交付日是休息日，就自动往前找最近的工作日，并在结果里提示一句"已将交付日顺延至 X 月 X 日"。后端（开工日）：算出来的最晚开工日如果落在休息日，同样要处理——是往前找还是往后找？显然是往前，因为你要保证还有足够的工作日。这两个方向搞反了，结果会差好几天。

还有一个反算特有的问题：工期超过可用日历范围时怎么办。比如你的日历只维护到明年年底，而反算出来的开工日落在后年，这时候工具必须明确报错，而不是给出一个基于不完整数据的日期。这一点我在第 2 节提过，在反算里尤其致命，因为反算出来的日期往往在更早的时间点，反而是正算不容易碰到的边界。

3.4 区间统计与性能取舍

第三种计算是"两个日期之间有多少个工作日"，常用于结算、考勤、进度统计。它的口径比前两种更麻烦，因为要明确左闭右开还是双闭：从 3 月 1 日到 3 月 31 日，是算 31 天还是 30 天，取决于你含不含结束日。这个口径如果没有在一开始定死，统计结果就会和别人的报表对不上。

我的默认约定是左闭右开，也就是包含起始日、不包含结束日。理由是它在拼接区间的时候天然正确：1 月到 2 月的天数加上 2 月到 3 月的天数，正好等于 1 月到 3 月的天数，不会重复计算边界那一天。这个性质在做月度汇总、分段统计的时候非常重要。如果业务方坚持要双闭口径，那就单独提供一个开关，并在结果旁边标注清楚。

性能上，区间统计的迭代次数取决于区间长度，跨年统计也就几百次，同样不需要特殊优化。真正需要留意的是区间跨出了日历覆盖范围的情况，这时候应该截断到覆盖范围内计算，并明确提示"部分日期不在日历覆盖范围内，结果可能不完整"，而不是静默算完给个数。

3.5 代码实现

下面是我现在用的核心实现，精简过但逻辑完整。日历数据结构就用两个集合，一个存休息日、一个存补班日，都存成YYYY-MM-DD字符串。

const DAY_MS = 86400000; // 日期字符串 <-> UTC 时间戳（只保留日维度） function toTs(dateStr) { const [y, m, d] = dateStr.split('-').map(Number); return Date.UTC(y, m - 1, d); } function toStr(ts) { const d = new Date(ts); const y = d.getUTCFullYear(); const m = String(d.getUTCMonth() + 1).padStart(2, '0'); const day = String(d.getUTCDate()).padStart(2, '0'); return `${y}-${m}-${day}`; } // 判定某天是否为工作日 // cfg.weekendMask: 七位数组，索引 0 为周日 // cfg.restDays: Set<string> 一次性休息日 // cfg.workDays: Set<string> 补班日 function isWorkday(ts, cfg) { const key = toStr(ts); if (cfg.workDays.has(key)) return true; // 补班优先 if (cfg.restDays.has(key)) return false; // 一次性休息 const dow = new Date(ts).getUTCDay(); return !cfg.weekendMask[dow]; } // 正算：开始日期 + 工期（工作日） -> 结束日期 function addWorkdays(startTs, duration, cfg, includeStart) { if (duration <= 0) { return { end: startTs, warning: '工期必须为正整数' }; } let cur = startTs; let count = (includeStart && isWorkday(cur, cfg)) ? 1 : 0; let guard = 0; while (count < duration) { cur += DAY_MS; guard++; if (guard > 366 * 50) { return { end: cur, warning: '工期超出日历覆盖范围，请补充日历数据' }; } if (isWorkday(cur, cfg)) count++; } return { end: cur, warning: null }; } // 反算：交付日期 -> 最晚开工日期 function latestStart(endTs, duration, cfg, includeEnd) { let cur = endTs; let count = (includeEnd && isWorkday(cur, cfg)) ? 1 : 0; let guard = 0; while (count < duration) { cur -= DAY_MS; guard++; if (guard > 366 * 50) { return { start: cur, warning: '反推超出日历覆盖范围' }; } if (isWorkday(cur, cfg)) count++; } return { start: cur, warning: null }; } // 区间统计：左闭右开，返回工作日数量 function countWorkdays(fromTs, toTs, cfg) { let n = 0; for (let t = fromTs; t < toTs; t += DAY_MS) { if (isWorkday(t, cfg)) n++; } return n; }

调用起来就是这样：

const cfg = { weekendMask: [1, 0, 0, 0, 0, 0, 1], // 双休 restDays: new Set(['2025-01-01', '2025-05-01']), // 示例数据，实际自行维护 workDays: new Set(['2025-01-04']) // 示例补班 }; const r = addWorkdays(toTs('2025-01-01'), 10, cfg, true); console.log(toStr(r.end), r.warning); // 起点是休息日且含起算日，计数从 0 开始，实际从 1 月 2 日起算

这段代码里有三个地方值得单独说。一是guard计数器，它的作用是防止死循环——如果日历数据配置错误，比如把连续几百天全标成休息日，while就会一直转下去，页面直接僵死。加一个上限然后返回警告，比让用户对着转圈的页面发呆要好得多。二是返回结构里带着warning字段，而不是抛异常，因为这类问题多半是数据不完整，属于"能算但结果可能不准"的情况，需要让用户看见但不应该中断流程。三是countWorkdays用左闭右开，注释里写清楚，避免以后有人贴代码过去用错了口径。

4. 从零搭一个能用的在线工期计算器

算法有了，接下来是把这些东西拼成一个真能用的页面。这一节讲的是工程实现层面的取舍，包括界面该放多少东西、数据怎么存、哪些默认值必须拍板、以及上线前怎么验证。我一贯的原则是：内部工具的功能范围要小到能在一天内做完，但每个做进去的功能都得是真的会被用到的。做大了没人用，做小了没人用，这个度得靠对自己的团队了解来把握。

4.1 最小可用界面与交互路径

最小可用集我总结成"四输入、三输出、两辅助"。四输入：开始日期（或截止日期，二选一）、工期数值、时间单位（日历天/工作日）、计日规则（含不含起算日）。三输出：结算日期、该日期是星期几、总共跨越了多少个日历天（这个数字很多人以为没用，实际上对账时非常关键，因为合同里写的是日历天）。两辅助：日历数据版本号、一个"复制结果"按钮，点一下把整段结果以文本形式复制走，方便直接贴进邮件或群里。

交互上有一个我坚持要做的设计：实时计算，不要按钮。用户改任何一个输入，结果立刻刷新，不需要点"计算"。工期工具的计算量极小，完全没有性能顾虑，而多点一次按钮就意味着多一次"我是不是没点"的犹豫。反过来，如果是那种需要调用后端、耗时较长的计算，才需要显式按钮。这个判断标准很简单：计算耗时低于 16 毫秒的，一律实时。

还有个小细节值得做：结果区的日期要能一键切换到"下一个工作日"和"上一个工作日"。因为实际使用中经常会出现"这个日期我不满意，往后挪一天看看"，有了这个快捷操作，比重新输一遍快得多。这个功能是某次我连着调了十几遍工期之后才加上的，属于那种"不做也能用、做了就回不去"的改进。

4.2 数据结构与本地存储设计

因为这个工具大概率是纯前端的，所有数据都存在浏览器里，所以数据结构的设计直接决定了后面好不好改。我的方案是三个独立的键：calendar-vX（日历快照，每个版本一份）、settings（当前选中的日历版本、默认计日规则、默认周末规则）、history（最近 N 次计算的输入输出记录）。

日历快照的结构就是一个对象，包含版本标识、生效区间、休息日数组、补班日数组、周末掩码。用数组而不是用 Set 存储，是因为要序列化成 JSON 存进 localStorage，Set 不能直接序列化。读取的时候再转成 Set 用于查询。这个转换成本可以忽略，但省了不少序列化的麻烦。

history这个设计我要多说两句。它的价值不在于"方便回顾"，而在于出事的时候能自证。项目结算的时候，甲方拿着三个月前的一个日期来问"当时不是说这天交吗"，你打开历史记录，能看到当时的输入是什么、用的是哪版日历、口径是什么，一眼就能确认是对方记错了还是自己算错了。历史记录不需要存很多，二十条就够，超过就滚动删除。这个功能的存在感极低，但它是这个工具从"能用"到"敢用"的分水岭。

4.3 必须自己拍板的几个默认值

有几个默认值是没有标准答案的，必须由使用者自己决定，工具要做的是给一个合理的初始值，并且让它足够容易被改。我列一下我这边定下来的几个。

这里面最值得讨论的是"结果日期为休息日怎么办"。有两种处理：顺延或者报错。我选顺延，理由是大部分使用者的真实意图是"下一个能干活的日子"，而不是"你必须给我一个精确到休息日的结果"。但顺延必须在界面上明确标出来，用一行小字写"原计算结果为 X 月 X 日（周六），已顺延至 X 月 X 日（周一）"。如果不标注，用户会以为工具算错了。自动修正一定要伴随显式说明，否则修正本身就成了新的困惑源。

4.4 上线前必跑的用例表

自己做的工具最容易犯的错是"只测了正常路径"。工期计算的边界特别多，我整理了一张必跑清单，每次改完算法都要过一遍。下面这些用例里的日期和节假日都是演示用的示例配置，实际使用时请按当时公布的安排自行维护。

这十二个用例里，最难被发现的是第 5 和第 6 条，因为它们的错误表现是"结果差几天但不明显"，不像第 7 条那样直接卡死。我的建议是给这几条写死断言，做成一个自检页面，改完代码点一下，全部通过才算完。这个自检页面本身大概二十行代码，但它省下的排查时间是以小时计的。

5. 常见问题与排查实录

这一节全部来自实际踩过的坑。工期计算的错误有个共同特点：结果看起来总是"差不多对"，所以很难靠肉眼看出来，往往要等到交付那天才发现不对。所以我倾向于把问题按"症状"来归类，而不是按"原因"——因为排查的时候，你手上掌握的永远是症状。

5.1 "总是差一天"的六种成因

差一天是这个领域最典型的症状，我遇到过至少六种不同的原因，每一种的修法都不一样。

第一种，含起算日的开关状态与预期不符。这是最常见的，尤其在从别处抄来的代码里，那个+1或者-1到底代表什么，原作者自己可能都忘了。修法是把这个开关显式暴露到界面上，并在结果区标注当前状态。

第二种，起点是休息日但被计入了。比如周五下班前定的"周一开始"，实际输入的起点是周六，含起算日的逻辑下如果没判断工作日，就会把周六算成第一天。修法是在计数前先判isWorkday。

第三种，时区偏移导致的日期错位。用new Date('2024-03-01')在某些环境里会变成前一天晚上，取getDate()得到的是 29 号。修法是全程用 UTC 或者用日序号。

第四种，跨月的天数算错。用手写的方式算月份差，遇到 31 天和 30 天的月份就会错。修法是别自己算月份，直接用日序号加减。

第五种，补班日没生效。判断顺序写反了，先查周末规则就直接返回了，压根没走到补班表。修法是固定顺序：补班 → 休息 → 规则。

第六种，结算日和交付日的定义混用。有人说的"交付"是干完那天，有人说的"交付"是干完的第二天才能交付，这在跨零点作业的场景里很常见。这个不是代码问题，是术语问题，只能靠约定解决。

我的排查套路是固定的：先打印起点、终点的日序号差，再打印区间内每一天的判定结果，一张表列出来，肉眼一看就知道是哪天判错了。这个方法土，但比对着代码猜快十倍。

5.2 节假日表过期与补班漏配

这是最隐蔽的一类问题，因为代码没变、逻辑没错，错的只是数据。症状是：去年用得好好的，今年突然开始集体算错，而且错得不多，通常就差一两天。用户的第一反应往往是"这个工具不准了"，很少有人会想到是数据过期。

我现在的做法是给日历表加有效期。每条日历数据都带一个覆盖区间，比如"2025 全年"。当计算涉及的日期超出这个区间时，工具必须显式提示，而不是默默按周末规则算。这个提示不需要很重，结果区一行黄字就够，但它能救很多场对账。

补班漏配是另一个高频问题，因为它比节假日更容易被忘。休息日是"多放一天"，大家都有感知；补班日是"少放一天"，感知弱得多，录入的时候容易漏。我的建议是：录入的时候把休息日和补班日放在同一张表里成对维护，看到"放 7 天"就立刻去查"补哪两天"，不要分两次录。另外，录完之后用工具自己跑一遍全年的工作日总数，和往年对比一下，如果差得多就说明有漏。

注意：千万不要在内置数据里写死某一年的安排然后发布出去。哪怕你标注了"示例数据"，也一定会有用户直接拿来用。比较稳妥的做法是首次打开时数据为空，引导用户自己录入或者导入。

5.3 跨年跨闰年与月末的坑

跨年本身在日序号的模型下不是问题，但它会带出两个衍生问题。一是日历覆盖边界：12 月的项目往往要算到次年 1 月，而次年的日历数据可能还没维护，这时候必须提示。二是"工期跨年但合同按年度拆分"：很多合同是按年度计量的，跨年工期需要拆成两段分别核对，工具如果能顺手给出"本年度内工作日 X 天、次年 Y 天"的拆分，会省不少事。

闰年的坑比较集中：2 月 29 日只在闰年存在，如果你的日历数据里手动录了2024-02-29而实际那年是平年，就会出现一个"不存在的日期"被当成工作日。这个错误的触发概率很低，但一旦触发就非常难查，因为日期看上去完全正常。我的处理是在加载日历数据时做一次合法性校验，把非法日期直接剔除并打日志。

月末的坑主要在"按月统计"的场景。如果有人要求"每月按 21.75 个工作日折算"，那这个数字是年度平均值，用在单个月上必然有误差。这种折算方式只适合粗算，不能用于精确排期。凡是要精确到日的，就必须逐日判定，不能折算。

5.4 问题速查表

下面这张表是我贴在自己工位上的，症状对原因，直接查。

最后补一句实操心得：这个工具最值得投入的地方不是算法，而是让每一处判断依据都可见。日历版本、口径开关、顺延提示、警告信息，这些东西加起来可能占了一半的界面空间，看起来很啰嗦，但它们的存在让"结果对不对"这个问题变得可以当场回答，而不用回去翻代码。我在给团队做第二版的时候，把界面上的说明文字加了一倍，结果支持类的问题问了少了八成。做工具的人都该记住一件事：用户不信任的不是你的算法，而是他看不见的那些规则。

后来我又给这个工具加了一个小功能，就是每次计算完之后，自动在结果下面生成一段可以直接复制的话术，比如"以 2025 年 3 月 3 日为开工日，按工作日口径、含起算日计算，工期 20 个工作日，预计 2025 年 3 月 28 日（周五）完成，期间跨越 26 个日历天"。这段话往群里一发，基本不会再有人来问"你这个是怎么算的"。从我的经验看，排期沟通里的九成扯皮，都源于一方只给了结论没给依据，而把依据自动写出来这件事，成本低到可以忽略，收益却大得离谱。