企业微信应用开发完全指南：以考勤系统为例

@Service
public class WeComTokenService {

    @Value("${wecom.corpid}")
    private String corpId;

    @Value("${wecom.secret}")
    private String secret;

    private final StringRedisTemplate redisTemplate;
    private final RestTemplate restTemplate;

    private static final String TOKEN_KEY="wecom:...oken";
    private static final String TOKEN_URL="https:...t=%s";

    /**
     * 获取 access_token，优先从 Redis 读取，过期则刷新
     */
    public String getAccessToken() {
        String token = redisTemplate.opsForValue().get(TOKEN_KEY);
        if (StringUtils.hasText(token)) {
            return token;
        }
        return refreshToken();
    }

    /**
     * 强制刷新 access_token
     */
    public synchronized String refreshToken() {
        // 双重检查，避免并发重复刷新
        String token = redisTemplate.opsForValue().get(TOKEN_KEY);
        if (StringUtils.hasText(token)) {
            return token;
        }

        String url = String.format(TOKEN_URL, corpId, secret);
        JSONObject response = restTemplate.getForObject(url, JSONObject.class);

        if (response.getInteger("errcode") == 0) {
            token = response.getString("access_token");
            int expiresIn = response.getInteger("expires_in");
            // 缓存时间比实际过期时间少 100 秒，避免边界问题
            redisTemplate.opsForValue().set(
                TOKEN_KEY, token, expiresIn - 100, TimeUnit.SECONDS);
            return token;
        }

        throw new RuntimeException("获取 access_token 失败: " + response);
    }
}

@RestController
@RequestMapping("/auth")
public class AuthController {

    private final WeComTokenService tokenService;
    private final UserService userService;
    private final JwtUtil jwtUtil;

    /**
     * OAuth2 回调，用 code 换取用户身份
     */
    @GetMapping("/callback")
    public void callback(
            @RequestParam String code,
            @RequestParam(required = false) String state,
            HttpServletResponse response) throws IOException {

        // 1. 用 code 获取 userid
        String accessToken = tokenService.getAccessToken();
        String userInfoUrl = String.format(
            "https://qyapi.weixin.qq.com/cgi-bin/auth/getuserinfo?access_token=%s&code=%s",
            accessToken, code);

        JSONObject userInfo = restTemplate.getForObject(userInfoUrl, JSONObject.class);

        if (userInfo.getInteger("errcode") != 0) {
            throw new RuntimeException("获取用户身份失败: " + userInfo);
        }

        String userId = userInfo.getString("userid");

        // 2. 查询或创建本地用户
        User user = userService.findByWeComUserId(userId);
        if (user == null) {
            // 首次登录，同步用户信息
            user = userService.syncFromWeCom(userId, accessToken);
        }

        // 3. 生成 JWT token
        String jwtToken = jwtUtil.generateToken(user.getId(), user.getName());

        // 4. 重定向到前端，携带 token
        response.sendRedirect(String.format(
            "/#/authsuccess?token=%s", URLEncoder.encode(jwtToken, "UTF-8")));
    }
}

@Service
public class ContactSyncService {

    /**
     * 全量同步通讯录，建议每天凌晨执行一次
     */
    @Scheduled(cron = "0 0 2 * * ?")
    public void fullSync() {
        String token = tokenService.getAccessToken();
        
        // 1. 同步部门
        List<Department> departments = weComClient.getDepartments(token, 0);
        departmentService.batchUpsert(departments);

        // 2. 同步每个部门的成员
        for (Department dept : departments) {
            List<WeComUser> users = weComClient.getUsersByDept(
                token, dept.getId(), true);
            userService.batchUpsert(users);
        }

        log.info("通讯录同步完成: {} 个部门, {} 个员工",
            departments.size(), /* ... */);
    }

    /**
     * 增量同步，通过回调事件触发（见 3.6 节）
     */
    public void incrementalSync(ChangeEvent event) {
        switch (event.getChangeType()) {
            case "create_user" -> userService.create(event.getUser());
            case "update_user" -> userService.update(event.getUser());
            case "delete_user" -> userService.delete(event.getUserId());
        }
    }
}

@Service
public class WeComMessageService {

    private static final String SEND_URL = 
        "https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=%s";

    /**
     * 发送考勤提醒消息
     */
    public void sendCheckinReminder(String userId, String message, String url) {
        JSONObject body = new JSONObject();
        body.put("touser", userId);
        body.put("msgtype", "textcard");
        body.put("agentid", agentId);

        JSONObject card = new JSONObject();
        card.put("title", "考勤提醒");
        card.put("description", message);
        card.put("url", url);
        card.put("btntxt", "去打卡");
        body.put("textcard", card);

        send(body);
    }

    /**
     * 发送审批通知（带交互按钮）
     */
    public void sendApprovalNotice(String approverId, 
            String title, String desc, String taskId) {
        JSONObject body = new JSONObject();
        body.put("touser", approverId);
        body.put("msgtype", "template_card");
        body.put("agentid", agentId);

        JSONObject card = new JSONObject();
        card.put("card_type", "button_interaction");
        card.put("source", Map.of("desc", "考勤系统"));
        card.put("main_title", Map.of("title", title, "desc", desc));
        card.put("button_list", List.of(
            Map.of("text", "同意", "style", 1, "key", "approve"),
            Map.of("text", "拒绝", "style", 2, "key", "reject")
        ));
        card.put("task_id", taskId);
        body.put("template_card", card);

        send(body);
    }

    private void send(JSONObject body) {
        String url = String.format(SEND_URL, tokenService.getAccessToken());
        JSONObject result = restTemplate.postForObject(url, body, JSONObject.class);

        if (result.getInteger("errcode") != 0) {
            log.error("消息发送失败: {}", result);
            throw new RuntimeException("消息发送失败: " + result.getString("errmsg"));
        }
    }
}

@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {

    private final WeComService weComService;
    private final JwtUtil jwtUtil;

    /**
     * OAuth2 回调，用 code 换取用户身份
     */
    @GetMapping("/callback")
    public RedirectView callback(@RequestParam String code,
                                  @RequestParam(required = false) String state) {
        // 1. 用 code 获取访问用户身份
        WeComUserInfo userInfo = weComService.getUserInfoByCode(code);

        // 2. 获取用户详情（姓名、部门等）
        WeComUserDetail detail = weComService.getUserDetail(userInfo.getUserId());

        // 3. 同步用户信息到本地数据库
        User localUser = userService.syncFromWeCom(userInfo.getUserId(), detail);

        // 4. 生成 JWT
        String token = jwtUtil.generate(localUser.getId(), localUser.getUserId());

        // 5. 重定向到前端，token 通过 URL 参数传递
        String redirectUrl = frontendUrl + "/#/auth?token=" + token;
        return new RedirectView(redirectUrl);
    }
}

@Service
@RequiredArgsConstructor
public class WeComService {

    private final WeComConfig config;
    private final RestClient restClient;

    /**
     * 获取 access_token（带缓存）
     * access_token 有效期 7200 秒，需提前刷新
     */
    @Cacheable(value = "wecom_token", key = "'access_token'")
    public String getAccessToken() {
        String url = String.format(
            "%s/cgi-bin/gettoken?corpid=%s&corpsecret=%s",
            config.getApiBase(), config.getCorpId(), config.getSecret()
        );

        TokenResponse resp = restClient.get()
            .uri(url)
            .retrieve()
            .body(TokenResponse.class);

        if (resp.getErrcode() != 0) {
            throw new BusinessException("获取 access_token 失败: " + resp.getErrmsg());
        }
        return resp.getAccess_token();
    }

    /**
     * 用 OAuth2 code 获取用户身份
     */
    public WeComUserInfo getUserInfoByCode(String code) {
        String token = getAccessToken();
        String url = String.format(
            "%s/cgi-bin/auth/getuserinfo?access_token=%s&code=%s",
            config.getApiBase(), token, code
        );

        UserInfoResponse resp = restClient.get()
            .uri(url)
            .retrieve()
            .body(UserInfoResponse.class);

        if (resp.getErrcode() != 0) {
            throw new BusinessException("获取用户身份失败: " + resp.getErrmsg());
        }
        return new WeComUserInfo(resp.getUserid(), resp.getUserTicket());
    }

    /**
     * 获取用户详情
     */
    public WeComUserDetail getUserDetail(String userId) {
        String token = getAccessToken();
        String url = String.format(
            "%s/cgi-bin/user/get?access_token=%s&userid=%s",
            config.getApiBase(), token, userId
        );

        UserDetailResponse resp = restClient.get()
            .uri(url)
            .retrieve()
            .body(UserDetailResponse.class);

        return WeComUserDetail.builder()
            .userId(resp.getUserid())
            .name(resp.getName())
            .department(resp.getDepartment())
            .avatar(resp.getAvatar())
            .build();
    }
}

@RestController
@RequestMapping("/api/attendance")
@RequiredArgsConstructor
public class AttendanceController {

    private final AttendanceService attendanceService;

    /**
     * 提交打卡
     */
    @PostMapping("/clock")
    public Result<ClockResponse> clock(@Valid @RequestBody ClockRequest req) {
        return Result.success(attendanceService.clock(req));
    }
}

@Service
@RequiredArgsConstructor
public class AttendanceService {

    private final AttendanceRuleRepository ruleRepo;
    private final AttendanceRecordRepository recordRepo;
    private final WeComService weComService;
    private final RedisTemplate<String, String> redisTemplate;

    /**
     * 打卡核心逻辑
     */
    @Transactional
    public ClockResponse clock(ClockRequest req) {
        String userId = SecurityUtil.getCurrentUserId();

        // 1. 分布式锁，防止重复打卡
        String lockKey = "clock:lock:" + userId + ":" + LocalDate.now();
        Boolean locked = redisTemplate.opsForValue()
            .setIfAbsent(lockKey, "1", 5, TimeUnit.SECONDS);
        if (Boolean.FALSE.equals(locked)) {
            throw new BusinessException("请勿重复点击，正在处理中");
        }

        try {
            // 2. 查找今日适用的考勤规则
            AttendanceRule rule = findTodayRule(userId);
            if (rule == null) {
                throw new BusinessException("今日非工作日，无需打卡");
            }

            // 3. 判断打卡类型（上班/下班）
            LocalTime now = LocalTime.now();
            int clockType = now.isBefore(rule.getWorkStartTime()
                .plusMinutes(rule.getFlexMinutes())) ? 1 : 2;

            // 4. 校验位置
            if (rule.getLocationLat() != null) {
                double distance = GeoUtil.distance(
                    req.getLatitude(), req.getLongitude(),
                    rule.getLocationLat(), rule.getLocationLng()
                );
                if (distance > rule.getLocationRadius()) {
                    throw new BusinessException(
                        String.format("您不在打卡范围内（距离 %.0f 米，超出 %d 米限制）",
                        distance, rule.getLocationRadius())
                    );
                }
            }

            // 5. 校验 WiFi
            if (rule.getWifiMacs() != null && !rule.getWifiMacs().isEmpty()) {
                if (!rule.getWifiMacs().contains(req.getWifiMac())) {
                    throw new BusinessException("当前 WiFi 不在允许范围内");
                }
            }

            // 6. 处理照片
            String photoUrl = null;
            if (rule.isNeedPhoto() && req.getMediaId() != null) {
                photoUrl = weComService.downloadAndSaveMedia(req.getMediaId());
            }

            // 7. 计算迟到/早退
            boolean isLate = false, isEarlyLeave = false;
            int lateMinutes = 0, earlyMinutes = 0;

            if (clockType == 1) {
                LocalTime deadline = rule.getWorkStartTime()
                    .plusMinutes(rule.getFlexMinutes() + rule.getLateAllowance());
                if (now.isAfter(deadline)) {
                    isLate = true;
                    lateMinutes = (int) Duration.between(deadline, now).toMinutes();
                }
            } else {
                if (now.isBefore(rule.getWorkEndTime())) {
                    isEarlyLeave = true;
                    earlyMinutes = (int) Duration.between(now, rule.getWorkEndTime()).toMinutes();
                }
            }

            // 8. 保存打卡记录
            AttendanceRecord record = AttendanceRecord.builder()
                .userId(userId)
                .userName(SecurityUtil.getCurrentUserName())
                .clockType(clockType)
                .clockTime(LocalDateTime.now())
                .clockDate(LocalDate.now())
                .latitude(req.getLatitude())
                .longitude(req.getLongitude())
                .wifiMac(req.getWifiMac())
                .wifiName(req.getWifiName())
                .photoUrl(photoUrl)
                .isLate(isLate)
                .isEarlyLeave(isEarlyLeave)
                .lateMinutes(lateMinutes)
                .earlyMinutes(earlyMinutes)
                .source(1)
                .build();

            recordRepo.save(record);

            return ClockResponse.builder()
                .clockType(clockType)
                .clockTime(record.getClockTime())
                .isLate(isLate)
                .lateMinutes(lateMinutes)
                .isEarlyLeave(isEarlyLeave)
                .earlyMinutes(earlyMinutes)
                .message(getClockMessage(clockType, isLate, isEarlyLeave))
                .build();
        } finally {
            redisTemplate.delete(lockKey);
        }
    }

    private String getClockMessage(int type, boolean late, boolean early) {
        if (type == 1) {
            return late ? "上班打卡成功（迟到）" : "上班打卡成功";
        }
        return early ? "下班打卡成功（早退）" : "下班打卡成功，辛苦了";
    }
}

/**
 * 考勤规则引擎
 * 根据日期、用户、部门匹配适用规则
 */
@Service
@RequiredArgsConstructor
public class AttendanceRuleEngine {

    private final AttendanceRuleRepository ruleRepo;
    private final AttendanceRuleDeptRepository ruleDeptRepo;
    private final WeComService weComService;

    /**
     * 查找用户在某天的适用规则
     */
    public AttendanceRule findRule(String userId, LocalDate date) {
        // 1. 获取用户部门信息
        List<Long> deptIds = weComService.getUserDeptIds(userId);

        // 2. 查找部门关联的规则
        List<Long> ruleIds = ruleDeptRepo.findRuleIdsByDeptIds(deptIds);
        if (ruleIds.isEmpty()) {
            return null; // 无规则 = 不需要打卡
        }

        // 3. 获取规则列表
        List<AttendanceRule> rules = ruleRepo.findAllById(ruleIds);

        // 4. 按优先级匹配
        for (AttendanceRule rule : rules) {
            if (matchesDate(rule, date)) {
                return rule;
            }
        }
        return null;
    }

    /**
     * 判断规则是否在指定日期生效
     */
    private boolean matchesDate(AttendanceRule rule, LocalDate date) {
        // 检查工作日掩码
        // 周一=1(0b0000001) ... 周日=64(0b1000000)
        int dayOfWeek = date.getDayOfWeek().getValue(); // 1=Monday ... 7=Sunday
        int dayBit = 1 << (dayOfWeek - 1);
        if ((rule.getWorkDaysMask() & dayBit) == 0) {
            return false; // 非工作日
        }

        // 检查法定节假日（可接入国务院节假日 API）
        if (HolidayUtil.isHoliday(date)) {
            return false;
        }

        // 检查调休日（法定节假日调休上班）
        if (HolidayUtil.isWorkdayOverride(date)) {
            return true;
        }

        return true;
    }

    /**
     * 计算日考勤汇总
     */
    public AttendanceDailySummary summarize(String userId, LocalDate date) {
        AttendanceRule rule = findRule(userId, date);
        if (rule == null) {
            return buildRestDaySummary(userId, date);
        }

        List<AttendanceRecord> records = recordRepo
            .findByUserIdAndClockDateOrderByClockTime(userId, date);

        if (records.isEmpty()) {
            return buildAbsentSummary(userId, date, rule);
        }

        // 找到最早上班打卡和最后下班打卡
        AttendanceRecord firstIn = records.stream()
            .filter(r -> r.getClockType() == 1)
            .min(Comparator.comparing(AttendanceRecord::getClockTime))
            .orElse(null);

        AttendanceRecord lastOut = records.stream()
            .filter(r -> r.getClockType() == 2)
            .max(Comparator.comparing(AttendanceRecord::getClockTime))
            .orElse(null);

        // 计算状态
        int status = 1; // 正常
        int lateMin = 0, earlyMin = 0;

        if (firstIn != null && firstIn.isLate()) {
            status = 2; // 迟到
            lateMin = firstIn.getLateMinutes();
        }
        if (lastOut != null && lastOut.isEarlyLeave()) {
            status = status == 2 ? 4 : 3; // 迟到+早退 或 早退
            earlyMin = lastOut.getEarlyMinutes();
        }
        if (firstIn == null || lastOut == null) {
            status = 5; // 缺卡
        }

        // 计算工作时长
        BigDecimal workHours = BigDecimal.ZERO;
        if (firstIn != null && lastOut != null) {
            long minutes = Duration.between(
                firstIn.getClockTime(), lastOut.getClockTime()
            ).toMinutes();
            workHours = BigDecimal.valueOf(minutes)
                .divide(BigDecimal.valueOf(60), 2, RoundingMode.HALF_UP);
        }

        return AttendanceDailySummary.builder()
            .userId(userId)
            .summaryDate(date)
            .status(status)
            .firstClockIn(firstIn != null ? firstIn.getClockTime() : null)
            .lastClockOut(lastOut != null ? lastOut.getClockTime() : null)
            .workHours(workHours)
            .lateMinutes(lateMin)
            .earlyMinutes(earlyMin)
            .ruleId(rule.getId())
            .build();
    }
}

/**
 * 考勤定时任务
 */
@Component
@RequiredArgsConstructor
@Slf4j
public class AttendanceScheduler {

    private final AttendanceRuleEngine ruleEngine;
    private final AttendanceDailySummaryRepository summaryRepo;
    private final WeComService weComService;
    private final MessageService messageService;

    /**
     * 每天 23:30 生成日考勤汇总
     */
    @Scheduled(cron = "0 30 23 * * ?")
    public void generateDailySummary() {
        LocalDate today = LocalDate.now();
        List<String> allUserIds = weComService.getAllUserIds();

        int success = 0, fail = 0;
        for (String userId : allUserIds) {
            try {
                AttendanceDailySummary summary = ruleEngine.summarize(userId, today);
                summaryRepo.upsert(summary);
                success++;
            } catch (Exception e) {
                log.error("生成汇总失败: userId={}", userId, e);
                fail++;
            }
        }
        log.info("日考勤汇总完成: 日期={}, 成功={}, 失败={}", today, success, fail);
    }

    /**
     * 工作日早上 8:50 发送上班打卡提醒
     */
    @Scheduled(cron = "0 50 8 * * MON-FRI")
    public void remindClockIn() {
        LocalDate today = LocalDate.now();
        if (HolidayUtil.isHoliday(today)) return;

        List<String> userIds = weComService.getAllUserIds();
        for (String userId : userIds) {
            messageService.sendTextMessage(userId,
                "早上好！请在 9:00 前完成上班打卡。");
        }
        log.info("上班打卡提醒已发送: 用户数={}", userIds.size());
    }

    /**
     * 工作日 18:00 发送下班打卡提醒
     */
    @Scheduled(cron = "0 0 18 * * MON-FRI")
    public void remindClockOut() {
        LocalDate today = LocalDate.now();
        if (HolidayUtil.isHoliday(today)) return;

        List<String> userIds = weComService.getAllUserIds();
        for (String userId : userIds) {
            messageService.sendTextMessage(userId,
                "下班时间到了，别忘了打卡下班哦！");
        }
    }

    /**
     * 每月 1 号 00:30 生成月度统计
     */
    @Scheduled(cron = "0 30 0 1 * ?")
    public void generateMonthlyReport() {
        YearMonth lastMonth = YearMonth.now().minusMonths(1);
        // 统计上月数据，生成月报...
        log.info("月度考勤报表已生成: {}", lastMonth);
    }
}

@Service
@RequiredArgsConstructor
public class MessageService {

    private final WeComService weComService;
    private final WeComConfig config;

    /**
     * 发送文本消息
     */
    public void sendTextMessage(String userId, String content) {
        String token = weComService.getAccessToken();
        String url = String.format(
            "%s/cgi-bin/message/send?access_token=%s",
            weComService.getApiBase(), token
        );

        Map<String, Object> body = Map.of(
            "touser", userId,
            "msgtype", "text",
            "agentid", config.getAgentId(),
            "text", Map.of("content", content)
        );

        restClient.post().uri(url).body(body).retrieve().toBodilessEntity();
    }

    /**
     * 发送打卡结果卡片消息（模板卡片）
     */
    public void sendClockResultCard(String userId, ClockResponse result) {
        String token = weComService.getAccessToken();
        String url = String.format(
            "%s/cgi-bin/message/send?access_token=%s",
            weComService.getApiBase(), token
        );

        String statusText = result.isLate() ? "迟到 " + result.getLateMinutes() + "分钟"
            : result.isEarlyLeave() ? "早退 " + result.getEarlyMinutes() + "分钟"
            : "正常";

        Map<String, Object> body = Map.of(
            "touser", userId,
            "msgtype", "template_card",
            "agentid", config.getAgentId(),
            "template_card", Map.of(
                "card_type", "text_notice",
                "main_title", Map.of("title", "打卡结果"),
                "sub_title_text", statusText,
                "card_image", Map.of(
                    "url", config.getLogoUrl(),
                    "aspect_ratio", "2.25:1"
                ),
                "card_action", Map.of(
                    "type", 1,
                    "url", config.getFrontendUrl() + "/#/report"
                )
            )
        );

        restClient.post().uri(url).body(body).retrieve().toBodilessEntity();
    }
}