CalendarAuthtimeController（工作日历管理）

管理企业域下的工作日历全生命周期：工作日历列表查询、新建（基于模板日历复制）、更新、删除（系统日历 / 用户在用日历禁删）、当前域可用工作日历字典、日历编辑回填（含标准工作周）、标准工作周列表 / 保存、例外日列表 / 新建 / 保存 / 删除，以及按年月日渲染的日历月卡 HTML。

• 类级基址：${myapps.context-path.manager:}/api/authtime（完整路径：{manager-context}/api/authtime<相对路径>）
• Tag：工作日历模块
• 控制器源码：obpm-manager/src/main/java/cn/myapps/manager/authtime/controller/workcalendar/CalendarAuthtimeController.java
• 公共说明：
• 类继承 BaseAuthTimeController，通过其 success(errmsg, data) / error(errcode, errmsg, errors) 返回统一 Resource（字段 errcode/errmsg/data/errors，结构见 ../index.md「统一响应结构」）。
• 所有端点在 try/catch 内捕获 Exception 并 e.printStackTrace() 后返回 errcode=500、errmsg=e.getMessage()、data=null（HTTP 状态码 200）；业务校验失败常用 errcode=500（与 user/domain 模块的 4001 不同）。
• 鉴权说明见 index.md「鉴权说明」（adminToken JWT）。
• 路径变量 domainid 为企业域 id；id 为工作日历 id。
• 包体与查询参数中的下划线前缀字段（如 _calendarid、_orderby）为源码原样字段名，注意大小写与下划线。
• 时间字段（startTime1~startTime5 / endTime1~endTime5 / startDate / endDate）统一按 yyyy-MM-dd HH:mm:ss、GMT+8:00 解析；服务器内部并据此校验开始时间不得晚于结束时间。

---

1. 查询工作日历列表

按企业域分页查询工作日历列表，支持按名称（name）模糊匹配、排序（_orderby）、分页。响应中每条日历的 standardDays / specialDays 被置空以减小包体，remark 会经多语言资源（MultiLanguageProperty）本地化。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/domain/{domainid}/calendars（完整：{manager-context}/api/authtime/domain/{domainid}/calendars）
• 鉴权：是（需管理员 adminToken，详见 index.md「鉴权说明」）
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
content	body	JSON 文本	是	过滤条件包体（字段见下）
pagelines	query	string	否	每页条数，缺省 Integer.MAX_VALUE（即不分页）
currpage	query	string	否	当前页码，缺省 1
_orderby	query	string	否	排序字段

请求体

JSON 对象（application/json，控制器以字符串接收后解析）：

字段	类型	必填	说明
name	string	否	日历名称模糊匹配关键字

请求示例

POST /api/authtime/domain/__P1UD2yVWpnFpUedONr/calendars?currpage=1&pagelines=20 HTTP/1.1
Content-Type: application/json

{ "name": "标准" }

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：DataPackage<CalendarVO> 序列化后的 JSONObject，字段：

字段	类型	说明
linesPerPage	int	每页条数
pageCount	int	总页数
pageNo	int	当前页码
rowCount	int	总记录数
datas	array\<CalendarVO>	工作日历数组（每个元素的 standardDays、specialDays 已置空，remark 已本地化）

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 20,
    "pageCount": 1,
    "pageNo": 1,
    "rowCount": 2,
    "datas": [
      { "id": "__CAL01", "name": "标准日历", "remark": "标准", "type": "...", "domainid": "__P1UD2yVWpnFpUedONr" },
      { "id": "__CAL02", "name": "24小时日历", "remark": "", "domainid": "__P1UD2yVWpnFpUedONr" }
    ]
  },
  "errors": null
}

失败示例：

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

---

2. 新建工作日历

基于现有「模板日历」（_calendarid）复制出一条新工作日历：复制模板的软件归属、类型、工作时间，并逐条深拷贝模板的标准工作周（StandardDayVO，含 5 段上下班时间、weekDays、workingDayStatus 等字段，赋予新的 id 与 sortId），例外日不复制。新日历的 name / remark 取自请求体。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/domain/{domainid}/calendar（完整：{manager-context}/api/authtime/domain/{domainid}/calendar）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id（路径变量，方法签名持有但实际以模板日历的域为准）
jsonObj	body	JSON	是	新建参数包体（字段见下）

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
name	string	是	新日历名称
_calendarid	string	是	模板日历 id（从中复制标准工作周、软件、类型、域等）
remark	string	否	备注

请求示例

POST /api/authtime/domain/__P1UD2yVWpnFpUedONr/calendar HTTP/1.1
Content-Type: application/json

{ "name": "研发部日历", "_calendarid": "__CAL01", "remark": "复制自标准日历" }

响应

结构：统一 Resource。 data：字符串 "保存成功"。

条件	errcode	errmsg	data
模板日历不存在（doView 返回 null 触发 NPE）	500	<异常信息>	null
成功	0	ok	保存成功

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "保存成功", "errors": null }

失败示例：

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

---

3. 更新工作日历

更新指定工作日历的 name 与 remark。先做名称唯一性兼容校验（getCountByName）：同名数大于 1 时拒绝；同名数为 1 时需 id 一致才允许直接更新；同名数为 0 时按现 id 更新；若以上分支均未命中（旧数据兼容路径），则以现日历为模板重新建一条新 id 的日历并 doUpdate，原 id 日历留存。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/domain/{domainid}/calendar/{id}（完整：{manager-context}/api/authtime/domain/{domainid}/calendar/{id}）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
id	path	string	是	待更新的工作日历 id
jsonObj	body	JSON	是	更新参数包体（字段见下）

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
name	string	是	日历名称
remark	string	否	备注

请求示例

PUT /api/authtime/domain/__P1UD2yVWpnFpUedONr/calendar/__CAL01 HTTP/1.1
Content-Type: application/json

{ "name": "标准日历-2026", "remark": "更新备注" }

响应

结构：统一 Resource。 data：字符串 "保存成功"。

条件	errcode	errmsg	data
同名日历数 > 1（数据脏）	500	保存失败	null
同名日历存在但 id 不一致	500	保存失败	null
成功	0	ok	保存成功
抛异常	500	<异常信息>	null

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "保存成功", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "保存失败", "data": null, "errors": null }

---

4. 删除工作日历

按工作日历 id 数组批量删除。系统日历（名称为 24小时日历 / 夜班日历 / 标准日历）不允许删除；任一日历被某用户设为 calendarType（用户在用）时也不允许删除。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/domain/{domainid}/calendar（完整：{manager-context}/api/authtime/domain/{domainid}/calendar）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id（路径变量，方法签名持有但实际逻辑按各日历自身的域查询用户）
ids	body	string[]	是	待删除的工作日历 id 数组

请求体

application/json，字符串数组：

[ "__CAL02", "__CAL03" ]

请求示例

DELETE /api/authtime/domain/__P1UD2yVWpnFpUedONr/calendar HTTP/1.1
Content-Type: application/json

[ "__CAL02" ]

响应

结构：统一 Resource。 data：字符串 "删除成功"。

条件	errcode	errmsg	data
ids 为 null	500	请选择数据	null
包含系统日历	500	删除日历中包含系统日历，不能删除	null
日历被用户选中在用	500	删除日历中包含用户选中日历，不能删除	null
成功	0	ok	删除成功
抛异常	500	<异常信息>	null

成功示例：

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

失败示例：

{ "errcode": 500, "errmsg": "删除日历中包含系统日历，不能删除", "data": null, "errors": null }

---

5. 获取工作日历字典

返回当前企业域下所有可用工作日历的「id → 名称」映射，用于前端下拉选择。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/getworkcalendars（完整：{manager-context}/api/authtime/domain/{domainid}/getworkcalendars）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/getworkcalendars HTTP/1.1

响应

结构：统一 Resource。 data：JSONObject，键为日历 id，值为日历名称。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "__CAL01": "标准日历",
    "__CAL02": "24小时日历",
    "__CAL03": "夜班日历"
  },
  "errors": null
}

失败示例：

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

---

6. 编辑工作日历（回填）

按工作日历 id 加载日历详情，并附加该日历的标准工作周集合（按页码 1、每页 7 查询），用于前端编辑页回填。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/calendar/{id}/edit（完整：{manager-context}/api/authtime/domain/{domainid}/calendar/{id}/edit）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
id	path	string	是	工作日历 id

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/calendar/__CAL01/edit HTTP/1.1

响应

结构：统一 Resource。 data：CalendarVO，其中 standardDays 为按页大小 7 查询出的标准工作周集合（通常 7 条，对应一周七天）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "id": "__CAL01",
    "name": "标准日历",
    "domainid": "__P1UD2yVWpnFpUedONr",
    "type": "...",
    "standardDays": [
      { "id": "__SD01", "weekDays": 1, "workingDayStatus": "01", "startTime1": "08:00:00", "endTime1": "12:00:00" }
    ]
  },
  "errors": null
}

失败示例：

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

---

7. 获取标准工作周列表

按工作日历 id 分页查询其标准工作周（StandardDayVO），每条记录附带所属日历对象 calendar。控制器内部固定以页码 1、每页 7 查询（即一周七天的标准班次）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/calendar/{id}/getstandardday（完整：{manager-context}/api/authtime/domain/{domainid}/calendar/{id}/getstandardday）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
id	path	string	是	工作日历 id

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/calendar/__CAL01/getstandardday HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<JSONObject>，字段：

字段	类型	说明
linesPerPage	int	每页条数（固定 7）
pageNo	int	当前页码（固定 1）
rowCount	int	总记录数
datas	array\<JSONObject>	标准工作周数组，每个元素为 StandardDayVO 序列化结果，并附加字段 calendar（所属 CalendarVO）

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 7,
    "pageNo": 1,
    "rowCount": 7,
    "datas": [
      {
        "id": "__SD01", "weekDays": 1, "workingDayStatus": "01",
        "startTime1": "08:00:00", "endTime1": "12:00:00",
        "startTime2": "13:00:00", "endTime2": "17:00:00",
        "calendar": { "id": "__CAL01", "name": "标准日历" }
      }
    ]
  },
  "errors": null
}

失败示例：

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

---

8. 保存标准工作周

更新一条标准工作周（StandardDayVO）的 weekDays、workingDayStatus、5 段上下班时间、备注，并重新绑定到指定日历。先校验每段 startTimeN 不得晚于 endTimeN（按 yyyy-MM-dd HH:mm:ss GMT+8 解析）。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/domain/{domainid}/calendar/{id}/savestandardday（完整：{manager-context}/api/authtime/domain/{domainid}/calendar/{id}/savestandardday）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
id	path	string	是	工作日历 id
jsonObject	body	JSON	是	标准工作周字段（见下）

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
id	string	是	待保存的标准工作周记录 id
weekDays	int	否	星期几（1~7）
strstatus	string	否	工作日状态（如 01=上班）
startTime1 ~ startTime5	string	否	5 段上班时间（yyyy-MM-dd HH:mm:ss）
endTime1 ~ endTime5	string	否	5 段下班时间（yyyy-MM-dd HH:mm:ss）
remark	string	否	备注

请求示例

PUT /api/authtime/domain/__P1UD2yVWpnFpUedONr/calendar/__CAL01/savestandardday HTTP/1.1
Content-Type: application/json

{
  "id": "__SD01",
  "weekDays": 1,
  "strstatus": "01",
  "startTime1": "2026-08-04 08:00:00",
  "endTime1": "2026-08-04 12:00:00",
  "startTime2": "2026-08-04 13:00:00",
  "endTime2": "2026-08-04 17:00:00"
}

响应

结构：统一 Resource。 data：字符串 "保存成功"。

条件	errcode	errmsg	data
任一时段开始时间晚于结束时间	500	时间N开始时间值不得晚于结束时间值！（N 为 1~5）	null
成功	0	ok	保存成功
抛异常	500	<异常信息>	null

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "保存成功", "errors": null }

失败示例：

{ "errcode": 500, "errmsg": "时间1开始时间值不得晚于结束时间值！", "data": null, "errors": null }

---

9. 获取例外日列表

按工作日历 id 分页查询其例外日（SpecialDayVO，例如法定节假日、调休），每条记录附带所属日历对象 calendar。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/{domainid}/calendar/{id}/getspecialday（完整：{manager-context}/api/authtime/domain/{domainid}/calendar/{id}/getspecialday）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
id	path	string	是	工作日历 id
currpage	query	string	是	当前页码（控制器 Integer.valueOf 解析，缺省会抛 NPE）
pagelines	query	string	是	每页条数（同上）

请求示例

GET /api/authtime/domain/__P1UD2yVWpnFpUedONr/calendar/__CAL01/getspecialday?currpage=1&pagelines=20 HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<JSONObject>，字段：

字段	类型	说明
linesPerPage	int	每页条数
pageNo	int	当前页码
rowCount	int	总记录数
datas	array\<JSONObject>	例外日数组，每个元素为 SpecialDayVO 序列化结果，并附加字段 calendar（所属 CalendarVO）

SpecialDayVO 关键字段：id / startDate / endDate / workingDayStatus / startTime1~startTime5 / endTime1~endTime5 / remark。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 20,
    "pageNo": 1,
    "rowCount": 1,
    "datas": [
      {
        "id": "__SP01",
        "startDate": "2026-01-01 00:00:00",
        "endDate": "2026-01-01 23:59:59",
        "workingDayStatus": "00",
        "remark": "元旦",
        "calendar": { "id": "__CAL01", "name": "标准日历" }
      }
    ]
  },
  "errors": null
}

失败示例：

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

---

10. 新建例外日

在指定工作日历下新建一条例外日（SpecialDayVO），例外日会被同时挂到日历的 specialDays 集合上。strstatus=01 表示「上班日」，此时会校验每段 startTimeN 不得晚于 endTimeN；其他状态（如 00 休息）跳过时间校验且不写入时间字段。startDate / endDate 为整个例外日的起止边界。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/domain/{domainid}/calendar/{id}/addspecialday（完整：{manager-context}/api/authtime/domain/{domainid}/calendar/{id}/addspecialday）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
id	path	string	是	工作日历 id
jsonObject	body	JSON	是	例外日字段（见下）

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
strstatus	string	是	工作日状态：01=上班日（写入并校验时间段）/ 其他=休息日
startDate	string	是	例外日起始时间（yyyy-MM-dd HH:mm:ss，GMT+8）
endDate	string	是	例外日结束时间（yyyy-MM-dd HH:mm:ss，GMT+8）
startTime1 ~ startTime5	string	否	5 段上班时间（仅 strstatus=01 时生效）
endTime1 ~ endTime5	string	否	5 段下班时间（仅 strstatus=01 时生效）
remark	string	否	备注

请求示例

POST /api/authtime/domain/__P1UD2yVWpnFpUedONr/calendar/__CAL01/addspecialday HTTP/1.1
Content-Type: application/json

{
  "strstatus": "00",
  "startDate": "2026-01-01 00:00:00",
  "endDate": "2026-01-01 23:59:59",
  "remark": "元旦放假"
}

响应

结构：统一 Resource。 data：字符串 "保存成功"。

条件	errcode	errmsg	data
strstatus=01 且任一时段开始时间晚于结束时间	500	时间N开始时间值不得晚于结束时间值！（N 为 1~5）	null
成功	0	ok	保存成功
抛异常	500	<异常信息>	null

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "保存成功", "errors": null }

失败示例：

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

---

11. 保存例外日

更新一条已存在的例外日（SpecialDayVO）：workingDayStatus、时间段、备注、起止时间，并重新绑定到指定日历。strstatus=01 表示「上班日」，校验每段 startTimeN 不得晚于 endTimeN。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/domain/{domainid}/calendar/{id}/savespecialday（完整：{manager-context}/api/authtime/domain/{domainid}/calendar/{id}/savespecialday）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
domainid	path	string	是	企业域 id
id	path	string	是	工作日历 id
jsonObject	body	JSON	是	例外日字段（见下）

请求体

JSON 对象（application/json）：

字段	类型	必填	说明
id	string	是	待保存的例外日记录 id
strstatus	string	是	工作日状态：01=上班日（写入并校验时间段）/ 其他=休息日
startDate	string	是	例外日起始时间（yyyy-MM-dd HH:mm:ss，GMT+8）
endDate	string	是	例外日结束时间（yyyy-MM-dd HH:mm:ss，GMT+8）
startTime1 ~ startTime5	string	否	5 段上班时间（仅 strstatus=01 时生效）
endTime1 ~ endTime5	string	否	5 段下班时间（仅 strstatus=01 时生效）
remark	string	否	备注

请求示例

PUT /api/authtime/domain/__P1UD2yVWpnFpUedONr/calendar/__CAL01/savespecialday HTTP/1.1
Content-Type: application/json

{
  "id": "__SP01",
  "strstatus": "01",
  "startDate": "2026-02-07 00:00:00",
  "endDate": "2026-02-07 23:59:59",
  "startTime1": "2026-02-07 09:00:00",
  "endTime1": "2026-02-07 18:00:00",
  "remark": "春节调休上班"
}

响应

结构：统一 Resource。 data：字符串 "保存成功"。

条件	errcode	errmsg	data
strstatus=01 且任一时段开始时间晚于结束时间	500	时间N开始时间值不得晚于结束时间值！（N 为 1~5）	null
成功	0	ok	保存成功
抛异常	500	<异常信息>	null

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": "保存成功", "errors": null }

失败示例：

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

---

12. 删除例外日

按例外日 id 数组批量删除例外日（逐条 doRemove，不校验是否被引用）。注意该端点路径中**无** domainid 路径变量。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/domain/calendar/deletespecialday（完整：{manager-context}/api/authtime/domain/calendar/deletespecialday）
• 鉴权：是
• Tag：工作日历模块

请求参数

参数名	位置	类型	必填	说明
ids	body	string[]	否	待删除的例外日 id 数组；为 null 时直接返回成功

请求体

application/json，字符串数组：

[ "__SP01", "__SP02" ]

请求示例

DELETE /api/authtime/domain/calendar/deletespecialday HTTP/1.1
Content-Type: application/json

[ "__SP01" ]

响应

结构：统一 Resource。 data：字符串 "删除成功"。

成功示例：

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

失败示例：

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

---

13. 工作日历详情（按年月日渲染月卡）

按工作日历 id 与年月日，渲染该月的日历月卡 HTML 字符串（含标准工作周与例外日叠加后的每日 dayInfo）。计算结果同时写入会话：dayI（行索引）、dayJ（列索引）、showToday（是否当月当日）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/domain/calendar/{id}/viewcalender（完整：{manager-context}/api/authtime/domain/calendar/{id}/viewcalender）
• 鉴权：是
• Tag：工作日历模块

注：该端点路径中**无** domainid 路径变量。

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	工作日历 id
years	query	string	是	年份（4 位数字；非法或 ≤1900 时回退为当前年）
month	query	string	是	月份（1~12；越界回退为当前月）
day	query	string	是	日（≤0 时回退为当前日；大于月末则取月末）

请求示例

GET /api/authtime/domain/calendar/__CAL01/viewcalender?years=2026&month=8&day=4 HTTP/1.1

响应

结构：统一 Resource。 data：字符串，月卡 HTML 片段（由 Month.toHtml() 生成，含当月每日状态标记）。

副作用：往 HttpSession 写入 dayI / dayJ（定位光标行/列）与 showToday（是否高亮今天）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": "<table class='calendar'>...</table>",
  "errors": null
}

失败示例：

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

---