项目：xiaoye-admin-react ｜ 版本：v1.1 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析
本文盘点框架当前已知的技术债务：每一项给出位置、证据、影响与建议，并区分"仍存在"与"已修复但留有痕迹"两类；文末给出分阶段演进路线图。盘点依据有三：docs/bug-audit.md（2026-09-13 的全量审计报告，3 P0 / 7 P1 / 若干 P2）、当前源码逐项核实结果、以及各篇文档中标注 ⚠️ 待确认 的口径问题。阅读原则：债务清单不是缺陷指责，而是"接手者应预知的地图"——每项都标注了它被容忍的理由，判断"要不要还"时先看那个理由是否仍然成立。
D1：菜单数量三处口径不一（77 / 80 / 81）。 位置：src/assets/json/authMenuList.json（实际解析 77 个节点、14 个顶级，见《00-项目总览》4 的统计）、README.md（"菜单数据共 80 项"）、src/mocks/modules/auth.ts 注释（"复用项目内的静态菜单（81 项）"）以及 src/hooks/usePermissions.ts 注释（"放行全部 81 条动态路由"）。证据：以 Node 解析 JSON 遍历 children 计数为 77。影响：涉及"全量菜单放行多少条路由"的安全叙述时数字失真，且 docs/bug-audit.md 中的 81 也源于旧版菜单（历史版本菜单数量有增删）。建议：以 JSON 实际解析为准统一为 77，或在引用处改为"约 80 项"并注明以 JSON 为准。本套文档已于 2026-10-06 回刷统一为 77（见《00-项目总览》4）；源码侧 README.md 与两处源注释的失实数字仍待修订，本债务保持登记。
D2：国际化未覆盖的硬编码文案。 位置与证据：src/views/system/ 三页（accountManage / roleManage / menuMange）的表单标签与列标题为中文硬编码，src/views/system/accountManage/index.tsx 源码注释明确"语言包未覆盖 system.* 命名空间，沿用参考项目写法"；src/hooks/useMessage.tsx 的 modal 默认按钮 okText: "确认" / cancelText: "取消" 为中文；src/mocks/modules/ 各 handler 的业务错误 msg（"用户名或密码错误"等）为中文。影响：英文模式下系统管理三页与确认弹窗混入中文，演示国际化时的观感破绽；mock 错误文案在生产接后端后自然消失，无需处理。建议：补 system.* 命名空间词条（参照《05-核心流程》流程三的补词条路径），useMessage 默认按钮改走 common.* 词条（其模块级单例已能拿到 i18n 实例，技术可行）。
D3：.env.test 注释与实现出入（PWA）。 位置：.env.test 中注释"本项目未接入 PWA 插件，保持关闭"。证据：build/plugins.ts 的 createVitePwa 已完整实现且 VITE_PWA=true 的 production/mock 模式在用。影响：注释误导新人以为 PWA 未接入，可能在错误认知下改动 PWA 相关配置。建议：更新注释为"test 模式关闭 PWA（避免测试构建产出 SW）"。
D4：README 与实现的滞后面。 位置：README.md 除 D1 外，"可选增强"清单中的部分能力实际已实现（如 ErrorBoundary 接入、useMessage App 上下文化——均为 bug-audit P1-1/P1-7 的修复结果）。影响：新接手者可能按 README 误判能力现状。建议：README 增补一节"能力现状与 bug-audit 的差异说明"或直接更新对应段落。
D5：token 无刷新机制、无过期策略。 位置：src/api/index.ts 响应拦截器 401 分支（现状与扩展点）、src/stores/modules/user.ts（tokenUpdatedAt 记录但未使用）。证据：全仓无 refresh 端点与刷新逻辑。影响：长会话用户会被硬登出；token 长期驻留 localStorage 在 XSS 得手时无时效兜底。建议：见《08-安全与权限设计》2.2 的 single-flight + 请求重放方案，位置已预留。这是接生产前优先级最高的演进项。
D6：window.$navigate 的理论性缺陷。 位置：src/routers/helper/RouterGuard.tsx（render 期写入全局）。证据：bug-audit 第 15 条指出多实例并发渲染会互相覆盖、且 401 若发生在首个 RouterGuard 挂载前，跳转退化为整页导航（现由 navigateTo 的 hash/href 降级兜底，见《03-接口设计》1.5）。影响：单实例应用下无实际故障，属架构脆弱点。建议：维持现状可接受；若重构，把 navigate 实例移入模块级单例注册（App 挂载后注入）而非 render 期赋值。
D7：9 条 ESLint warning 未清零。 位置：useTheme.ts 5 条 exhaustive-deps、Menu/index.tsx 1 条 useMemo 缺依赖（bug-audit 标注为真实逻辑风险：布局模式切换可能不生效）、2 条 react-refresh、1 条 consistent-type-imports。影响：warning 长期存在会钝化对新增 warning 的敏感度。建议：一次性清零并在 CI 用 --max-warnings 0 收紧。
D8：零引用导出与死资源。 位置与证据（bug-audit 实测，本次复核大部分仍在）：src/api/config/servicePort.ts 的 PORT2、src/utils/color.ts 的 getDarkColor、src/utils/index.ts 的 getTimeState、src/utils/is/index.ts 的 9 个类型判断函数、src/enums/httpEnum.ts 的 RequestEnum/ContentTypeEnum、src/assets/fonts/font.css 及其引用的约 1.5MB 字体文件。影响：包体与认知噪音（tsconfig 的 noUnusedLocals 不检查导出符号，typecheck 拦不住）。建议：按"模板也许有人用"的判断分级——字体与 font.css 直接删；工具函数保留但加注释声明用途。
D9：密码 md5 摘要传输。 位置：src/views/login/components/LoginForm.tsx、src/api/modules/login.ts。证据：见《08-安全与权限设计》2.3 的完整分析（无盐、可彩虹表、HTTPS 时代增益有限）。影响：可能给使用者错误的安全感。建议：接真实后端时按后端约定调整，并在 README 注明 md5 不是安全特性。
D10：多标签页跨标签同步缺失。 位置：src/stores/modules/user.ts（无 storage 事件监听）。证据：一个标签页登出/401 后，另一标签页内存 token 仍在，直到下次请求被后端拒绝。影响：共享浏览器场景下有权限串用窗口。建议：监听 storage 事件同步 xiaoye-user 变更，触发 resetAuth，约 20 行代码。
以下为 docs/bug-audit.md 记录、经本次源码核实已修复的项，列出修复位置备查：P0-1（msw 未安装，现 2.15.0 精确锁定）；P0-2（生产权限失败回退全量菜单，现为清登录态，usePermissions.ts）；P0-3（顺序 await 连带失败，现 Promise.allSettled 并行）；P1-1（RefreshProvider 未挂载，现挂载于 src/App.tsx）；P1-2（iconfont.css 未引入，现于 src/main.tsx import）；P1-3（DEV 误判，现全部改用 !import.meta.env.PROD）；P1-4（401 不清权限，现统一 resetAuth()）；P1-5（登录失败无 catch，现 LoginForm 有内联 Alert 处理）；P1-7（静态 message 不继承主题，现 useMessage.tsx App 实例注入）；P2 性能类中的大屏问题（views/dataScreen 整目录已移除）、Echarts notMerge（已加）、latestRequestId 防竞态（已有）。历史审计报告因此不要直接当现状读，先对照本节。
清单只是快照，债务管理的关键是让"还债"可度量、可持续。本项目可用的度量入口有四个。其一，pnpm lint 的 warning 计数（当前 9 条）——它是唯一能进 CI 的硬数字，配合 --max-warnings 可把"warning 不新增"固化为门禁。其二，构建产物体积（VITE_REPORT=true 的 stats.html 与 dist/assets/js/ 目录对比），D8 的清理效果直接反映在这里。其三，docs/bug-audit.md 的编号体系（P0/P1/P2 + 序号）——建议延续该编号格式回写新发现，本篇的 D 编号与其并行使用：P 系列代表"审计发现的缺陷"，D 系列代表"已知且暂容忍的取舍"，两者语义不同，修复 D 系列前先确认容忍理由已失效。其四，文档口径一致性：D1/D2/D3/D4 这类文档债的验收标准是全文检索数字与注释（如菜单数量、PWA 描述）得到唯一答案，可用几行 grep 脚本做成周期性检查项。
追踪节奏上建议两层：接生产这类里程碑节点全量过一遍本文清单（第一阶段 items 逐项销账）；日常迭代则遵循"修复即存档"——每修一个 bug 回写 bug-audit 状态、每容忍一个新的取舍就登记进第 1 节并写明容忍理由。技术债务清单最忌两个极端：当纯文档摆设（永远不更新），或当任务板（把"容忍"也排期销毁）——它真正的作用是让每次"要不要现在还"的决策有据可依。
第一阶段（接生产前必须，约一周量级）：D5 token 刷新与过期策略；D1/D2/D3/D4 口径与文档统一（半天）；与后端核对权限语义三件事（请求头名、信封、菜单结构，见《11-扩展开发指南》场景五）；补齐拦截器 401 分支的测试（见《09-测试与质量保障》6 的 P1 清单）。这一阶段的主题是"把演示脚手架的简化取舍补回生产级语义"。
第二阶段（接生产后一个月内）：D10 跨标签同步；D7 warning 清零 + CI 门禁（--frozen-lockfile、tsc -b --force、--max-warnings 0、test、build 五连，见《09-测试与质量保障》4.1）；D8 死资源清理（可回收约 1.7MB）；补 utils/menu.ts 与 ConvertRouter 的纯函数测试。主题是"质量地基固化"。
第三阶段（按需投入的增强项）：E2E（Playwright 复用 MSW，覆盖登录 → 权限 → 深链 → 登出主干）；antd 按需引入与 bundle 治理（见《10-性能设计与优化》7）；按钮权限的运行时刷新（当前会话内权限快照不更新，若业务需要可加权限重取入口）；多语言第三语种（场景三 SOP 已备）；若组织内多项目复用，把 AuthButton / Echarts / KeepAlive / ProTable 范式抽为内部包。主题是"从框架到平台"。
不建议做的演进：为"更现代"而替换状态管理或路由库（zustand/react-router 的使用深度与源码注释密度意味着替换成本远大于收益）；把 KeepAlive 改回 <Activity>（实测有回归）；引入 CSS 预处理器（破坏无 Less 原则，见《01-系统架构》4.3）；在前端追加"更严格"的权限校验（安全边界在后端，前端加码只会增加维护面而不增加安全性）。演进项与债务项之间还有一个判断技巧：凡是"让事实源更单一、失败路径更从紧、清理更彻底"的改动，方向上大概率是对的；凡是"增加一个并行事实源、或让某条失败路径变宽"的改动，无论动机多正当都要先在本文登记取舍理由再动手。
这份清单的底层判断是：本框架的技术债务总量不大，且大部分集中在"演示便利性取舍"（D1/D2/D5/D9）而非"设计错误"。历史审计（bug-audit）到当前源码的修复轨迹也证明了这一点——3 个 P0 全部闭环，P1 闭环率高，且修复方式与审计建议一致（并行请求、PROD 判定、resetAuth 统一出口），说明项目有健康的"审计 → 修复 → 存档"循环。维护者要做的不是清空清单，而是保持这个循环运转：每次排障后回写 bug-audit 或本文，每次接生产前过一遍第一阶段清单。
最后重申本文与其它篇目的分工：各功能机制"为什么这样设计"不在本文展开（回《01》《03》《08》对应章节），本文只回答"现在还有什么不够好、什么时候还、怎么还"。若在使用中发现新的债务项，按第 1 节的 D 编号格式续编（位置/证据/影响/建议四要素齐全），并在第 3 节路线图中归入相应阶段——债务清单的生命力来自每一次接手者的续写。