create-jnrs-vue 1.2.31 → 1.2.33

package/jnrs-vue/README.md

@@ -1,21 +1,38 @@
 # jnrs-vue
 
 ## ✨ 介绍
+
 巨能前端工程化开发，Vue 项目信息化管理系统
 
 ## 💻 技术栈
+
 TypeScript、Vue3 生态
 
 ## 🧩 安装使用说明
+
 ```shell
 pnpm i
 pnpm dev
 pnpm build
 ```
 
+## 🤖 AI Agent 使用说明
+
+- 前置准备
+  - 将业务功能原型图作为生成前端代码的参考图
+  - 从 api 工具（如 ApiFox） 中导出 openapi 文档，或接入其提供的 MCP 服务
+  - 使用 AI Agent 读取并分析当前 `README.md` 文件及 `/agentic/RULES_BASE.md` 文件并作为 IDE AI Agent 的记忆
+- 预置提示词
+  - 保存记忆：`读取并分析当前 README.md 文件及 /agentic/RULES_BASE.md 文件并作为 IDE AI Agent 的记忆`
+  - 生成菜单：`根据提供的菜单原型图，生成菜单`
+  - 生成服务文件：`根据提供的 openapi 文档或 MCP 服务，生成API 服务文件`
+  - 生成增删改查页面文件：`根据提供的界面原型图，生成增删改查页面文件`
+
 #### 项目结构
+
 ```Text
 jnrs-vue/
+├── agentic/              # AI Agent 规则与提示词
 ├── viteMockServe/        # Mock 服务配置
 ├── public/               # 静态资源
 ├── src/                  # 源码目录
@@ -46,4 +63,5 @@ jnrs-vue/
 ```
 
 ## ⚠️ 注意事项
-- layout 中使用了 KeepAlive 内置组件进行组件实例缓存，使用生命周期进行如“副作用清理“时注意用 onActivated / onDeactivated 替代 onMounted / onUnmounted
+
+- layout 中使用了 KeepAlive 内置组件进行组件实例缓存，使用生命周期进行如“副作用清理“时注意用 onActivated / onDeactivated 替代 onMounted / onUnmounted

package/jnrs-vue/agentic/RULES_API.md

@@ -0,0 +1,91 @@
+# API 服务文件配置规则(Service Layer)
+
+说明：对提供的 `open api` 进行业务模块解析，最终生成的 `API 服务文件(Service Layer)`代码示例参考 /src/api/agentic/project.ts，最终目的是作为 AI Agent 提示词，基于每个业务模块的 Service Layer 文件直接生成 views 等代码，便于 Vibe Coding。
+
+## apifox 中对于 open api 的导出规则
+
+- apifox 导出配置：
+  - 数据格式：OpenAPI Spec。
+  - OpenAPI Spec 版本：OpenAPI 3.1。
+  - 文件格式：JSON。
+  - 包含 Apifox 扩展的 OpenAPI 字段（x-apifox-\*\*\*）：包含。
+  - 将 API 文档的目录，作为 Tags 字段导出：否。
+
+- 最终导出的文件为 `*openapi.json`。
+- 优先使用 apifox 提供的 MCP 服务。
+
+## \*openapi.json 文件内容详细解析规则
+
+- 基本规则
+  - 禁止对 \*openapi.json 文件进行任何修改。
+  - 严格按照提供的 open api 文档进行解析，禁止编造新的接口或字段。
+  - 所有新生成的 Service Layer 文件及目录都存放在 /src/api 目录下。
+  - 所有新创建的 api 函数均命名为 `*Api`，如：`projectListApi`、`addProductApi`。
+
+- 解析规则
+  - 解析 'paths' 中 'x-apifox-folder' 的值，作为当前文件的模块名称，如：`project.ts`；如果'x-apifox-folder' 的值包含层级，则按照层级创建目录及文件，如：`product/craft.ts`、`product/process.ts`。
+  - 按需生成类型，按需拆分接口逻辑，如将编辑接口拆分为新增和修改接口。
+  - 解析 'paths' 中的 summary，作为 export 的注释信息，如：`/** 项目 - 列表 */`。
+  - 解析 'paths' 中的 URL Path，作为 axiosRequest 函数的 url 参数值。
+  - 解析 'paths' 中的 HTTP Method，作为 axiosRequest 函数的 method 参数值。
+  - 解析 'paths' 中的 parameters，作为 axiosRequest 函数的 params 参数值。
+  - 解析 'paths' 中的 requestBody，作为 axiosRequest 函数的 data 参数值；如果 content-type 为 `form-data`，则 axiosRequest 函数的 data 类型值必须使用 objectToFormData 函数包裹，如 `data: objectToFormData(data)`。
+  - 如果 views 中需要使用原始响应数据，如需要显示后端返回的 msg 信息，则需要在 axiosRequest 函数中设置属性 `returnRawResponse: true`
+
+- parameters 特殊处理
+  - 如果查询参数包含 `pageNo` 和 `pageSize`，则查询类型必须继承 `IPagination`
+
+- requestBody 特殊处理
+  - 如果某个 'properties' 类型名为 '\*Id'，如 'projectId、productProcessId'，则认为该属性和 `components/select` 相关，则类型值固定为 `Record<string, unknown> | number | undefined`，如下所示：
+
+    ```ts
+    managerId?: Record<string, unknown> | number
+    ```
+
+  - 如果某个 'properties' 的类型名同时包含 'orginAttachmentName、newAttachmentFile' 或 'orginImageNames
+    newImageFiles'，则创建一个新的类型并继承模块类型，按需额外添加 `newImageFiles` 和 `newAttachmentFile` 属性供列表使用，类型值固定为 `IAttachment[] | undefined`，如下所示：
+
+    ```ts
+    export interface ProcessedProject extends Project {
+      newImageFiles?: IAttachment[]
+      newAttachmentFile?: IAttachment[]
+    }
+    ```
+
+    但是在新增和修改功能中，则设置其类型值为 `[]`，如下所示：
+
+    ```ts
+    export interface AddProject {
+      // ...其他属性
+      newImageFiles: []
+      newAttachmentFile: []
+    }
+    export interface UpdateProject {
+      // ...其他属性
+      newImageFiles: []
+      newAttachmentFile: []
+    }
+    ```
+
+- responses 特殊处理
+  - 如果存在属性 `imageDocument` 或 `attachmentDocument`，则类型值固定设置为`IDocument | undefined`，如下所示：
+
+  ```ts
+  export interface Project {
+    // ...其他属性
+    imageDocument?: IDocument
+    attachmentDocument?: IDocument
+  }
+  ```
+
+  - 如果查询参数包含 `pageNo` 和 `pageSize`，则 api 函数返回值必须使用 `IPageTableData` 包裹业务模块数据类型，如下所示：
+
+  ```ts
+  export const ProjectListApi = (params?: ProjectQuery): Promise<IPageTableData<Project>> => {
+    return axiosRequest({
+      url: '/agentic/project/list',
+      method: 'get',
+      params
+    })
+  }
+  ```

package/jnrs-vue/agentic/RULES_BASE.md

@@ -0,0 +1,8 @@
+# 基础规则
+
+- 提示词关键字：
+  - `生成服务` 时，参考 [服务配置规则](./RULES_API.md)
+  - `生成菜单` 时，参考 [菜单配置规则](./RULES_MENU.md)
+  - `生成增删改查页面` 时，参考 [增删改查页面配置规则](./RULES_CRUD.md)
+
+- 所有新创建的文件或目录都使用小驼峰命名，命名需简洁精炼，不同目录下但是属于同一个模块的文件命名应保持统一，如 `/src/views/productManagement.vue`、`/src/api/productManagement.ts`

package/jnrs-vue/agentic/RULES_COMMON.md

@@ -0,0 +1,6 @@
+# 工程内部提供的通用能力规则
+
+- 名称语义定义：
+  - 模块：模块是业务逻辑的集合，如：项目模块、产品模块、用户模块、系统模块...，基本是一个模块对应一个 'menu.json' 中一个菜单或目录项；一个模块对应一个 Service Layer 文件，如：`project.ts`、`product.ts`、`user.ts`、`system.ts`。
+  - components/select：选择功能组件，可借助 AI Agent 通过引用 JnSelectTemplate 生成，具体使用参考 SelectProject.vue 文件，如：`SelectProject.vue`、`SelectProduct.vue`、`SelectUser.vue`，功能为“选择某模块的某项数据，获取其 id 值”，如 'SelectProject.vue' 的功能为选择项目模块的某个项目，获取项目 id 值。
+  - components/common：通用功能组件，属于编程人员预置文件，不可通过 AI Agent 自动生成，如：`CardTable.vue`、`DictTag.vue`、`ImageView.vue`、`PdfView.vue`。

package/jnrs-vue/agentic/RULES_CRUD.md

@@ -0,0 +1,53 @@
+# 增删改查页面文件配置规则
+
+说明：对某个业务模块提供针对 Create（新增） / Read（数据列表） / Update（修改） / Delete（删除） 等操作的功能使用说明、模块化使用说明、规则约束、交互行为、API 负载（payload）示例，结合 `特征映射表` 和 `上下文权重数组` 来决定参考的相关性，最终目的是作为 AI Agent 提示词，基于每个业务模块的 API 文档直接生成前端代码，便于 Vibe Coding。
+
+## 特征映射表
+
+作用：作为上下文权重数组的索引表，基于权重数据来决定下列文件作为上下文的相关性，权重值区间：[-1, 1]。
+
+| 特征文件路径                                                                | 特征描述                                                         | 特征索引 |
+| --------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------- |
+| /agentic/RULES_BASE.md                                                      | 基础规则                                                         | 0        |
+| /agentic/RULES_DEPENDENCIES.md                                              | 工程外部依赖包提供的能力                                         | 1        |
+| /agentic/RULES_COMMON.md                                                    | 工程内部提供的通用能力                                           | 2        |
+| /src/views/agentic/crud/index.vue 和 /src/views/agentic/crud/EditDialog.vue | 具体的业务功能：数据列表页、新增&修改弹窗面                      | 3        |
+| /src/api/agentic/project.ts                                                 | API 服务文件(Service Layer)，即具体的业务功能 API 函数及类型系统 | 4        |
+
+## 通用规则约束
+
+- 所有以 `Select*` 开头的组件，如 `SelectProject.vue`， 其文件路径均在 /src/components/select 目录下，功能为“选择某模块的某项数据，获取其 id 值”，如 `SelectProject.vue` 的功能为选择项目模块的某个项目，获取项目 id 值。
+
+## 详细规则约束
+
+index.vue 文件内容：
+
+| 主要组成部分描述                                                                                                   | 使用场景                                                            | 上下文权重数组 |
+| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | -------------- |
+| template 顶层块内编写 `<span class="jn-card-title">项目管理</span>`                                                | 当前模块名称，通常在“ElCard#header“组件中配套使用，具体名称按需修改 | [0,-1,-1,1,-1] |
+| template 顶层块内使用 `JnTable` 组件                                                                               | 当前模块存在列表功能                                                | [0,1,1,1,1]    |
+| template 顶层块内使用 `JnPagination` 组件                                                                          | 当前模块存在分页功能                                                | [0,1,1,1,1]    |
+| template 顶层块内使用 `EditDialog` 组件                                                                            | 当前模块存在新增、修改功能                                          | [1,1,1,1,1]    |
+| template 顶层块内使用 `JnImportAndExport` 组件                                                                     | 当前模块存在倒入、导出功能                                          | [0,1,1,1,1]    |
+| template 顶层块内使用 `Select*` 组件                                                                               | 当前模块存在选择其他模块数据功能，通常在“查询条件“表单中配套使用    | [0,0,1,1,1]    |
+| template 顶层块内使用 `DictTag` 组件                                                                               | 当前模块存在字典标签功能                                            | [0,0,1,1,1]    |
+| template 顶层块内使用 `JnDatetime` 组件                                                                            | 当前模块存在ISO 8601 日期时间格式化功能                             | [0,1,1,1,1]    |
+| template 顶层块内使用 `ImageView` 组件                                                                             | 当前模块存在图片查看功能                                            | [0,0,1,1,1]    |
+| template 顶层块内使用 `PdfView` 组件                                                                               | 当前模块存在 PDF 文件查看功能                                       | [0,0,1,1,1]    |
+| script 顶层块内，getTable 函数体对 tableData 的特殊处理（基于 raw data 新增 newImageFiles,newAttachmentFile 属性） | 表格中要使用 `ImageView` 组件时需处理                               | [0,0,1,1,1]    |
+
+edit.vue 文件内容：
+
+| 主要组成部分描述                                             | 使用场景                                                                                                                       | 上下文权重数组 |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------------- |
+| template 顶层块内使用 JnDialog 组件                          | 封装好的弹窗组件，必须使用                                                                                                     | [1,1,1,1,1]    |
+| el-form 组件内编写 `<el-form-item prop="id"></el-form-item>` | 为了调用 resetFields 方法时捕捉到 id 属性，必须使用                                                                            | [0,-1,-1,1,1]  |
+| el-form 组件内使用 `Select*` 组件                            | 当前模块存在选择其他模块数据功能，和 `components/select` 相关，其 simpleValue 属性值需设置为 false                             | [0,0,1,1,1]    |
+| el-form 组件内使用 `JnFileUpload` 组件                       | 当前模块存在上传功能，downloadFileFn 属性按需使用，如果当前属性是必填项，则必须配置 `:formRef="ruleFormRef"` 属性和值          | [0,1,1,1,1]    |
+| open 函数中关于 Select 组件数据回填的特殊处理                | 当前模块存在选择其他模块数据功能，和 `components/select` 相关                                                                  | [0,0,1,1,1]    |
+| submitForm 函数中关于 Select 组件数据取 id 值的特殊处理      | 当前模块存在选择其他模块数据功能，和 `components/select` 相关，最终传给 api 函数的 id 参数必须使用 extractFieldId 函数进行处理 | [0,0,1,1,1]    |
+
+edit.vue 文件其他规则：
+
+- el-form 组件内编写的 el-input 组件加 `maxlength`、`show-word-limit` 属性。
+- el-form 组件内编写的 el-input-number 组件的 '#prefix' 按需使用。

package/jnrs-vue/agentic/RULES_DEPENDENCIES.md

@@ -0,0 +1,11 @@
+# 工程外部提供的作用域依赖包的规则
+
+说明：使用当前工程依赖 `@jnrs` 命名空间下的包时，如：`@jnrs/shared`、`@jnrs/vue-core`、`@jnrs/lingshu-smart`，详细描述参考各自的 `README.md` 和 `AGENTIC.md` 文件。
+
+## 使用优先级
+
+当需要使用上述作用域依赖提供的能力，去实现当前工程中一个业务功能时，优先级顺序如下：
+
+1. `@jnrs/vue-core` 的大多数功能基于 `@jnrs/shared` 提供的能力基础上，封装了一些通用业务功能以及 vue 组件，优先级高。
+2. `@jnrs/shared` 提供了一些通用的方法，优先级低。
+3. `@jnrs/lingshu-smart` 提供了数字孪生系统的能力，在明确使用 `lingshu-smart` 进行数字孪生开发时，优先级最高。