diff --git a/en/docs/api-reference/internal.md b/en/docs/api-reference/internal.md index b782547..edec082 100644 --- a/en/docs/api-reference/internal.md +++ b/en/docs/api-reference/internal.md @@ -54,6 +54,7 @@ virtual tables) there is a parallel surface in | `/procedureCall/*` | `GenericProcedureCallController` | Generic stored-procedure invocation by name + parameters — see [generic procedure dispatch](../reference/maintainer/proc-dispatch.md). | | `/panel/*` | `ConfigformPanelController` | Panel-layout persistence in `gdsconfigformpanel`. | | `/checkflow/*` | `CheckFlowController` | Activiti workflow surface (approve / reject / view) — only meaningful in deployments that run a flow. The class file is `CheckFlowController.java` (camelCase) but the `@RequestMapping` value is all-lowercase `/checkflow`. | +| `/modelCenter/getModelCenter`, `/modelCenter/getModelCenterCalculation` | `BusinessModelCenterController` | The FROUNT home-page **KPI Work Center** card (titled `KPI监控`). Aggregates open tasks across modules tagged `gdsmodule.bUnTask=1`, partitioned by role and business flow. **Not Activiti-driven.** See [The KPI Work Center](../reference/maintainer/runtime.md#the-kpi-work-center-front-end-home-dashboard). | ## Reporting and printing diff --git a/en/docs/reference/maintainer/runtime.md b/en/docs/reference/maintainer/runtime.md index dedf9a7..a73246a 100644 --- a/en/docs/reference/maintainer/runtime.md +++ b/en/docs/reference/maintainer/runtime.md @@ -17,12 +17,93 @@ controllers and services that carry most of the generic form runtime. | `GenericProcedureCallController` | `web/businessweb/` | Generic stored-procedure invocation by name + parameters. | `/procedureCall/doGenericProcedureCall` | | `ConfigformPanelController` | `web/businessweb/` | Panel-layout persistence in `gdsconfigformpanel`. | `/panel/get/{sFormId}`, `/panel/save/{sFormId}` | | `CheckFlowController` | `web/businessweb/` | Activiti workflow surface (approve / reject / view) — only meaningful when workflow is deployed. | endpoints under `/checkflow/*` (the class file is `CheckFlowController.java` in camelCase but the `@RequestMapping` value is all-lowercase) | +| `BusinessModelCenterController` | `web/businessweb/` | The "KPI Work Center" home dashboard on FROUNT — open-task aggregation across modules tagged with `gdsmodule.bUnTask=1`. **Not Activiti-driven** despite the workflow-flavoured UI; reads from `gdsmodule` rows partitioned by `sUnType` ∈ {`Pending`, `PendingCheck`, `MyWarning`}. Cached per user. See [The KPI Work Center](#the-kpi-work-center-front-end-home-dashboard) below. | `/modelCenter/getModelCenter`, `/modelCenter/getModelCenterCalculation` | Note that the controllers split across **two packages**: `businessweb/` hosts the runtime-facing endpoints, while `systemweb/` hosts the metadata-CRUD endpoints used by the builder side. Both compile into the same `xlyEntry` WAR. +## The KPI Work Center (front-end home dashboard) + +When a user lands on FROUNT (`http://:8598/indexPage`), the home +page shows a card titled **`KPI监控`** ("KPI Monitor"). Despite the +name, this is *not* a KPI dashboard in the analytics sense — there +are no targets, no charts, no measurements. It's an **open-task +aggregator**: a unified inbox of "things you owe action on", grouped +by role and by business flow. + +The handler: + +- `POST /xlyEntry/modelCenter/getModelCenter` → + `BusinessModelCenterController.java:44-48` → + `BusinessModelCenterServiceImpl.getKPIModelList` (a thin wrapper) → + `BusinessModelKpiServiceImpl.getKPIModelList` in `xlyBusinessService`. +- `POST /xlyEntry/modelCenter/getModelCenterCalculation` recomputes + the counts and evicts the cache region `getKpiModelByUser`. + +The Javadoc on `getModelCenter` calls it **"初次获取KPI工作中心"** +("initial fetch of KPI Work Center") — that's the framework's +internal name for this surface. + +### Data source — `gdsmodule` open-task tagging + +The KPI Work Center reads from `gdsmodule`, not from +Activiti's `act_*` tables. Every module that participates in the +dashboard sets four columns on its `gdsmodule` row: + +| Column | Comment | Meaning | +|---|---|---| +| `bUnTask` | `是否增加到未清` ("add to open list?") | `1` = include in the dashboard, `0` = ignore | +| `sUnType` | `未清类型` ("open type") | Bucket: one of `Pending`, `PendingCheck`, `MyWarning` | +| `sChineseUnMemo`, `sEnglishUnMemo`, `sBig5UnMemo` | `未清描述` ("open description") | Display label per language | + +In the live dev DB, `bUnTask = 1` is set on **92** module rows, split: + +| `sUnType` | Count | Frontend bucket label | +|---|---:|---| +| `Pending` | 79 | 待处理事务 (pending tasks) | +| `PendingCheck` | 1 | 发起新事务 (initiate new) | +| `MyWarning` | 3 | 我的预警报表 (my warnings) | +| (NULL) | 9 | (untagged — excluded) | + +For each tagged module, `BusinessModelKpiServiceImpl` runs the +module's per-user count query and aggregates results by: + +- **Role** (按角色 in the UI): joins `sftlogininfojurisdictiongroup` + ⋈ `sisjurisdictionclassify` to map the calling user to roles, then + partitions counts by role. +- **Flow** (按流程 in the UI): the labels like `估价管理流程` / + `订单生产流程` come from the module's parent in the `gdsmodule` + tree — each business flow is a parent module containing 1-N + ordered child modules. The "01/04, 02/04…" step numbering in the + UI is the child module's `iOrder` within its parent flow. + +### Cache + +`@Cacheable(value="getKpiModelByUser", key=…)` caches the per-user +result; `getModelCenterCalculation` and any +`gdsmodule`-changing path invalidate this region via +[`CleanRedisServiceImpl`](cache-invalidation.md). With `bUnTask` / +`sUnType` editable through BACK's 系统模块配置 screen, a maintainer +adding a new "open task" to the dashboard does so by editing +metadata, not Java. + +### Why not Activiti? + +Activiti's job is **approval workflow** — when a row needs sign-off +through an N-step `act_re_procdef` graph, the `act_ru_task` / +`biz_todo_item` tables hold pending tasks per assignee. That is a +*different* surface from the KPI Work Center, even though both +present "things to do" to the user. + +In this dev DB, `biz_todo_item` and `biz_flow` are both empty +(0 rows) — yet the KPI Work Center still shows non-zero counts. +That's the empirical proof that the two systems are independent. +A deployment with active Activiti flows would surface those tasks +through `CheckFlowController` (`/checkflow/*`) and a separate flow +panel — not through the KPI Work Center. + ## The five-key read For any metadata-driven module, the request lifecycle (see