# chekcin

**Repository Path**: lichaoge/chekcin

## Basic Information

- **Project Name**: chekcin
- **Description**: chekcin
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-25
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 工时打卡 (Worklog Check-in)

基于 Spring Boot 的工时打卡与负载查看系统，支持按账号、按团队查询，每日 24 小时空闲/忙碌可视化。

## 技术栈

- **后端**: Java 17、Spring Boot 2.7、Spring Data JPA、Apache Shiro
- **数据库**: H2（开发/演示）或 PostgreSQL（生产）
- **前端**: 静态 HTML / CSS / JavaScript，无构建工具

## 环境要求

- JDK 17+
- Maven 3.6+
- （可选）PostgreSQL，用于生产环境

## 快速开始

### 使用 H2 内存库（默认）

```bash
# 使用 H2 时需在 application.yml 中启用 H2 配置并注释掉 PostgreSQL 配置
mvn spring-boot:run -DskipTests
```

### 使用 PostgreSQL

1. 在 `src/main/resources/application.yml` 中配置数据源（或使用 `spring.profiles.active=pg` 的 profile）。
2. 启动：

```bash
mvn spring-boot:run -DskipTests -Dspring-boot.run.profiles=pg
```

### 访问应用

- 地址: `http://localhost:8083/worklog/`
- 默认账号: `admin`，密码: `123456`（首次启动由 `DataInitializer` 初始化）

## 功能模块

| 模块       | 说明 |
|------------|------|
| 快速打卡   | 选择日期与时间段，填写事项内容提交打卡记录；支持填写交付信息与备注 |
| 打卡列表   | 查看、筛选打卡记录列表；支持自定义列与导出；长文本（打卡事项/备注）通过“详情”行内展开查看 |
| 按账号查询 | 按用户与时间范围查询，展示每日 24 小时空闲/忙碌格子，可点击查看时间段与打卡事项 |
| 整体概览   | 按团队查看整体负载与成员负载，按检索时间范围按天展示，支持 24 小时格子和纵向/横向滚动 |
| 用户管理   | 仅管理员可见；用户列表与检索，添加/编辑/禁用/删除用户；一个用户可属于多个团队（私有云、智算、云原生、AIOps、多云、AI技术平台） |

## 打卡记录字段说明

打卡记录（`CheckInRecord`）除基础字段外，新增以下字段用于交付场景补充信息：

| 字段 | 含义 | 备注 |
|------|------|------|
| 打卡事项（`description`） | 本次打卡事项/工作内容 | 可能较长 |
| 交付/POC 触发（`pocTriggered`） | 是否为交付/POC 触发 | Yes/No（前端以选择框呈现） |
| 交付方式（`deliveryMode`） | 现场 / 远程 / 现场+远程 | 前端以选择框呈现 |
| 交付地点（`deliveryLocation`） | 交付地点 | 手工输入 |
| 备注（`remark`） | 补充说明 | 可能较长 |

## 打卡列表（列与长文本展示）

- **默认列**：列表默认**不显示**「打卡事项」「备注」，避免列过多拥挤。
- **查看长文本**：每行在“操作”列提供**详情**按钮，点击后在该行下方**行内展开**显示「打卡事项 + 备注」，支持复制。
- **自定义列**：支持在列表页选择/排序显示列，选择结果存储在浏览器 Cookie。
- **导出联动**：导出列与当前“自定义列”保持一致（自定义列里有什么字段就导出什么字段）。

## 项目结构

```
chekcin/
├── pom.xml
├── README.md
└── src/main/
    ├── java/com/xteam/worklog/
    │   ├── WorklogApplication.java      # 启动类
    │   ├── config/                      # Shiro、数据初始化等配置
    │   ├── controller/                  # 认证、打卡、查询、概览等 API
    │   ├── dto/
    │   ├── entity/                      # Team、User、CheckInRecord
    │   ├── repository/
    │   ├── security/                    # Shiro Realm
    │   └── service/
    └── resources/
        ├── application.yml              # 端口 8083，context-path: /worklog
        ├── static/
        │   ├── css/
        │   ├── html/                    # checkin, list, search, overview, login
        │   └── js/
        └── ...
```

## 配置说明

- **端口与上下文**: 默认 `server.port=8083`，`server.servlet.context-path=/worklog`。
- **Shiro**: 未认证跳转 `loginUrl`，成功跳转 `successUrl`（见 `application.yml`）。
- **数据库**: 使用 PostgreSQL 时需配置 `spring.datasource.*`；使用 H2 时可用 `jdbc:h2:mem:worklog;MODE=PostgreSQL` 等。

### 数据库迁移（用户-团队多对多）

若生产环境此前为「用户单团队」结构（`wl_user.team_id`），升级到「用户多团队」后需做一次数据迁移，否则旧用户会丢失团队关联。在**停用应用**后执行（以 PostgreSQL 为例）：

```sql
-- 1. 创建关联表并迁移数据
CREATE TABLE IF NOT EXISTS wl_user_team (user_id BIGINT NOT NULL, team_id BIGINT NOT NULL, PRIMARY KEY (user_id, team_id));
INSERT INTO wl_user_team (user_id, team_id) SELECT id, team_id FROM wl_user WHERE team_id IS NOT NULL ON CONFLICT DO NOTHING;
-- 2. 删除旧列（若仍存在）
ALTER TABLE wl_user DROP COLUMN IF EXISTS team_id;
```

然后启动新版本应用。新库或 `ddl-auto: update` 已创建 `wl_user_team` 时，仅需执行第 2 步（若存在 `team_id` 列）。

## 开发与构建

```bash
# 编译
mvn compile

# 跳过测试运行
mvn spring-boot:run -DskipTests

# 打包（生成的 jar 用于 Linux 部署）
mvn package -DskipTests
# 产物: target/worklog-0.0.1-SNAPSHOT.jar
```

## Linux 服务器部署

### 前置条件

- 服务器已安装 **JDK 17+**（`java -version` 可验证）
- 已在本机执行 `mvn package -DskipTests` 得到 `worklog-0.0.1-SNAPSHOT.jar`

### 部署步骤

1. **上传文件到服务器**
   - 将 `target/worklog-0.0.1-SNAPSHOT.jar` 和项目根目录下的 `deploy.sh` 放到同一目录（例如 `/opt/worklog` 或任意目录）。

2. **赋予执行权限并安装/启动**
   ```bash
   chmod +x deploy.sh
   ./deploy.sh install   # 创建部署目录、复制 jar（若与脚本同目录则不必复制）
   ./deploy.sh start     # 启动应用
   ```

3. **脚本命令说明**
   | 命令        | 说明 |
   |-------------|------|
   | `install`  | 创建部署目录、复制 jar 到部署目录（若需要） |
   | `start`    | 后台启动应用 |
   | `stop`     | 停止应用 |
   | `restart`  | 先停止再启动 |
   | `status`   | 查看是否在运行及 PID |

4. **默认部署目录**
   - 默认为 `/opt/worklog`。可通过环境变量修改：
   ```bash
   export OVERRIDE_DEPLOY_DIR=/home/app/worklog
   ./deploy.sh install && ./deploy.sh start
   ```

5. **日志与配置**
   - 运行日志：`<部署目录>/logs/stdout.log`
   - 若需在服务器上覆盖端口、数据源等，可将 `application.yml` 或 `application-prod.yml` 放到**部署目录**下，脚本会自动追加 `--spring.config.additional-location` 加载该配置。

### 使用 systemd 管理服务（推荐生产环境）

1. **复制示例 service 文件**

   将仓库中的 `deploy/worklog.service` 拷贝到服务器：

   ```bash
   sudo mkdir -p /opt/worklog
   # 将打好的 jar（target/worklog-0.0.1-SNAPSHOT.jar）上传到 /opt/worklog
   sudo cp deploy/worklog.service /etc/systemd/system/worklog.service
   ```

2. **按需修改 service 配置**

   编辑 `/etc/systemd/system/worklog.service`，根据实际情况修改：

   - `User` / `Group`：运行服务的 Linux 用户（例如 `worklog`）
   - `WorkingDirectory`：部署目录（例如 `/opt/worklog`）
   - `ExecStart`：jar 的完整路径，可以追加 JVM 参数或 `--spring.profiles.active=pg` 等

3. **加载并启动服务**

   ```bash
   sudo systemctl daemon-reload
   sudo systemctl enable worklog
   sudo systemctl start worklog
   sudo systemctl status worklog
   ```

4. **查看日志**

   默认日志输出到 systemd 日志中，可通过：

   ```bash
   journalctl -u worklog -f
   ```

### 访问

- 默认地址：`http://<服务器IP>:8083/worklog/`
- 若在 `application.yml` 中修改了 `server.port` 或 `server.servlet.context-path`，请按实际配置访问。

## 许可证

内部使用 / 演示项目。