docs: en wiki — document the KPI Work Center (FROUNT home dashboard)

Investigated the FROUNT home-page card titled `KPI监控` to determine whether it's Activiti-driven (it isn't). Findings: - Endpoint: POST /xlyEntry/modelCenter/getModelCenter → BusinessModelCenterController.getModelCenter (xlyEntry, web/businessweb/) → BusinessModelCenterServiceImpl.getKPIModelList (thin wrapper) → BusinessModelKpiServiceImpl.getKPIModelList (xlyBusinessService). - Internal name: "KPI Work Center" (Javadoc 初次获取KPI工作中心). - Data source: gdsmodule rows where bUnTask=1, partitioned by sUnType ∈ {Pending, PendingCheck, MyWarning}. No KPI math; just open-task aggregation. - Categorisation in UI: by role (sftlogininfojurisdictiongroup ⋈ sisjurisdictionclassify) and by business flow (gdsmodule parent- child tree; "01/04, 02/04…" is the iOrder within a flow parent). - Cache: @Cacheable(value="getKpiModelByUser") evicted by getModelCenterCalculation and gdsmodule-changing paths. - Empirical proof of independence from Activiti: in this dev DB, biz_todo_item and biz_flow are both 0 rows, yet the KPI Work Center still shows non-zero counts. Activiti's task surface flows through CheckFlowController instead. Updates: - runtime.md: add BusinessModelCenterController row to the load- bearing-controllers table; new "The KPI Work Center" subsection with full architecture, data source, cache behaviour, and the why-not-Activiti contrast. - internal.md: add /modelCenter/* row to the runtime endpoints table with cross-link.

docs: en wiki — document the KPI Work Center (FROUNT home dashboard)
Investigated the FROUNT home-page card titled `KPI监控` to determine whether it's Activiti-driven (it isn't). Findings: - Endpoint: POST /xlyEntry/modelCenter/getModelCenter → BusinessModelCenterController.getModelCenter (xlyEntry, web/businessweb/) → BusinessModelCenterServiceImpl.getKPIModelList (thin wrapper) → BusinessModelKpiServiceImpl.getKPIModelList (xlyBusinessService). - Internal name: "KPI Work Center" (Javadoc 初次获取KPI工作中心). - Data source: gdsmodule rows where bUnTask=1, partitioned by sUnType ∈ {Pending, PendingCheck, MyWarning}. No KPI math; just open-task aggregation. - Categorisation in UI: by role (sftlogininfojurisdictiongroup ⋈ sisjurisdictionclassify) and by business flow (gdsmodule parent- child tree; "01/04, 02/04…" is the iOrder within a flow parent). - Cache: @Cacheable(value="getKpiModelByUser") evicted by getModelCenterCalculation and gdsmodule-changing paths. - Empirical proof of independence from Activiti: in this dev DB, biz_todo_item and biz_flow are both 0 rows, yet the KPI Work Center still shows non-zero counts. Activiti's task surface flows through CheckFlowController instead. Updates: - runtime.md: add BusinessModelCenterController row to the load- bearing-controllers table; new "The KPI Work Center" subsection with full architecture, data source, cache behaviour, and the why-not-Activiti contrast. - internal.md: add /modelCenter/* row to the runtime endpoints table with cross-link.
zichun
1 parent 047d358b
Showing 2 changed files with 82 additions and 0 deletions
en/docs/api-reference/internal.md
en/docs/reference/maintainer/runtime.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
@@ -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://<host>: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