기업위챗 앱 개발 완전 가이드: 기존 근태 + Activiti 결재 시스템을 H5로 연동하는 실전

/**
 * WeCom H5 자동 로그인
 *
 * @author cuckoom
 */
@RestController
@RequestMapping("/api/auth/wecom")
@Slf4j
public class WecomAuthController {

    @Resource
    private WecomAuthService wecomAuthService;

    /**
     * H5 OAuth 무소음 로그인: code로 userid를 교환하고 시스템 계정에 바인딩한 후 JWT 발급
     */
    @PostMapping("/login")
    public Result<WecomLoginVO> login(@RequestBody @Valid WecomLoginDTO dto) {
        log.info("WeCom H5 자동 로그인, code={}", dto.getCode());
        WecomLoginVO vo = wecomAuthService.loginByCode(dto.getCode());
        return Result.success(vo);
    }
}

/**
 * WeCom 자동 로그인 Service
 *
 * @author cuckoom
 */
@Service
@Slf4j
public class WecomAuthService {

    @Resource
    private WecomTokenManager tokenManager;
    @Resource
    private RestTemplate restTemplate;
    @Resource
    private SysUserService userService;
    @Resource
    private JwtTokenProvider jwtTokenProvider;

    public WecomLoginVO loginByCode(String code) {
        // 1. code → userid 교환
        String accessToken = tokenManager.getAccessToken();
        String url = String.format(
                "https://qyapi.weixin.qq.com/cgi-bin/auth/getuserinfo?access_token=%s&code=%s",
                accessToken, code);

        JSONObject resp = restTemplate.getForObject(url, JSONObject.class);
        if (resp == null || resp.getIntValue("errcode") != 0) {
            throw new BusinessException(ErrorCode.WECOM_AUTH_FAILED,
                    "WeCom 신원 획득 실패: " + (resp == null ? "null" : resp.getString("errmsg")));
        }

        String wecomUserId = resp.getString("userid");
        if (StrUtil.isBlank(wecomUserId)) {
            // openid만 있는 경우: 기업 내부 멤버가 아니고 앱 공개 범위 밖
            throw new BusinessException(ErrorCode.WECOM_USER_NOT_IN_SCOPE,
                    "현재 계정은 앱 인가 범위 밖입니다. 관리자에게 문의하세요");
        }

        // 2. userid를 시스템 계정에 매핑(핵심, 4.6 참고)
        SysUser user = userService.getOrBindByWecomUserId(wecomUserId);
        if (user.getStatus() != null && user.getStatus() == 0) {
            throw new BusinessException(ErrorCode.ACCOUNT_DISABLED, "계정이 비활성화되었습니다");
        }

        // 3. 시스템 자체 JWT 발급, 기존 인증 체계 재사용
        String jwt = jwtTokenProvider.generateToken(user.getId(), user.getUsername());
        return WecomLoginVO.builder()
                .token(jwt)
                .userInfo(UserInfoVO.of(user))
                .build();
    }
}

/**
 * WeCom userid로 시스템 계정 바인딩
 * 약속: WeCom userid는 시스템 사번(username)과 일치
 */
public SysUser getOrBindByWecomUserId(String wecomUserId) {
    // 1. 먼저 바인딩된 wecom_user_id로 조회
    SysUser user = userMapper.findByWecomUserId(wecomUserId);
    if (user != null) {
        return user;
    }

    // 2. 미바인딩: 사번(username)으로 기존 계정 자동 매칭 시도
    user = userMapper.findByUsername(wecomUserId);
    if (user != null) {
        // 바인딩 관계를 생성하여 다음 번에 바로 적중
        user.setWecomUserId(wecomUserId);
        userMapper.updateById(user);
        log.info("시스템 계정 {}이(가) WeCom userid {}에 자동 바인딩됨", user.getUsername(), wecomUserId);
        return user;
    }

    // 3. 여전히 매칭되지 않음: 조용히 계정을 만들지 말고 바인딩 안내가 필요한 상태를 반환,
    //    관리자 또는 셀프 바인딩 프로세스가 처리
    throw new BusinessException(ErrorCode.WECOM_ACCOUNT_NOT_BOUND,
            "WeCom 계정과 연결된 시스템 계정을 찾을 수 없습니다. 관리자에게 바인딩을 문의하세요");
}

/**
 * Spring Security 보안 설정
 *
 * @author cuckoom
 */
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(
                        "/api/auth/wecom/**",      // WeCom 자동 로그인
                        "/api/wecom/callback/**"   // WeCom 콜백
                ).permitAll()
                .anyRequest().authenticated()
            )
            // 프런트/백엔드 분리 + JWT: 무상태, CSRF 비활성화, JWT 필터가 토큰을 해석
            .csrf(AbstractHttpConfigurer::disable)
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .addFilterBefore(jwtAuthenticationFilter(),
                    UsernamePasswordAuthenticationFilter.class);
        return http.build();
    }
    // JwtAuthenticationFilter: Authorization 헤더를 해석하고 SecurityContext에 기록, 기존 구현을 재사용
}

/**
 * JS-SDK 서명 Service
 *
 * @author cuckoom
 */
@Service
public class WecomJsapiService {

    @Resource
    private WecomTokenManager tokenManager;
    @Resource
    private RestTemplate restTemplate;
    @Resource
    private StringRedisTemplate redisTemplate;

    private static final String JSAPI_TICKET_KEY = "wecom:jsapi_ticket";

    /** jsapi_ticket 획득(캐시, 로직은 access_token과 동일, 분산 락은 생략, 8.1 참고) */
    public String getJsapiTicket() {
        String cached = redisTemplate.opsForValue().get(JSAPI_TICKET_KEY);
        if (StrUtil.isNotBlank(cached)) {
            return cached;
        }
        String token = tokenManager.getAccessToken();
        String url = "https://qyapi.weixin.qq.com/cgi-bin/get_jsapi_ticket?access_token=" + token;
        JSONObject resp = restTemplate.getForObject(url, JSONObject.class);
        if (resp == null || resp.getIntValue("errcode") != 0) {
            throw new BusinessException(ErrorCode.WECOM_API_ERROR, "jsapi_ticket 획득 실패");
        }
        String ticket = resp.getString("ticket");
        redisTemplate.opsForValue().set(JSAPI_TICKET_KEY, ticket, 7100, TimeUnit.SECONDS);
        return ticket;
    }

    /**
     * wx.config에 필요한 서명 생성
     * @param pageUrl 프런트엔드가 전달한 서명용 페이지 URL(iOS 특수 처리는 5.3 참고)
     */
    public WxConfigSignatureVO buildConfigSignature(String pageUrl) {
        String ticket = getJsapiTicket();
        String nonceStr = IdUtil.fastSimpleUUID();
        String timestamp = String.valueOf(System.currentTimeMillis() / 1000);

        // 주의: 서명에 참여하는 url은 프런트엔드 location.href와 완전히 일치해야 함(hash 처리 규칙은 아래 참고)
        String raw = String.format(
                "jsapi_ticket=%s&noncestr=%s&timestamp=%s&url=%s",
                ticket, nonceStr, timestamp, pageUrl);
        String signature = SecureUtil.sha1(raw);

        return WxConfigSignatureVO.builder()
                .corpId(tokenManager.getCorpId())
                .agentId(tokenManager.getAgentId())
                .nonceStr(nonceStr)
                .timestamp(timestamp)
                .signature(signature)
                .build();
    }
}

@RestController
@RequestMapping("/api/wecom/jssdk")
public class WecomJsdkController {

    @Resource
    private WecomJsapiService jsapiService;

    /** 프런트엔드가 페이지 진입 후 현재 URL로 서명을 교환 */
    @GetMapping("/config")
    public Result<WxConfigSignatureVO> config(@RequestParam("url") String url) {
        return Result.success(jsapiService.buildConfigSignature(url));
    }
}

/**
 * 모바일 결재 Service(Activiti TaskService 재사용)
 *
 * @author cuckoom
 */
@Service
public class MobileApprovalService {

    @Resource
    private TaskService taskService;
    @Resource
    private HistoryService historyService;
    @Resource
    private RepositoryService repositoryService;

    /** 현재 사용자의 대기 태스크(직접 지정 + 또는결재 후보, 미수령 포함) */
    public List<TodoVO> listMyTodo(String username) {
        List<Task> owned = taskService.createTaskQuery()
                .taskAssignee(username)
                .active()
                .orderByTaskCreateTime().desc()
                .list();

        List<Task> candidate = taskService.createTaskQuery()
                .taskCandidateUser(username)
                .active()
                .list();

        return Stream.concat(owned.stream(), candidate.stream())
                .distinct()
                .map(this::toTodoVO)
                .collect(Collectors.toList());
    }

    private TodoVO toTodoVO(Task task) {
        Map<String, Object> vars = taskService.getVariables(task.getId());
        BpmnModel model = repositoryService.getBpmnModel(task.getProcessDefinitionId());
        String nodeType = readNodeType(model, task.getTaskDefinitionKey()); // COUNTERSIGN/ORSIGN/NORMAL

        return TodoVO.builder()
                .taskId(task.getId())
                .processInstanceId(task.getProcessInstanceId())
                .title(String.valueOf(vars.getOrDefault("title", task.getName())))
                .nodeName(task.getName())
                .nodeType(nodeType)
                .applyUserName(String.valueOf(vars.get("applyUserName")))
                .createTime(task.getCreateTime())
                .candidate(Objects.isNull(task.getAssignee()))  // 또는결재 미수령
                .build();
    }
}

/** 회람 진행 상황: 과거 작업 + 현재 작업에서 각 처리자의 상태를 집계 */
public List<ApproverProgressVO> countersignProgress(String processInstanceId) {
    List<HistoricTaskInstance> done = historyService.createHistoricTaskInstanceQuery()
            .processInstanceId(processInstanceId)
            .finished()
            .list();
    List<Task> pending = taskService.createTaskQuery()
            .processInstanceId(processInstanceId)
            .list();
    // 병합: done에는 결재 의견(COMMENT)이 포함되고, pending은 "결재 대기"로 표시
    // 조립은 생략, [{user, userName, status: APPROVED/REJECTED/PENDING, comment, time}] 반환
    return mergeProgress(done, pending);
}

@Transactional(rollbackFor = Exception.class)
public void approve(String taskId, String username, boolean agree, String comment) {
    Task task = taskService.createTaskQuery().taskId(taskId).active().singleResult();
    if (task == null) {
        throw new BusinessException(ErrorCode.TASK_NOT_FOUND, "대기 태스크가 존재하지 않거나 이미 처리되었습니다");
    }

    // 또는결재: 후보자 작업은 먼저 수령
    if (task.getAssignee() == null) {
        boolean isCandidate = taskService.createTaskQuery()
                .taskId(taskId).taskCandidateUser(username).count() > 0;
        if (!isCandidate) {
            throw new BusinessException(ErrorCode.NO_PERMISSION, "이 작업을 처리할 권한이 없습니다");
        }
        taskService.claim(taskId, username);
    } else if (!username.equals(task.getAssignee())) {
        throw new BusinessException(ErrorCode.NO_PERMISSION, "이 작업은 귀하에게 속하지 않습니다");
    }

    // 결재 의견 기록
    Authentication.setAuthenticatedUserId(username);
    taskService.addComment(taskId, task.getProcessInstanceId(),
            (agree ? "동의: " : "반려: ") + comment);

    // 흐름 변수 기록: 회람 완료 조건이 approveResultList에 의존
    Map<String, Object> vars = new HashMap<>();
    if (isCountersign(task)) {
        @SuppressWarnings("unchecked")
        List<String> results = (List<String>) taskService.getVariable(taskId, "approveResultList");
        if (results == null) results = new ArrayList<>();
        results.add(agree ? "APPROVE" : "REJECT");
        vars.put("approveResultList", results);
    }
    vars.put("approved", agree);

    taskService.complete(taskId, vars);

    // 결재 후 처리: 다음 노드 대기 태스크 푸시, 흐름 종료 시 근태 연동(6.5, 6.6 참고)
    afterTaskComplete(task.getProcessInstanceId(), agree);
}

public void afterProcessFinished(String processInstanceId) {
    // 흐름 종료 후 흐름 인스턴스 변수는 히스토리 테이블로 이관되므로 HistoricVariableInstance에서 비즈니스 변수를 가져옴
    Map<String, Object> vars = historyService.createHistoricVariableInstanceQuery()
            .processInstanceId(processInstanceId)
            .list()
            .stream()
            .collect(Collectors.toMap(HistoricVariableInstance::getVariableName,
                    HistoricVariableInstance::getValue, (a, b) -> a));
    String bizType = String.valueOf(vars.get("bizType"));     // MAKEUP / LEAVE / OVERTIME
    Boolean approved = (Boolean) vars.get("approved");

    if (!Boolean.TRUE.equals(approved)) {
        notifyApplicant(processInstanceId, false);   // 반려 통지
        return;
    }

    switch (bizType) {
        case "MAKEUP":
            // 근태 보정 통과: 해당 날짜의 체크인 기록을 수정/보완 등록(기존 근태 Service)
            attendanceService.applyMakeupCard(
                (Long) vars.get("recordId"),
                (String) vars.get("makeupTime"),
                String.valueOf(vars.get("reason")));
            break;
        case "LEAVE":
            // 휴가 통과: 휴가 기록, 휴가 잔여 일수 차감
            leaveService.grantLeave(vars);
            break;
        default:
            break;
    }
    notifyApplicant(processInstanceId, true);
}

import org.activiti.engine.delegate.event.ActivitiEntityEvent;
import org.activiti.engine.delegate.event.ActivitiEvent;
import org.activiti.engine.delegate.event.ActivitiEventListener;
import org.activiti.engine.delegate.event.ActivitiEventType;

/**
 * Activiti 흐름 종료 리스너: 결재가 최종 종료된 뒤 근태와 연동
 * RuntimeService.addEventListener(...) 또는 ProcessEngineConfiguration으로 등록
 */
@Component
public class ApprovalProcessListener implements ActivitiEventListener {

    @Resource
    private ApprovalFlowService approvalFlowService;

    @Override
    public void onEvent(ActivitiEvent event) {
        if (event.getType() == ActivitiEventType.PROCESS_COMPLETED) {
            approvalFlowService.afterProcessFinished(event.getProcessInstanceId());
        }
    }

    @Override
    public boolean isFailOnException() {
        return false;   // 리스너 예외가 흐름 자체에 영향을 주지 않음
    }
}

import org.activiti.engine.delegate.event.ActivitiEntityEvent;
import org.activiti.engine.delegate.event.ActivitiEventListener;
import org.activiti.engine.delegate.event.ActivitiEventType;
import org.activiti.engine.impl.persistence.entity.TaskEntity;
import org.activiti.engine.task.IdentityLink;

@Component
public class WecomTodoPushListener implements ActivitiEventListener {

    @Resource private WecomMessageService wecomMessageService;
    @Resource private SysUserMapper userMapper;
    @Resource private TaskService taskService;

    @Override
    public void onEvent(org.activiti.engine.delegate.event.ActivitiEvent event) {
        if (event.getType() != ActivitiEventType.TASK_CREATED) return;
        TaskEntity task = (TaskEntity) ((ActivitiEntityEvent) event).getEntity();

        // 직접 지정(회람은 각자에게 작업 하나씩) → assignee에게 푸시
        if (StrUtil.isNotBlank(task.getAssignee())) {
            pushToUser(task, task.getAssignee());
        } else {
            // 또는결재 후보 작업 → 모든 후보자/후보 그룹을 펼친 멤버에게 푸시하고, 진입 후 선착순으로 수령
            for (IdentityLink link : taskService.getIdentityLinksForTask(task.getId())) {
                if (StrUtil.isNotBlank(link.getUserId())) {
                    pushToUser(task, link.getUserId());
                } else if (StrUtil.isNotBlank(link.getGroupId())) {
                    // 후보 그룹: 그룹으로 멤버 username을 조회한 뒤 하나씩 푸시(구현 생략)
                    userMapper.findUsernamesByGroup(link.getGroupId())
                            .forEach(username -> pushToUser(task, username));
                }
            }
        }
    }

    private void pushToUser(TaskEntity task, String username) {
        SysUser u = userMapper.findByUsername(username);
        if (u == null || StrUtil.isBlank(u.getWecomUserId())) {
            log.warn("사용자 {}가 기업위챗에 바인딩되지 않아 대기 태스크 푸시를 건너뜁니다", username);
            return;
        }
        wecomMessageService.sendApprovalTodoCard(u.getWecomUserId(), task);
    }

    @Override
    public boolean isFailOnException() {
        return false;   // 푸시 실패가 Activiti 작업 생성을 롤백해서는 안 됨
    }
}

@Service
@Slf4j
public class WecomMessageService {

    @Resource private WecomTokenManager tokenManager;
    @Resource private RestTemplate restTemplate;
    @Value("${wecom.agentid}") private Integer agentId;

    /** 결재 대기 카드 발송, 탭하면 H5 결재 상세로 이동 */
    public void sendApprovalTodoCard(String wecomUserId, Task task) {
        Map<String, Object> card = new HashMap<>();
        card.put("title", "결재 대기: " + task.getName());
        card.put("description", "새로운 결재 대기 태스크가 하나 있어 처리가 필요합니다");
        card.put("btntxt", "지금 결재");
        card.put("url", "https://attendance.yourcompany.com/mobile/approval/" + task.getId());

        Map<String, Object> msg = new HashMap<>();
        msg.put("touser", wecomUserId);
        msg.put("msgtype", "textcard");
        msg.put("agentid", agentId);
        msg.put("textcard", card);
        msg.put("duplicate_check_interval", 1800);

        send(msg);
    }

    public void send(String msg) { /* message/send로 POST, invaliduser/errcode 기록 */ }
}

@RestController
@RequestMapping("/api/wecom/callback")
@Slf4j
public class WecomCallbackController {

    @Resource private WecomCallbackService callbackService;

    /** URL 검증 */
    @GetMapping("/message")
    public String verify(@RequestParam("msg_signature") String signature,
                         @RequestParam String timestamp,
                         @RequestParam String nonce,
                         @RequestParam String echostr) {
        try {
            return callbackService.verifyUrl(signature, timestamp, nonce, echostr);
        } catch (Exception e) {
            log.error("기업위챗 콜백 URL 검증 실패", e);
            return "";
        }
    }

    /** 이벤트 수신: 반드시 빠르게 success를 반환하고, 오래 걸리는 처리는 비동기로 두어 기업위챗 재시도를 방지 */
    @PostMapping(value = "/message", produces = "application/xml")
    public String receive(@RequestParam("msg_signature") String signature,
                          @RequestParam String timestamp,
                          @RequestParam String nonce,
                          @RequestBody String encryptedBody) {
        try {
            callbackService.handleAsync(signature, timestamp, nonce, encryptedBody);
        } catch (Exception e) {
            log.error("기업위챗 콜백 처리 실패", e);
        }
        return "success";   // 비즈니스 성패와 무관하게 먼저 success를 반환해 지수 백오프 재시도를 방지
    }
}

@Service
@Slf4j
public class WecomCallbackService {

    @Resource private MobileApprovalService approvalService;
    @Resource private ContactSyncService contactSyncService;
    @Resource private WXBizMsgCrypt crypt;   // 공식 암호화/복호화 클래스

    /** 복호화 후 이벤트 유형에 따라 분기 */
    public void handle(String sig, String ts, String nonce, String body) throws Exception {
        String xml = crypt.DecryptMsg(sig, ts, nonce, body);
        // XStream/Digester로 XML을 파싱하여 Event / ChangeType / TaskId / EventKey / FromUserName 추출
        CallbackEvent event = CallbackEvent.parse(xml);

        switch (event.getEvent()) {
            case "template_card_event":
                // 템플릿 카드 버튼: EventKey가 버튼 key, FromUserName이 탭한 사람의 userid
                onCardButton(event);
                break;
            case "change_contact":
                contactSyncService.handleChange(event.getChangeType(), event.getUserId());
                break;
            default:
                log.info("처리하지 않는 기업위챗 이벤트: {}", xml);
        }
    }

    private void onCardButton(CallbackEvent e) {
        boolean agree = "approve".equals(e.getEventKey());
        String username = contactSyncService.wecomUserIdToUsername(e.getFromUserName());
        // task_id는 카드 발송 시 우리가 생성해 Activiti taskId와 연결해 두고, Redis/DB에 저장했다 가져옴
        String taskId = taskCardMapping.get(e.getTaskId());
        approvalService.approve(taskId, username, agree, agree ? "동의" : "반려");
        // update_template_card를 호출해 원래 카드를 "동의됨/반려됨"으로 갱신해 중복 탭을 방지할 수 있음
    }
}

@Component
@Slf4j
public class WecomTokenManager {

    private static final String TOKEN_KEY = "wecom:access_token";
    private static final String LOCK_KEY  = "wecom:access_token:lock";
    private static final long EXPIRE_SECONDS = 7100;   // 7200보다 100초 여유를 둠

    @Value("${wecom.corpid}") private String corpId;
    @Value("${wecom.secret}") private String secret;
    @Resource private StringRedisTemplate redis;
    @Resource private RestTemplate restTemplate;

    public String getAccessToken() {
        String cached = redis.opsForValue().get(TOKEN_KEY);
        if (StrUtil.isNotBlank(cached)) return cached;

        Boolean locked = redis.opsForValue().setIfAbsent(LOCK_KEY, "1", 10, TimeUnit.SECONDS);
        if (Boolean.FALSE.equals(locked)) return waitForToken();   // 다른 인스턴스가 갱신하기를 기다림

        try {
            String again = redis.opsForValue().get(TOKEN_KEY);      // 이중 확인
            if (StrUtil.isNotBlank(again)) return again;
            return refresh();
        } finally {
            redis.delete(LOCK_KEY);
        }
    }

    private String refresh() {
        String url = String.format(
            "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=%s&corpsecret=%s", corpId, secret);
        JSONObject resp = restTemplate.getForObject(url, JSONObject.class);
        if (resp == null || resp.getIntValue("errcode") != 0) {
            throw new BusinessException(ErrorCode.WECOM_API_ERROR, "access_token 획득 실패");
        }
        String token = resp.getString("access_token");
        redis.opsForValue().set(TOKEN_KEY, token, EXPIRE_SECONDS, TimeUnit.SECONDS);
        return token;
    }

    private String waitForToken() {
        for (int i = 0; i < 10; i++) {
            sleep(200);
            String t = redis.opsForValue().get(TOKEN_KEY);
            if (StrUtil.isNotBlank(t)) return t;
        }
        throw new BusinessException(ErrorCode.WECOM_API_ERROR, "access_token 획득 타임아웃");
    }

    public String getCorpId() { return corpId; }
}

@Service
public class ContactSyncService {

    /** 전량 동기화(매일 새벽 폴백) */
    public void syncAll() {
        String token = tokenManager.getAccessToken();
        // 1. 부서 트리 department/list
        // 2. 말단 부서를 순회하며 user/list?fetch_child=1로 멤버를 가져옴
        // 3. 사번으로 sys_user.username에 맞추고, wecom_user_id, 부서, 이름, 휴대폰, 상태를 채워 넣음
        // 4. 기업위챗 status=5(퇴사)/멤버 삭제 이벤트 → 시스템 계정을 비활성화
    }

    /** 증분 이벤트(실시간) */
    public void handleChange(String changeType, String wecomUserId) {
        switch (changeType) {
            case "create_user": case "update_user": upsertOne(wecomUserId); break;
            case "delete_user": disableByWecomUserId(wecomUserId); break;
            // 부서 변경은 부서 테이블로 동기화하여 orgService.findLeader 조직 라우팅에 사용
            default: break;
        }
    }

    public String wecomUserIdToUsername(String wecomUserId) {
        return userMapper.findUsernameByWecomId(wecomUserId);
    }
}