timi-web/.workbuddy/memory/2026-08-06.md

2026-08-06 工作日志

TypeScript enum 重构（全量消除 enum）

用户决定改用纯联合类型，自行修改依赖方。全项目 18 处 enum 分两类处理：

改为纯联合类型（字符串枚举，仅作类型用）

• Attachment.ts AttachmentBizType、Template.ts TemplateBizType
• Model.ts RunEnv / OrderType / ImageType（ImageType 值为 ir-auto 等，与 key 不同）
• Comment.ts CommentReplyBizType / CommentBizType
• User.ts UserAttachType（在 UserAPI.ts 有值引用，已同步改为字符串字面量，import 改 type-only）

改为 const 对象 + 派生类型（数字枚举或运行时值引用，纯联合不可行）

• User.ts LoginType、Article.ts ArticleType / ArticleAttachType / ArticleSoftwareDownloadType / ArticleSoftwareRuntime（数字枚举，保留数值避免破坏数据契约）
• deviceStore.ts Breakpoints（数字，用于比较 width < Breakpoints.SM）
• IOSize.ts Unit（用 Object.keys/values + Unit.KB 值引用）
• Prismjs.ts PrismjsType / PrismjsViewer（Map 键值引用）
• directives/Popup.ts PopupType（switch case 值引用）

结论

• vue-tsc --noEmit 通过（exit 0）
• ESLint 因项目缺 eslint.config.js（仍用旧 .eslintrc，ESLint9 不支持）无法运行，属项目既有配置问题
• 判断依据：纯联合无运行时存在，凡 Object.keys(enum)、map.set(Enum.X)、case Enum.X、Enum.X 作值的都无法纯联合，必须 const 对象

Storage.ts 设计修正

• getString 返回 string | null（对齐 localStorage.getItem 契约），不再 throw
• getJSON 返回 unknown，键不存在时返回 null，值无法解析时才抛错
• getObject 返回 T | null，不再 throw（修正原 JSDoc 已写 T | undefined 但代码 throw 的矛盾）
• is / not 键不存在时自然返回 false / true，不再崩
• has 去掉死代码 !== undefined（localStorage.getItem 只返回 string|null），单次查询
• vue-tsc --noEmit 通过

Toolkit.ts debounce 修复

• Bug 修复：cancel() 原先只清定时器不重置 leading 状态，导致立即模式下 cancel 后首次调用丢失 leading 触发
• 类型修复：返回类型从 T & { cancel(): void } 改为 ((...args: Parameters<T>) => void) & { cancel(): void }，防抖函数实际返回 void 而非 T 的返回值
• 补充完整 JSDoc（含 @example），说明立即模式（leading + trailing）和延迟模式（trailing only）的行为差异
• 状态变量 immediate → leading，参数 defaultImmediate → immediate，语义更清晰
• 去掉 eslint-disable-next-line 和多余注释
• vue-tsc --noEmit 通过