copilot-instructions

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 配置；改动保持最小范围，不重写无关模块。
• 不臆测接口或业务逻辑；上下文不足时说明缺口或反问。
• 数据转换函数必须保持幂等性（相同输入多次调用产生相同输出），如果函数会修改入参对象，首行使用 _.cloneDeep(values) 保护原始引用不被污染。
• 同一组件中应避免多次调用同一有副作用的转换函数，优先提取变量复用计算结果。
• 类型收窄优先使用原生接口：用 Array.isArray 代替 _.isArray，用 typeof x === 'number' 代替 _.isNumber，用 x == null 代替 _.isNil，以此类推。lodash 的类型守卫函数在缺少 @types/lodash 时不会被 TypeScript 识别为类型守卫，导致 unknown 类型无法收窄。

数据与错误

• 异步请求须有错误处理（try/catch、.catch、onError 等，与现有模式一致）。

弹窗与表单状态

• 弹窗、抽屉等临时容器组件在卸载时，必须显式清理表单数据和本地状态（如 form.resetFields()、loading、临时选择值），避免再次打开时回显旧数据。
• 注意 form.setFieldsValue 是增量更新：未传入的字段会保留原值。需要全量覆盖场景时，先重置表单（如 form.resetFields()）再设置新值。
• antd 的 Collapse.Panel 初始折叠时不会挂载内容。若面板内的 Form.Item / Form.List 需要参与校验、回填或提交，必须添加 forceRender，确保字段注册到 Form；纯展示内容无需添加。

样式与颜色

• 颜色、主题相关值使用 src/theme/variable.css（及现有主题体系）中的变量，避免魔法色值。

Tailwind 与 Less 的分工

原则

1. 能直接用 Tailwind 表达的（布局、间距、排版、圆角、常见交互态）→ 用 Tailwind。
2. Tailwind 不划算或做不到的 → 少量 Less/CSS，选择器尽量收束在页面/模块根类名下。
3. 同一视觉属性不要同时被 Tailwind 与 Less 争抢（避免难排查的覆盖问题）。

优先用 Tailwind

• 容器布局：flex / grid / gap / 内外边距 / 对齐。
• 业务界面：按钮、表单外观、文案层级、状态色（需与主题变量一致时，用已有 Tailwind 主题映射或 CSS 变量类，不硬编码色值）。
• 局部状态：hover / focus / disabled 等。
• 仅当前组件使用的展示类样式。

用 Less / 普通 CSS 更合适的情况

• 覆盖第三方组件内部结构（如 antd 深层节点、复杂表格头）。
• 全局或跨多页复用的 token、keyframes、无法用工具类清晰表达的动画。
• 强依赖复杂选择器（深层后代、兄弟组合、兼容向 hack 等）。

Less/CSS 侧要求：

• 选择器尽量局部化；嵌套不宜过深（≤3 层为宜）。
• 不复制一套与 Tailwind 等价的冗长规则。