fe: Instructions file for Claude Code

N9E 前端项目

目录速览

src/
├── components/     # 通用 UI 与业务无关的基础组件
├── pages/          # 路由页面
├── plus/           # Plus 扩展（datasource、parcels 等，路径别名 plus:/*）
├── plugins/        # 数据源等插件化功能（含 Explorer/Dashboard 等）
├── store/          # Zustand 等状态
├── services/       # 接口与领域服务
├── utils/          # 工具函数
├── routers/        # 路由配置
├── theme/          # 主题与 CSS 变量（如 variable.css）
├── locales/        # 国际化资源
├── assets/         # 静态资源
├── types/          # 全局类型
├── App.tsx
└── main.tsx

技术栈与风格

• TypeScript + React Hooks；优先函数组件，避免 class 组件。
• 组件 Props 使用 interface 显式声明，避免 any。
• 遵循仓库既有格式与 Prettier 配置；改动保持最小范围，不重写无关模块。
• 修改源码后，必须依据根目录 .prettierrc.json 对改动文件执行 ./node_modules/.bin/prettier --write，并在交付前执行 ./node_modules/.bin/prettier --check；不得遗留仅格式问题。
• 不臆测接口或业务逻辑；上下文不足时说明缺口或反问。
• 数据转换函数必须保持幂等性（相同输入多次调用产生相同输出），如果函数会修改入参对象，首行使用 _.cloneDeep(values) 保护原始引用不被污染。
• 同一组件中应避免多次调用同一有副作用的转换函数，优先提取变量复用计算结果。
• 类型收窄优先使用原生接口：用 Array.isArray 代替 _.isArray，用 typeof x === 'number' 代替 _.isNumber，用 x == null 代替 _.isNil，以此类推。lodash 的类型守卫函数在缺少 @types/lodash 时不会被 TypeScript 识别为类型守卫，导致 unknown 类型无法收窄。

React Router 路由与部署前缀

• 项目使用 React Router 的 basename 支持子路径部署。应用内路由路径应使用 Router 提供的路径：例如部署前缀为 /flashcat 时，useLocation().pathname 和 React Router history.location.pathname 是 /dial-analysis，而 window.location.pathname / 全局 location.pathname 是浏览器完整路径 /flashcat/dial-analysis。
• 构造应用内跳转、调用 React Router 的 history.push / history.replace，或保留当前路由路径时，使用 Router 的相对路径（如 useLocation() 或 history.location）。不要把全局 location.pathname 直接当作 Router 路径，也不要给 Router 路径手动再拼 basename，否则可能出现 /flashcat/flashcat/polaris 这样的重复前缀。
• useLocation() 是当前渲染对应的路由快照。异步请求等延迟回调需要读取执行时的最新路径或查询串时，使用对应 Router history 的 history.location，避免使用闭包中的旧值覆盖后来更新的路由状态。
• 只有确实需要浏览器完整 URL（例如整页跳转、刷新或生成带部署前缀的浏览器级地址）时才使用 window.location / 全局 location；注意它们与 Router 的路由路径语义不同。window.history 的原生 History API 也不等同于 React Router 的 history。
• 构造复制、分享、保存或自定义组件使用的 URL 时，先区分 Router 路径、应用相对 URL 和完整 URL；优先复用 src/utils/appUrl.ts 的 getAppBaseUrl / addAppBasePrefix，不要随手拼接 basePrefix。这些 helper 会避免重复前缀，并让绝对 URL 保持原样。
• $local_url 已包含协议、域名和部署前缀；替换后不要再给结果加前缀。Vite 前缀插件只处理它识别的浏览器 URL 接收点，不会处理复制到剪贴板、显示在输入框、存入对象或经自定义组件传递的 URL；这些场景需要显式构造。