团队（TeamController）¶
提供 KMS 知识管理模块「团队协作域」（tkm）下的团队管理能力：团队的创建/更新/删除/查询、团队名称更新、我的团队列表、团队序列号生成、团队详情查询，以及团队与专委会（领域）模块开关状态查询。所有端点均返回 JSON 资源（最后一个 realmAndTeam 端点返回原始 JSON 字符串，详见 #9）。
- 接口类型：REST 资源（
@RestController，类级与所有方法级produces = MediaType.APPLICATION_JSON_VALUE） - 基址：
${myapps.context-path.kms:}/api/kms（类级@RequestMapping仅声明单一前缀，无/kms备用前缀；与 SearchController/FileController 不同） - Tag：kms团队模块
公共说明¶
- 鉴权（据源码
KmsMvcConfig+KmsSecurityFilter）：KmsMvcConfig注册全局 Servlet 过滤器KmsSecurityFilter（URL 模式/*，context-path 为/时为/kms/*）。本控制器路径/api/kms/teams/**、/api/kms/myTeams、/api/kms/realmAndTeam均不在KmsSecurityFilter.isExcludeURI的豁免名单内（豁免仅覆盖/login.*、/admin、/domain.*、/tray/service、/authtime、service/OfficeServer、.*outsideshare/.*/preview、静态资源后缀、actuator/health等）。过滤器调用Security.getUserIdFromToken(request)，取不到用户则返回 HTTP401。因此所有端点均需 accessToken，可通过以下任一方式传递（据Security.getUserIdFromToken）：query 参数accessToken、query 参数access_token（移动端）、请求头accessToken、CookieaccessToken、请求头Authorization: Bearer <token>。完整鉴权机制见 index.md「鉴权说明」。 - 执行用户：控制器内
getUser()（继承自AbstractBaseController）调用Security.getUserIdFromToken(request)还原当前用户 id，再经 Feign（UserAPI.getUserById）装载KmsUser。无userCode参数。 - 响应结构：统一
Resource（见 ../index.md「统一响应结构」），字段为errcode/errmsg/data/errors。KMS 的Resource为AbstractBaseController内部类，其构造器对data执行ESAPI.encode(data)做 XSS 编码，故data中的 HTML 特殊字符会被转义。 - HTTP 状态码与错误码（据源码
AbstractBaseController全局异常处理）：成功默认 HTTP 200；InvalidRequestException→ HTTP 400 / errcode=400；UnauthorizedException→ HTTP 403 / errcode=403；ForbiddenException→ HTTP 403 / errcode=403；ResourceNotFoundException→ HTTP 404 / errcode=404；其他Exception→ HTTP 500 / errcode=500。 @RequestParam默认必填：未标required=false且无defaultValue的 query 参数按 Spring 约定为必填。- 路径变量：
teamId为 KMS 内部主键（明文 id）。
1. 创建团队¶
创建一个新的团队。请求体为 Team 对象 JSON；服务端会自动填充 creator/creatorId/domainId（取自当前登录用户）。
- 接口类型：REST 资源
- 请求方式：
POST - 请求路径：
/teams（完整：{kms-context}/api/kms/teams） - 鉴权：是（需 accessToken，据源码）
- Tag：kms团队模块
请求参数¶
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| body | body | object | 是 | Team 对象 JSON，见下方请求体 |
请求体¶
请求示例¶
POST /api/kms/teams?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json
{ "name": "研发一组", "serialNumber": "T20260804001", "description": "研发协作团队" }
响应¶
结构：统一 Resource。
data：创建后的 Team 对象（含服务端回填的 creator/creatorId/domainId）。
失败示例（请求体为空）：
2. 更新团队¶
更新指定 Id 的团队信息（全量更新）。teamId 为空或请求体为 null 时抛 InvalidRequestException（HTTP 400）。
- 接口类型：REST 资源
- 请求方式：
PUT - 请求路径：
/teams/{teamId}（完整：{kms-context}/api/kms/teams/{teamId}） - 鉴权：是（需 accessToken，据源码）
- Tag：kms团队模块
请求参数¶
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| teamId | path | string | 是 | 团队Id |
| body | body | object | 是 | Team 对象 JSON（请求体 id 为空时，服务端用路径 teamId 补齐） |
请求体¶
请求示例¶
PUT /api/kms/teams/__TEAMID__?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json
{ "name": "研发一组（更新）", "description": "更新后的描述" }
响应¶
结构：统一 Resource。
data：更新后的 Team 对象。
失败示例（参数有误）：
3. 更新团队名称¶
仅更新指定团队的名称。teamName 非空时，服务端先取出团队、重置名称并刷新成员列表后落库。
- 接口类型：REST 资源
- 请求方式：
PUT - 请求路径：
/teams/{teamId}/name（完整：{kms-context}/api/kms/teams/{teamId}/name） - 鉴权：是（需 accessToken，据源码）
- Tag：kms团队模块
请求参数¶
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| teamId | path | string | 是 | 团队Id |
| teamName | query | string | 是 | 新团队名称 |
请求示例¶
响应¶
结构：统一 Resource。
data：更新后的 Team 对象（含刷新后的 members 列表）。
据源码：当
teamName为空时方法直接return null;（不经过Resource包装，Spring 将写入空响应体）。建议调用方始终传入非空名称。
4. 删除团队¶
按团队 Id 列表批量删除团队。删除前会以当前用户做权限校验。
- 接口类型：REST 资源
- 请求方式：
DELETE - 请求路径：
/teams（完整：{kms-context}/api/kms/teams） - 鉴权：是（需 accessToken，据源码）
- Tag：kms团队模块
请求参数¶
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| body | body | array(string) | 是 | 待删除团队Id数组 |
请求体¶
请求示例¶
DELETE /api/kms/teams?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json
["__TEAMID1__", "__TEAMID2__"]
响应¶
结构：统一 Resource。
data：boolean，固定为 true（删除由 teamService.delete(select, user) 完成，过程中抛出的异常由全局处理器映射）。
5. 获取团队集合¶
按多条件分页查询团队列表。可通过 isMyTeams=true 限定为「我参与的团队」。
- 接口类型：REST 资源
- 请求方式：
GET - 请求路径：
/teams（完整：{kms-context}/api/kms/teams） - 鉴权：是（需 accessToken，据源码）
- Tag：kms团队模块
请求参数¶
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| isMyTeams | query | string | 是 | 是否仅查询我参与的团队（字符串布尔值，如 "true"/"false"） |
| serialNumber | query | string | 否 | 团队编号过滤 |
| creator | query | string | 否 | 创建者过滤 |
| departmentId | query | string | 否 | 所属部门Id过滤 |
| teamName | query | string | 否 | 团队名称关键字 |
| beginTime | query | string | 否 | 起始时间戳（毫秒，字符串型） |
| endTime | query | string | 否 | 截止时间戳（毫秒，字符串型） |
| linesPerPage | query | string | 是 | 每页条数（字符串型数字） |
| pageNo | query | string | 是 | 页码（字符串型数字） |
请求示例¶
响应¶
结构：统一 Resource。
data：DataPackage<Team>，团队分页数据。
失败示例（分页参数缺失）：
6. 获取我的团队¶
返回当前用户创建或参与的团队列表（不分页，以列表形式返回）。
- 接口类型：REST 资源
- 请求方式：
GET - 请求路径：
/myTeams（完整：{kms-context}/api/kms/myTeams） - 鉴权：是（需 accessToken，据源码）
- Tag：kms团队模块
请求参数¶
无。
请求示例¶
响应¶
结构：统一 Resource。
data：List<Team>，我创建或参与的团队列表。
7. 获取团队序列号¶
生成并返回一个新的团队序列号（供前端创建团队时预填）。
- 接口类型：REST 资源
- 请求方式：
GET - 请求路径：
/teams/serialNumber（完整：{kms-context}/api/kms/teams/serialNumber） - 鉴权：是（需 accessToken，据源码）
- Tag：kms团队模块
请求参数¶
无。
请求示例¶
响应¶
结构：统一 Resource。
data：String，新生成的团队序列号。
8. 获取团队信息¶
按团队 Id 获取团队详情。团队不存在时抛 ResourceNotFoundException（HTTP 404）。
- 接口类型：REST 资源
- 请求方式：
GET - 请求路径：
/teams/{teamId}（完整：{kms-context}/api/kms/teams/{teamId}） - 鉴权：是（需 accessToken，据源码）
- Tag：kms团队模块
请求参数¶
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| teamId | path | string | 是 | 团队Id |
请求示例¶
响应¶
结构：统一 Resource。
data：Team 对象（据源码，返回前会将 subscription 字段置为 true）。
失败示例（团队不存在）：
9. 获取团队和专委会状态¶
返回「团队（kmTeam）」与「专委会（kmRealm）」模块的启用状态映射。
据源码：本端点方法返回类型为
String（而非Resource），由JsonUtil.bean2Json(maps)序列化为 JSON 字符串直接写入响应体；当前实现中读取企业域systemModuleConfigJson的逻辑被整体注释，maps实际为空HashMap，故响应体固定为{}。鉴权仍受KmsSecurityFilter控制，需 accessToken。
- 接口类型：REST 资源（返回类型为原始 JSON 字符串，非统一
Resource） - 请求方式：
GET - 请求路径：
/realmAndTeam（完整：{kms-context}/api/kms/realmAndTeam） - 鉴权：是（需 accessToken，据源码）
- Tag：kms团队模块
请求参数¶
无。
请求示例¶
响应¶
结构：原始 JSON 字符串（非 统一 Resource）。Content-Type 仍为 application/json。
data：Map<String, Object> 序列化结果；据源码当前实现固定返回 {}（企业域配置读取逻辑已被注释）。
示例：