# Internal API (`xlyEntry`)

The `xlyEntry` service hosts the SPA's runtime API. It is the largest of
the three tiers — its controllers compile into the same WAR as the
framework's metadata-driven runtime, and most calls hit one of a handful
of universal endpoints that read or write any module.

This API is **not a stable contract for external callers**. Endpoint
shapes change as the framework changes. External integrations belong on
the [External API](external.md). This page exists for maintainers and
SPA-extension authors.

For the request-lifecycle and code-level walkthrough, see the
[Maintainer runtime chapter](../reference/maintainer/runtime.md). This
page is the catalog of HTTP entry points.

## The universal CRUD surface — `/business/*`

| Endpoint | Method | Purpose |
|---|---|---|
| `/business/getModelBysId/{moduleId}` | GET | Returns the form layout for a module — the five-key composite (`formData`, `gdsformconst`, `gdsjurisdiction`, `billnosetting`, `report`). |
| `/business/getBusinessDataByFormcustomId/{formId}` | POST | Returns rows of business data for a form, paginated. Branches to `getBusinessDataByGroup` when `sGroupList` is set. |
| `/business/getBusinessDataByIndex` | POST | First / last / next / previous-record navigation. |
| `/business/addBusinessData` | POST | Single insert. |
| `/business/addUpdateDelBusinessData` | POST | Bundled add+update+delete in one transactional call. The frontend names the target table directly via `sTable`. |
| `/business/getSelectDataBysControlId/{sId}` | POST | Dropdown population for a single control, by control `sId`. |
| `/business/getSelectLimit/{sId}` | POST | Paginated variant of the dropdown call. |
| `/business/addSysLocking` | POST | Optimistic-lock acquisition when a user starts editing a document — inserts a row in the system lock table keyed by `(sFormGuid, sUserId)`. The SPA fires this when entering edit mode so concurrent editors get a conflict warning. Handler: `BusinessBaseController.java:400-407`. |
| `/business/doExamine` | POST | Simple "approve" — flips `bCheck = 1` on the named row via SQL. **Does NOT invoke Activiti**; this is xly's lightweight approval path used by every module that doesn't need multi-step workflow. Handler: `BusinessBaseController.java:384-391` → `BusinessBaseServiceImpl.doExamine` → `ExamineServiceImpl`. See [Two approval paths](../reference/maintainer/activiti.md#two-approval-paths) for when Activiti is used instead. |
| `/business/getProData` | POST | Generic stored-procedure invocation for a module — alternate path to `/procedureCall/doGenericProcedureCall`. Handler: `BusinessBaseController.java:350-358` → `BusinessBaseServiceImpl.getProData`. Used by FROUNT for module-level proc reads (the home dashboard `/getProData?sModelsId=...&sName=` pattern). |

These endpoints are documented in detail by [Slice 1](../slices/01-hello-world.md)
(`getModelBysId` + grid load + save) and
[Slice 3](../slices/03-report.md) (the view-backed read variant). The
handler classes are in
`xlyEntry/src/main/java/com/xly/web/businessweb/`.

## Metadata-management endpoints

For builder-side actions (creating modules, defining forms, declaring
virtual tables) there is a parallel surface in
`xlyEntry/src/main/java/com/xly/web/systemweb/`:

| Endpoint root | Controller | Purpose |
|---|---|---|
| `/gdsmodule/*` | `GdsmoduleController` | Module-tree CRUD, including `getModuleTreePro`, `addGdsmodule`, `updateGdsmodule`. |
| `/gdsconfigform/*` | `GdsconfigformController` | Form-master and form-slave metadata CRUD. |
| `/gdsconfigtb/*` | `GdsconfigtbController` | Virtual-table master/slave metadata CRUD. |

## Specialised runtime endpoints

| Endpoint root | Controller | Purpose |
|---|---|---|
| `/configform/*` | `BusinessConfigformController` | Per-user / per-group display customization. |
| `/treegrid/*` | `BusinessTreeGridController` | Tree-grid endpoints (the proc-backed path is implemented in this branch). |
| `/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` | **Empty shell — returns 404.** The class declares the prefix but has zero handler methods. The actual workflow approve/reject/complete URLs come from xlyFlow's `CurrencyFlowController` (served at xlyEntry's context-path because xlyFlow is a library dep): `/complete/{taskId}/{sBrandsId}/{sSubsidiaryId}/{sUserId}`, `/completeerp/...`, plus `/modeler/*` for the BPMN modeler. See [Activiti integration](../reference/maintainer/activiti.md). |
| `/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

The print surface lives under `xlyEntry/src/main/java/com/xly/web/report/`:

- `PrintReportController` — current jxls / iText print path.
- `PrintReportControllerOld.java` — file exists but its class body is
  fully commented out (and the commented-out class inside is named
  `PrintReportController`, not `*Old`). It is dead source kept for
  reference, not an active controller.

The frontend's "打印" / "导出" buttons hit these controllers, which load a
template from `sysreport`, run the matching view-backed query, and stream
a binary file back. See [Slice 3](../slices/03-report.md#6-printable-reports-when-present)
for the flow.

## Authentication

Every controller method that participates in business data is annotated
with `@Authorization` and receives a resolved `UserInfo` via
`@CurrentUser`. The session-to-`UserInfo` mapping is the framework's
own (cookie + Redis-backed session); see
[the multi-tenancy concept page](../concepts/multi-tenancy.md).

A request that reaches a controller without authentication does not
get past `@Authorization`; if it does (e.g., an unannotated method),
that method also bypasses the universal tenant injection in
`RequestAddParamUtil` — and is therefore a multi-tenant bug.

## BACK builder sidebar (admin surface)

The 10 top-level items in the BACK admin sidebar (login `admin`/`123`,
edition `基础版/8s`) — each is a metadata-driven screen wired through
the framework primitives above:

| Sidebar | URL fragment | Backing form-master `sTbName` | Owning service |
|---|---|---|---|
| 系统模块配置 (System Module Config) | `/xtmkpz` | `gdsmodule` | `GdsmoduleServiceImpl` |
| 数据表内容配置 (Virtual Table Config) | n/a | `gdsconfigtbmaster`/`slave` | `GdsconfigtbServiceImpl` |
| 界面显示内容配置 (Form Definition + Customization) | n/a | `gdsconfigformmaster`/`slave`/`customslave`/`personalize` | `GdsconfigformServiceImpl` |
| 接口自定义配置 (API Definition) | `/sjbnrpz` | `sysapi` family | (xlyApi-side admin) |
| 系统常量配置 (System Constants) | `/xtclpz` | `gdsformconst` | `GdsformconstServiceImpl` — Slice 1 anchor |
| 系统权限配置 (Permission Catalog) | n/a | `gdsjurisdiction` | `GdsjurisdictionServiceImpl` |
| 常用操作配置 (Common Operations / Button Groups) | n/a | (no entry in `gdsconfigformmaster` for this dev DB; the page is rendered as an admin special-case wired directly in the SPA — when extended via metadata, the data lives under the user-defined button-group tier) | n/a |
| 用户信息配置 (User Info) | n/a | `sftlogininfo` family | `GdslogininfoServiceImpl` |
| Mysql脚本配置 (SQL Script Authoring) | n/a | (BACK editor over the [`templesql/` scaffolds](../reference/maintainer/sql-templates.md)) | `SqlScriptsServiceImpl` |
| 图表配置 (Chart Config) | (no `gdsroute` entry; navigated via SPA state) | `gdsconfigcharmaster`/`slave` | `GdsconfigformServiceImpl` (chart subset) |

8 of 10 are framework primitives covered elsewhere in this catalog +
the [Maintainer Reference](../reference/maintainer/management-services.md).
**`常用操作配置` is a SPA-side admin special-case** — it appears in the
sidebar without a corresponding `gdsconfigformmaster` row in the dev
DB, suggesting the page is hardcoded in BACK rather than metadata-
driven. **`图表配置`** is fully metadata-driven via two
`gdsconfigformmaster` rows pointing at `gdsconfigcharmaster` and
`gdsconfigcharslave`; chart definitions there are consumed by xly's
dashboard rendering elsewhere in the SPA.

## Coverage policy — what this catalog includes

`xlyEntry` hosts **~71 controllers** in total. This page enumerates
the ~19 that are part of the framework's universal runtime:
`/business/*`, `/configform/*`, `/treegrid/*`, `/procedureCall/*`,
`/panel/*`, `/checkflow/*`, `/gdsmodule/*`, `/gdsconfigform/*`,
`/gdsconfigtb/*`, plus the print surface. Every form in the system
flows through these.

The remaining ~52 controllers are **business-domain modules**
(`/sysworkorder`, `/salesorder`, `/productionPlan`, `/oee`,
`/eleMaterialsStock`, etc.) — they implement specific industry-tier
flows on top of the framework primitives above. The wiki treats those
as *illustrations of the framework at work*, not as catalogued surface
of their own. Maintainers who need to find a specific business
controller should grep `xlyEntry/src/main/java/com/xly/web/` for the
URL prefix; the framework primitives on this page are what's worth
reading first.

## What this API is *not*

- **Not stable** — endpoint shapes change with the framework.
- **Not authenticated for outside callers** — there is no API-key flow
  here; cookies/sessions are not what an integrator wants.
- **Not documented for self-service** — the surface is too large and
  too generic to publish as an OpenAPI doc. External integrators get
  the curated [External API](external.md) instead.