# 固定地点签到（Site Attendance）模块

> **负责人**: 待定
> **状态**: 🚧 In Development
> **最后更新**: 2026-04-17

---

## 通用字段

| 字段 | 内容 |
|------|------|
| 模块 | site-attendance |
| 文档类型 | Module-README |
| 目标 | 提供固定地点（如公司入口）的日常签到/签退能力，二维码支持永久或定时轮换，支持登录签到和免登录兜底，支持多公司共享签到分诊 |
| 关键入口 | 前端: `frontend/src/app/(modules)/siteattendance/` / 后端: `backend/src/modules/site-attendance/` / 数据库: `platform_site_attendance.*` |
| API Base | `/api/v1/site-attendance` |
| 核心实体 | Checkpoint, AttendanceEvent, DailySummary, SharedCheckinPartner (v1.5), SharedCheckinTicketUsage (v1.5) |
| 接口数量 | 24（v1.0: 15 + v1.5: 9） |
| 关联文档 | `01-prd.md` / `03-architecture.md` / `05-ui-interaction-spec.md` / `06-data-model.md` / `07-api.md` / `08-error-codes.md` / `09-test-scenarios.md` / `10-e2e-test-spec.md` / `11-user-guide.md` |

## 文档导航

| 文档 | 状态 | 何时读取 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | 🚧 | 了解模块目标、功能范围、业务规则 |
| [架构设计](./03-architecture.md) | 🚧 | 理解分诊/token/ticket 设计、部署形态 |
| [UI 交互规范](./05-ui-interaction-spec.md) | 🚧 | 实现前端页面时（含签到页/分诊页/大屏页/管理后台） |
| [数据模型](./06-data-model.md) | 🚧 | 设计数据库 schema 或编写后端逻辑时 |
| [API 文档](./07-api.md) | 🚧 | 实现或对接后端接口时 |
| [错误码](./08-error-codes.md) | 🚧 | 实现后端错误处理 / 前端错误态文案时 |
| [测试场景](./09-test-scenarios.md) | 🚧 | 编写/执行 L1 集成测试时 |
| [E2E 测试编排](./10-e2e-test-spec.md) | 🚧 | Playwright MCP 全链路验收时 |
| [配置与使用指南](./11-user-guide.md) | ✅ | 管理员配置签到点 / 员工日常签到 / 常见 Q&A |

## 模块概述

该模块用于公司门口等固定地点的日常考勤签到。管理员配置签到点（checkpoint）并生成二维码，员工扫码完成签到和签退。

v1.5 引入**共享签到**（多公司在同一办公地共用分诊二维码）和 **QR 轮换**（防截图流传），兼容存量 v1.0 静态二维码。

与 meeting-attendance 的区别：
- meeting-attendance 的二维码绑定会议实例，每场会议码不同
- site-attendance 的二维码绑定签到点，支持永久或定时轮换
- 签到点没有开始/结束时间概念，每天都可用

### 核心流程（v1.0）

1. 管理员创建签到点，配置经纬度、定位校验规则
2. 系统生成二维码，管理员贴在入口 / 在大屏展示
3. 员工扫码进入签到页
4. 页面显示签到/签退按钮和当天状态
5. 已登录用户直接操作；未登录用户点击后选择"登录继续"或"免登录继续"
6. 免登录需搜索并选择系统用户后操作
7. 操作时进行定位校验（如已启用），记录签到事件

### v1.5 新增流程（共享签到）

1. 管理员为某个 checkpoint 开启共享签到 + 配置公司标识 + 添加合作伙伴（其他公司签到点 URL）
2. 该 checkpoint 的二维码自动指向分诊页 `/shared/:code`
3. 员工扫码 → 分诊页展示公司选择（本地 + 合作伙伴） → 选择后签发 ticket 跳转对应签到页
4. localStorage 记住上次选择，下次扫码自动跳；签到页右上角"切换公司"按钮可重选

### 代码与数据位置

- **前端**: `frontend/src/app/(modules)/siteattendance/`
- **后端**: `backend/src/modules/site-attendance/`
- **数据库**: `platform_site_attendance` schema