From 7e0532f43e67da46b52d04fa40cf2dfa0c97716a Mon Sep 17 00:00:00 2001 From: Z8MB1E Date: Thu, 13 Aug 2026 17:00:57 -0400 Subject: [PATCH] docs: expand Discord bot docs and update task list Rewrite the AGENTS.md Discord Bot section to reflect the live bot (features, structure, gotchas) and tidy TODO.md formatting plus a 'To-Dos for later' section. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- AGENTS.md | 10 +++++++++- TODO.md | 28 +++++++++++++++++----------- 2 files changed, 26 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cf43da3..02a373c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -214,7 +214,15 @@ gameTick → POST `/api/game-tick/notify` (guarded by `x-game-tick-secret` heade ## Discord Bot -A Discord bot (planned, not started) living in `src/bot/`, run as a standalone long-running process that imports `@payload-config` directly (same pattern as `src/scripts/` and `src/tools/seed/`). **Full product requirements live in `docs/bot/context.md`; the approved implementation design is in `docs/bot/design.md` — read both before touching bot code.** In short: (1) Discord sign-up/linking using the Discord username, no OAuth; (2) recurring operations calendar with Yes/No/Tentative attendance synced two-way between Discord embeds and the website; (3) announcements + optional per-user Discord notifications for app events (market offers, shipments, banking). Known gaps: no mission attendance model exists yet (missions do have `startDateTime`/`estimatedDuration`), no Discord snowflake ID on users, no Discord-specific preferences. +A Discord bot living in `src/bot/`, run as a standalone long-running process via `bun run bot` — it imports `@payload-config` directly (same pattern as `src/scripts/` and `src/tools/seed/`) and shares the Postgres DB with the web app. **Under active development and testing.** **Full product requirements live in `docs/bot/context.md`; the approved implementation design is in `docs/bot/design.md` — read both before touching bot code.** + +- **Env / run**: requires `DISCORD_TOKEN` and `DISCORD_GUILD_ID` (fail-fast on missing required vars in `src/bot/config.ts`); optional `DISCORD_OPS_CHANNEL_ID`, `DISCORD_ANNOUNCE_CHANNEL_ID`, `DISCORD_STAFF_ROLE_IDS`, `DISCORD_ATTENDANCE_POLL_MS` (default 60s), `DISCORD_NOTIFICATION_POLL_MS` (default 20s), plus existing `APP_URL`. Logs through `payload.logger`. +- **Structure**: `commands/` — `ping`, `signup`, `link`, `announce`; `events/interactionCreate.ts` — routes `ptf-att:` RSVP buttons; `services/` — `missionEmbeds` (attendance embed lifecycle + reconcile loop) and `notificationBridge` (poll → Discord DMs); `lib/` — `roles.ts` (`isStaff`), `resolve.ts` (discordId ↔ Payload user lookups). Command registration scope: `signup`/`link`/`ping` are **global** (DM-usable — guild-scoped commands never appear in DMs), `announce` is guild-only. +- **Sign-up / linking (feature 1)**: `/signup` is **DM-only** (the temp password flows through the DM). Creates the Payload user with `username` = `discordUsername` = the caller's Discord username, plus `discordId`, `displayName`, `steamId`, and a random temp password. The ephemeral reply carries the password as the guaranteed delivery path; `interaction.user.send()` is a best-effort persistent copy, so a blocked DM never orphans the account. `/link` works in servers **and** DMs (credential-free, ephemeral reply only) — matches `discordUsername` → sets `discordId`. +- **DM gotcha**: a user with "Allow direct messages from server members" off in Discord privacy settings can neither receive the bot's DMs nor open a DM with the bot. The `/signup` rejection message explains how to enable it. +- **Attendance (feature 2)**: `mission-attendances` collection + `src/lib/attendance/` (single write path, emits `mission:attendance-change`). The bot posts RSVP embeds (Yes/Tentative/No) for future, `Ready`/`Scheduled`, `visibility: "unit"` missions into the ops channel; stores `discordMessageId` + `discordAttendanceHash` on the mission; reconciles hash changes every poll tick (web ↔ Discord two-way sync, loop-safe). Web UI: `MissionAttendance` component on the mission detail page. `bun run payload generate-mission` clones the next weekly main mission. +- **Notifications / announcements (feature 3)**: `notificationBridge` polls `user-notifications` (cursor = last seen id; cap 5 DMs/tick) and DMs opted-in users (`preferences.discord.enabled`, not in `mutedTypes`). `/announce` (staff only) posts an announcement embed. New notify sites partially done: banking emits `finance:deposit`; shipments has no notify site yet. +- **Remaining polish**: the web preferences UI does not yet expose the `preferences.discord` toggles — they exist on the Users collection and are read by the bridge, but are currently only settable in the Payload admin panel. ## Auth diff --git a/TODO.md b/TODO.md index a7acf46..455e964 100644 --- a/TODO.md +++ b/TODO.md @@ -1,22 +1,22 @@ # To-Do Feature List -- [ ] Personal "locker" for users - A secure space where users can store, equip, and manage their items, gear, weapons, loadout, and other personal assets. - - [x] Wardrobe - A virtual representation of the user's character that can be customized with different outfits, accessories, and gear. The wardrobe should reflect the user's current loadout and inventory. - - [x] Equipment editor - A tool that allows users to modify and customize their equipment, including changing attachments, skins, and other visual elements. The editor should provide a user-friendly interface for easy adjustments. -- [ ] Inventory management system - A comprehensive system that allows users to view, organize, and manage their items, including sorting, filtering, and categorizing options. -- [ ] Item crafting and customization - A feature that enables users to craft new items or customize existing ones, allowing for unique combinations and personalization. -- [ ] Trading and marketplace - A platform where users can trade items with other players or buy/sell items in a virtual marketplace, including features like bidding, auctions, and secure transactions. It should be reminiscent of the flea market in Escape from Tarkov. Automatically generated market entries should be available for items that are not listed by users, allowing for a dynamic and evolving marketplace. +- [ ] Personal "locker" for users – A secure space where users can store, equip, and manage their items, gear, weapons, loadout, and other personal assets. + - [x] Wardrobe – A virtual representation of the user's character that can be customized with different outfits, accessories, and gear. The wardrobe should reflect the user's current loadout and inventory. + - [x] Equipment editor – A tool that allows users to modify and customize their equipment, including changing attachments, skins, and other visual elements. The editor should provide a user-friendly interface for easy adjustments. +- [ ] Inventory management system – A comprehensive system that allows users to view, organize, and manage their items, including sorting, filtering, and categorizing options. +- [ ] Item crafting and customization – A feature that enables users to craft new items or customize existing ones, allowing for unique combinations and personalization. +- [ ] Trading and marketplace – A platform where users can trade items with other players or buy/sell items in a virtual marketplace, including features like bidding, auctions, and secure transactions. It should be reminiscent of the flea market in Escape from Tarkov. Automatically generated market entries should be available for items that are not listed by users, allowing for a dynamic and evolving marketplace. - [x] Core buy/sell marketplace - Users list items from their locker at a fixed price; buyers pay via the banking system and items transfer directly into the buyer's locker. Runs `bun run payload market-tick` to expire listings and top up auto-generated vendor entries. - - [ ] Bidding and auctions - Allow sellers to list items as auctions with timed bidding instead of fixed-price buyouts. - - [ ] Marketplace fees and market price drift - Percentage listing/sale fees and price fluctuations that tend toward each asset's resting `baseBuyPrice`/`baseSellPrice` over time. -- [ ] Implement command palette - A feature that provides users with a list of available commands and allows them to execute them with a single keystroke or gesture. The command palette should be accessible from a designated keybind or gesture and should display a list of relevant commands based on the user's current context. + - [ ] Bidding and auctions – Allow sellers to list items as auctions with timed bidding instead of fixed-price buyouts. + - [ ] Marketplace fees and market price drift – Percentage listing/sale fees and price fluctuations that tend toward each asset's resting `baseBuyPrice`/`baseSellPrice` over time. +- [ ] Implement command palette – A feature that provides users with a list of available commands and allows them to execute them with a single keystroke or gesture. The command palette should be accessible from a designated keybind or gesture and should display a list of relevant commands based on the user's current context. -## MVP - Priority Deadline by 8/15 +## MVP – Priority Deadline by 8/15 This application must be available to my users by 8/15. The minimum viable product is defined as: - [ ] Working authentication (login, logout, forgot password without using email) -- [ ] Automatically generated profile with customization options for user on front-end +- [ ] Automatically generated profile with customization options for user on the front-end - [ ] Full permissions and ACL system for all components - [ ] ALL ADMIN UI access should be blocked behind a "trusted" role. - [ ] Admin UI access to the Intelligence section should be blocked behind an "intelligence" qualification. @@ -37,3 +37,9 @@ This application must be available to my users by 8/15. The minimum viable produ - [ ] Working vehicles screen - [ ] Banking system - [ ] Working market screen + +### To-Dos for later +- [ ] Add division art to profiles +- [ ] Medical stat tracking +- [ ] Community hub for posting videos, screenshots, and other media +- [ ] Player decoration for a "Player of the Week" award \ No newline at end of file