SpecialDayAPIController（特殊日期 API）¶

用户中心模块的特殊日期（特例日/节假日）域 CRUD/查询控制器，提供特殊日期（日历中特定日期的安排，如法定节假日、调休加班日等例外日）的创建、更新、查找、删除，以及「按日历分页查询特殊日期」能力。该控制器由 obpm-runtime、obpm-manager、obpm-kms 等宿主服务以 Feign 方式内部调用（SpecialDayAPI 接口），属于后端服务间数据面接口。

控制器全限定名：cn.myapps.usercenter.controller.SpecialDayAPIController
接口（Feign 契约）：cn.myapps.usercenter.controller.SpecialDayAPI
Tag：特殊日期管理
类级 @RequestMapping：${myapps.context-path.usercenter:}/specialday
基址：<host>/usercenter/specialday
独立部署（obpm-usercenter-war/obpm-usercenter-consul）：server.servlet.context-path=/usercenter，占位符 ${myapps.context-path.usercenter:} 缺省为空，故实际基址为 <host>:<port>/usercenter/specialday（war 端口 8080，consul 端口 8088）。
统一部署（obpm-lite）：server.servlet.context-path=/，yml 显式配置 myapps.context-path.usercenter=/usercenter，故实际基址同样为 <host>:8888/usercenter/specialday。
接口类型：REST 资源

公共说明¶

鉴权¶

（据源码）usercenter 模块本身**不定义**任何安全过滤器或鉴权拦截器，仅注册 PersistenceHandlerInterceptor（用于 DAO 资源清理——事务提交与 Hibernate Session 关闭，不做权限判断）。本控制器 /specialday/** 路径下所有端点**不做用户级身份校验**——既不读取 accessToken，也不读取 adminToken/designerToken，控制器方法内也不调用任何 getUser() 之类方法。

usercenter 作为共享库被宿主服务加载后，会继承 obpm-common 提供的 CommonSecurityFilter（由 CommWebMvcConfig 以 @Bean 注册，URL 模式 /*，order=-1，详见 index.md「鉴权说明」），对 /specialday/** 的影响仅限：

HTTP 方法限制：未携带合法 systemToken 请求头时，仅允许 GET/POST/HEAD/OPTIONS 方法；直接发起 PUT/DELETE/PATCH 等请求会被 CommonSecurityFilter 以 HTTP 405（HTML 错误页，无 JSON 体）拒绝。
systemToken 放行：携带合法 systemToken 请求头（系统间 Feign 调用，JWT 内 username 固定为 systemToken）的请求被标记 pass=true 并绕过上述方法限制——这是本控制器 PUT /update、DELETE /remove/{id} 在生产中正常工作的前提。

结论：本控制器的真实访问控制依赖**网络层隔离**（仅由可信的内部服务经 Feign 调用，附 systemToken 请求头），并非用户令牌。终端用户不应直接访问这些端点。

响应结构¶

本控制器不使用统一 Resource 结构（与 ../index.md「统一响应结构」不同）。响应遵循以下规则：

情形	HTTP 状态	响应体
返回值为 `void` 的方法（创建/更新/删除）成功	200	空响应体
返回值为领域对象/集合/包装类型的方法成功	200	直接序列化的对象 JSON（如 `SpecialDayPO`、`DataPackage<SpecialDayPO>`），不包裹 `errcode`/`errmsg`/`data`/`errors`
业务/系统异常	500	`{"errcode":500,"errmsg":"<异常信息>"}`（由 obpm-common 的 `CommonsExceptionResolver` 全局异常处理器渲染，仅含 `errcode`/`errmsg` 两字段，无 `data`/`errors`）
HTTP 方法不被允许（无 `systemToken` 的 `PUT`/`DELETE`）	405	HTML 错误页（由 `CommonSecurityFilter` 直接返回）
系统启动中	500	HTML 错误页（由 `CommonSecurityFilter` 直接返回）

数据模型：`SpecialDayPO`¶

返回的 SpecialDayPO 继承自 AuthtimeValueObject，类级标注 @JSR303，表示一条特例日（节假日/调休等例外日）记录。主要字段：id（主键）、calendar（所属日历 ID，反向引用 CalendarPO）、startDate（执行开始日期，@NotNull 必填）、endDate（执行结束日期，@NotNull 必填）、weekDays（星期）、workingDayStatus（工作日状态，常量 WORKING_DAY="01" 工作日/"02" 非工作日）、dayIndex（日序号）、startTime1_{startTime5/endTime1}endTime5（最多 5 段工作时段的起止时间）、remark（备注）、cssClass（CSS 类名，按 spc 派生：Wwday/Wday/Wspcday/Wtoday）、spc（特殊分类码，由 workingDayStatus 与 isBorder 派生）、isBorder（是否边界日，默认 false）、lastModifyDate（最后修改时间）。提供 isWorkingDay() 便捷方法依据 workingDayStatus 判定是否工作日。

分页结构：`DataPackage<SpecialDayPO>`¶

queryByCalendar 返回 cn.myapps.common.data.DataPackage<SpecialDayPO>，标准字段为 datas（当前页数据集合）、rowCount（总行数）、pageNo（当前页码）、linesPerPage（每页行数）等。

1. 创建特殊日期¶

创建新的特殊日期记录。事务保护：失败回滚。

接口类型：REST 资源
请求方式：POST
请求路径：/create（完整：<host>/usercenter/specialday/create）
鉴权：内部（建议经 systemToken 的 Feign 调用；直接调用因 POST 方法不被 CommonSecurityFilter 拦截故技术上无需 token，但本控制器为内部数据面接口）
Tag：特殊日期管理

请求参数¶

参数名	位置	类型	必填	说明
body	body	`SpecialDayPO`	是	特殊日期信息，须包含 `startDate`/`endDate`（`@NotNull`）；通常还包含 `calendar`（日历 ID）、`workingDayStatus` 等时段字段

请求示例¶

POST /usercenter/specialday/create HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

{
  "calendar": "__CAL001",
  "startDate": "2026-01-01",
  "endDate": "2026-01-03",
  "workingDayStatus": "02",
  "remark": "元旦假期"
}

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500（如缺少 startDate/endDate 触发 @NotNull 校验异常）。

成功示例：（HTTP 200，空响应体）

失败示例：

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

2. 更新特殊日期¶

更新现有的特殊日期记录。事务保护：失败回滚。

接口类型：REST 资源
请求方式：PUT
请求路径：/update（完整：<host>/usercenter/specialday/update）
鉴权：内部（PUT 方法需携带合法 systemToken 请求头，否则被 CommonSecurityFilter 以 HTTP 405 拒绝）
Tag：特殊日期管理

请求参数¶

参数名	位置	类型	必填	说明
body	body	`SpecialDayPO`	是	待更新记录（须含主键 `id`），可携带需更新的字段

请求示例¶

PUT /usercenter/specialday/update HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

{
  "id": "__SP001",
  "startDate": "2026-01-01",
  "endDate": "2026-01-05",
  "remark": "元旦假期（调整后）"
}

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。若未带 systemToken，HTTP 405（HTML 错误页）。

成功示例：（HTTP 200，空响应体）

失败示例：

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

3. 根据 ID 查找特殊日期¶

根据特殊日期 ID 查找单条记录。

接口类型：REST 资源
请求方式：GET
请求路径：/find/{id}（完整：<host>/usercenter/specialday/find/{id}）
鉴权：内部
Tag：特殊日期管理

请求参数¶

参数名	位置	类型	必填	说明
id	path	string	是	特殊日期 ID

请求示例¶

GET /usercenter/specialday/find/__SP001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 SpecialDayPO 对象 JSON（不包裹 Resource）；未找到时由 DAO 行为决定（通常返回 null 或抛异常进入 CommonsExceptionResolver）。

成功示例：

{
  "id": "__SP001",
  "calendar": "__CAL001",
  "startDate": "2026-01-01",
  "endDate": "2026-01-03",
  "workingDayStatus": "02",
  "remark": "元旦假期"
}

失败示例：

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

4. 根据 ID 删除特殊日期¶

根据特殊日期 ID 删除记录。事务保护：失败回滚。

接口类型：REST 资源
请求方式：DELETE
请求路径：/remove/{id}（完整：<host>/usercenter/specialday/remove/{id}）
鉴权：内部（DELETE 方法需携带合法 systemToken 请求头，否则被 CommonSecurityFilter 以 HTTP 405 拒绝）
Tag：特殊日期管理

请求参数¶

参数名	位置	类型	必填	说明
id	path	string	是	特殊日期 ID

请求示例¶

DELETE /usercenter/specialday/remove/__SP001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。若未带 systemToken，HTTP 405（HTML 错误页）。

成功示例：（HTTP 200，空响应体）

失败示例：

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

5. 按日历查询特殊日期¶

按日历 ID 与域 ID 分页查询该日历下的特殊日期。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByCalendar/{domainId}（完整：<host>/usercenter/specialday/queryByCalendar/{domainId}）
鉴权：内部
Tag：特殊日期管理

请求参数¶

参数名	位置	类型	必填	说明
domainId	path	string	是	域 ID（路径占位段）
calendarId	query	string	是	日历 ID
page	query	int	是	页码（1 起）
lines	query	int	是	每页行数

请求示例¶

GET /usercenter/specialday/queryByCalendar/__DMN001?calendarId=__CAL001&page=1&lines=20 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DataPackage<SpecialDayPO> 对象 JSON（不包裹 Resource），含 datas（当前页特殊日期集合）、rowCount、pageNo、linesPerPage 等字段。

成功示例：

{
  "datas": [
    {
      "id": "__SP001",
      "calendar": "__CAL001",
      "startDate": "2026-01-01",
      "endDate": "2026-01-03",
      "workingDayStatus": "02",
      "remark": "元旦假期"
    }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

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

SpecialDayAPIController（特殊日期 API）¶

公共说明¶

鉴权¶

响应结构¶

数据模型：SpecialDayPO¶

分页结构：DataPackage<SpecialDayPO>¶

1. 创建特殊日期¶

请求参数¶

请求示例¶

响应¶

2. 更新特殊日期¶

请求参数¶

请求示例¶

响应¶

3. 根据 ID 查找特殊日期¶

请求参数¶

请求示例¶

响应¶

4. 根据 ID 删除特殊日期¶

请求参数¶

请求示例¶

响应¶

5. 按日历查询特殊日期¶

请求参数¶

请求示例¶

响应¶

数据模型：`SpecialDayPO`¶

分页结构：`DataPackage<SpecialDayPO>`¶