# 会议出勤（Meeting Attendance）模块

> **负责人**: 待定
> **状态**: v1.0（议程能力首发开发中） · 出勤主体能力 ✅ / 议程能力 🚧
> **最后更新**: 2026-05-20

---

## ✅ 机器读取区（必填）

### 通用字段

| 字段 | 内容 |
|------|------|
| 模块 | meeting-attendance |
| 文档类型 | Module-README |
| 目标 | 复用现有线上会议出勤系统能力并集成到 FFOA 统一登录与权限体系；v1.0 起在会议层引入议程 + 任务分配 + 资料上传能力 |
| 关键入口 | 前端: `frontend/src/app/(modules)/meetingattendance/`（规划）/ 后端: `backend/src/modules/meeting-attendance/`（规划） / 数据库: `platform_meeting_attendance.*`（规划） |
| API Base | `/api/v1/meeting-attendance` |
| 关联文档 | `01-prd.md` / `03-architecture.md` / `05-ui-interaction-spec.md` / `07-api.md` / `99-changelog.md` |

### 文档导航（状态）

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | ✅（议程章节） | 2026-05-20 |
| [用户场景](./02-user-journey.md) | 🚧 | 2026-04-21 |
| [架构设计](./03-architecture.md) | ✅（议程章节） | 2026-05-20 |
| [状态机](./04-state-machine.md) | 🚧 | 2026-04-21 |
| [UI 交互规范](./05-ui-interaction-spec.md) | 🚧 | 2026-04-21 |
| [数据模型](./06-data-model.md) | 🚧 | 2026-04-21 |
| [API 文档](./07-api.md) | 🚧 | 2026-04-21 |
| [错误码](./08-error-codes.md) | 🚧 | 2026-04-21 |
| [测试场景](./09-test-scenarios.md) | 🚧 | 2026-04-21 |
| [E2E 测试规范](./10-e2e-test-spec.md) | 🚧 | 2026-04-21 |
| [使用指南](./11-user-guide.md) | ✅ | 2026-05-11 |
| [变更日志](./99-changelog.md) | ✅（v1.0） | 2026-05-20 |

---

## 🧭 人类阅读区（可选）

### 模块概述

该模块负责会议创建、系列会议管理、参会名单、扫码签到（含访客免登录）、出勤统计报表与审计记录。目标是在不改变现有业务行为与页面交互的前提下，接入 FFOA 的统一登录与权限体系。

**v1.0（2026-05-20）新增议程能力**：在会议层引入"议程段 + 主题项 + 上传任务 + 资料附件"四层模型，覆盖会前准备（管理员配议程 + 分配上传任务）、会中陈述（按议程驱动）、会后回顾（议程项级 + 会议级资料长期归档）全链路。外部访客视图仅展示议程标题，保护内部资料。

### 功能清单（截至 v1.0）

| 能力 | 状态 | 说明 |
|------|------|------|
| 会议 / 系列管理 | ✅ | 创建 / 编辑 / 取消 / 批量改期 / 双二维码 |
| 系统用户 + 访客签到 | ✅ | 含设备限制 / 迟到判定 / 签到方式校验 |
| 参会名单维护 | ✅ | 仅系统用户 / Outlook 自动同步 / 自动入组真人 |
| 出勤统计报表 | ✅ | 单场 + 系列 / 可选参会人口径分离 / 签到方式校验 UI 一致性 |
| Outlook 自动同步 | ✅ | Webhook + Delta + 对账兜底 / 本地维护优先 |
| 审计日志 | ✅ | 会议 / 签到 / Outlook 同步 / 议程操作 |
| **议程管理 + 任务分配 + 资料上传** | 🚧 v1.0 | 议程段 / 主题项 CRUD + 上传任务 + 议程项级 / 会议级资料 |

### 代码与数据位置

- **前端**: `frontend/src/app/(modules)/meetingattendance/`（规划）
- **后端**: `backend/src/modules/meeting-attendance/`（规划，议程能力含 `agenda.controller` / `upload-task.controller` / `attachment.controller`）
- **数据库**: `platform_meeting_attendance` schema（议程能力新增 5 张表：`MeetingAgendaSection` / `MeetingAgendaItem` / `MeetingAgendaItemUploadTask` / `MeetingAgendaItemAttachment` / `MeetingAttachment`）

### 主要接口

**出勤主体**：
- `GET /meeting-attendance/meetings` - 会议列表
- `GET /meeting-attendance/meetings/:id` - 会议详情
- `POST /meeting-attendance/meetings/:id/checkin` - 系统用户签到
- `POST /meeting-attendance/meetings/:id/guest-checkin` - 访客签到
- `GET /meeting-attendance/reports/series` - 系列会议报表

**议程能力（v1.0 新增，详见 `07-api.md`）**：
- `GET /meeting-attendance/meetings/:id/agenda` - 会议议程视图（外部访客自动走受限视图）
- `POST|PATCH|DELETE /meeting-attendance/meetings/:id/agenda/sections[/:sectionId]` - 议程段 CRUD + `PATCH .../sections/reorder` 拖拽排序
- `POST|PATCH|DELETE /meeting-attendance/agenda-sections/:sectionId/items[/:itemId]` - 主题项 CRUD + 排序
- `GET|POST|PATCH|DELETE /meeting-attendance/agenda-items/:itemId/upload-tasks[/:taskId]` - 上传任务 CRUD
- `GET /meeting-attendance/my-upload-tasks?status=PENDING` - 我的待办
- `POST|GET|DELETE /meeting-attendance/agenda-items/:itemId/attachments[/:attachmentId]` - 议程项级资料 + `POST|GET|DELETE /meeting-attendance/meetings/:id/attachments[/:attachmentId]` - 会议级资料
- `GET /meeting-attendance/attachments/agenda-item/:id/download` - 议程项级资料下载（stream + RFC 5987 Content-Disposition）
- `GET /meeting-attendance/attachments/meeting/:id/download` - 会议级资料下载（同上）