跳到主要内容

考勤接口

考勤模块负责管理校区地点、服务、服务时间、考勤会话、访问记录和访问会话。它为记录谁参加了哪个服务或小组聚会提供基础设施,支持签到流程,并提供考勤趋势和汇总报表功能。

基础路径: /attendance

校区​

基础路径:/attendance/campuses

标准 CRUD 控制器(继承 GenericCrudController)。通过 CRUD 基类提供 getById、getAll、post 和 delete 路由。

方法路径认证权限说明
GET/JWT—列出教会的所有校区
GET/:idJWT—按 ID 获取校区
POST/JWTServices.Edit创建或更新校区
DELETE/:idJWTServices.Edit删除校区

服务​

基础路径:/attendance/services

继承 GenericCrudController,提供 CRUD 路由 getById、getAll、post 和 delete。getAll(GET /)和 search 接口使用自定义实现进行重写。

方法路径认证权限说明
GET/JWT—列出所有服务(包含校区信息)
GET/:idJWT—按 ID 获取服务
GET/search?campusId=JWT—按校区 ID 搜索服务
POST/JWTServices.Edit创建或更新服务
DELETE/:idJWTServices.Edit删除服务

示例:按校区搜索服务​

GET /attendance/services/search?campusId=abc-123
Authorization: Bearer <token>
[
{
"id": "svc-001",
"churchId": "church-123",
"campusId": "abc-123",
"name": "Sunday Morning"
}
]

服务时间​

基础路径:/attendance/servicetimes

继承 GenericCrudController,提供 CRUD 路由 getById、post 和 delete。getAll 和 search 接口为自定义实现。

方法路径认证权限说明
GET/JWT—列出所有服务时间。可使用 ?serviceId= 筛选。添加 ?include=groups 可附加小组数据。每一行都包含计算得出的 checkinOpen 布尔值(仅当服务时间设有签到时间表且当前处于关闭的时间窗口内时为 false)。时间窗口按服务所在校区的时区计算,其次是教会的时区,然后是第一个设有时区的校区,最后是 America/New_York
GET/:idJWT—按 ID 获取服务时间
GET/search?campusId=&serviceId=JWT—按校区和服务搜索服务时间
GET/public/:churchIdPublic—获取某教会的校区 → 服务 → 时间树形数据。为网站构建器的 serviceTimes 元素提供数据
POST/JWTServices.Edit创建或更新服务时间。可选的时间表字段:dayOfWeek(0 = 周日 … 6 = 周六)、startTime / endTime(HH:mm)、checkinOpenMinutes(开始之前)、checkinCloseMinutes(结束之后)。只有同时设置了 dayOfWeek 和 startTime 时,签到才会受时间限制
DELETE/:idJWTServices.Edit删除服务时间

小组服务时间​

基础路径:/attendance/groupservicetimes

将小组与特定服务时间关联。

方法路径认证权限说明
GET/JWT—列出所有小组与服务时间的关联。可使用 ?groupId= 筛选,以获取包含服务名称的关联
GET/:idJWT—按 ID 获取小组服务时间关联
POST/JWTServices.Edit创建或更新小组服务时间关联
DELETE/:idJWTServices.Edit删除小组服务时间关联

考勤记录​

基础路径:/attendance/attendancerecords

提供只读的考勤数据汇总视图,用于报表和展示。

方法路径认证权限说明
GET/JWTAttendance.View加载某人的考勤记录。需要 ?personId=
GET/myJWT—自助查询:当前登录成员最近 12 个月的考勤记录,按最新排序。如果用户未关联到某个人员,则返回 401。为 B1 Me 页面中的 我的考勤 部分提供数据
GET/treeJWT—加载完整的考勤树(校区、服务、服务时间、小组)
GET/trend?campusId=&serviceId=&serviceTimeId=&groupId=JWTAttendance.View Summary按可选筛选条件加载考勤趋势数据
GET/groups?serviceId=&week=JWTAttendance.View加载某服务在指定周的小组考勤情况
GET/sessionStatus?serviceTimeId=&date=JWTAttendance.View对于分配给该服务时间的每个小组,返回该日期的 { groupId, sessionId, attendanceCount }(date 格式为 YYYY-MM-DD;若小组没有会话,则 sessionId 为 null)。为 B1Admin 中的 谁还需要考勤 对话框提供数据
GET/search?campusId=&serviceId=&serviceTimeId=&groupId=&startDate=&endDate=JWTAttendance.View按筛选条件(校区、服务、服务时间、小组、日期范围)搜索考勤记录

示例:考勤趋势​

GET /attendance/attendancerecords/trend?serviceId=svc-001
Authorization: Bearer <token>
[
{ "week": "2025-01-05", "count": 142 },
{ "week": "2025-01-12", "count": 156 },
{ "week": "2025-01-19", "count": 138 }
]

会话​

基础路径:/attendance/sessions

继承 GenericCrudController,提供 CRUD 路由 getById 和 delete。getAll 和 save 接口为自定义实现,同时允许小组负责人管理其所负责小组的会话。

方法路径认证权限说明
GET/JWTAttendance.View 或小组负责人列出所有会话。可使用 ?groupId= 筛选(包含名称)。小组负责人可查看其所负责小组的会话
GET/:idJWTAttendance.View按 ID 获取会话
POST/JWTAttendance.Edit 或小组负责人创建或更新会话。小组负责人可保存其所负责小组的会话
DELETE/:idJWTAttendance.Edit删除会话

访问记录​

基础路径:/attendance/visits

管理单次访问记录(某人在特定日期的出席),并提供签到流程。

方法路径认证权限说明
GET/JWTAttendance.View列出所有访问记录。可使用 ?personId= 筛选
GET/:idJWTAttendance.View按 ID 获取访问记录
GET/checkin?serviceId=&peopleIds=JWTAttendance.View 或 Attendance.Checkin加载某服务中指定人员的签到数据。返回包含最近一次记录日期的访问会话的访问记录
POST/JWTAttendance.Edit创建或更新访问记录
POST/checkin?serviceId=&peopleIds=JWTAttendance.Edit 或 Attendance.Checkin提交签到数据。创建或更新访问记录及访问会话,并删除过期记录
DELETE/:idJWTAttendance.Edit删除访问记录

示例:签到流程​

第 1 步 -- 加载现有签到数据:

GET /attendance/visits/checkin?serviceId=svc-001&peopleIds=person-1,person-2
Authorization: Bearer <token>
[
{
"id": "visit-001",
"personId": "person-1",
"visitDate": "2025-01-19T00:00:00.000Z",
"visitSessions": [
{
"id": "vs-001",
"sessionId": "sess-001",
"visitId": "visit-001",
"session": {
"id": "sess-001",
"groupId": "group-001",
"serviceTimeId": "st-001",
"sessionDate": "2025-01-19T00:00:00.000Z"
}
}
]
}
]

第 2 步 -- 提交签到:

POST /attendance/visits/checkin?serviceId=svc-001&peopleIds=person-1,person-2
Authorization: Bearer <token>

[
{
"personId": "person-1",
"visitSessions": [
{
"session": { "serviceTimeId": "st-001", "groupId": "group-001" }
}
]
}
]

如果目标服务时间设有签到时间表且其时间窗口已关闭(按与 checkinOpen 相同的校区优先时区顺序计算),则不会保存任何数据,响应为 409 { "error": "notOpen", "groups": [{ "groupId", "groupName", "reason": "notOpen" }] }。容量和志愿者比例超限同样返回 409(error: "capacity" 或 "ratio")。某人今天已持有的会话(每次签到时重新提交)会跳过时间窗口检查,因此家庭成员可以在之前某个服务时间的窗口关闭后,仍然添加一个开放中的服务时间。

访问会话​

基础路径:/attendance/visitsessions

管理访问记录与会话之间的关联(某人在某次访问中具体参加了哪个会话)。同时提供快速记录接口和下载/导出接口。

方法路径认证权限说明
GET/JWTAttendance.View 或小组负责人列出访问会话。可使用 ?sessionId= 筛选。小组负责人可查看其所负责小组的访问会话
GET/:idJWTAttendance.View按 ID 获取访问会话
GET/download/:sessionIdJWTAttendance.View下载某会话的考勤数据(返回人员姓名及出席/缺席状态)
POST/JWTAttendance.Edit创建或更新访问会话
POST/logJWTAttendance.Edit 或小组负责人快速记录某人在某会话中的考勤。如有需要会自动创建访问记录。小组负责人可为其所负责小组记录考勤
DELETE/:idJWTAttendance.Edit按 ID 删除访问会话
DELETE/?personId=&sessionId=JWTAttendance.Edit 或小组负责人将某人从会话中移除。删除该访问会话,若其父访问记录已无剩余会话,则一并删除。小组负责人可移除其所负责小组的考勤

示例:快速记录考勤​

POST /attendance/visitsessions/log
Authorization: Bearer <token>

{
"personId": "person-001",
"visitSessions": [
{ "sessionId": "sess-001" }
]
}
{}

示例:下载会话考勤​

GET /attendance/visitsessions/download/sess-001
Authorization: Bearer <token>
[
{
"id": "vs-001",
"personId": "person-001",
"visitId": "visit-001",
"sessionDate": "2025-01-19T00:00:00.000Z",
"personName": "John Smith",
"status": "present"
},
{
"id": "",
"personId": "person-002",
"visitId": "",
"sessionDate": "2025-01-19T00:00:00.000Z",
"personName": "Jane Doe",
"status": "absent"
}
]

连续出勤​

基础路径:/attendance/streaks

追踪个人的考勤连续记录,即某人连续参加服务的周数。可用于参与度指标和游戏化场景。

方法路径认证权限说明
GET/person/:personIdJWT—加载某人的考勤连续记录

相关页面​