设计时首页小工具管理（PageWidgetController）

首页小工具（PageWidget）的设计时管理：小工具的列表查询、详情获取、新建、更新与批量删除；用于配置门户首页中显示的 Widget 实例。

• 接口类型：REST 资源
• 基址：${myapps.context-path.designer:}/api/designtime/applications（类级 @RequestMapping，produces = APPLICATION_JSON_VALUE）
• Tag：设计时-首页小工具模块

公共说明

• 鉴权：是（需 designerToken）。控制器继承自 AbstractDesignTimeController（基类为 @RestController），通过 Security.getDesignerIdFromToken(request) 从 designerToken JWT 中解析设计器用户。鉴权机制详见 index.md「鉴权说明」。
• 路径变量：{applicationId}、{widgetId} 均为**明文设计时 ID**。
• 响应：统一 Resource（见 ../index.md「统一响应结构」）。成功 errcode=0；异常默认 errcode=500；保存校验失败捕获 OBPMValidateException，返回 errcode=40001，常见 errmsg：{*[page.name.notexist]*}（名称为空）、"请选择widget分组！"（分组为空）、" 该名称已存在,请重新命名再保存！ "（重名）。
• HTTP 方法：受 CommonSecurityFilter 限制，仅允许 GET/POST/HEAD/OPTIONS。
• 请求体约定：POST/PUT 接收原始 JSON 字符串（@RequestBody String content），由服务端用 JSONObject.fromObject 解析后 json2obj 转 PageWidget；DELETE 接收 JSON 字符串数组（@RequestBody String[]）。
• 隶属关系：新建/更新时 parentId 固定设为 widgetGroupId（小工具挂在其所属分组下）。
• 类型常量（来自 PageWidget，对应 type）：含 TYPE_SUMMARY（汇总）等；当 type=TYPE_SUMMARY 时，详情接口会附带 summaryName（取自 SummaryCfgVO.title）。

---

1. 获取小工具列表

分页获取指定应用下的首页小工具列表，可按名称关键字与所属分组过滤。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/widgets（完整：{designer-context}/api/designtime/applications/{applicationId}/widgets）
• 鉴权：是（需 designerToken）
• Tag：设计时-首页小工具模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
name	query	string	否	按名称查询关键字（@RequestParam(required=false)）
widgetGroupId	query	string	否	按所属 widget 分组Id过滤（@RequestParam(required=false)）
pageNo	query	string	否	页码（缺省 1，取自 ParamsTable）
linesPerPage	query	string	否	每页条数（缺省 10，取自 ParamsTable）

请求示例

GET /api/designtime/applications/{applicationId}/widgets?name=&widgetGroupId=&pageNo=1&linesPerPage=10 HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：DataPackage<PageWidget>（含分页字段与 datas）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 10,
    "pageNo": 1,
    "pageCount": 1,
    "rowCount": 1,
    "datas": [
      { "id": "...", "name": "小工具名", "type": "...", "widgetGroupId": "...", "...": "..." }
    ]
  },
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

2. 获取小工具详情

按小工具Id获取详情。当小工具类型为 TYPE_SUMMARY 时，额外返回其关联汇总配置（SummaryCfgVO）的标题。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/widgets/{widgetId}
• 鉴权：是（需 designerToken）
• Tag：设计时-首页小工具模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
widgetId	path	string	是	小工具Id

响应

data：Map，结构 {data: PageWidget, summaryName: string}。当 type ≠ TYPE_SUMMARY 或汇总配置不存在时 summaryName 为空字符串。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "data": { "id": "...", "name": "...", "type": "...", "...": "..." },
    "summaryName": "<汇总标题或空字符串>"
  },
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

3. 新建小工具

在指定应用下新建首页小工具。请求体解析为 PageWidget 后强制覆盖 applicationid，并将 parentId 设为 widgetGroupId；id 为空时生成新的设计时序列号。保存前校验：名称非空、widgetGroupId 非空、名称不重复。HTTP 状态码 201。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/widgets
• 鉴权：是（需 designerToken）
• Tag：设计时-首页小工具模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
content	body	string(JSON)	是	小工具对象 JSON

请求体

对应 PageWidget 对象 JSON（name、type、widgetGroupId、actionContent 等）。

{ "name": "<小工具名>", "type": "...", "widgetGroupId": "<分组Id>", "actionContent": "...", "...": "..." }

响应

data：JSONObject，仅含 id（新建小工具Id）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "<小工具Id>" }, "errors": null }

失败示例（名称为空）：

{ "errcode": 40001, "errmsg": "{*[page.name.notexist]*}", "data": null, "errors": null }

失败示例（未选分组）：

{ "errcode": 40001, "errmsg": "请选择widget分组！", "data": null, "errors": null }

失败示例（重名）：

{ "errcode": 40001, "errmsg": " 该名称已存在,请重新命名再保存！ ", "data": null, "errors": null }

---

4. 更新小工具

按小工具Id更新小工具。请求体解析后强制覆盖 applicationid，将 parentId 设为 widgetGroupId、清空 uri，校验后 saveOrUpdate。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/widgets/{widgetId}
• 鉴权：是（需 designerToken）
• Tag：设计时-首页小工具模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
widgetId	path	string	是	小工具Id
content	body	string(JSON)	是	小工具对象 JSON

请求体

对应 PageWidget 对象 JSON。

{ "name": "<小工具名>", "widgetGroupId": "<分组Id>", "...": "..." }

响应

data：null（成功）。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

失败示例（校验失败）：

{ "errcode": 40001, "errmsg": "<校验信息>", "data": null, "errors": null }

---

5. 删除小工具（可批量）

按小工具Id数组批量删除小工具（含路径信息收集）。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/{applicationId}/widgets
• 鉴权：是（需 designerToken）
• Tag：设计时-首页小工具模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
ids	body	string	是	小工具Id字符串数组

请求体

["<widgetId1>", "<widgetId2>"]

响应

data：String，固定为 "删除成功"。

{ "errcode": 0, "errmsg": "ok", "data": "删除成功", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---