---
name: ecs-attend-requirements
overview: 为 ECS 电子班牌模块生成「考勤管理」功能的需求规格说明书，包含字段定义、VO结构、字典项、建表DDL等完整规格。
todos:
  - id: generate-attend-requirements
    content: 使用 [skill:require] 生成 ECS 考勤模块完整需求规格说明书到 doc/ecs-attend-requirements.md
    status: completed
---

## 产品概述

ECS 电子班牌系统考勤管理模块，用于记录和管理学员的刷卡/人脸识别考勤数据，支持考勤记录查询、详情查看、手工补录和 Excel 导出功能。

## 核心功能

### 数据结构（14个业务字段）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| attendId | Long | 考勤ID（主键） |
| userId | Long | 学员ID |
| userNumb | String | 学号 |
| realName | String | 学员姓名 |
| classId | Long | 班级ID |
| className | String | 班级名称 |
| roomId | Long | 教室ID |
| roomName | String | 教室名称 |
| checkTime | LocalDateTime | 考勤时间 |
| checkType | Integer | 考勤方式：0-刷卡 1-人脸（字典 check_type） |
| uploadTime | LocalDateTime | 上传时间 |
| pushStatus | Integer | 推送状态：0-未推送 1-成功 2-失败（字典 push_status） |
| pushTime | LocalDateTime | 推送时间 |
| pushRetry | Integer | 推送尝试次数 |


### 列表显示字段（8列）

班级名称、学员姓名、学号、教室名称、考勤时间、上传时间、推送状态、推送时间

### 查询条件（3项）

学员姓名（模糊）、班级名称（精确）、推送状态（字典下拉）

### 业务操作

- **导出**：Excel 导出考勤数据
- **查看**：考勤记录详情
- **手工考勤**：新增手工录入的考勤记录

### 约束条件

- 无编辑/删除接口（考勤记录生成后不可修改）
- 多租户隔离
- 数据库类型：kingbase（人大金仓）

## 技术方案

基于 require 技能的需求规格说明书模板，参照 `doc/ecs-course-requirements.md` 已有文档格式，生成 ECS 考勤模块的需求规格说明书。

## 实现方式

按照 require 技能的工作流程执行：

1. **解析需求**：从用户 JSON 数据结构和业务描述中提取全部字段及属性
2. **字段推断**：按技能规则推断每个字段的 inTable/inQuery/inForm/dictType/component 等属性
3. **模板填充**：生成完整的9章节需求规格说明书 Markdown 文档
4. **DDL 生成**：根据 kingbase 方言生成建表 SQL 语句

## 关键设计决策

1. **className/userNumb/roomName 为 VO 承载字段（inDb=false）**：这些是关联实体的名称冗余字段，实际存储在表中但由关联 ID 字段决定。根据用户给出的数据结构，这些字段直接存在于数据中（可能是设备上报时由系统填充），所以 `inDb=true`。
2. **userId/classId/roomId 不在列表显示但在表单中使用**：作为隐藏关联字段存在。
3. **无编辑/删除**：接口清单仅保留 list/query/add/export 三类操作接口。
4. **checkType/pushStatus 使用字典组件**：分别对应 `check_type` 和 `push_status` 字典。
5. **手工考勤 = 新增接口**：通过 POST /attend/ 实现，表单中选择学员、教室、考勤方式等。

## Agent Extensions

### Skill

- **require**
- Purpose: 根据需求模板和字段解析规则，生成结构化的需求规格说明书 Markdown 文档
- Expected outcome: 在 `doc/ecs-attend-requirements.md` 产出完整的9章节需求规格说明书，包含基础信息、接口清单、字段清单（YAML）、VO 结构、特殊需求、字典项、Kingbase DDL 建表语句、备注