# ninca-crk-smart-attendance-common/ — 智能考勤公共模块

**Generated:** 2026-05-01
**Commit:** 376f94e
**Branch:** release/cw-elevator-v1-lib-min-risk

## OVERVIEW

智能考勤四条业务线中**最复杂的 common 模块**（207 `.java`）。承载考勤规则 DTO、排班/班次/节假日数据模型、报表结构、工具类。CFR 反编译产物，走查用。

## STRUCTURE

```
src/main/java/cn/cloudwalk/common/ninca/attendance/
├── bean/
│   ├── rule/         # ★ 44 个 AttendRule*DTO（规则核心数据契约）
│   ├── config/       # 班次/排班/设备配置 DTO
│   ├── report/       # 报表 DTO（日报/月报/转换）
│   └── result/       # 考勤结果 DTO
├── util/             # CollectionUtils, ExcelUtil, StringUtils（与三套 *-common 重复）
├── em/               # 枚举
└── config/           # AttendLockConstants, DeviceConstants
```

## WHERE TO LOOK

| Task | Location | Notes |
|------|----------|-------|
| 考勤规则 CRUD DTO | `bean/rule/AttendRule*DTO.java` | 44 个类，Add/Query/Delete/Result 四类模式 |
| 排班 DTO | `bean/config/dto/` | 37 个类 |
| 班次 DTO | `bean/config/clas/dto/` | 43 个类 |
| 报表模型 | `bean/report/` | 28 个类 |
| 工具类 | `util/CollectionUtils.java` | `split(List, int...)` 泛型已修正 |

## CONVENTIONS

- DTO 命名：`Attend<Domain><Operation>DTO`（如 `AttendRuleSchedulingQueryDTO`）
- 四套 `CollectionUtils` / `ExcelUtil` / `StringUtils` 按业务线分别拷贝（非共享模块）

## ANTI-PATTERNS (THIS MODULE)

- **不要**尝试 `mvn compile` 完整工程（CFR产物，依赖未全）
- **不要**修改 DTO 字段名而不对应 `*-interface` / `*-service` 中的使用方
- CFR 头注释 `Could not load the following classes` 属正常，不影响走查

## NOTES

- 泛型修正：`CollectionUtils.split` 已从 CFR 误生成的 `ArrayList<List<ArrayList<E>>>` 修正为 `ArrayList<List<E>>`
- 与 `ninca-crk-smart-attendance-service` 的规则服务实现（21 个 `*ServiceImpl`）配套走查
- 参见根 `AGENTS.md` 了解全仓 Maven/编译约束