ERP 组件库

Appearance

业务系统 AI 组件开发规则 ​

本文档用于约束业务系统在使用 AI（Cursor / Copilot / Chat）开发页面时，如何准确使用 ERP 组件库并交付可上线代码。
组件文档站点：https://lib.fukerp.com/

术语 ​

  • MUST：强制要求，不满足不得合入
  • SHOULD：推荐要求，特殊情况需在 PR 说明
  • MAY：可选项，按场景选择

1. 目标与适用范围 ​

  • 适用于 ERP 业务系统的新页面开发、旧页面重构、CRUD 场景改造
  • 适用于“人 + AI”协作编码，不区分具体 AI 工具
  • 目标是统一组件选型、交互行为、代码结构、提交流程，降低页面风格漂移和返工成本

2. AI 开发基本原则 ​

  • AI 生成代码 MUST 以现有组件能力优先，不重复造轮子
  • AI 输出 MUST 为可运行完整代码，不允许只给片段思路
  • AI 输出 MUST 包含：imports、类型定义、事件处理、异常处理、成功反馈
  • AI 输出 MUST NOT 引入项目内未安装依赖或未知工具函数
  • 对于不确定 API，AI MUST 使用“待替换标记”明确位置，不得臆造后端字段

3. 组件选型强约束（MUST） ​

  • 查询区：优先 FilterForm 或 SearchForm
  • 编辑区：优先 DynamicForm
  • 列表区：优先 VxeGrid（配置化）
  • 弹窗体系：统一使用 pop
  • 新建/编辑标准弹窗：优先 createDynamicFormPop
  • 危险操作确认：使用 pop.confirm
  • 异步过程反馈：使用 pop.loading / pop.success / pop.error
  • 业务组件从 @erp/biz 引入，基础组件从 @erp/common 引入

3.1 导入入口约束（MUST） ​

  • @erp/common 的仓库导出入口为 packages/common/index.ts
  • @erp/biz 的仓库导出入口为 packages/common-biz/index.ts
  • AI 生成代码时，MUST 优先使用以上包入口导入，不直接引用内部深层路径

4. CRUD 页面交付标准（MUST） ​

  • 页面必须包含：查询、重置、新建、编辑、删除、结果反馈
  • 新建/编辑成功后必须刷新列表
  • 删除前必须二次确认
  • 所有异步按钮必须有 loading 或 disabled 防重入
  • 用户主动取消（关闭弹窗、取消确认）不得在控制台抛错

5. 页面目录与职责分层（MUST） ​

以 erp_main_front 为例，建议结构如下：

  • src/views/<module>/<page>/index.vue：页面编排、事件绑定
  • src/views/<module>/<page>/config.ts(x)：表单项、表格列、按钮配置
  • src/views/<module>/<page>/api/*.ts：接口调用与类型定义

职责要求：

  • 页面层只做编排，不堆积请求细节
  • 配置与业务逻辑分离，避免在模板中写大量内联逻辑
  • 接口入参/出参类型集中管理，减少重复声明

6. TypeScript 质量底线（MUST） ​

  • 禁止裸 any（必要时使用精确联合类型或泛型）
  • 接口返回值、表单模型、表格行数据必须定义类型
  • 事件函数命名语义化：如 handleCreate、handleDelete、reloadGrid
  • 可空字段要显式处理，禁止依赖隐式类型推断“碰运气”

7. AI 标准提示词（直接复制） ​

text
你是 ERP 业务前端高级工程师，请严格按 ERP 组件库规范生成可运行页面代码：
1) 查询区必须使用 FilterForm 或 SearchForm；
2) 列表区必须使用 VxeGrid（配置化）；
3) 新建/编辑优先使用 createDynamicFormPop；
4) 删除必须使用 pop.confirm，异步过程使用 pop.loading；
5) 成功提示使用 pop.success，失败提示使用 pop.error；
6) 所有接口入参、返回值、表单模型必须提供 TypeScript 类型；
7) 禁止 any，禁止省略关键逻辑（校验、异常处理、刷新列表）；
8) 输出完整可运行代码（含 imports、类型、配置、事件、API 调用）；
9) 对不确定后端字段使用“TODO: 待后端确认”标记，不得臆造字段。

8. 场景化提示词模板 ​

8.1 新增 CRUD 页面 ​

text
请在 src/views/<module>/<page>/ 下生成 CRUD 页面：
- index.vue：页面编排
- config.ts：FilterForm 与 VxeGrid 配置
- api/index.ts：接口函数与类型
要求：新建/编辑使用 createDynamicFormPop，删除使用 pop.confirm，所有操作有成功/失败反馈。

8.2 旧页面组件化改造 ​

text
请将当前页面改造成 ERP 组件库标准写法：
1) 原生/自定义查询区替换为 FilterForm 或 SearchForm；
2) 原生 table 替换为 VxeGrid；
3) 新建/编辑入口改为 createDynamicFormPop；
4) 补齐 TypeScript 类型与错误提示；
5) 输出改造前后差异说明。

9. 禁止事项（MUST NOT） ​

  • 禁止绕过 pop.confirm 直接执行删除
  • 禁止仅返回“伪代码/示意代码”
  • 禁止在页面中硬编码大段 mock 数据后直接提交
  • 禁止出现“成功无提示、失败无反馈”的静默交互
  • 禁止新增文档后不注册导航与侧边栏路由

10. 文档与路由同步规范（MUST） ​

  • 指南文档放在 docs/src/guide/*.md
  • API 文档放在 docs/src/api-docs/**/*.md
  • 模板文档放在 docs/src/template/**
  • 新增文档后同步更新 docs/src/.vitepress/config.mts 中 nav 与 sidebar

11. 提交前验收清单 ​

  • CRUD 全链路可操作（查、增、改、删）
  • 表单校验与禁用态生效
  • 成功/失败提示完整可见
  • 页面刷新与状态回填符合预期
  • 文档路由可访问
  • 本地构建通过：pnpm -C docs build

12. 推荐阅读路径 ​

  • 组件文档首页：https://lib.fukerp.com/
  • CRUD 模板：/template/crud-page/crud-page.md
  • 弹窗服务：/api-docs/biz/pop
  • 动态表单弹窗：/api-docs/biz/create-dynamic-form-pop

基于 MIT 许可发布

版权所有 © 2023-2026 ERP Team