# 前端规范（入口） > **目标**: 统一前端实现、交互、设计系统与国际化规范 > **最后更新**: 2026-03-13 --- ## ✅ 入口与执行 - 前端实现与设计：`frontend-main` --- ## 核心规则（摘要） ### 文档先行 - 用户可见功能变更前，先确认对应模块的 `05-ui-interaction-spec.md`，必要时回补 `01-prd.md`、`02-user-journey.md` 与 `04-state-machine.md`。 - 未文档化的导航、信息架构或设计系统改动，不要直接落代码。 ### 设计系统 - 视觉规范以现有设计系统为准，优先复用现有组件、颜色、阴影和交互模式。 - 未定义场景优先提议补设计系统，不要在页面里发明新视觉规则。 - 表格优先使用原生 ``，交互和视觉保持一致性。 ### 国际化 - 所有用户可见文案必须国际化。 - 复用现有 i18n key；没有时按模块命名空间新增稳定语义 key。 - 动态内容使用插值，不做字符串拼接。 ### 导航与交互 - 主侧栏折叠态必须支持“悬停/聚焦显示菜单名称”浮层，文案复用导航 i18n。 - 展开态禁止重复显示该浮层。 - 不得改变既有导航行为与权限过滤语义。 ### 状态管理与空数据防御 - **`useState(true)` 的 loading 状态**：在所有提前 return 的分支中必须 `setLoading(false)`。否则当依赖数据（如周期列表）为空时，页面会永久显示 loading。 - **API 返回值防御**：对后端返回的数据做防御性处理（如 `res.items || res`），避免因返回格式不一致（`{ items: [...] }` vs 裸数组）导致 `.filter is not a function` 等运行时错误。 - **空状态优先验证**：每个页面开发后，先在无数据的场景下访问一次，确认不会卡 loading 或报错。 - **`