task_auto_plan/include/app.hpp

/**
 * @file app.hpp
 * @brief 智能考勤管理系统核心数据结构与业务接口声明
 *
 * 需求追溯：
 * - SRS-ATT_F-001: 多终端打卡支持
 * - SRS-ATT_F-002: 考勤数据自动核算
 * - SRS-ATT_F-003: 异常考勤预警
 * - SRS-ATT_F-004: 考勤报表生成导出
 * - SRS-ATT_F-005: 第三方系统集成
 */

#ifndef APP_HPP
#define APP_HPP

#include <string>
#include <vector>
#include <map>
#include <ctime>

// ---------- 数据结构 ----------

// 打卡请求（SRS-ATT_F-001 输入）
struct PunchRequest {
    std::string employeeId;      // 员工唯一标识
    std::string terminalType;    // 终端类型：MOBILE / WEB / MACHINE
    std::string deviceId;        // 设备标识
    std::time_t timestamp;       // 打卡时间戳（降级模式下仅缓存此字段）
    double latitude;             // 纬度（可选）
    double longitude;            // 经度（可选）
};

// 打卡结果响应（SRS-ATT_F-001 输出）
struct PunchResponse {
    bool success;
    std::string message;
    std::time_t serverTime;
};

// 考勤规则配置（SRS-ATT_F-002 输入）
struct AttendanceRule {
    std::string department;
    std::string shift;           // 班次
    int startHour;               // 上班时间（小时）
    int startMinute;
    int endHour;                 // 下班时间（小时）
    int endMinute;
    int lateThreshold;           // 迟到容忍分钟数
    int earlyLeaveThreshold;     // 早退容忍分钟数
    std::vector<std::string> holidays; // 节假日列表
};

// 原始打卡记录（SRS-ATT_F-002 输入）
struct RawRecord {
    std::string employeeId;
    std::time_t punchTime;
    std::string terminalType;
};

// 核算结果（SRS-ATT_F-002 输出，SRS-ATT_F-003 输入）
struct CalculationResult {
    std::string employeeId;
    std::time_t date;
    enum Status { NORMAL, LATE, EARLY_LEAVE, ABSENT, MISSING_CARD };
    Status status;
    std::string shiftName;
    std::time_t actualArrival;
    std::time_t actualDeparture;
};

// 预警通知（SRS-ATT_F-003 输出）
struct WarningNotification {
    std::string employeeId;
    std::string managerId;      // 管理员ID（严重异常时填充）
    CalculationResult::Status anomalyType;
    std::string message;
    long long sendTimestamp;
};

// 报表查询条件（SRS-ATT_F-004 输入）
struct ReportQuery {
    std::string department;
    std::string employeeId;     // 可选，若为空则查部门
    std::time_t startDate;
    std::time_t endDate;
    enum Format { EXCEL, PDF, ONLINE };
    Format format;
};

// 统计报表文件（SRS-ATT_F-004 输出）
struct ReportFile {
    std::string fileName;
    std::string downloadUrl;
    std::vector<char> rawData;  // 二进制数据
};

// 第三方同步请求（SRS-ATT_F-005 输入）
struct ThirdPartySyncRequest {
    std::string apiKey;          // 鉴权密钥
    std::string systemType;      // HR / OA / DoorAccess
    std::vector<RawRecord> records; // 需要同步的打卡记录
};

// 考勤同步数据（SRS-ATT_F-005 输出）
struct SyncResponse {
    bool success;
    int syncedCount;
    int failedCount;
    std::string message;
};

// ---------- 业务接口 ----------
class AttendanceSystem {
public:
    AttendanceSystem();
    ~AttendanceSystem();

    // SRS-ATT_F-001: 处理打卡请求（移动端、Web端、考勤机）
    PunchResponse processPunch(const PunchRequest& req);

    // SRS-ATT_F-002: 自动核算考勤数据（定时/事件触发）
    void autoCalculateAttendance();

    // SRS-ATT_F-003: 异常预警通知
    void sendWarningForAnomaly(const CalculationResult& result);

    // SRS-ATT_F-004: 生成并导出报表
    ReportFile generateReport(const ReportQuery& query);

    // SRS-ATT_F-005: 与第三方系统同步数据
    SyncResponse syncWithThirdParty(const ThirdPartySyncRequest& request);

private:
    // 辅助函数
    bool validateEmployee(const std::string& employeeId);
    AttendanceRule getRuleForEmployee(const std::string& employeeId);
    void storeRawRecord(const RawRecord& rec);
    void storeCalculationResult(const CalculationResult& res);
    std::vector<RawRecord> fetchUncalculatedRecords();
    CalculationResult calculateSingleRecord(const RawRecord& rec, const AttendanceRule& rule);
    void logWarningSend(const WarningNotification& notif);
    std::vector<std::string> getManagersForEmployee(const std::string& employeeId);
    bool authenticateThirdParty(const std::string& apiKey);
};

#endif // APP_HPP