feat: add attendance APIs

2026-08-31 13:27:12 +08:00
parent 9f647de4d0
commit cb7dc36cad
10 changed files with 1749 additions and 12 deletions
@@ -2061,6 +2061,17 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 - 全局搜索：`GET /v1/im/organization/search?q=&types=department,user&cursor=`。服务端执行组织范围授权，离职用户标记不可联系或从结果移除。
 - 组织架构可见范围由服务端按当前登录用户裁剪：上架测试账号可看全部组织；手机号注册账号默认只能看到自己与好友所在组织路径及成员；邀请码注册账号默认只能看到自己所在组织路径及本人。上架测试账号通过租户业务库 `im_org_visibility_overrides` 配置 `visibility_scope=all`，客户端不传可见范围参数。

+### 9.2.1 打卡考勤
+
+**状态：已实现基础版。**
+
+- 打卡规则、班次、位置/Wi-Fi 约束、补卡窗口、异常判定和统计结果必须以后端为真源；客户端只负责展示、采集设备侧上下文和临时离线队列，不能把正式打卡记录或规则只保存在本地。
+- 配置：`GET /v1/im/attendance/config?date=2026-08-31` 返回当前用户当天适用的规则、班次、允许打卡动作和前端展示文案。服务端按租户、部门、人员、节假日和特殊排班裁剪，前端不得自行推导是否迟到/早退/缺卡。
+- 记录：`GET /v1/im/attendance/records?from=2026-08-01&to=2026-08-31&scope=mine` 返回当前用户打卡记录、异常状态和补卡状态；管理员用 `scope=managed&department_id=&user_id=&cursor=` 查询权限范围内记录。
+- 打卡：`POST /v1/im/attendance/checkins`，Body 带 `date,action,rule_id,shift_id,client_time,location,wifi,device`，写操作必须带 `Idempotency-Key`。服务端校验打卡窗口、地理围栏/Wi-Fi、重复提交和设备风险，成功后返回服务端判定状态。
+- 补卡/异常申诉：`POST /v1/im/attendance/appeals` 创建申请，`GET /v1/im/attendance/appeals?scope=mine|managed&status=&cursor=` 查询列表，审批动作由管理端或后续办公审批接口处理。
+- 主动下行：规则变更、打卡状态变化、补卡审批变化可通过 `info.what="im"`，事件 `attendance.rule.updated/attendance.record.updated/attendance.appeal.updated` 下发；前端收到后刷新配置、记录或列表。
+
 ### 9.3 会议通知-发起人状态.png

 <img src="images/会议通知-发起人状态.png" alt="会议通知-发起人状态" width="360">
@@ -2180,15 +2191,21 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 - 失败响应统一包裹为 `{"code":30000,"reason":"MALFORMED_REQUEST","message":"...","details":{},"request_id":"...","server_time":"..."}`。
 - 标注“待实现/需修复”的接口是产品目标协议，前端可按示例准备，但联调前以后端发布状态为准。

-#### 9.14.1 工作台、组织、会议、日报、月报、信箱
+#### 9.14.1 工作台、组织、打卡、会议、日报、月报、信箱

 | 接口 | 输入示例 | 成功 `data` 示例 |
 | --- | --- | --- |
-| `GET /v1/im/workbench` | Query only | `{"layout_version":1,"modules":[{"code":"organization","name":"组织架构","icon_file_id":"","route":"/organization","unread_count":0,"enabled":true,"permission":"enabled"}],"enterprise":{"tenant_code":"default","feature_flags":{"organization":true,"meetings":true}}}` |
+| `GET /v1/im/workbench` | Query only | `{"layout_version":1,"modules":[{"code":"organization","name":"组织架构","icon_file_id":"","route":"/organization","unread_count":0,"enabled":true,"permission":"enabled"},{"code":"attendance","name":"打卡考勤","icon_file_id":"","route":"/attendance","unread_count":0,"enabled":true,"permission":"enabled"}],"enterprise":{"tenant_code":"default","feature_flags":{"organization":true,"attendance":true,"meetings":true}}}` |
 | `GET /v1/im/organization/departments?parent_id=root&cursor=` | Query only | `{"items":[{"department_id":"dep_1","name":"研发部","parent_id":"root","child_count":0,"member_count":12,"version":1}],"next_cursor":""}` |
 | `GET /v1/im/organization/departments/{id}/members?cursor=` | Query only | `{"items":[{"user_id":"usr...","display_name":"张三","avatar_file_id":"","department_id":"dep_1","title":"工程师","can_contact":true}],"next_cursor":""}` |
 | `GET /v1/im/organization/members?query=&department_id=&cursor=` 待实现/可由部门成员接口替代 | Query only | `{"items":[{"user_id":"usr...","display_name":"张三","department_id":"dep_1","department_name":"研发部","can_contact":true}],"next_cursor":""}` |
 | `GET /v1/im/organization/search?q=&types=department,user&cursor=` | Query only | `{"items":[{"type":"user","user_id":"usr...","display_name":"张三","department_name":"研发部","can_contact":true}],"next_cursor":""}` |
+| `GET /v1/im/attendance/config?date=2026-08-31` | Query only | `{"date":"2026-08-31","timezone":"Asia/Shanghai","rule":{"rule_id":"att_rule_default","name":"默认考勤规则","workday":true,"location_required":false,"wifi_required":false,"allow_outside_checkin":true,"appeal_allowed":true},"shifts":[{"shift_id":"shift_default","name":"默认班次","checkin_start":"08:30","work_start":"09:00","work_end":"18:00","checkout_end":"20:00"}],"allowed_actions":["check_in","check_out"],"today_record":{"record_id":"evt_...","user_id":"usr...","date":"2026-08-31","status":"checked_in","checkins":[]},"permissions":{"can_checkin":true,"can_appeal":true,"can_view_managed":true}}` |
+| `GET /v1/im/attendance/records?scope=mine&from=2026-08-01&to=2026-08-31&cursor=` | Query only | `{"items":[{"record_id":"evt_...","user_id":"usr_me","date":"2026-08-31","rule_id":"att_rule_default","shift_id":"shift_default","status":"normal","checkins":[{"checkin_id":"attc_...","action":"check_in","client_time":"2026-08-31T00:55:00Z","server_time":"2026-08-31T00:55:02Z","result":"normal","location":{"name":"上海办公室","distance_meters":38},"wifi":{"ssid":"Office-WiFi"},"device":{"platform":"ios"}}],"exceptions":[],"appeal_status":"","version":3}],"next_cursor":"","has_more":false,"statistics":{"expected_count":1,"checked_count":1,"exception_count":0,"not_checked_count":0},"permissions":{"can_checkin":true,"can_view_managed":true,"can_appeal":true}}` |
+| `GET /v1/im/attendance/records?scope=managed&department_id=dep_1&date=2026-08-31&status=late&cursor=` | Query only | `{"items":[{"record_id":"evt_...","user_id":"usr...","date":"2026-08-31","status":"late","exceptions":["late"],"appeal_status":"pending","version":2}],"next_cursor":"","has_more":false,"statistics":{"expected_count":20,"checked_count":19,"exception_count":2,"not_checked_count":1}}` |
+| `POST /v1/im/attendance/checkins` | Header `Idempotency-Key`；Body `{"date":"2026-08-31","action":"check_in","rule_id":"att_rule_default","shift_id":"shift_default","client_time":"2026-08-31T08:55:00+08:00","location":{"latitude":31.2304,"longitude":121.4737,"accuracy_meters":30},"wifi":{"ssid":"Office-WiFi","bssid":"00:11:22:33:44:55"},"device":{"device_id":"ios-device-1","platform":"ios"}}` | `{"record":{"record_id":"evt_...","user_id":"usr...","date":"2026-08-31","status":"checked_in","version":2,"checkins":[{"checkin_id":"attc_...","action":"check_in","result":"normal"}]},"checkin":{"checkin_id":"attc_...","action":"check_in","client_time":"2026-08-31T00:55:00Z","server_time":"2026-08-31T00:55:02Z","result":"normal","location":{"latitude":31.2304,"longitude":121.4737},"wifi":{"ssid":"Office-WiFi"},"device":{"platform":"ios"}}}` |
+| `POST /v1/im/attendance/appeals` | Header `Idempotency-Key`；Body `{"record_id":"evt_...","appeal_type":"missing_checkin","reason":"外出拜访客户，忘记打卡","target_action":"check_in","target_time":"2026-08-31T09:00:00+08:00","attachment_file_ids":["file_1"]}` | `{"appeal_id":"atta_...","record_id":"evt_...","user_id":"usr...","appeal_type":"missing_checkin","reason":"外出拜访客户，忘记打卡","target_action":"check_in","target_time":"2026-08-31T01:00:00Z","attachment_file_ids":["file_1"],"status":"pending","submitted_at":"2026-08-31T03:00:00Z","version":1}` |
+| `GET /v1/im/attendance/appeals?scope=mine&status=pending&cursor=` | Query only | `{"items":[{"appeal_id":"atta_...","record_id":"evt_...","user_id":"usr...","appeal_type":"missing_checkin","status":"pending","submitted_at":"2026-08-31T03:00:00Z","version":1}],"next_cursor":"","has_more":false}` |
 | `GET /v1/im/meetings?cursor=` 待补列表 | Query only | `{"items":[{"meeting_id":"mtg_1","title":"周会","start_at":"2026-08-21T10:00:00Z","end_at":"2026-08-21T10:30:00Z","my_response":"pending","state":"scheduled"}],"next_cursor":""}` |
 | `POST /v1/im/meetings` | `{"title":"周会","start_at":"2026-08-21T10:00:00Z","end_at":"2026-08-21T10:30:00Z","location":"线上","attendee_user_ids":["usr..."],"reminder_minutes":[10]}` | `{"meeting_id":"mtg_1","title":"周会","start_at":"2026-08-21T10:00:00Z","end_at":"2026-08-21T10:30:00Z","location":"线上","participants":[{"user_id":"usr_me","response":"accepted"},{"user_id":"usr...","response":"pending"}],"permissions":{"can_update":true,"can_cancel":true,"can_remind":true,"can_respond":false},"version":1}` |
 | `GET /v1/im/meetings/{meeting_id}` | Path meeting ID | `{"meeting_id":"mtg_1","title":"周会","participants":[{"user_id":"usr...","response":"pending"}],"permissions":{"can_respond":true},"version":1}` |
@@ -818,6 +818,113 @@ CREATE TABLE IF NOT EXISTS tinode.im_feedback_submissions (
  INDEX idx_im_feedback_submissions_user (user_id, id DESC)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

+-- ============================================================
+-- Attendance.
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS tinode.im_attendance_rules (
+  id                    BIGINT NOT NULL AUTO_INCREMENT,
+  rule_id               VARCHAR(64) NOT NULL,
+  name                  VARCHAR(128) NOT NULL,
+  workday               TINYINT NOT NULL DEFAULT 1,
+  location_required     TINYINT NOT NULL DEFAULT 0,
+  wifi_required         TINYINT NOT NULL DEFAULT 0,
+  allow_outside_checkin TINYINT NOT NULL DEFAULT 1,
+  appeal_allowed        TINYINT NOT NULL DEFAULT 1,
+  effective_from        DATE,
+  effective_to          DATE,
+  state                 VARCHAR(16) NOT NULL DEFAULT 'active',
+  created_at            DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at            DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  UNIQUE INDEX uk_im_attendance_rules_rule (rule_id),
+  INDEX idx_im_attendance_rules_state (state, effective_from, effective_to)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+
+CREATE TABLE IF NOT EXISTS tinode.im_attendance_shifts (
+  id            BIGINT NOT NULL AUTO_INCREMENT,
+  shift_id      VARCHAR(64) NOT NULL,
+  rule_id       VARCHAR(64) NOT NULL,
+  name          VARCHAR(128) NOT NULL,
+  work_start    TIME NOT NULL,
+  work_end      TIME NOT NULL,
+  checkin_start TIME NOT NULL,
+  checkout_end  TIME NOT NULL,
+  state         VARCHAR(16) NOT NULL DEFAULT 'active',
+  sort_order    INT NOT NULL DEFAULT 0,
+  created_at    DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at    DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  UNIQUE INDEX uk_im_attendance_shifts_shift (shift_id),
+  INDEX idx_im_attendance_shifts_rule (rule_id, state, sort_order)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+
+CREATE TABLE IF NOT EXISTS tinode.im_attendance_records (
+  id            BIGINT NOT NULL AUTO_INCREMENT,
+  record_id     VARCHAR(64) NOT NULL,
+  user_id       BIGINT NOT NULL,
+  record_date   DATE NOT NULL,
+  rule_id       VARCHAR(64) NOT NULL,
+  shift_id      VARCHAR(64) NOT NULL,
+  status        VARCHAR(32) NOT NULL DEFAULT 'not_checked',
+  exceptions    JSON,
+  appeal_status VARCHAR(32) NOT NULL DEFAULT '',
+  version       INT NOT NULL DEFAULT 1,
+  created_at    DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at    DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  UNIQUE INDEX uk_im_attendance_records_record (record_id),
+  UNIQUE INDEX uk_im_attendance_records_user_date_shift (user_id, record_date, shift_id),
+  INDEX idx_im_attendance_records_user_id (user_id, id DESC),
+  INDEX idx_im_attendance_records_date_status (record_date, status, id DESC)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+
+CREATE TABLE IF NOT EXISTS tinode.im_attendance_checkins (
+  id              BIGINT NOT NULL AUTO_INCREMENT,
+  checkin_id      VARCHAR(64) NOT NULL,
+  record_id       VARCHAR(64) NOT NULL,
+  user_id         BIGINT NOT NULL,
+  record_date     DATE NOT NULL,
+  action          VARCHAR(32) NOT NULL,
+  rule_id         VARCHAR(64) NOT NULL,
+  shift_id        VARCHAR(64) NOT NULL,
+  client_time     DATETIME(3) NOT NULL,
+  server_time     DATETIME(3) NOT NULL,
+  result          VARCHAR(32) NOT NULL,
+  location        JSON,
+  wifi            JSON,
+  device          JSON,
+  idempotency_key VARCHAR(128) NOT NULL,
+  created_at      DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  UNIQUE INDEX uk_im_attendance_checkins_checkin (checkin_id),
+  UNIQUE INDEX uk_im_attendance_checkins_idempotency (user_id, idempotency_key),
+  INDEX idx_im_attendance_checkins_record (record_id, id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+
+CREATE TABLE IF NOT EXISTS tinode.im_attendance_appeals (
+  id                  BIGINT NOT NULL AUTO_INCREMENT,
+  appeal_id           VARCHAR(64) NOT NULL,
+  record_id           VARCHAR(64) NOT NULL,
+  user_id             BIGINT NOT NULL,
+  appeal_type         VARCHAR(64) NOT NULL,
+  reason              VARCHAR(512) NOT NULL,
+  target_action       VARCHAR(32) NOT NULL DEFAULT '',
+  target_time         DATETIME(3),
+  attachment_file_ids JSON,
+  status              VARCHAR(32) NOT NULL DEFAULT 'pending',
+  version             INT NOT NULL DEFAULT 1,
+  idempotency_key     VARCHAR(128) NOT NULL,
+  submitted_at        DATETIME(3) NOT NULL,
+  created_at          DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at          DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  UNIQUE INDEX uk_im_attendance_appeals_appeal (appeal_id),
+  UNIQUE INDEX uk_im_attendance_appeals_idempotency (user_id, idempotency_key),
+  INDEX idx_im_attendance_appeals_record (record_id),
+  INDEX idx_im_attendance_appeals_user_status (user_id, status, id DESC)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+
 -- ============================================================
 -- Seed data.
 -- ============================================================
@@ -837,10 +944,11 @@ ON DUPLICATE KEY UPDATE updated_at = CURRENT_TIMESTAMP(3);
 INSERT INTO tinode.im_workbench_apps(code, name, route, sort_order, unread_key, enabled, permission)
 VALUES
  ('organization', '组织架构', '/organization', 10, 'organization', 1, 'enabled'),
-  ('meetings', '会议通知', '/meetings', 20, 'meetings', 1, 'enabled'),
-  ('daily_reports', '日报', '/reports/daily', 30, 'daily_reports', 1, 'enabled'),
-  ('monthly_reports', '月报', '/reports/monthly', 40, 'monthly_reports', 1, 'enabled'),
-  ('executive_mailbox', '总经理信箱', '/executive-mailbox', 50, 'executive_mailbox', 1, 'enabled')
+  ('attendance', '打卡', '/attendance', 20, 'attendance', 1, 'enabled'),
+  ('meetings', '会议通知', '/meetings', 30, 'meetings', 1, 'enabled'),
+  ('daily_reports', '日报', '/reports/daily', 40, 'daily_reports', 1, 'enabled'),
+  ('monthly_reports', '月报', '/reports/monthly', 50, 'monthly_reports', 1, 'enabled'),
+  ('executive_mailbox', '总经理信箱', '/executive-mailbox', 60, 'executive_mailbox', 1, 'enabled')
 ON DUPLICATE KEY UPDATE
  name = VALUES(name),
  route = VALUES(route),
@@ -848,6 +956,14 @@ ON DUPLICATE KEY UPDATE
  unread_key = VALUES(unread_key),
  updated_at = CURRENT_TIMESTAMP(3);

+INSERT INTO tinode.im_attendance_rules(rule_id, name, workday, location_required, wifi_required, allow_outside_checkin, appeal_allowed)
+VALUES ('att_rule_default', '默认考勤规则', 1, 0, 0, 1, 1)
+ON DUPLICATE KEY UPDATE updated_at = updated_at;
+
+INSERT INTO tinode.im_attendance_shifts(shift_id, rule_id, name, work_start, work_end, checkin_start, checkout_end, sort_order)
+VALUES ('shift_default', 'att_rule_default', '默认班次', '09:00:00', '18:00:00', '08:30:00', '20:00:00', 10)
+ON DUPLICATE KEY UPDATE updated_at = updated_at;
+
 INSERT INTO tinode.im_mailbox_config(id, enabled, allow_anonymous, required_fields, max_length, attachment_policy, notice_title, notice_content)
 VALUES (1, 1, 1, '["subject","content"]', 5000, '{"max_files":5,"purpose":"executive_mailbox"}', '总经理信箱', '请如实填写诉求，匿名提交将按企业政策保护展示身份。')
 ON DUPLICATE KEY UPDATE updated_at = updated_at;