基础数据接口（bd 域）¶

📄 创建: ZCode AI 2026-08-14 · 修改: JimWb 2026-08-14

https://doc.xpku.com/raw/tech/backend/api-standards/biz-api/base.md

bams-apex 基础数据的 9 个 Controller（公司/部门/人员/岗位/单位/字典/缓存）。全部继承 EnergyBaseController（标准 21 个 CRUD 接口），其中 3 个有自定义接口。

📖 标准 CRUD 接口格式见 标准CRUD接口规范。

一、模块总览¶

二、有自定义接口的模块¶

1. 缓存管理 /bd/cache¶

GET /bd/cache/initBaseCache — 初始化 Redis 缓存¶

后台异步线程全量重建 Redis 基础缓存（bd_cache 配置的全部表）。设置刷新标志位（5 分钟超时），完成后删除。

• 请求参数：无
• 响应：JsonResult<Object>，立即返回 msg="正在刷新缓存数据，请稍等1分钟"（异步执行，不等待完成）

POST /bd/cache/refreshCache — 刷新指定缓存¶

按表键或分组定向刷新。tableKey 优先，其次 groupCode，两者都空不做操作。

• 请求参数：BdCache JSON

{
  "table_key": "bd_dictionary",
  "group_code": "dict"
}

BdCache 实体字段（表 bd_cache）：

2. 人员管理 /bd/person¶

BdPerson 关键字段：person_code（编码）、person_name（姓名）、psn_sex（0男1女2未知）、birthday、telephone、email、dept_code、post_code、account_code（登录账号）、enable_state（1未启用/2已启用/3已停用）、corp_code、account_id/account/account_name（底座账号）

POST /bd/person/listSysOrUmsp — 人员列表（本地或 UMSP 平台）¶

分页查人员。读 sys_config 的 umsp 配置： - umsp.isUmspSendMessage=true：代理请求 UMSP 平台（header 带 umsp.Authorization、umsp.accountid），返回映射为 BdPerson（personName←name、email←mail、telephone←phone） - 默认：走本地 listPage

• 请求参数：BasicParamWrapper（likeMap.person_name 作为 UMSP 姓名模糊条件）

{
  "current": 1,
  "size": 10,
  "likeMap": { "person_name": "张" }
}

• 响应：JsonResult<Page<BdPerson>>

POST /bd/person/createAccount — 为人员创建账号¶

为指定人员创建/更新登录账号（sys_user）。登录名优先手机号，无手机号用人员编码；已关联 accountId 则更新，否则查重后新建。

• 请求参数：{"personId": "人员ID"}（必填）
• 响应：JsonResult<SysUser>

三、典型调用示例¶

公司树（BdCorp 支持 /tree）¶

POST /apex-api/bd/corp/tree
{ "andMap": { "enable_state": 2 } }

部门下拉字典¶

POST /apex-api/bd/dept/dict
{
  "columns": ["dept_code", "dept_name"],
  "andMap": { "corp_code": "C001" }
}

按字典类型查字典项¶

POST /apex-api/bd/dictionary/list
{ "andMap": { "dtype": "sex_type" } }

分页查人员¶

POST /apex-api/bd/person/list
{
  "current": 1,
  "size": 20,
  "andMap": { "corp_code": "C001", "enable_state": 2 },
  "orderBy": { "created_time": "desc" }
}

相关文档¶

• 标准CRUD接口规范
• 业务中台接口首页