flow:Improve code comments (#732)

Author: ZzIsGod1019

Cargo.toml

@@ -60,9 +60,9 @@ run_script = { version = "0.10" }
 testcontainers-modules = { version = "0.3", features = ["redis"] }
 strum = { version = "0.26", features = ["derive"] }
 # tardis
-tardis = { version = "0.1.0-rc.15" }
+# tardis = { version = "0.1.0-rc.15" }
 # tardis = { path = "../tardis/tardis" }
-# tardis = { git = "https://github.com/ideal-world/tardis.git", rev = "694ff92" }
+tardis = { git = "https://github.com/ideal-world/tardis.git", rev = "9c18c2a" }
 #spacegate
 
 # spacegate-kernel = { git = "https://github.com/ideal-world/spacegate.git", rev = "f37a81a", features = [

backend/middlewares/flow/src/api/cc/flow_cc_model_api.rs

@@ -12,7 +12,7 @@ use tardis::web::web_resp::{TardisApiResult, TardisPage, TardisResp, Void};
 
 use crate::dto::flow_model_dto::{
     FlowModelAddCustomModelReq, FlowModelAddCustomModelResp, FlowModelAddReq, FlowModelAggResp, FlowModelBindStateReq, FlowModelFilterReq, FlowModelFindRelStateResp,
-    FlowModelModifyReq, FlowModelSortStatesReq, FlowModelSummaryResp, FlowModelUnbindStateReq, FlowTemplateModelResp,
+    FlowModelModifyReq, FlowModelSortStatesReq, FlowModelSummaryResp, FlowModelUnbindStateReq,
 };
 use crate::dto::flow_state_dto::FlowStateRelModelModifyReq;
 use crate::dto::flow_transition_dto::{FlowTransitionModifyReq, FlowTransitionSortStatesReq};
@@ -101,9 +101,9 @@ impl FlowCcModelApi {
         TardisResp::ok(result)
     }
 
-    /// Find the specified models, or add it if it doesn't exist.
+    /// Find the specified models, or create it if it doesn't exist.
     ///
-    /// 查找指定model，如果不存在则新增
+    /// 查找指定model，如果不存在则创建。创建规则遵循add_custom_model接口逻辑。
     ///
     /// # Parameters
     /// - `tag_ids` - list of tag_id
@@ -117,10 +117,10 @@ impl FlowCcModelApi {
         is_shared: Query<Option<bool>>,
         ctx: TardisContextExtractor,
         _request: &Request,
-    ) -> TardisApiResult<HashMap<String, FlowTemplateModelResp>> {
+    ) -> TardisApiResult<HashMap<String, FlowModelSummaryResp>> {
         let mut funs = flow_constants::get_tardis_inst();
         funs.begin().await?;
-        let tag_ids: Vec<_> = tag_ids.split(',').collect();
+        let tag_ids= tag_ids.split(',').map(|tag_id| tag_id.to_string()).collect_vec();
         let result = FlowModelServ::find_or_add_models(tag_ids, temp_id.0, is_shared.unwrap_or(false), &funs, &ctx.0).await?;
         funs.commit().await?;
         TardisResp::ok(result)
@@ -255,6 +255,7 @@ impl FlowCcModelApi {
     /// copy parent model to current own_paths
     ///
     /// 复制父级模型到当前 own_paths
+    /// 实际创建规则：按照 tags 创建模型，若传入proj_template_id，则优先寻找对应的父级模型，否则则获取默认模板模型生成对应的自定义模型。
     #[oai(path = "/add_custom_model", method = "post")]
     async fn add_custom_model(&self, req: Json<FlowModelAddCustomModelReq>, ctx: TardisContextExtractor, _request: &Request) -> TardisApiResult<Vec<FlowModelAddCustomModelResp>> {
         let mut funs = flow_constants::get_tardis_inst();

backend/middlewares/flow/src/domain/flow_transition.rs

@@ -4,7 +4,7 @@ use tardis::db::sea_orm::prelude::Json;
 use tardis::db::sea_orm::*;
 use tardis::{chrono, TardisCreateEntity, TardisEmptyBehavior, TardisEmptyRelation};
 
-use crate::dto::flow_transition_dto::{FlowTransitionActionChangeInfo, FlowTransitionDoubleCheckInfo, FlowTransitionFrontActionInfo};
+use crate::dto::flow_transition_dto::{FlowTransitionPostActionInfo, FlowTransitionDoubleCheckInfo, FlowTransitionFrontActionInfo};
 use crate::dto::flow_var_dto::FlowVarInfo;
 
 /// Transfer / 流转
@@ -91,7 +91,7 @@ pub struct Model {
 
     #[sea_orm(column_type = "Json")]
     #[tardis_entity(custom_type = "Json")]
-    pub action_by_post_changes: Vec<FlowTransitionActionChangeInfo>,
+    pub action_by_post_changes: Vec<FlowTransitionPostActionInfo>,
 
     #[sea_orm(column_type = "Json")]
     #[tardis_entity(custom_type = "Json")]

backend/middlewares/flow/src/dto/flow_external_dto.rs

@@ -7,15 +7,18 @@ use tardis::web::poem_openapi::{
 
 use super::{flow_state_dto::FlowSysStateKind, flow_transition_dto::FlowTransitionActionByVarChangeInfoChangedKind};
 
+/// External data exchange requests
+/// 
+/// 对外数据交换请求
 #[derive(Serialize, Deserialize, Debug, Default, poem_openapi::Object)]
 pub struct FlowExternalReq {
-    /// Type of request initiated, ex: query field, modification field, status change notification...
+    /// Associated [enum](FlowExternalKind)
     ///
-    /// 发起请求的类型，例：查询字段，修改字段，状态变更通知..
+    /// 关联的[枚举](FlowExternalKind)
     pub kind: FlowExternalKind,
-    /// When kind is ModifyField, the field is modified in a specific way, for example: validate the content, post action, precondition trigger ...
+    /// Associated [enum](FlowExternalCallbackOp)
     ///
-    /// 当 kind 为 ModifyField 时，字段被修改的具体操作方式，例：验证内容，后置动作，前置条件触发..
+    /// 关联的[枚举](FlowExternalCallbackOp)
     pub callback_op: Option<FlowExternalCallbackOp>,
     /// The tag corresponding to the current business
     ///
@@ -25,25 +28,25 @@ pub struct FlowExternalReq {
     ///
     /// 当前业务ID
     pub curr_bus_obj_id: String,
-    /// Workflow Instance ID
+    /// Associated [flow_instance](super::flow_inst_dto::FlowInstDetailResp) id
     ///
-    /// 工作流实例ID
+    /// 关联的[工作流实例](super::flow_inst_dto::FlowInstDetailResp) id
     pub inst_id: String,
     /// Modified State ID
     ///
     /// 修改后的状态ID
     pub target_state: Option<String>,
-    /// Modified state type
+    /// Associated [enum](super::flow_state_dto::FlowSysStateKind)
     ///
-    /// 修改后的状态类型
+    /// 关联的[枚举](super::flow_state_dto::FlowSysStateKind)
     pub target_sys_state: Option<FlowSysStateKind>,
     /// Status ID before modification
     ///
     /// 修改前的状态ID
     pub original_state: Option<String>,
-    /// Type of state before modification
+    /// Associated [enum](super::flow_state_dto::FlowSysStateKind)
     ///
-    /// 修改前的状态类型
+    /// 关联的[枚举](super::flow_state_dto::FlowSysStateKind)
     pub original_sys_state: Option<FlowSysStateKind>,
     /// Name of the action actually triggered (business side logging operation)
     ///
@@ -64,31 +67,53 @@ pub struct FlowExternalReq {
     pub params: Vec<FlowExternalParams>,
 }
 
+/// Type of request initiated, ex: query field, modification field, status change notification...
+/// 
+/// 发起请求的类型，例：查询字段，修改字段，状态变更通知..
 #[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize, Serialize, poem_openapi::Enum)]
 pub enum FlowExternalKind {
     #[default]
+    /// 获取关联业务对象
     FetchRelObj,
+    /// 修改字段
     ModifyField,
+    /// 状态变更通知
     NotifyChanges,
+    /// 查询字段值
     QueryField,
 }
 
+/// When kind is ModifyField, the field is modified in a specific way, for example: validate the content, post action, precondition trigger ...
+/// 
+/// 当 kind 为 ModifyField 时，字段被修改的具体操作方式，例：验证内容，后置动作，前置条件触发..
 #[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Deserialize, Serialize, poem_openapi::Enum)]
 pub enum FlowExternalCallbackOp {
     #[default]
     Default,
+    /// 后置动作
     PostAction,
+    /// 验证内容
     VerifyContent,
+    /// 条件触发
     ConditionalTrigger,
 }
 
+/// 扩展字段
+/// 
+/// Extended params
 #[derive(Debug, Deserialize, Serialize, poem_openapi::Object, Clone)]
 pub struct FlowExternalParams {
+    /// 关联的 Tag
     pub rel_tag: Option<String>,
+    /// 关联类型 TagRelKind
     pub rel_kind: Option<String>,
+    /// 字段ID
     pub var_id: Option<String>,
+    /// 字段名
     pub var_name: Option<String>,
+    /// 修改成的值
     pub value: Option<Value>,
+    /// 修改方式
     pub changed_kind: Option<FlowTransitionActionByVarChangeInfoChangedKind>,
 }
 
@@ -104,14 +129,19 @@ where
 
 #[derive(Default, Serialize, Deserialize, Debug, poem_openapi::Object)]
 pub struct FlowExternalFetchRelObjResp {
+    /// 当前Tag
     pub curr_tag: String,
+    /// 当前业务ID
     pub curr_bus_obj_id: String,
+    /// 关联业务对象
     pub rel_bus_objs: Vec<RelBusObjResp>,
 }
 
 #[derive(Default, Serialize, Deserialize, Debug, poem_openapi::Object)]
 pub struct RelBusObjResp {
+    /// 关联对象的Tag
     pub rel_tag: String,
+    /// 关联业务对象ID
     pub rel_bus_obj_ids: Vec<String>,
 }