From a2596d4124bb04fe14754c1c9a89ca8aea8b0015 Mon Sep 17 00:00:00 2001 From: syntaxbullet Date: Mon, 5 Jan 2026 13:13:46 +0100 Subject: [PATCH] docs: Add command reference and database schema documentation. --- docs/COMMANDS.md | 63 ++++++++++++++++++++ docs/DATABASE.md | 149 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 212 insertions(+) create mode 100644 docs/COMMANDS.md create mode 100644 docs/DATABASE.md diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md new file mode 100644 index 0000000..11eaae9 --- /dev/null +++ b/docs/COMMANDS.md @@ -0,0 +1,63 @@ +# Command Reference + +This document lists all available slash commands in Aurora, categorized by their function. + +## Economy + +| Command | Description | Options | Permissions | +|---|---|---|---| +| `/balance` | View your or another user's balance. | `user` (Optional): The user to check. | Everyone | +| `/daily` | Claim your daily currency reward and streak bonus. | None | Everyone | +| `/pay` | Transfer currency to another user. | `user` (Required): Recipient.
`amount` (Required): Amount to send. | Everyone | +| `/trade` | Start a trade session with another user. | `user` (Required): The user to trade with. | Everyone | +| `/exam` | Take your weekly exam to earn rewards based on XP gain. | None | Everyone | + +## Inventory & Items + +| Command | Description | Options | Permissions | +|---|---|---|---| +| `/inventory` | View your or another user's inventory. | `user` (Optional): The user to check. | Everyone | +| `/use` | Use an item from your inventory. | `item` (Required): The item to use (Autocomplete). | Everyone | + +## User & Social + +| Command | Description | Options | Permissions | +|---|---|---|---| +| `/profile` | View your or another user's Student ID card. | `user` (Optional): The user to view. | Everyone | +| `/leaderboard` | View top players. | `type` (Required): 'Level / XP' or 'Balance'. | Everyone | +| `/feedback` | Submit feedback, bug reports, or suggestions. | None | Everyone | +| `/quests` | View your active quests. | None | Everyone | + +## Admin + +> [!IMPORTANT] +> These commands require Administrator permissions or specific roles as configured. + +### General Management +| Command | Description | Options | +|---|---|---| +| `/config` | Manage bot configuration. | `group` (Req): Section.
`key` (Req): Setting.
`value` (Req): New value. | +| `/refresh` | Refresh commands or configuration cache. | `type`: 'Commands' or 'Config'. | +| `/update` | Update the bot from the repository. | None | +| `/features` | Enable/Disable system features. | `feature` (Req): Feature name.
`enabled` (Req): True/False. | +| `/webhook` | Send a message via webhook. | `payload` (Req): JSON payload. | + +### Moderation +| Command | Description | Options | +|---|---|---| +| `/warn` | Warn a user. | `user` (Req): Target.
`reason` (Req): Reason. | +| `/warnings` | View active warnings for a user. | `user` (Req): Target. | +| `/clearwarning`| Clear a specific warning. | `case_id` (Req): Case ID. | +| `/case` | View details of a specific moderation case. | `case_id` (Req): Case ID. | +| `/cases` | View moderation history for a user. | `user` (Req): Target. | +| `/note` | Add a note to a user. | `user` (Req): Target.
`note` (Req): Content. | +| `/notes` | View notes for a user. | `user` (Req): Target. | +| `/prune` | Bulk delete messages. | `amount` (Req): Number (1-100). | + +### Game Admin +| Command | Description | Options | +|---|---|---| +| `/create_item` | Create a new item in the database. | (Modal based interaction) | +| `/create_color`| Create a new color role. | `name` (Req): Role name.
`hex` (Req): Hex color code. | +| `/listing` | Manage shop listings (Admin view). | None (Context sensitive?) | +| `/terminal` | Control the terminal display channel. | `action`: 'setup', 'update', 'clear'. | diff --git a/docs/DATABASE.md b/docs/DATABASE.md new file mode 100644 index 0000000..f3ed4b6 --- /dev/null +++ b/docs/DATABASE.md @@ -0,0 +1,149 @@ +# Database Schema + +This document outlines the database schema for the Aurora project. The database is PostgreSQL, managed via Drizzle ORM. + +## Tables + +### Users (`users`) +Stores user data, economy, and progression. + +| Column | Type | Description | +|---|---|---| +| `id` | `bigint` | Primary Key. Discord User ID. | +| `class_id` | `bigint` | Foreign Key -> `classes.id`. | +| `username` | `varchar(255)` | User's Discord username. | +| `is_active` | `boolean` | Whether the user is active (default: true). | +| `balance` | `bigint` | User's currency balance. | +| `xp` | `bigint` | User's experience points. | +| `level` | `integer` | User's level. | +| `daily_streak` | `integer` | Current streak of daily command usage. | +| `settings` | `jsonb` | User-specific settings. | +| `created_at` | `timestamp` | Record creation time. | +| `updated_at` | `timestamp` | Last update time. | + +### Classes (`classes`) +Available character classes. + +| Column | Type | Description | +|---|---|---| +| `id` | `bigint` | Primary Key. Custom ID. | +| `name` | `varchar(255)` | Class name (Unique). | +| `balance` | `bigint` | Class bank balance (shared/flavor). | +| `role_id` | `varchar(255)` | Discord Role ID associated with the class. | + +### Items (`items`) +Definitions of items available in the game. + +| Column | Type | Description | +|---|---|---| +| `id` | `serial` | Primary Key. Auto-incrementing ID. | +| `name` | `varchar(255)` | Item name (Unique). | +| `description` | `text` | Item description. | +| `rarity` | `varchar(20)` | Common, Rare, etc. Default: 'Common'. | +| `type` | `varchar(50)` | MATERIAL, CONSUMABLE, EQUIPMENT, etc. | +| `usage_data` | `jsonb` | Effect data for consumables/usables. | +| `price` | `bigint` | Base value of the item. | +| `icon_url` | `text` | URL for the item's icon. | +| `image_url` | `text` | URL for the item's large image. | + +### Inventory (`inventory`) +Items held by users. + +| Column | Type | Description | +|---|---|---| +| `user_id` | `bigint` | PK/FK -> `users.id`. | +| `item_id` | `integer` | PK/FK -> `items.id`. | +| `quantity` | `bigint` | Amount held. Must be > 0. | + +### Transactions (`transactions`) +Currency transaction history. + +| Column | Type | Description | +|---|---|---| +| `id` | `bigserial` | Primary Key. | +| `user_id` | `bigint` | FK -> `users.id`. The user affecting the balance. | +| `related_user_id` | `bigint` | FK -> `users.id`. The other party (if any). | +| `amount` | `bigint` | Amount transferred. | +| `type` | `varchar(50)` | Transaction type identifier. | +| `description` | `text` | Human-readable description. | +| `created_at` | `timestamp` | Time of transaction. | + +### Item Transactions (`item_transactions`) +Item flow history. + +| Column | Type | Description | +|---|---|---| +| `id` | `bigserial` | Primary Key. | +| `user_id` | `bigint` | FK -> `users.id`. | +| `related_user_id` | `bigint` | FK -> `users.id`. | +| `item_id` | `integer` | FK -> `items.id`. | +| `quantity` | `bigint` | Amount gained (+) or lost (-). | +| `type` | `varchar(50)` | TRADE, SHOP_BUY, DROP, etc. | +| `description` | `text` | Description. | +| `created_at` | `timestamp` | Time of transaction. | + +### Quests (`quests`) +Quest definitions. + +| Column | Type | Description | +|---|---|---| +| `id` | `serial` | Primary Key. | +| `name` | `varchar(255)` | Quest title. | +| `description` | `text` | Quest text. | +| `trigger_event` | `varchar(50)` | Event that triggers progress checks. | +| `requirements` | `jsonb` | Completion criteria. | +| `rewards` | `jsonb` | Rewards for completion. | + +### User Quests (`user_quests`) +User progress on quests. + +| Column | Type | Description | +|---|---|---| +| `user_id` | `bigint` | PK/FK -> `users.id`. | +| `quest_id` | `integer` | PK/FK -> `quests.id`. | +| `progress` | `integer` | Current progress value. | +| `completed_at` | `timestamp` | Completion time (null if active). | + +### User Timers (`user_timers`) +Generic timers for cooldowns, temporary effects, etc. + +| Column | Type | Description | +|---|---|---| +| `user_id` | `bigint` | PK/FK -> `users.id`. | +| `type` | `varchar(50)` | PK. Timer type (COOLDOWN, EFFECT, ACCESS). | +| `key` | `varchar(100)` | PK. specific ID (e.g. 'daily'). | +| `expires_at` | `timestamp` | When the timer expires. | +| `metadata` | `jsonb` | Extra data. | + +### Lootdrops (`lootdrops`) +Active chat loot drop events. + +| Column | Type | Description | +|---|---|---| +| `message_id` | `varchar(255)` | Primary Key. Discord Message ID. | +| `channel_id` | `varchar(255)` | Discord Channel ID. | +| `reward_amount` | `integer` | Currency amount. | +| `currency` | `varchar(50)` | Currency type constant. | +| `claimed_by` | `bigint` | FK -> `users.id`. Null if unclaimed. | +| `created_at` | `timestamp` | Spawn time. | +| `expires_at` | `timestamp` | Despawn time. | + +### Moderation Cases (`moderation_cases`) +History of moderation actions. + +| Column | Type | Description | +|---|---|---| +| `id` | `bigserial` | Primary Key. | +| `case_id` | `varchar(50)` | Unique friendly ID. | +| `type` | `varchar(20)` | warn, timeout, kick, ban, etc. | +| `user_id` | `bigint` | Target user ID. | +| `username` | `varchar(255)` | Target username snapshot. | +| `moderator_id` | `bigint` | Acting moderator ID. | +| `moderator_name` | `varchar(255)` | Moderator username snapshot. | +| `reason` | `text` | Reason for action. | +| `metadata` | `jsonb` | Extra data. | +| `active` | `boolean` | Is this case active? | +| `created_at` | `timestamp` | Creation time. | +| `resolved_at` | `timestamp` | Resolution/Expiration time. | +| `resolved_by` | `bigint` | User ID who resolved it. | +| `resolved_reason` | `text` | Reason for resolution. |