# AuroraContainerLog

AuroraContainerLog 是一个面向 Spigot 1.12.2 的箱子容器日志插件，用于记录指定世界内玩家对箱子类容器的物品放入和取出行为，适合地皮服排查箱子物品被盗问题。

当前插件版本：`1.1.5`

## 1. 功能概览

- 支持指定世界监听箱子容器。
- 支持普通箱子、陷阱箱、大箱子记录与查询。
- 支持记录玩家名称和 UUID。
- 支持记录容器坐标：`world/x/y/z`。
- 支持记录动作：`TAKE`、`PUT`。
- 支持记录物品类型、数量、展示名、lore、附魔和完整 ItemStack Base64。
- 支持 SQLite 存储。
- 支持自动清理超过指定保留天数的历史数据。
- 支持按玩家、指定箱子、附近范围分页查询。
- 数据库写入和查询通过异步队列执行，避免阻塞主线程。

## 2. 运行环境

```text
Java: 8
服务端: Spigot 1.12.2
构建工具: Maven
数据库: SQLite
```

运行依赖：

```text
HikariCP
sqlite-jdbc
```

插件 JAR 不内置 `HikariCP` 和 `sqlite-jdbc`。运行环境必须通过服务端公共依赖、启动 classpath、依赖插件或统一依赖加载方案提供这两个依赖。

## 3. 安装方式

构建插件：

```bash
mvn package
```

构建完成后，将生成的插件包放入服务端：

```text
plugins/AuroraContainerLog-1.1.5.jar
```

启动服务端后，插件会生成默认配置文件：

```text
plugins/AuroraContainerLog/config.yml
```

## 4. 配置文件

默认配置：

```yml
listen-worlds:
  - world

query:
  page-size: 8
  chest-recent-days: 30
  max-near-radius: 50
  default-page: 1

database:
  file: containerlog.db

cleanup:
  enabled: true
  retention-days: 60
  interval-hours: 24

message-prefix: "&8[&bACL&8] &7"
```

配置说明：

- `listen-worlds`：启用箱子日志监听的世界列表。
- `query.page-size`：每页显示的日志数量。
- `query.chest-recent-days`：`/acl chest` 默认查询最近多少天的记录。
- `query.max-near-radius`：`/acl near` 允许的最大查询半径。
- `query.default-page`：未填写页码时使用的默认页。
- `database.file`：SQLite 数据库文件名。
- `cleanup.enabled`：是否启用过期日志自动清理。
- `cleanup.retention-days`：日志保留天数，超过后自动清理。
- `cleanup.interval-hours`：自动清理执行间隔。
- `message-prefix`：命令消息前缀。

## 5. 记录内容

每条日志会记录以下字段：

```text
时间
世界
容器坐标 x/y/z
玩家名称
玩家 UUID
动作 TAKE / PUT
物品 material
物品 amount
物品 displayName
物品 lore
物品 enchantments
完整 ItemStack Base64
```

插件采用打开容器时快照、关闭容器时对比差异的方式记录变化，只记录箱子容器库存变化，不记录玩家背包自身变化。

## 6. 命令

管理命令需要权限：

```text
auroracontainerlog.admin
```

重载配置：

```text
/acl reload
```

查询指定玩家最近记录：

```text
/acl player <玩家名> [天数] [页码]
```

查询当前看着的箱子最近记录：

```text
/acl chest [页码]
```

查询附近箱子记录：

```text
/acl near <半径> [天数] [页码]
```

命令别名：

```text
/aclog
```

## 7. 权限

```text
auroracontainerlog.admin
```

默认权限：

```text
op
```

## 8. 数据库说明

当前版本仅支持 SQLite。

SQLite 使用 HikariCP 单连接池：

```text
maximumPoolSize: 1
minimumIdle: 1
connectionTimeout: 10000
validationTimeout: 3000
idleTimeout: 600000
maxLifetime: 1700000
```

连接池大小固定为 1，避免 SQLite 多连接写入导致数据库锁竞争。

## 9. 自动清理规则

插件启动后会排队执行一次过期数据清理，之后按 `cleanup.interval-hours` 周期执行。

默认规则：

```text
保留最近 60 天日志
每 24 小时清理一次
```

清理操作进入数据库异步执行队列，不在主线程直接执行 SQL。

## 10. 查询行为

- `/acl chest` 会查询玩家准星指向的箱子。
- 大箱子查询会同时匹配相邻两侧箱子坐标。
- 玩家执行查询时，结果支持点击传送到记录坐标。
- 控制台查询会显示完整坐标文本。
- 查询结果按时间倒序分页显示。

## 11. 使用流程

1. 确认服务端运行环境已提供 `HikariCP` 和 `sqlite-jdbc`。
2. 将插件 JAR 放入服务端 `plugins` 目录。
3. 启动服务端生成默认配置。
4. 修改 `listen-worlds`，填入需要监听的世界。
5. 按需调整分页、自动清理和数据库文件配置。
6. 执行 `/acl reload` 重载配置。
7. 使用 `/acl chest`、`/acl player`、`/acl near` 查询日志。

## 12. 注意事项

- 插件包不包含 `sqlite-jdbc` 和 `HikariCP`，缺少运行依赖会导致 SQLite 连接池初始化失败。
- 修改监听世界后，只影响后续容器操作记录，不会修改历史数据。
- 关闭容器时只记录最终净变化，不记录打开期间每一次中间点击动作。
- 若玩家取出物品后又在关闭前放回相同数量，最终差异为 0，不会写入日志。
- 发布新版本前应确认 `plugin.yml` 中版本号已递增。
- 上线前建议在测试服验证普通点击、shift-click、数字键、拖拽、大箱子和未监听世界场景。