jeeflow-facade

    jeeflow unified facade: flow(action, args) over the whole action surface + contract outlet layer

    Download zip
    Author
    Version
    0.1.67
    License
    Apache-2.0
    Last updated
    9 days ago
    Downloads
    828

    #jeeflow-facade

    Every jeeflow workflow capability behind one call — flow(action, args).

    The unified action facade of jeeflow-moon: one entry point, one federation envelope (code=0 success / 99999999 failure), one outbound contract layer that every response passes through.

    #Install

    moon add without a version resolves the latest published generation and pins the exact number into moon.mod. The facade needs its own module plus the engine core it dispatches into, and an async runtime for async fn main:

    moon new my-flow && cd my-flow moon add mldong/jeeflow-core # engine heart + SPI (zero registry dependencies) moon add mldong/jeeflow-facade # this module: flow(action, args) moon add moonbitlang/async # flow is async; async main needs it

    #Quickstart

    Two files, copy-paste complete. On a factory-fresh MemoryRepository nothing is seeded, so the very first call already proves the envelope:

    // cmd/main/moon.pkg
    import {
    "mldong/jeeflow-core/spi" @spi,
    "mldong/jeeflow-core/memory" @memory,
    "mldong/jeeflow-core/json" @json,
    "mldong/jeeflow-facade" @facade,
    "moonbitlang/async",
    }

    pkgtype(kind: "executable")

    // cmd/main/main.mbt — the repository is a generic parameter, small SPIs are closure fields
    async fn main raise {
    let repo = @memory.MemoryRepository::new()
    let ctx = @spi.Ctx::new(repo, repo)
    let facade = @facade.Facade::make(ctx)
    let args : Map[String, Json] = { "processDefineId": 1, "operator": "applicant" }
    println(@json.stringify(facade.flow("processDefine/startAndExecute", args)))
    }

    {"code":99999999,"msg":"流程定义不存在: 1"}

    Run it with moon run cmd/main --target wasm. To drive a real flow, put a process definition in the store first (processDefine/deploy, or processDefine/startAndExecute against mldong/jeeflow-repository-mysql pointed at a database holding schema/schema-mysql.sql).

    For the positive counterpart — a full leave flow (start, todo, execute, end) on the same in-memory wiring — see the mldong/jeeflow-core page's Quickstart. It drives the engine directly; flow(action, args) wraps those same engine steps behind one call.

    The response of any action is the same three-key envelope, so flow can sit behind one HTTP route in your framework of choice — that is exactly how the mldong MoonBit stack (github.com/mldong/mldong-moon, plugins/jeeflow) wires it.

    #The action surface

    groupactions
    processDefinepage · detail · startAndExecute · deploy · redeploy · remove · upAndDown · getLastByName
    processInstancepage · detail · startAndExecute · withdraw · bizData · highLight · approvalRecord · getAssigneeTextData · createCCInstance · updateCCStatus · ccList · stats/overview · stats/trend · stats/group
    processTasktodoList · doneList · execute · detail · jumpAbleTaskNameList · candidatePage · surrogate · addCandidate · transfer · removeTaskActor · recall · revokeDynamicCountersign · aidant · latest
    processDesign (ext repository)page · detail · save · update · updateDefine · remove · deploy · redeploy · listByType
    processSurrogate (ext repository)page · save · update · detail · remove

    Every accepted name is a dispatch arm in ./facade.mbt, which ships inside this package: that file, not this table, is the authority. In the source repository the same list is also kept as scripts/action-manifest.json and diffed against the Java reference implementation in both directions (node scripts/check-action-manifest.mjs). This page lists the names, not a number, so it cannot silently fall behind.

    #Outbound contract layer (enforced, not optional)

    • recursive id stringification — id / *Id / *_id, and plural ids / *Ids arrays element-wise (snowflakes exceed float64);
    • five-key pagination — pageNum/pageSize/recordCount/totalPage/rows;
    • time normalization — yyyy-MM-dd HH:mm:ss, ISO T folded to space;
    • stats as pure columns — overview, trend (hour/day/ISO-week/month buckets), group (dimensions incl. stuck-node/approver and duration buckets), explicit errors on missing/invalid params;
    • an unknown action is not a crash: {code:99999999, msg:"未知 action: <action>"}.

    #License

    Apache-2.0 — the full text ships next to this README (./LICENSE). Part of jeeflow-moon.

    Facade

    pub(all) struct Facade[R, E] {
    engine :
    Engine
    [R, E]
    repo : R
    ext_repo : E
    }

    Facade::approval_record

    审批记录(spec 06 §processInstance/approvalRecord · issues/154 四条口径逐条对号): ① 排序 ORDER BY id ASC——本栈两条取数腿都已经是 id 升序,无需门面再排:内存仓 core/memory/memory.mbt:233 find_history_tasks 走 sorted_ids→@model.sort_i64(升序); SQL 腿 repository-mysql/repo/repository.mbt:376 明写 ORDER BY id。共享方法 engine_ops.mbt:100 也吃这条腿,本轮不动它(排序已合规,动它是无收益的连带风险)。 ② 实例 id 不存在 ⇒ 空数组,不报「流程实例不存在」——本函数从不 find_instance_by_id, 直接 find_history_tasks(id),查不到行就是空表 ⇒ 已合规(withdraw 那种先查实例再 raise InstanceNotFound 的姿势才是违约形状,此处没有)。 ③ 任务变量为空 ⇒ ext 出空对象,不得回落实例变量——本函数只读 t.variables, to_object_json() 对空 FlowData 出 {},代码里不存在任何实例变量回落分支 ⇒ 已合规。 ④ 出口列集合=九键(id/taskName/displayName/taskType/performType/taskState/operator/finishTime/ext), variable 原串不得再出现——variable 那一列本轮之前就已下线,本轮补首列 id 补齐九键。

    Facade::design_list_by_type

    listByType:发起页数据契约(issues/28;分组契约 C14)

    Facade::engine

    fn[R, E] Facade::engine(self : Facade[R, E]) ->
    Engine
    [R, E]

    Facade::execute

    提交任务(submitType 分发,java execute 同款)

    issues/247 动态会签(征询模式)在这一跳分两次截流,判据全部排在状态变更之前: ① try_dynamic_countersign_async——征询节点带 tf_addSignOperators 的提交=只建成员行、 不办结主办行,返回响应 marker {dynamicCountersign:{round,total,submitted}} 直接出信封 (=java execute 里 if (collect != null) return ok(collect) 那一刀); ② gate_dynamic_countersign_async——主办行未收齐成员意见 ⇒ 逐字文案报错,挡全部 submitType (含驳回 2),唯一出口=processTask/revokeDynamicCountersign(owner 拍「全部置灰+撤回接口」); 成员行携带拉人参数同样在这里报它的逐字文案。 两刀都在分发之前 ⇒ 被拦下的那一次一行状态都没动(报错即零写入)。

    Facade::flow

    统一入口:flow(action, args) → {code,msg,data}

    Facade::make

    fn[R, E] Facade::make(ctx :
    Ctx
    [R, E]) -> Facade[R, E]

    Facade::start_and_execute

    发起并自动完成申请节点(define/instance 共用)

    Facade::task_aidant

    动态协办(issues/253):主办把"这活"交给别人干——按人派生 task_type=1 协办子行, 主办行原样保留 DOING,节点推进仍由主办行办结触发。

    参数位序照 java:operator 硬必填在前(空/纯空白 ⇒ operator 必填, ⚠️ 严禁用 operator_arg——那支空档回落 demo 缺省 user1,本 action 不接受), 再取 processTaskId(缺失 ⇒ processTaskId 缺失),actorIds 逗号串与数组两形共用 §2.11 那枚归一单点(arg_actor_ids),空 ⇒ 逐字「actorIds 必填」。 reason 选填(缺失/JSON null ⇒ None,其余标量按原文串收,=java toStr); waitCompletion 选填 bool,缺省 false=主办不等协办办结即可推进。

    Facade::task_recall

    已办撤回(issues/246,spec 06 §processTask/recall):办理人撤回自己刚办结的那一手, 同实例内复活重办。判据与落库全在引擎(Engine::recall_task_async),门面只做参数归一 (主键档缺失响亮报错,绝不拿 ''/0 当 id 落库)与信封包装。

    参数位序照 java:operator 硬必填在前(空/纯空白 ⇒ operator 必填, ⚠️ 严禁用 operator_arg——那支空档回落 demo 缺省 user1,本 action 不接受), 再取 processTaskId(缺失 ⇒ processTaskId 缺失)。

    出参 data={processTaskId, taskState}:processTaskId=复活的新行 id(出口层 C1 把 *Id 键字符串化 ⇒ 与 java String.valueOf(taskId) 同形),taskState=10(DOING)。

    Facade::task_remove_actor

    摘除参与人(issues/115 残留 · 门面第 47 个 action,spec 06 §processTask/removeTaskActor)。 SPI 的 remove_task_actor 从第一天起就是必选方法(两仓都实现),本 action 补的是"上到门面" 这一段,逐字基准=java JeeflowFacade.taskRemoveActor。三个兄弟 action 的分工: · processTask/surrogate/addCandidate = 只加(追加,原人保留可办); · processTask/transfer = 换人(摘 A 加 B + submitType=7 留痕 + tf_transferHistory); · 本 action = 只摘不加、零留痕、不 fire 事件:删掉 actorIds 在本任务的参与者行,不新建任务、 不写任何任务变量、不覆写任务 actor_id/operator 列,也一次事件都不发——issues/132 §11.3 定稿事件集里没有"摘人"这一码,码 7 TASK_TRANSFER 的语义是"参与者被替换",只摘不加套它 等于凭空造出一条没发生的转办事实(要留痕请用 transfer)。

    守卫次序(spec 同节钉死、逐栈一致,门禁按 msg 断言,不接受本栈自行排序): operator 必填 → processTaskId/actorIds 缺失 → 任务不存在 → 无权限摘除该任务参与人 → 任务非进行中,不可摘除参与人 → 至少需保留一名参与人 → 落库。

    Facade::task_revoke_countersign

    撤回动态会签(issues/247,spec 06 §processTask/revokeDynamicCountersign):废弃主办行下全部 未答成员行、账本追加撤回条目(revoked=true)、已交意见行原样保留、闸门自然恢复、轮次不消耗。 独立 action,不进 execute 参数空间(撤回不是办结动作;任务操作族先例=transfer/removeTaskActor)。 判据与废弃全在引擎(Engine::revoke_dynamic_countersign_async)。

    Facade::task_surrogate

    加签(addTaskActor=去重追加非全删全插,C14)

    Facade::task_transfer

    转办(issues/115,spec/06 §processTask/transfer 七条语义): 摘原人 → 加新人 → 同一 taskId 不新建 → 三件留痕(submitType=7 槽位 + tf_transferHistory 追加式账本 + tf_transferTo/tf_transferReason 便捷键 + 末跳 tf_approvalComment)→ 去重/前置态四类明确报错。区别于 processTask/surrogate 加签的"只追加不动原人"。

    Facade::withdraw

    撤回(issues/113/114):operator 硬必填 + 三条归属判据 + 任务态 30 级联 + update_user 回写

    CODE_ERROR

    let CODE_ERROR : Int64

    CODE_SUCCESS

    let CODE_SUCCESS : Int64

    arg_actor_ids

    fn arg_actor_ids(args : Map[String,
    Json
    ]) -> Array[String]
    空入参档由调用方沿用各自既有的"缺参数"错误信封(§2.11 要求③:不新造错误码与文案)。

    arg_i64

    fn arg_i64(args : Map[String,
    Json
    ], key : String) -> Int64? raise
    JeeflowError
    i64 双收:数字/字符串;存在但不可解析 → "非法id"

    arg_i64_or

    fn arg_i64_or(args : Map[String,
    Json
    ], key : String, default : Int64) -> Int64 raise
    JeeflowError

    arg_id

    fn arg_id(args : Map[String,
    Json
    ], keys : Array[String]) -> Int64? raise
    JeeflowError
    首个存在的 i64(多候选键)

    arg_ids

    批量主键:{ids} 优先 {id} 兜底;空显式报错(issues/95)

    arg_str

    fn arg_str(args : Map[String,
    Json
    ], key : String) -> String?

    arg_str_or

    fn arg_str_or(args : Map[String,
    Json
    ], key : String, default : String) -> String

    arg_submit_type

    fn arg_submit_type(args : Map[String,
    Json
    ], key? : String) -> Int64? raise
    JeeflowError
    submitType 双收(数字/字符串)

    args_to_flow_data

    fn args_to_flow_data(args : Map[String,
    Json
    ], exclude : Array[String]) ->
    FlowData
    args → FlowData(剔除 facade 控制键)

    candidate_row

    fn candidate_row(actor_id : String, real_name : String, extra : Map[String,
    Json
    ]?) ->
    Json
    candidate 行键归一(issues/80)

    content_bytes

    fn content_bytes(args : Map[String,
    Json
    ]) -> String?
    content:字符串/对象/顶层 JSON 兼容(issues/27)

    err

    fn err(msg : String) ->
    Json

    facade_parse_m_filters

    first_task_node_id

    fn first_task_node_id(json_object :
    Json
    ?) -> String?

    flow_data_to_object

    form_data_of_flow

    fn form_data_of_flow(vars :
    FlowData
    , prefix : String) ->
    Json

    form_data_of_map

    fn form_data_of_map(vars : Map[String,
    Json
    ], prefix : String) ->
    Json
    表单数据派生(issues/15):prefix 键带前缀 + 去前缀双份

    format_time_fields

    C7:时间键格式化(NOW() 占位 / ISO T → 空格)

    is_ok

    fn is_ok(env :
    Json
    ) -> Bool

    operator_arg

    fn operator_arg(args : Map[String,
    Json
    ]) -> String
    issues/114 的 `arg_required_str`(operator 硬必填、缺失即报错、返回 trim 后值)是另一档语义,别混用。

    page_to_json

    分页五键(C22)

    parse_epoch_secs

    fn parse_epoch_secs(s : String) -> Int64?
    "yyyy-MM-dd[ HH:mm[:ss]]" → epoch 秒(civil 算法逆运算)

    parse_graph

    fn parse_graph(content : String) ->
    Json
    ?

    parse_json_map

    fn parse_json_map(s : String?) -> Map[String,
    Json
    ]

    stringify_ids

    C1:id/Id/_id 单数键值字符串化(递归);ids/Ids/_ids 复数键逐元素

    transform_output

    出口统一变换:camelCase → id 字符串化 → 时间格式化