初始化项目

README.md

@@ -0,0 +1,222 @@
+# 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、数字键、拖拽、大箱子和未监听世界场景。