更新 llms-full.txt

llms-full.txt

@@ -508,6 +508,16 @@ DateTime endTime； //会议结束时间
     - 建议在Converter中进行代码扩展，不建议修改结构定义文件。其中VO的**自定义字段**由于不直接派生自DTO，所以一般会对应取数逻辑代码。通常如果涉及到数据获取、计算和拼装，批量处理的性能最好，所以自定义字段对应的代码位置**必须**放在Converter的**Map**基础转换方法convertTo${VoName}Map中，批量取数组装，如UserVoConverter.convertToUserVoMap
 #### **2.8 查询对象(WO)**
 - **定义与用途:** 在TOCO中，WO表达某个Entity为基本，通过外键关系不断关联多个Entity的数据结构。WO还隐式表达了数据的取数拼装，这种拼装符合外键关系. WO作为ReadPlan的查询上下文使用，所以在创建ReadPlan之前需要先创建WO对象。在理解一个ReadPlan的语义的时候需要以WO作为上下文。
+  如果对应的需求，在返回DTO|VO的时候需要对DTO|VO的列表属性进行过滤,则需要根据对应的DTO|VO的结构定义，扩展出对应的WO对象（需要过滤的字段名需要和DTO|VO的字段名保持一致),例如：
+  查询DTO
+```java
+  class MeetingDto {
+     String meetingId;
+     String meetingName;
+     List<MeetingAgenda> agendaList;
+  }
+```
+需求是需要根据会议名称查询会议列表，并且根据会议议程信息过滤掉部分议程，那在定义查询对象的时候就需要包含议程信息，并且扩展字段的名称要定义为**agendaList**
 - **查询对象案设计元素的表达**
   - 以json格式表达，json schema 定义如下
     ```json
@@ -546,6 +556,9 @@ DateTime endTime； //会议结束时间
     }
     ```
 - **如何创建/生成:**
+  - **创建思路**  按照需要查询返回的DTO|VO的结构，构建出同构的WO对象（扩展和反向扩展的字段名保持一致），然后根据查询需求和过滤需求对WO进行二次裁剪或和扩展：
+  - 去掉过滤和查询都不需要的扩展
+  - 补全查询或者字段过滤需要扩展
   - **关键配置:**  Wo中的字段分为三种：a.继承Entity的字段，和Entity的字段类型一样；b.扩展字段，含正向替换和反向注入字段，类型为WO或List<WO>;
   - **字段扩展方式:** TOCO定义了一个WO组装方法，适用于WO通过外键关系替换/注入对应Entity的信息，对象化表达有外键关系的Entity信息。只要存在外键关系且满足以下条件即可扩展：a.对于正向替换：当前实体存在指向其他实体的外键字段；b.对于反向注入：其他实体存在指向当前实体的外键字段。
     例如：有两个Entity
@@ -559,8 +572,8 @@ DateTime endTime； //会议结束时间
    Long roomid; //占用的会议室id，到MeetingRoom的外键，n:1关系
    Long backupRoomid; //备用的会议室id，到MeetingRoom的外键，n:1关系
    String title; //会议标题
-  DateTime startTime； //会议开始时间
-  DateTime endTime； //会议结束时间
+   DateTime startTime; //会议开始时间
+   DateTime endTime; //会议结束时间
   }
   ```
 其中Meeting和MeetingRoom是n:1关系。即多个会议室会占用同一个会议室。
@@ -630,12 +643,19 @@ DateTime endTime； //会议结束时间
 }
 ```
 #### **2.9 读方案 (ReadPlan)**
-- **定义与用途:** 在TOCO中，读方案描述了一种数据库查询方案，查询条件为一个面向对象的查询语句，其中可以包含存在外键关系的多个实体的字段(如age=18 and name like #nameLike and school.name like #schoolNameLike，其中以#开头的是自定义参数，会自动生成一个QTO结构，由查询调用方动态传入),结果为符合查询条件的**一种**DTO或VO列表。读方案内部会将该面向对象的查询条件转化为复杂的join sql语句，来实现对数据库的查询，以及返回的复杂DTO和VO数据的组装。读方案可以指定其分页方式（不分页、页码分页、瀑布流分页），以及是否生成计数方法(用于返回符合条件的记录数量)。
-- **使用建议:** 如果查询条件只有主键，则建议使用预定义的getBy${PrimaryKey}或getBy${PrimaryKey}s方法来获取DTO（参照DTO的**预定义方法**）或VO（参照**复杂嵌套VO获取流程**），不建议使用读方案。非主键查询或多条件查询建议使用读方案。
-- **关键配置:**  名称(小写字母+下划线，不要以read_plan结尾)、返回结构(DTO/VO，一个读方案**不能**同时返回多种DTO或VO)、查询条件的自然语言描述、是否生成计数方法、排序字段（如果选择不分页，则不需要）
+- **定义与用途:** 在TOCO中，针对DTO和VO，读方案描述了如何基于查询对象从数据库获取DTO和VO列表数据，主要提供了两个能力
+  - 根据查询条件，返回符合条件的DTO或VO的id列表
+  - 根据字段过滤条件，对DTO和VO的列表字段数据进行过滤
+- **关键配置:**  名称(小写字母+下划线，不要以read_plan结尾)、返回结构(DTO/VO，一个读方案**不能**同时返回多种DTO或VO)、查询条件的自然语言描述、是否生成计数方法、排序字段（如果选择不分页，则不需要）、过滤字段以及过滤条件。
 - **与RPC、代码的关系:** 对于每一个返回DTO的读方案，TOCO会为每种分页方式自动生成一个RPC方法，其参数为对应的QTO，返回值为DTO列表；如果选择了生成计数方法，则还会生成一个RPC，参数为QTO，返回值为符合条件的DTO数量。同样，对于每一个返回VO的读方案，TOCO会自动生成一个Java方法，其参数为对应的QTO，返回值为VO列表，方法内部逻辑已经由TOCO完全实现;如果选择了生成计数方法，则还会生成一个count方法，参数为QTO，返回值为符合条件的DTO数量，方法内部逻辑已经由TOCO完全实现
 - **如何创建/生成:** 在创建读方案时，必须先调用工具创建或选择现有的**一种**DTO或VO作为返回值类型，然后再定义查询条件的自然语言描述（如：根据用户姓名、年龄、学校名称，查询用户列表），分页方式、是否生成计数方法、排序字段等。
+- **排序** 对于返回列表数据的排序，排序规则和SQL的排序类似(通过指定字段以及升序|降序，字段可以组合；ReadPlan支持有**两种**方式：
+  - **默认排序**：指定默认排序字段（不需要入参指定排序字段）
+  - **自定义排序**：指定排序字段（需要入参指定排序字段），这种方式通常能很好的满足列表头动态指定排序的需求
+  - **排序字段的来源**：并不是查询字段中的所有字段都能作为排序字段，因为返回的根DTO|VO的id去重列表，所以排序字段只能来源自根WO（不包括列表WO属性: 比如MeetingWO包含了List<MeetingAgendaWO> agendaList属性， 那么agendaList不能作为排序字段），以及根WO扩展出来的非列表属性的WO的字段（比如MeetingWO包含了MeetingRoomWO,那么MeetingRoomWO的属性也能作为排序字段），**注意**：为了唯一确定是给按照那个字段进行排序，排序字段是一个从根节点到当前属性的路径，例如：ADto包含了BDto bDto，BDto具备属性name，如果指定对BDto的name字段排序，则字段路径为：bDto.name
 - 你需要提取需求中的查询部分信息，以输入的查询对象作为查询上下文件，构建一个查询语句
+- 如果有列表属性过滤需求(如果没有filter，对每个列表属性都是放回全部数据，例如：MeetingDto的MeetingAgendaDtoList属性，如果不设置MeetingAgendaDtoList的filter，则返回该会议的全部议程信息)：你需要提取需求中的过滤部分信息，以输入的查询对象作为查询上下文件，针对可过滤字段（列表属性）分别创建过滤条件， **注意** 过滤条件不能使用列表属性作为查询条件属性（即不能使用contains语法），为了唯一确定是给那个列表属性的指定过滤条件，属性字段是一个从根节点属性到当前属性的路径，例如：ADto包含了List<BDto> bDtoList;BDto包含了List<CDto> cDtoList，如果对cDtoList使用Filter，则字段路径为：bDtoList.cDtoList
+- 查询语法和过滤语法
   - 基本语法格式是 属性名 操作符 变量或常量，变量表示了这个数据是外部传入的,用 #变量名为格式；如果是枚举类型常量，需要使用'符号包起来,例如: 男性枚举类型 'MALE'
   - 对于数值、时间类型属性有：!=, ==, >, <,<=,>=, in,notIn, isNullOrNot 这些操作符
   - 对于文本类型属性有：like, isNotNull, isNull,!=, ==, in,notIn, isNullOrNot 这些操作符
@@ -742,20 +762,35 @@ DateTime endTime； //会议结束时间
         "supportUnPage":{"type":"boolean", "description":"如果不需要分页，一次性返回部数据，则返回true"},
         "supportWaterfall":{"type":"boolean","description":"是否需要瀑布流"},
         "query":{"type":"string","description":"查询语句，符合前述语法定义"},
-        "voOrDtoId":{"type":"string","description":"返回数据对象(VO或DTO)的uuid,创建的时候必须指定，更新的时候不传递"}
+        "voOrDtoId":{"type":"string","description":"返回数据对象(VO或DTO)的uuid,创建的时候必须指定，更新的时候不传递"},
+        "outOrder":{"type":"array","description":"入参排序方式定义",
+            "items":{"type":"object","description":"定义字段排序方式","required":["field", "incr"],
+                  "properties":{"fieldPath": {"type":"string","description":"字段名路径"},"incr": {"type":"boolean","description":"是否升序"}}}
+        },
+        "defaultOrder": {"type":"array","description":"默认排序方式定义",
+            "items": {"type":"object","description":"定义字段排序方式","required":["field", "incr"],
+            "properties":{"fieldPath": {"type":"string","description":"字段名"},"incr": {"type":"boolean","description":"是否升序"}}}
+        },  
+        "filters": {"type": "array", "description":"过滤条件定义",
+            "items": {"type":"object","description":"定义过滤条件","required":["field", "filter"],
+                "properties":{
+                  "fieldPath": {"type":"string","description":"需要过滤的列表字段路径"},
+                  "filter": {"type":"object","description":"过滤语法，符合前述的语法定义,不能使用contains语法"}
+                } 
+            } 
        },
        "required":["name","description","query"]
      }
     },
     "required":["qto"]
     }
+  }
   ```
 - **举例**
   - 上下文
     ```java
     public class meeting_room { 
             storey storey;  // 楼层id
-            List<image_storage_info_eo> picture;  // 照片
             String name;  // 名称
             room_type_enum room_type;  // 会议室类型
             List<equipment_enum> equipment;  // 设备
@@ -764,21 +799,14 @@ DateTime endTime； //会议结束时间
             String description;  // 说明
             Boolean enable_indicator;  // 是否启用
             String input_code;  // 输入码
-            Date created_at;  // 创建时间
-            Date updated_at;  // 更新时间
             Long storey_id;  // 楼层id
-            Long lock_version;  // 乐观锁字段
             Long contact_staff_id;  // 联系员工ID
-            List<meeting> meeting;  
-            Long deleted_at;  // 删除时间
+            List<meeting> meeting;  //注意：该字段可添加过滤条件
         class storey { // 建筑的楼层
             location location;  // 位置id
             String name;  // 楼层
             Long id;  // 主键
             Long sort_number;  // 排序号
-            Date created_at;  // 创建时间
-            Date updated_at;  // 更新时间
-            Long deleted_at;  // 删除时间
             Long location_id;  // 位置id
         }
         class meeting { 
@@ -789,18 +817,12 @@ DateTime endTime； //会议结束时间
             Long room_id;  // 会议室id
             String description;  // 描述
             Long create_user_id;  // 创建人id
-            Date created_at;  // 创建时间
-            Date updated_at;  // 更新时间
-            Long deleted_at;  // 删除时间
         }
         class location { // 位置信息，如楼栋
             String name;  // 名称
             Long id;  // 主键
             String description;  // 描述
             Long sort_number;  // 排序号
-            Date created_at;  // 创建时间
-            Date updated_at;  // 更新时间
-            Long deleted_at;  // 删除时间
         }
         enum room_type_enum { // 
             SMALL, //小会议室 
@@ -816,21 +838,25 @@ DateTime endTime； //会议结束时间
       }
      ```
   - 用户需求
-    获取一段时间未被使用的会议室(包含当前会议已选择的会议室),分页返回
+    获取一段时间未被使用的会议室(包含当前会议已选择的会议室),并且根据会议名称会议信息，最后分页返回。
   - 对应的读方案定义
     ```json
     {
-      "qto": {
         "name": "get_unused_meeting_room_list",
         "description": "获取未使用的会议室(包含当前会议已选择的会议室)",
         "woId":"759bedd4-4540-4de6-b65d-d44912fb0991",
-        "dtoOrVoId":"e50c02c3-f336-4dc6-88e1-24ffe3dea1e2"
+        "dtoOrVoId":"e50c02c3-f336-4dc6-88e1-24ffe3dea1e2",
         "generateCountApi": true,
         "supportPaginate": true,
         "supportUnPage": false,
         "supportWaterfall": false,
-        "query": "enable_indicator == true AND ( id == #idIs OR meeting isNull OR NOT ( meeting contains ( start_time <= #meetingEndTime AND end_time >= #meetingStartTime ) ) )"
+        "query": "enable_indicator == true AND ( id == #idIs OR meeting isNull OR NOT ( meeting contains ( start_time <= #meetingEndTime AND end_time >= #meetingStartTime ) ) )",
+        "filters": [
+            {
+              "filteredField": "meeting",
+              "filter": "title like #meetingTitleLike"
             }
+        ]
     }
     ```
 - **代码产物和修改建议**