@epxing/utils 0.0.0-stage → 5.3.0-beta.2

package/src/moment-compat.js

@@ -0,0 +1,744 @@
+// `$moment` 兼容层：对外是 moment 的用法，对内是 dayjs。
+// 设计与实测依据：docs/superpowers/specs/2026-09-03-moment-to-dayjs-design.md
+//
+// 为什么需要一层包装而不是直接给 dayjs：**moment 可变、dayjs 不可变**。
+// `const m = $moment(); m.add(1,'d')` 在 moment 下改的是 m 自己，在 dayjs 下这句是无效语句
+// （实测：docs 里的 D1/D2/D3 三条）。包装类让写方法改内部实例并 return this，
+// 于是「当语句用」和「链式用」两种写法同时成立，与 moment 一致。
+// ⚠️ 说明符里的 `.js` 不是可有可无的装饰：dayjs 的 package.json **没有 exports 映射**
+// （只有 main + types），所以子路径就是裸文件路径。Vite / vitest 会替你补扩展名，但纯
+// Node ESM 不会 —— 实测 `import('dayjs/plugin/relativeTime')` 在 node 下直接
+// ERR_MODULE_NOT_FOUND。产品项目若以 Node ESM 方式消费发布出去的 @epxing/utils 就会挂。
+import dayjs from 'dayjs'
+import 'dayjs/locale/zh-cn.js'
+import relativeTime from 'dayjs/plugin/relativeTime.js'
+import duration from 'dayjs/plugin/duration.js'
+import customParseFormat from 'dayjs/plugin/customParseFormat.js'
+import advancedFormat from 'dayjs/plugin/advancedFormat.js'
+import localizedFormat from 'dayjs/plugin/localizedFormat.js'
+import calendarPlugin from 'dayjs/plugin/calendar.js'
+import objectSupport from 'dayjs/plugin/objectSupport.js'
+import arraySupport from 'dayjs/plugin/arraySupport.js'
+import utcPlugin from 'dayjs/plugin/utc.js'
+import minMax from 'dayjs/plugin/minMax.js'
+import isSameOrBefore from 'dayjs/plugin/isSameOrBefore.js'
+import isSameOrAfter from 'dayjs/plugin/isSameOrAfter.js'
+import isBetween from 'dayjs/plugin/isBetween.js'
+import isLeapYear from 'dayjs/plugin/isLeapYear.js'
+import weekOfYear from 'dayjs/plugin/weekOfYear.js'
+import isoWeek from 'dayjs/plugin/isoWeek.js'
+import quarterOfYear from 'dayjs/plugin/quarterOfYear.js'
+import dayOfYear from 'dayjs/plugin/dayOfYear.js'
+import weekday from 'dayjs/plugin/weekday.js'
+import toArray from 'dayjs/plugin/toArray.js'
+import toObject from 'dayjs/plugin/toObject.js'
+
+// ⚠️ customParseFormat / objectSupport / arraySupport 当前仓库用不到，但 moment 支持
+// `$moment(str, fmt)` / `$moment({y,M,d})` / `$moment([y,M,d])` 这三种写法。不装的话
+// dayjs 会**静默**忽略第二参 / 得到 Invalid Date —— 是错值不是报错，产品项目最可能踩这个。
+//
+// ⚠️⚠️ **下面这个数组的顺序是语义相关的，别按字母序或"看着顺眼"重排。**
+// dayjs 插件是「取出当前的 proto.X，换成一个包着它的新函数」——后 extend 的包在外层，
+// 先被调用。两个插件包同一个方法时，谁在外面决定行为：
+//
+//   ① `objectSupport` **必须排在最后**（至少要在 `quarterOfYear` 之后）。它给 add/set/
+//      subtract 加的是「参数是对象就按 key 逐个转发」这一层；而 `quarterOfYear` 也包
+//      `add`，且首句是无条件的 `e = Number(e)`（见 node_modules/dayjs/plugin/quarterOfYear.js）。
+//      quarterOfYear 若在外层，对象参数会先被 Number() 变成 NaN，objectSupport 的分支
+//      永远走不到 ⇒ `$moment(x).add({days:1})` 全形态返回 `Invalid date`。
+//      （最终评审实测：set/subtract 不受影响——quarterOfYear 只包了 add——所以这个 bug
+//       躲过了「测了 set(object) 就以为 add(object) 也行」的抽查。）
+//   ② `localizedFormat` 排在 `advancedFormat` **之后**，于是它在外层、先跑：L/LL/LT/…
+//      先按 locale 展开成普通 token 串，再交给 advancedFormat 与核心 format 处理。
+for (const p of [relativeTime, duration, customParseFormat, advancedFormat, localizedFormat,
+  calendarPlugin, arraySupport, utcPlugin, minMax, isSameOrBefore, isSameOrAfter, isBetween,
+  isLeapYear, weekOfYear, isoWeek, quarterOfYear, dayOfYear, weekday, toArray, toObject,
+  objectSupport]) {
+  dayjs.extend(p)
+}
+// locale 只设这一处。moment 时代散在 install.js 与 plugins/frame.js 各写了一遍，
+// 而其中一遍还因为 moment 的双实例问题静默失效过（见 spec §1）。
+//
+// ⚠️⚠️ **这一句改的是 dayjs 的全局默认 locale，而 dayjs 与 Element Plus 是同一个实例**
+// （node_modules 里只有一份 dayjs@1.11.21，EP 的 `dependencies.dayjs` 指向它）。已知的
+// 两条外溢，裁定（R9）是**保留现行为 + 文档化，不做隔离**——`dayjs.locale('zh-cn')` 是
+// 本 shim 中文输出的前提，隔离掉会让 `locale()` 的对拍断言（必须返回 'zh-cn'）失效，
+// 而且中文平台上周一起始本来就更合理：
+//   ① `el-calendar` 的每周首日由**周日变周一**：EP 的
+//      element-plus/es/components/calendar/src/use-date-table.mjs:12 读的是
+//      `dayjs.localeData().firstDayOfWeek()`，取的正是这个全局默认 locale（zh-cn 的
+//      weekStart = 1）。
+//   ② `createMoment.locale('en')`（下面静态面那一行）会**全局翻掉** dayjs 的默认 locale，
+//      于是数据库里的一行页面 JS 就能改到 EP 的日期显示——这是 moment 时代没有的触达范围。
+// 同步记录在 docs/WINDOW-FRAME-ABI.md。
+dayjs.locale('zh-cn')
+
+// ⚠️ dayjs 内置 zh-cn 的 future 模板是 "%s内"，moment 是 "%s后"（node_modules 里两家
+// 的 locale 源码逐字节核对过，past 模板 "%s前" 一致，只有 future 不同）——受影响的不只
+// duration.humanize(true)，MomentLike 转发的 from/to/fromNow/toNow 在"未来方向"上全部
+// 会说错。全仓只有这一处 `dayjs.extend(relativeTime)`（grep 过，没有第二处），且 Element
+// Plus 自身的产物里搜不到 "relativeTime" 这个字符串（它不装这个插件，读不到这个字段），
+// 所以这里直接覆盖 dayjs 内置的 zh-cn 表，不会波及除本 shim 外的任何 dayjs 消费方。
+// 不改注册一份新 locale 的原因：`createMoment.locale()` / `m.locale()` 的对拍断言钉的是
+// 名字必须还是 'zh-cn'。
+dayjs.Ls['zh-cn'].relativeTime.future = '%s后'
+
+// ⚠️ 同上一处的做法（裁定 R11），补齐另外两张 dayjs 与 moment 内容不同的 zh-cn 子表。
+//
+// ① `meridiem`（A/a token）：dayjs 内置 zh-cn 的分界是 1100/1300，moment 是 **1130/1230**
+//    （node_modules/moment/locale/zh-cn.js:56,60 逐行核对）。差集实测：11:00–11:29 moment
+//    说「上午」dayjs 说「中午」、12:30–12:59 moment 说「下午」dayjs 说「中午」。这是一整段
+//    时间里的静默错字，`LLL`/`LLLL` 也会跟着错（它们的模板里含 A）。
+//    爆炸半径（本轮独立复核）：element-plus 全包对 "meridiem" 的引用 **0 次**；EP 自带的
+//    默认格式串是 HH:mm / HH:mm:ss / YYYY-MM-DD / gggg[w]ww，**没有一条含 A 或 a**；EP 里
+//    带字面量的 `.format()` 只有 `.format('M')` 三处。本仓自身的 13 种格式串也全部不含 A/a。
+// ② `calendar`：dayjs 的 zh-cn locale **根本没有这张表**，calendar 插件会退回它内置的英文
+//    默认值（`[Today at] h:mm A`）。不补的话 `$moment().calendar()` 输出英文——又是一个
+//    「看起来像样的错值」。表内容逐字抄自 moment zh-cn（moment/locale/zh-cn.js:66-83）。
+//    ⚠️ 两家对**函数型**取值的处理不同：moment 拿函数的返回值当格式串再 `format()` 一次，
+//    dayjs 是 `l.call(this, dayjs())` 后**直接返回**、不再 format。所以这里的两个函数必须
+//    自己调用 `this.format(...)`，不能照抄 moment 那样只返回格式串。
+dayjs.Ls['zh-cn'].meridiem = (hour, minute) => {
+  const hm = hour * 100 + minute
+  if (hm < 600) return '凌晨'
+  if (hm < 900) return '早上'
+  if (hm < 1130) return '上午'
+  if (hm < 1230) return '中午'
+  if (hm < 1800) return '下午'
+  return '晚上'
+}
+dayjs.Ls['zh-cn'].calendar = {
+  sameDay: '[今天]LT',
+  nextDay: '[明天]LT',
+  nextWeek (now) { return this.format(now.week() !== this.week() ? '[下]dddLT' : '[本]dddLT') },
+  lastDay: '[昨天]LT',
+  lastWeek (now) { return this.format(this.week() !== now.week() ? '[上]dddLT' : '[本]dddLT') },
+  sameElse: 'L'
+}
+
+// 只读方法：直接转发。除 clone 外返回的都不是日期对象，不需要再包一层。
+export const READ_METHODS = ['format', 'valueOf', 'unix', 'toDate', 'toISOString', 'toJSON',
+  'toString', 'toArray', 'toObject', 'diff', 'isValid', 'isBefore', 'isAfter', 'isSame',
+  'isSameOrBefore', 'isSameOrAfter', 'isBetween', 'isLeapYear', 'daysInMonth', 'clone',
+  'get', 'from', 'to', 'fromNow', 'toNow', 'utcOffset', 'weekday', 'isoWeekday',
+  // `calendar` 是本仓自己的页面 JS 编写指南（.claude/skills/epx-frame-web/tools/Moment日期.md）
+  // 教过的写法，漏了它等于指南里的示例一跑就抛错。
+  'calendar']
+
+// 写方法：改内部 dayjs 实例并 return this —— 这就是"模拟可变"的全部内容。
+export const WRITE_METHODS = ['add', 'subtract', 'startOf', 'endOf', 'set', 'local', 'utc',
+  'locale', 'year', 'month', 'date', 'day', 'hour', 'minute', 'second', 'millisecond',
+  'quarter', 'week', 'isoWeek', 'dayOfYear']
+
+// ⚠️ 这些是 **getter/setter 双身份**：无参取值（返回 number/string），有参赋值（返回 this）。
+// moment 就是这个语义。按 arguments.length 分支，写错一边是静默错值、没有任何报错。
+export const DUAL_METHODS = new Set(['locale', 'year', 'month', 'date', 'day', 'hour',
+  'minute', 'second', 'millisecond', 'quarter', 'week', 'isoWeek', 'dayOfYear'])
+
+// ⚠️ 框架探针放行名单。**漏了会白屏**：Vue 3 的 reactive/isRef 会读 `__v_*`，
+// Promise 解析会读 `then`，模板与 JSON 序列化会读 Symbol.toPrimitive / toJSON。
+// 这些必须返回 undefined 或真实值，绝不能抛错。
+export const PASSTHROUGH = new Set(['then', 'nodeType', 'tagName', 'length', 'name',
+  'constructor', 'hasOwnProperty', 'isPrototypeOf', 'propertyIsEnumerable',
+  '__v_isRef', '__v_isReactive', '__v_isReadonly', '__v_raw', '__v_skip',
+  '_isAMomentObject', '_d', '$$typeof'])
+
+class MomentLike {
+  constructor (d) {
+    this._d = d
+    // 让 Vue 的 reactive() 整体跳过本对象：日期对象没有需要被追踪的内部字段，
+    // 包进响应式只有开销（本仓已有 meta markRaw 的同类处置）。
+    this.__v_skip = true
+    // 存量代码可能用 moment 的这个内部标记判型
+    this._isAMomentObject = true
+  }
+}
+
+function wrapMaybe (v) {
+  return dayjs.isDayjs(v) ? createMoment(v) : v
+}
+
+// 转发只读方法前，把参数里混入的 MomentLike 换成它内部的裸 dayjs 实例（比如
+// a.diff(b)、a.from(b) 的 b）：dayjs 的 diff/from 等实现会直接读参数上的内部字段
+// （如 $u、$isDayjsObject），不会先规整成 dayjs()。MomentLike 是 Proxy，这些字段
+// 不在白名单里，直接传给 dayjs 会被当成「不在覆盖范围」抛错（实测：
+// createMoment(a).diff(createMoment(b)) 会命中）。判据与上面 createMoment 里
+// `input._d` 同一个套路。
+function unwrapMaybe (v) {
+  return (v && v._d) ? v._d : v
+}
+
+for (const name of READ_METHODS) {
+  MomentLike.prototype[name] = function (...args) {
+    return wrapMaybe(this._d[name](...args.map(unwrapMaybe)))
+  }
+}
+
+// moment 对无效日期输出 "Invalid date"（小写 d），dayjs 输出 "Invalid Date"。
+// 这个串可能被直接显示或参与比较，必须对齐到 moment 那一侧。
+const INVALID = 'Invalid date'
+
+// ⚠️ **无效日期的兜底值**。数据库里的日期字段可空，`$moment(row.SOME_DATE)` 拿到
+// null/''/非法串是这个平台的日常，所以这条路径不是边角。moment 对无效日期有一套统一兜底
+// （数值 getter → NaN、字符串输出 → 'Invalid date'、toISOString/toJSON → null）；dayjs 大部分
+// 对得上（year()/month()/diff()/valueOf() 都给 NaN，toJSON 给 null），但下面这 6 个没有——
+// 生成式矩阵（方法 × 入参形态）扫出来的，逐条都是"看起来像样的错值"或读不懂的内部错：
+//   toISOString  moment: null          dayjs: **抛 RangeError: Invalid time value**
+//   isoWeekday   moment: NaN           dayjs: 7（实现是 `$W || 7`，NaN 落进了 || 分支）
+//   from/to      moment: 'Invalid date' dayjs: '1 个月前'（拿 NaN 去做差，档位随机）
+//   fromNow/toNow 同上
+//   calendar     moment: 'Invalid date' dayjs: 'Invalid Date'（大小写，插件内部直接 format）
+const INVALID_FALLBACKS = {
+  toISOString: null,
+  isoWeekday: NaN,
+  calendar: INVALID,
+  from: INVALID,
+  to: INVALID,
+  fromNow: INVALID,
+  toNow: INVALID
+}
+// from/to 的**参照物**也可能无效（`ref.from(null)`），moment 同样给 'Invalid date'。
+const CHECKS_ARG = new Set(['from', 'to'])
+
+for (const [name, fallback] of Object.entries(INVALID_FALLBACKS)) {
+  const raw = MomentLike.prototype[name]
+  MomentLike.prototype[name] = function (...args) {
+    if (!this._d.isValid()) return fallback
+    if (CHECKS_ARG.has(name) && args[0] !== undefined) {
+      const other = unwrapMaybe(args[0])
+      if (!dayjs(other).isValid()) return fallback
+    }
+    return raw.apply(this, args)
+  }
+}
+
+// ⚠️ moment 的 68 个 format token 里，有 16 个是 dayjs + 本文件所装插件**给不出同样输出**的。
+// 它们分三类，共同点是**全都不报错**：
+//   · 静默错值：`DDD`/`DDDD`（年内第几天）在 dayjs 下会被当成 D 系 token，2026-09-02 输出
+//     "022"/"0202"，moment 是 "245"——像模像样，肉眼查不出来；
+//   · 原样吐字面量：`Qo` `Mo` `do` `Wo` `e` `E` `gg` `GG` `N` `NN` 输出的就是 token 本身；
+//   · 抛一个读不懂的内部错：`gggg` → `t.weekYear is not a function`，`z`/`zz` → `t.offsetName
+//     is not a function`（advancedFormat 会去调 weekYear/timezone 插件的方法，我们没装）。
+// 按用户裁定的绑定姿态（厚 shim、不留逃生开关、覆盖面外**响亮抛错**），这里在入口就把这批
+// token 拦下抛错。**这比逐个实现它们更便宜也更正确**：一整类静默错值换成一条自解释的报错。
+//
+// ⚠️ `y`（连同 `yy`/`yyy`/`yyyy`）**曾经也在这张表里**：第一轮修复把它当成「原样吐字面量」
+// 一类一并拦下抛错，随后评审抓到这是个**新引入的一等回归**——
+// packages/components/src/form-item/Date.vue:622 的 isDateNow 分支里有一句 moment 时代遗留的
+// `format('yyyy')`（历史写法，意为"当年 4 位数字"），shim 改成抛错后会整段打断 Vue 的
+// created() 钩子，isDateNow 之后的 pickerOptions/rangePickerOptions 设置也一并丢失（本仓无
+// app.config.errorHandler，Vue 只会打日志、不会让钩子继续跑）。这个 token 组便宜到可以直接
+// 实现（见下方 preprocessFormat 里紧挨 S+ 的那段），犯不着让"响亮抛错"这个姿态去背一个自己
+// 填得平的坑，于是把它从这张「拦下抛错」表里挪走，改走计算路径。
+//
+// 不在这张表里、经逐 token 对拍确认与 moment 逐字节一致的（别顺手加进来）：
+//   YYYY YY M MM MMM MMMM D DD Do d dd ddd dddd H HH h hh k kk m mm s ss SSS Z ZZ A a X x
+//   Q w ww wo W WW **GGGG**（isoWeek 插件提供 isoWeekYear，实测两边都是 "2026"）
+//   L LL LLL LLLL l ll lll llll LT LTS（localizedFormat 插件 + 上面补的 zh-cn formats）
+// ⚠️ 顺序即语义：长的必须排在短的前面（见下面正则的说明）。
+export const UNSUPPORTED_FORMAT_TOKENS = ['DDDo', 'DDDD', 'DDD', 'Mo', 'Qo', 'do', 'Wo',
+  'gggg', 'gg', 'GG', 'NN', 'N', 'zz', 'z', 'E', 'e']
+
+// moment 的亚秒 token：S=十分秒、SS=百分秒、SSS=毫秒。dayjs 只认 SSS，
+// 遇到 S / SS 会**原样吐字面量**（实测 `format('YYYYMMDDHHMMSS')` → "202609021309SS"）。
+// 这里把 S / SS（以及 moment 支持的 4 位以上）现算成数字字面量再交给 dayjs。
+//
+// `y`/`yy`/`yyy`/`yyyy` 同款处理（不走上面的抛错表，见该表旁边的说明）：这四个 token
+// 在 moment 里都是 eraYear（本仓未启用自定义 era，等价于 `this.year()`），左补零到至少
+// token 长度那么多位——不是「取后 N 位」（那是 `YY` 的语义）。逐字节核对自
+// node_modules/moment/moment.js 的 `zeroFill` + `addFormatToken('y', ['yyyy', 4], ...)`。
+// 本仓年份都是公元后 4 位数，补零目标位数（1~4）从不超过实际位数，所以 y/yy/yyy/yyyy 四种
+// 写法输出永远相同（都是完整的 4 位年份）。dayjs 核心 format 正则本就不认识小写 `y`
+// （node_modules/dayjs/dayjs.min.js 的 REGEX_FORMAT 没有这个分支），原生会把它当字面量原样
+// 吐出——这正是这个坑过去是"静默错值"而不是"抛错"的原因。
+//
+// 扫描用的这条正则同时承担三件事，**分支顺序是语义相关的**（JS 的 `|` 是有序的，
+// 同一位置先匹配上的赢），照 moment 自己的 formattingTokens 那套「长的排前面」写法：
+//   · `\[[^\]]*\]` 排最前——方括号转义段必须整体跳过（`format('[SS]')` 要输出 "SS"，
+//     `format('[yyyy]')` 同理要输出字面量 "yyyy"）；
+//   · `LTS` 必须排在 `S+` 前面，否则 `format('LTS')` 会被当成「LT + 十分秒」吐出 "LT0"；
+//   · `GGGG` 必须排在 `GG` 前面，否则一个**受支持**的 token 会被误判成不支持而抛错；
+//   · `DDDo`>`DDDD`>`DDD`、`gggg`>`gg`、`NN`>`N` 同理，保证报错信息指的是真正写的那个 token。
+// 反过来，`Mo`/`Qo`/`do`/`Wo` 都以字面 'o' 收尾，`MMMM`/`Q`/`dddd`/`WW` 这些受支持的写法
+// 匹配不上它们，不会误伤（大小写敏感：受支持的 `Do` 与不支持的 `do` 是两个 token）。
+// `y{1,4}` 自带的量词上限就是 4：`yyyyy`（5 个 y）第一轮贪婪吃掉前 4 个算一个 token，
+// 剩下 1 个在下一轮匹配里再算一个 token，两段各自算出同一个年份再拼接
+// （2026 年实测：`"2026" + "2026"` = "20262026"），与 moment 自己的 formattingTokens
+// 正则（同样只认到 4 个连续 y）行为一致。
+// 正则的大部分由上面那张表**推导**而来，不手写第二份——两份会漂；`y{1,4}` 是唯一手写的
+// 例外，因为它不再属于「拦下抛错」表，没有现成的数组可供 spread。
+const FORMAT_SCAN_RE = new RegExp(
+  ['\\[[^\\]]*\\]', 'LTS', 'GGGG', ...UNSUPPORTED_FORMAT_TOKENS, 'S+', 'y{1,4}'].join('|'), 'g')
+
+export function preprocessFormat (fmt, ms, year) {
+  if (typeof fmt !== 'string') return fmt
+  return fmt.replace(FORMAT_SCAN_RE, (seg) => {
+    // 转义段与「含 S/GG 但其实受支持」的两个 token：原样交给 dayjs
+    if (seg[0] === '[' || seg === 'LTS' || seg === 'GGGG') return seg
+    if (seg[0] === 'S') {
+      if (seg.length === 3) return seg // SSS：dayjs 原生支持，别碰
+      if (seg.length === 1) return String(Math.floor(ms / 100))
+      if (seg.length === 2) return String(Math.floor(ms / 10)).padStart(2, '0')
+      return String(ms).padStart(3, '0').padEnd(seg.length, '0')
+    }
+    if (seg[0] === 'y') {
+      // moment 的 zeroFill：负数保留符号位、对绝对值左补零，不能对带符号的字符串直接
+      // padStart（会把 0 垫进符号和数字之间，比如 "-5" 变成 "00-5"）。本仓实际年份恒正，
+      // 这里只是照 zeroFill 的算法补全，不额外增加行为面。
+      const sign = year < 0 ? '-' : ''
+      return sign + String(Math.abs(year)).padStart(seg.length, '0')
+    }
+    throw new Error(
+      `[epx-moment] format 串里的 \`${seg}\` 不在兼容层覆盖范围内。\n` +
+      '  本平台已从 moment 迁移到 dayjs，$moment 是一层兼容 shim。\n' +
+      '  dayjs 对这个 token 会静默给出错值（或抛一个读不懂的内部错），所以这里主动拦下——\n' +
+      `  想输出字面量 "${seg}" 请写成 [${seg}]（方括号是 moment/dayjs 通用的转义）。\n` +
+      '  确实需要这个 token 请补进 packages/utils/src/moment-compat.js；\n' +
+      '  临时可用 $moment(x).toDate() 拿到原生 Date 自行处理。'
+    )
+  })
+}
+
+MomentLike.prototype.format = function (fmt) {
+  if (!this._d.isValid()) return INVALID
+  return this._d.format(preprocessFormat(fmt, this._d.millisecond(), this._d.year()))
+}
+
+// ⚠️ 必须覆盖（不能走 READ_METHODS 那条通用转发）：**两家的 toString 输出完全不同**。
+//   moment：`Wed Sep 02 2026 13:45:06 GMT+0800`（本地时区、英文、逐字节抄自
+//           moment/src/lib/moment/prototype.js 的 `this.clone().locale('en')
+//           .format('ddd MMM DD YYYY HH:mm:ss [GMT]ZZ')`）
+//   dayjs ：`Wed, 02 Sep 2026 05:45:06 GMT`（它的 toString 就是 `$d.toUTCString()`——
+//           **连时区都换成 UTC 了**）
+// 这条是线上可见的：Vue 的 toDisplayString 对「带自定义 toString 的对象」走 String(val)，
+// 所以模板里的 `{{ dateObj }}`、字符串拼接、以及公式引擎把 DATE_ADD/DATE_SUBTRACT 的返回值
+// 当结果流出去（util.js:958）时，出来的都是这个串。
+// ⚠️ `_d.locale('en')` 返回的是新实例（dayjs 不可变），不会污染本对象的 locale。
+MomentLike.prototype.toString = function () {
+  if (!this._d.isValid()) return INVALID
+  return this._d.locale('en').format('ddd MMM DD YYYY HH:mm:ss [GMT]ZZ')
+}
+
+for (const name of WRITE_METHODS) {
+  MomentLike.prototype[name] = function (...args) {
+    if (DUAL_METHODS.has(name) && args.length === 0) return this._d[name]()
+    // 参数同样过一遍 unwrapMaybe：查过 dayjs 核心与这里装的插件（utc/duration/
+    // quarterOfYear/weekOfYear/isoWeek/dayOfYear）的源码，20 个写方法目前都没有
+    // 像 diff/isSame 那样直读参数内部字段的写法，此刻还搭不出复现用例；但对非
+    // MomentLike 的参数它是纯 no-op，跟只读转发保持同一防线不吃亏。
+    this._d = this._d[name](...args.map(unwrapMaybe))
+    return this
+  }
+}
+
+// —— set(object)：自己归一化 + 排序 + 逐个下发，不交给 dayjs 的 objectSupport ——
+//
+// moment 的 stringSet 是「normalizeObjectUnits 归一化键名 → getPrioritizedUnits 按
+// priorities 表升序排 → 逐个 this[unit](value)」。dayjs 的 objectSupport 两点都不同：
+// 按字面键序下发，且它的 set 只认核心那几个单位。实测两类分歧（改前 6/13 不一致）：
+//   ① 键序敏感：`set({date:31, month:1})` moment 先设 2 月再设 31 日 ⇒ 2 月 31 日**溢出**
+//      成 2026-03-03；dayjs 按字面序先设 31 日再设 2 月 ⇒ 2026-02-01。
+//   ② 单位面：quarter / week / isoWeek / dayOfYear 这四个 dayjs 的 set 不认，**静默忽略**
+//      （`set({year:2030, quarter:2})` 只有年生效）。静默错值正是本 shim 要消灭的失败模式。
+// 下面两张表逐字抄自 moment 2.30.1 的 src/lib/units/{aliases,priorities}.js。
+const UNIT_ALIASES = {
+  D: 'date',
+  dates: 'date',
+  date: 'date',
+  d: 'day',
+  days: 'day',
+  day: 'day',
+  e: 'weekday',
+  weekdays: 'weekday',
+  weekday: 'weekday',
+  E: 'isoWeekday',
+  isoweekdays: 'isoWeekday',
+  isoweekday: 'isoWeekday',
+  DDD: 'dayOfYear',
+  dayofyears: 'dayOfYear',
+  dayofyear: 'dayOfYear',
+  h: 'hour',
+  hours: 'hour',
+  hour: 'hour',
+  ms: 'millisecond',
+  milliseconds: 'millisecond',
+  millisecond: 'millisecond',
+  m: 'minute',
+  minutes: 'minute',
+  minute: 'minute',
+  M: 'month',
+  months: 'month',
+  month: 'month',
+  Q: 'quarter',
+  quarters: 'quarter',
+  quarter: 'quarter',
+  s: 'second',
+  seconds: 'second',
+  second: 'second',
+  w: 'week',
+  weeks: 'week',
+  week: 'week',
+  W: 'isoWeek',
+  isoweeks: 'isoWeek',
+  isoweek: 'isoWeek',
+  y: 'year',
+  years: 'year',
+  year: 'year'
+}
+const UNIT_PRIORITY = {
+  year: 1,
+  dayOfYear: 4,
+  week: 5,
+  isoWeek: 5,
+  quarter: 7,
+  month: 8,
+  date: 9,
+  day: 11,
+  weekday: 11,
+  isoWeekday: 11,
+  hour: 13,
+  minute: 14,
+  second: 15,
+  millisecond: 16
+}
+// 归一化后的单位 → 怎么在裸 dayjs 实例上设它。都走各自的 setter 而不是 `d.set(unit,v)`，
+// 因为后者认不得 quarter/week/isoWeek/dayOfYear（这四个是插件加在原型上的方法）。
+const UNIT_SETTER = {
+  year: (d, v) => d.year(v),
+  month: (d, v) => d.month(v),
+  date: (d, v) => d.date(v),
+  day: (d, v) => d.day(v),
+  weekday: (d, v) => d.weekday(v),
+  isoWeekday: (d, v) => d.isoWeekday(v),
+  hour: (d, v) => d.hour(v),
+  minute: (d, v) => d.minute(v),
+  second: (d, v) => d.second(v),
+  millisecond: (d, v) => d.millisecond(v),
+  quarter: (d, v) => d.quarter(v),
+  week: (d, v) => d.week(v),
+  isoWeek: (d, v) => d.isoWeek(v),
+  dayOfYear: (d, v) => d.dayOfYear(v)
+}
+
+MomentLike.prototype.set = function (unit, value) {
+  if (unit === null || typeof unit !== 'object') {
+    this._d = this._d.set(unit, value)
+    return this
+  }
+  const pending = []
+  for (const key of Object.keys(unit)) {
+    // 与 moment 一致：认不出的键**静默丢弃**，不抛错（normalizeObjectUnits 就是这么做的）
+    const u = UNIT_ALIASES[key] || UNIT_ALIASES[String(key).toLowerCase()]
+    if (u) pending.push([u, unit[key]])
+  }
+  // moment 的 weekYear/isoWeekYear（priority 1）本 shim 覆盖不到——dayjs 没有对应能力。
+  // 上面的别名表里就没有它们，所以会走「静默丢弃」；这与 moment 不一致，但这两个单位
+  // 连单独调用都不在白名单里，此处保持与 shim 其余部分同一覆盖面。
+  pending.sort((a, b) => UNIT_PRIORITY[a[0]] - UNIT_PRIORITY[b[0]])
+  for (const [u, v] of pending) this._d = UNIT_SETTER[u](this._d, v)
+  return this
+}
+
+// ⚠️ 必须在两个安装循环都跑完之后再构造：READ_METHODS 装完时 WRITE_METHODS
+// 还是空数组，若在此提前构造，所有写方法都会被这份白名单挡下抛错。
+const ALLOWED = new Set([...READ_METHODS, ...WRITE_METHODS])
+
+/**
+ * 造一个 moment 风格的日期对象。入参形态与 moment 一致（无参=当前时间、
+ * 字符串、时间戳、Date、dayjs 对象、MomentLike、对象/数组字面量）。
+ */
+function createMoment (input, ...rest) {
+  let d
+  if (arguments.length === 0) d = dayjs()
+  // ⚠️ 已经是 dayjs / MomentLike 的，**直接取用内部实例，别再过一次 dayjs()**：
+  //    再过一次会丢掉 UTC 模式等内部状态（createMoment.utc(...) 会因此按本地时区
+  //    格式化、跨时区差一天）。dayjs 不可变，共享内部实例是安全的——本包装类的写方法
+  //    是「替换 _d」而不是「原地改 _d」，两个包装对象共享初始实例互不影响。
+  //
+  // ⚠️ MomentLike 分支必须排在 dayjs.isDayjs(input) 前面（实测踩坑）：MomentLike 是
+  // Proxy，dayjs.isDayjs 内部会读 `$isDayjsObject` 这类不在白名单里的字段，对它调用
+  // 会被当成「不在覆盖范围」抛错——createMoment(既有的 MomentLike) 直接命中。
+  // `input._d` 是安全探测：_d 在 PASSTHROUGH 里，裸 dayjs 实例上则没有这个字段。
+  else if (input && input._d) d = input._d
+  else if (dayjs.isDayjs(input)) d = input
+  else d = dayjs(input, ...rest)
+  const inst = new MomentLike(d)
+  return new Proxy(inst, {
+    get (target, prop, receiver) {
+      if (typeof prop === 'symbol') return Reflect.get(target, prop, receiver)
+      // ⚠️ 判据是「**自有**字段」（_d / __v_skip / _isAMomentObject），**不能**写成
+      // `prop in target`——`in` 会一路走到 Object.prototype，于是 toLocaleString /
+      // __defineGetter__ / __lookupGetter__ 这类继承成员全部被当成"在覆盖范围内"静默放行。
+      // `toLocaleString` 尤其阴：moment 那边它等价于 toString()，dayjs 这边它同样落到
+      // toString 上，但两家 toString 的输出本来就不同（见上面的覆盖），放行等于把一个错值
+      // 伪装成"支持"。原型上的方法一律由 ALLOWED 白名单负责。
+      // ⚠️ 用 `hasOwnProperty.call` 而不是 `Object.hasOwn`：后者是 ES2022，要 iOS 15.4+，
+      // 而本仓的目标面里有更老的 iOS（曾因正则 lookbehind 需要 iOS 16.4 而整块白屏，见
+      // 那次事故记录）。语义完全一样，兼容面白赚。
+      if (ALLOWED.has(prop) || PASSTHROUGH.has(prop) ||
+        Object.prototype.hasOwnProperty.call(target, prop)) {
+        return Reflect.get(target, prop, receiver)
+      }
+      throw new Error(
+        `[epx-moment] \`$moment(...).${prop}\` 不在兼容层覆盖范围内。\n` +
+        '  本平台已从 moment 迁移到 dayjs，$moment 是一层兼容 shim。\n' +
+        '  需要这个 API 请补进 packages/utils/src/moment-compat.js；\n' +
+        '  临时可用 $moment(x).toDate() 拿到原生 Date 自行处理。'
+      )
+    }
+  })
+}
+
+// moment 的 duration.humanize() 默认阈值 + 天↔月固定换算常数，逐字节抄自
+// node_modules/moment/src/lib/duration/{humanize,bubble}.js（本仓没有任何
+// moment.relativeTimeThreshold() 调用改过默认阈值）。dayjs 自己的 duration.humanize()
+// 有两个问题：① 内部靠 `dayjs().add(ms,'ms').fromNow()` 读两次「真实现在」做差再分类，
+// 卡在四舍五入边界的值（比如 90 分钟＝1.5 小时）会被两次取值间的执行耗时污染，几毫秒的
+// 调度延迟就能把「2 小时」翻成「1 小时」；② 月/年分类靠 dayjs 的 `.diff()`，那是**日历
+// 感知**的（按相邻月份的真实天数做除法），而 moment 用的是固定比例 `days*4800/146097`
+// （400 个公历年=146097 天=4800 个月，摊平闰年后的常数）——两者在月/年边界上会给出不同
+// 档位（实测 46/75/546 天这三个值两套算法各不相同，且哪边"更接近真值"不重要，重要的是
+// 必须和 moment 一致）。这里干脆不用 dayjs 的日期做差，直接从 duration 的毫秒值按 moment
+// 的算法分类——时钟依赖和日历依赖一起消失。
+const DURATION_THRESHOLDS = { ss: 44, s: 45, m: 45, h: 22, d: 26, M: 11 }
+const daysToMonths = (days) => (days * 4800) / 146097
+const monthsToDays = (months) => (months * 146097) / 4800
+
+// ── duration 的「三桶」还原 ────────────────────────────────────────────────────
+// moment 的 Duration 内部是**三个互不折算的桶**：`_milliseconds` / `_days` / `_months`
+// （构造时写进去就定死，见 moment/src/lib/duration/constructor.js），`as()` 与 `humanize()`
+// 都按这三个桶算。dayjs 把一切塌缩成一个 `$ms`，桶信息**原则上已经丢了**——
+// 但它派生出来的 `$d` 用的月长是固定的 365/12 天（= 2628000000ms），所以按月/季/年单位
+// 构造时 `$ms` 恰好是这个常数的整数倍，`$d.years*12 + $d.months` 能把当初写进去的月数
+// **原样取回**。于是判据是「$d 里比月更小的位是否全为 0」：
+//   · 是（且确有年或月）⇒ 认定「按月/季/年构造」，还原成 `_months`，`_ms` 归 0；
+//   · 否 ⇒ 一律当成纯毫秒（`_days` = `_months` = 0）。这条与 dayjs 自己的算法等价，
+//         不改变现状（本仓 6 个调用点全走这条）。
+// ⚠️ 已知残留（实测无法消除）：`duration(47304000000)` 与 `duration(18,'M')` 在 dayjs 里
+// 是**同一个对象**（前者正好是 18 个 dayjs 月的毫秒数），而 moment 分得清——前者 `_ms`
+// 桶、后者 `_months` 桶，`humanize()` 一个给「1 年」一个给「2 年」。要消除只能自己重写
+// moment 的三桶模型。命中它需要写一个 2628000000 的整数倍毫秒值。
+function durationBuckets (d) {
+  // ⚠️ `$d` 的字段在不同构造形态下并不齐全（`duration({months:18})` 只有 months 一个键、
+  // `duration('abc')` 是空对象、ISO 串还会多出 weeks），所以逐个 `|| 0` 兜底，别解构带默认值。
+  const b = d.$d || {}
+  const ms = d.$ms || 0
+  const exact = !b.days && !b.hours && !b.minutes && !b.seconds && !b.milliseconds &&
+    !b.weeks && (b.years || b.months)
+  return exact ? { ms: 0, months: (b.years || 0) * 12 + (b.months || 0) } : { ms, months: 0 }
+}
+
+// moment 的 `as(units)`，逐行抄自 moment/src/lib/duration/as.js。
+// 'month'/'quarter'/'year' 与其余单位是**两个独立分支**（前者按月折算、后者按天折算），
+// 且后者会先把月数 `Math.round` 成整天——这一步是两家差异的主要来源
+// （`duration(1,'M').asHours()`：moment 走 round(30.436875)=30 天 ⇒ 720，dayjs 直接
+//  $ms/36e5 ⇒ 730）。生成式矩阵实测 9720 组里 4872 组不一致，全部落在含年/月/季的换算上。
+function durationAs (d, unit) {
+  const { ms, months } = durationBuckets(d)
+  if (unit === 'month' || unit === 'quarter' || unit === 'year') {
+    const m = months + daysToMonths(ms / 864e5)
+    return unit === 'month' ? m : unit === 'quarter' ? m / 3 : m / 12
+  }
+  const days = Math.round(monthsToDays(months))
+  switch (unit) {
+    case 'week': return days / 7 + ms / 6048e5
+    case 'day': return days + ms / 864e5
+    case 'hour': return days * 24 + ms / 36e5
+    case 'minute': return days * 1440 + ms / 6e4
+    case 'second': return days * 86400 + ms / 1e3
+    case 'millisecond': return Math.floor(days * 864e5) + ms
+    // ⚠️ 不要把这个 default 写成"当毫秒处理"——那就是本次要消灭的那种静默错值
+    // （`as('bogus')` 会安静地返回一个毫秒数）。moment 在这里也是抛 `Unknown unit`。
+    default: throw new Error(
+      `[epx-moment] \`$moment.duration(...).as('${unit}')\` 的单位无法识别。\n` +
+      '  可用单位：ms/s/m/h/d/w/M/Q/y（或它们的完整名，大小写敏感：M=月、m=分钟）。'
+    )
+  }
+}
+
+// ⚠️ 大小写敏感：`M` 是月、`m` 是分钟。所以先原样查表，查不到再小写查一次
+// （与 moment 的 normalizeUnits 同款：`aliases[u] || aliases[u.toLowerCase()]`）。
+const DURATION_UNITS = {
+  ms: 'millisecond',
+  millisecond: 'millisecond',
+  milliseconds: 'millisecond',
+  s: 'second',
+  second: 'second',
+  seconds: 'second',
+  m: 'minute',
+  minute: 'minute',
+  minutes: 'minute',
+  h: 'hour',
+  hour: 'hour',
+  hours: 'hour',
+  d: 'day',
+  day: 'day',
+  days: 'day',
+  w: 'week',
+  week: 'week',
+  weeks: 'week',
+  M: 'month',
+  month: 'month',
+  months: 'month',
+  Q: 'quarter',
+  quarter: 'quarter',
+  quarters: 'quarter',
+  y: 'year',
+  year: 'year',
+  years: 'year'
+}
+const normalizeDurationUnit = (u) =>
+  (typeof u === 'string' && (DURATION_UNITS[u] || DURATION_UNITS[u.toLowerCase()])) || u
+
+// dayjs 的 Duration 原型里**没有 asQuarters**（实测 Object.getOwnPropertyNames 里查无此名），
+// moment 有——不补的话是一句读不懂的 `d.asQuarters is not a function`。
+const AS_METHODS = {
+  asMilliseconds: 'millisecond',
+  asSeconds: 'second',
+  asMinutes: 'minute',
+  asHours: 'hour',
+  asDays: 'day',
+  asWeeks: 'week',
+  asMonths: 'month',
+  asQuarters: 'quarter',
+  asYears: 'year'
+}
+
+// 分档表本身与 moment 的 humanize.js 一致（见上面 DURATION_THRESHOLDS 那段），
+// 月/年两档的月数改走 durationAs('month') ⇒ 三桶还原（裁定 R10）：
+// `duration(18,'M')` 从「17.99/12=1.499 → 1 年」修正成「18/12=1.5 → 2 年」，与 moment 一致。
+function classifyDuration (d) {
+  // ⚠️ 不可解析的输入（如 dayjs.duration('abc')）内部 $ms 是 undefined，兜底成 0——
+  // moment 对同样的无效输入按空 duration 处理，humanize() 给"几秒"；不兜底的话
+  // `dayjs(undefined)` 会被当成"现在"，算出一个跟输入毫无关系的"57 年"。
+  const abs = Math.abs(d.$ms || 0)
+  const t = DURATION_THRESHOLDS
+  const seconds = Math.round(abs / 1e3)
+  const minutes = Math.round(abs / 6e4)
+  const hours = Math.round(abs / 36e5)
+  const days = Math.round(abs / 864e5)
+  // 年份必须用**未取整**的月数算，不能拿下面已取整的 months 再除 12——moment 的 as.js 里
+  // 'month' 与 'year' 是两个独立分支，各算各的。月数走三桶还原（见 durationBuckets）。
+  const monthsExact = Math.abs(durationAs(d, 'month'))
+  const months = Math.round(monthsExact)
+  const years = Math.round(monthsExact / 12)
+  return (
+    (seconds <= t.ss && ['s', seconds]) ||
+    (seconds < t.s && ['ss', seconds]) ||
+    (minutes <= 1 && ['m', 1]) ||
+    (minutes < t.m && ['mm', minutes]) ||
+    (hours <= 1 && ['h', 1]) ||
+    (hours < t.h && ['hh', hours]) ||
+    (days <= 1 && ['d', 1]) ||
+    (days < t.d && ['dd', days]) ||
+    (months <= 1 && ['M', 1]) ||
+    (months < t.M && ['MM', months]) ||
+    (years <= 1 && ['y', 1]) || ['yy', years]
+  )
+}
+
+function humanizeDuration (d, withSuffix) {
+  const [key, count] = classifyDuration(d)
+  const rt = dayjs.Ls[d.$l].relativeTime
+  const text = rt[key].replace('%d', count)
+  if (!withSuffix) return text
+  // moment 的 pastFuture(diff, output)：diff > 0 ? future : past（逐字节核对过
+  // node_modules/moment/src/lib/locale/relative.js），diff 用的是**带符号**的原值，
+  // 不是 classifyDuration 里已经取绝对值那份。
+  return ((d.$ms || 0) > 0 ? rt.future : rt.past).replace('%s', text)
+}
+
+// dayjs 的 add/subtract/clone/locale 都经内部工厂返回全新的 Duration 实例，带的是
+// 未打补丁的原型 humanize——不重新套一遍的话，`$moment.duration(60,'m').add(30,'m')
+// .humanize()` 又会掉回本节要消灭的那个实现。这四个是 dayjs duration 原型里*仅有的*
+// 会返回新 Duration 实例的方法（其余方法要么返回数字，要么就是 humanize 本身）。
+// __patched 短路：subtract 内部会调用 add、locale 内部会调用 clone，两条路径下这个
+// 补丁函数天然会在同一个新实例上被再调一次，短路成本很低，但能防止链式调用
+// （.subtract().subtract()...）让包装层数无限堆叠。
+function patchDuration (d) {
+  if (d.__patched) return d
+  d.__patched = true
+  d.humanize = (withSuffix) => humanizeDuration(d, withSuffix)
+  // as* 同样要按 moment 的算法重来一遍（不是 humanize 的附属，是独立的一族输出）。
+  d.as = (unit) => durationAs(d, normalizeDurationUnit(unit))
+  for (const [name, unit] of Object.entries(AS_METHODS)) d[name] = () => durationAs(d, unit)
+  for (const name of ['add', 'subtract', 'clone', 'locale']) {
+    const raw = d[name].bind(d)
+    d[name] = (...args) => patchDuration(raw(...args))
+  }
+  return d
+}
+
+// ⚠️ 两处入参规整，都是"静默错值"级别的坑：
+// ① `args[0] ?? 0`：`dayjs.duration(null)` 会抛 `Cannot convert undefined or null to object`，
+//    moment 的 `duration(null)` 返回零时长。duration 的入参最常见的来源就是可空的数据库字段，
+//    而 §2.2 的消费方 ①③④（页面 JS / 产品项目 / 公式引擎）都直接够得着这个静态面。
+//    （本仓那 2 个调用点紧挨的上一行有 `if (!duration) return null`，所以仓库自身撞不到。）
+// ② **季度单位**：dayjs 的 duration 插件压根不认 'Q'/'quarter'，`dayjs.duration(1,'Q').$ms`
+//    实测是 **0** —— `humanize()` 说"几秒"、`asDays()` 说 0，而 moment 是 3 个月 / 91 天。
+//    一整个单位静默归零。这里按 moment 的定义（1 季 = 3 个月）折成月再交给 dayjs。
+const QUARTER_KEYS = ['Q', 'quarter', 'quarters']
+function normalizeDurationArgs (args) {
+  const [input, unit] = args
+  if (normalizeDurationUnit(unit) === 'quarter') return [(input ?? 0) * 3, 'M']
+  if (input && typeof input === 'object' && !(input instanceof Date) && !Array.isArray(input)) {
+    const q = QUARTER_KEYS.reduce((sum, k) => sum + (input[k] || 0), 0)
+    if (q) {
+      const rest = { ...input }
+      for (const k of QUARTER_KEYS) delete rest[k]
+      return [{ ...rest, months: (rest.months || 0) + q * 3 }, ...args.slice(1)]
+    }
+  }
+  return [input ?? 0, ...args.slice(1)]
+}
+createMoment.duration = (...args) => patchDuration(dayjs.duration(...normalizeDurationArgs(args)))
+// ⚠️ 这一行会改掉 **dayjs 的全局默认 locale**，进而改到 Element Plus（el-calendar 的每周
+// 首日等），见文件顶部 `dayjs.locale('zh-cn')` 处的长注释与裁定 R9。moment 时代没有这个触达范围。
+createMoment.locale = (...args) => dayjs.locale(...args)
+createMoment.isMoment = (v) => !!(v && v._isAMomentObject === true)
+createMoment.unix = (sec) => createMoment(dayjs.unix(sec))
+createMoment.utc = (...args) => createMoment(dayjs.utc(...args))
+createMoment.max = (...args) => createMoment(dayjs.max(args.flat().map(unwrapMaybe)))
+createMoment.min = (...args) => createMoment(dayjs.min(args.flat().map(unwrapMaybe)))
+
+// 静态面的 7 个方法（与 spec §4.3 的清单一致）。
+const STATIC_ALLOWED = new Set(['duration', 'locale', 'isMoment', 'unix', 'max', 'min', 'utc'])
+
+// ⚠️ 函数自身的固有成员 + 框架探针，必须放行、不能抛错。理由与实例面的 PASSTHROUGH 同源：
+// `JSON.stringify({ m: $moment })` 会先读 `toJSON`（规范里对**任何**对象——函数也算——都先取
+// 一次 toJSON）、ESM/CJS 互操作垫片会读 `default` / `__esModule`、Vue 的响应式探针读 `__v_*`。
+// 这些读到 undefined 与真 moment 的行为一致（moment 上它们同样不存在），抛错则会白屏。
+const STATIC_PASSTHROUGH = new Set(['name', 'length', 'prototype', 'call', 'apply', 'bind',
+  'toString', 'valueOf', 'constructor', 'hasOwnProperty', 'isPrototypeOf',
+  'propertyIsEnumerable', 'then', 'toJSON', 'default', '__esModule', 'nodeType', 'tagName',
+  '$$typeof', '__v_isRef', '__v_isReactive', '__v_isReadonly', '__v_raw', '__v_skip',
+  '_isAMomentObject'])
+
+// ⚠️ 静态面也必须响亮抛错——这是 spec §4.3 明写的绑定姿态，而在此之前它是**没有的**：
+// `createMoment` 是个普通函数，7 个静态方法之外的一切（`isDuration` `isDate` `months`
+// `weekdays` `localeData` `ISO_8601` `parseZone` `invalid` `now` `updateLocale`
+// `defaultFormat`……moment 全都有）读出来都是 `undefined`，于是
+// `$moment.isDuration(x)` 直接 TypeError、`$moment.ISO_8601` 当格式串传下去变成静默错值。
+// 实例面早就抛错了，静态面不抛，正是 §4.3 要消灭的那种失败模式。
+// 只拦 get 的 miss 分支（命中白名单的走 Reflect.get，零额外开销）；Symbol 一律放行。
+const momentCompat = new Proxy(createMoment, {
+  get (target, prop, receiver) {
+    if (typeof prop === 'symbol') return Reflect.get(target, prop, receiver)
+    if (STATIC_ALLOWED.has(prop) || STATIC_PASSTHROUGH.has(prop)) {
+      return Reflect.get(target, prop, receiver)
+    }
+    throw new Error(
+      `[epx-moment] \`$moment.${prop}\` 不在兼容层覆盖范围内。\n` +
+      '  本平台已从 moment 迁移到 dayjs，$moment 是一层兼容 shim。\n' +
+      `  静态面只覆盖 ${[...STATIC_ALLOWED].join(' / ')}。\n` +
+      '  需要这个 API 请补进 packages/utils/src/moment-compat.js；\n' +
+      '  临时可用 $moment(x).toDate() 拿到原生 Date 自行处理。'
+    )
+  }
+})
+
+// 具名与默认导出**必须是同一个（被代理的）对象**：产品项目的构建产物里两种写法都出现过
+// （packages/utils/dist/src/formula.js 走的就是具名 `{ createMoment }`），只代理其中一个
+// 等于留了半扇后门。
+export { momentCompat as createMoment }
+export default momentCompat