This commit is contained in:
71
AGENTS.md
71
AGENTS.md
@@ -74,14 +74,21 @@ backend/src/
|
||||
├── index.js app bootstrap: dotenv, static uploads, json limits (50mb),
|
||||
│ passport init, CORS, route mounting, listen(5000)
|
||||
├── db.js connectDB() -> mongoose.connect(process.env.DB_URI)
|
||||
├── models/ User.js Campaign.js Note.js Folder.js
|
||||
├── routes/ user.js campaign.js note.js folder.js
|
||||
├── models/ User.js Campaign.js Note.js Folder.js Actor.js Item.js
|
||||
│ FoundryLinkRequest.js DiscordLinkRequest.js DiscordGuildLink.js
|
||||
├── routes/ user.js campaign.js note.js folder.js actor.js item.js
|
||||
│ foundry-link.js (token sync, mounted BEFORE auth) foundry.js (bridge proxy)
|
||||
│ discord.js
|
||||
├── services/
|
||||
│ ├── keys.js { secret: "putyoursecrethere" } <- JWT secret, hardcoded
|
||||
│ ├── passport.js JwtStrategy: Bearer token -> User.findById(jwt_payload._id)
|
||||
│ ├── middleware.js isAdmin — imported by routes/user.js but applied to no route yet
|
||||
│ ├── rate-limiter.js express-rate-limit: 150 req / 60 min, applied to /user/login and /user/setup
|
||||
│ └── storage.js multer diskStorage -> backend/src/uploads/, filename `<field>-<timestamp><ext>`
|
||||
│ ├── storage.js multer diskStorage -> backend/src/uploads/, filename `<field>-<timestamp><ext>`
|
||||
│ ├── foundry.js requestFoundry(): reads the optional snapshot bridge
|
||||
│ ├── foundry-fields.js shared asText/numberOr/plainText/stringList for the mappers
|
||||
│ ├── actor-foundry.js foundryActorToCharacter(): Foundry actor document -> Actor fields
|
||||
│ └── item-foundry.js foundryItemToItemData(): Foundry item document -> Item fields
|
||||
└── uploads/ created on demand, gitignored, served PUBLICLY at /api/public
|
||||
```
|
||||
|
||||
@@ -94,7 +101,9 @@ backend/src/
|
||||
`/get-settings`).
|
||||
3. `checkAuth = passport.authenticate('jwt', { session: false })` — note the **missing declaration**
|
||||
(implicit global). Everything mounted after this is JWT-protected.
|
||||
4. `/api/campaign`, `/api/note`, `/api/folder`.
|
||||
4. `/api/campaign`, `/api/note`, `/api/folder`, `/api/actor`, `/api/item` and `/api/foundry`
|
||||
(the read-only bridge proxy). `routes/foundry-link.js` is deliberately mounted **before** step 3 —
|
||||
it authenticates with the per-campaign sync token instead of a Dragonroll login (see §4.1).
|
||||
|
||||
JWT: signed in `POST /api/user/login` with payload `{ _id, username, name, email, admin, settings }`,
|
||||
`expiresIn: 172800` (48h). `req.user` is the Mongoose `User` document, so routes use `req.user.id`.
|
||||
@@ -130,14 +139,18 @@ Ownership is enforced per handler. `settings`, `color`, `description` and `User.
|
||||
```
|
||||
User ──< Campaign ──< Note ──?> Folder ──?> Folder (parentFolder, self-ref)
|
||||
└───────< Folder
|
||||
└───────< Actor (Foundry actors, when linked)
|
||||
└───────< Item (Foundry gear + hand-made items)
|
||||
```
|
||||
|
||||
| Model | File | Fields |
|
||||
|---|---|---|
|
||||
| `User` | `models/User.js` | `name*`, `username*` (unique), `email*` (unique), `password` (bcrypt hash, 10 salt rounds), `date`, `admin` (bool, default false), `image`, `setupCode`, `settings` (Object) |
|
||||
| `Campaign` | `models/Campaign.js` | `name*`, `description`, `color`, `createdBy*` → User, `date`, `settings` (Object) |
|
||||
| `Campaign` | `models/Campaign.js` | `name*`, `description`, `color`, `createdBy*` → User, `date`, `settings` (Object), `foundryWorldId` (unique, sparse), `foundryWorldTitle`, `foundrySystem`, `foundrySyncTokenHash` (`select: false`), `discordGuildId` |
|
||||
| `Note` | `models/Note.js` | `title`, `content` (markdown source string), `campaign*` → Campaign, `folder` → Folder (null = root), `color` (hex string, sidebar entry background), `date` |
|
||||
| `Folder` | `models/Folder.js` | `name*`, `campaign*` → Campaign, `parentFolder` → Folder (null = root), `color` (hex string, sidebar entry background), `date` |
|
||||
| `Actor` | `models/Actor.js` | `name*`, `type` (`character`\|`npc`\|`creature`), `species`, `className`, `subclass`, `level`, `background`, `challengeRating`, `description`, `image`, `abilityScores{str..cha}`, `armorClass`, `speed`, `proficiencies`, `inventory[{name,quantity,weight}]` (flattened Foundry items, embedded — not `Item` docs), `traits`, `spells` (newline text), `campaign*` → Campaign, `foundryActorId` (unique per campaign), `date` |
|
||||
| `Item` | `models/Item.js` | `name*`, `category` (`weapon`\|`armor`\|`shield`\|`adventuring-gear`\|`magic-item`\|`consumable`\|`tool`\|`treasure`\|`other`), `rarity` (`common`…`artifact`), `quantity`, `weight`, `properties`, `description`, `campaign*` → Campaign, `foundryItemId` (unique per campaign), `foundryNames` (names Foundry uses for it, keeps dedup stable across a Dragonroll rename), `date` |
|
||||
|
||||
`*` = required. Notes and folders are ordered by `date: -1` everywhere.
|
||||
|
||||
@@ -183,6 +196,54 @@ subfolders re-parented to null then deleted.
|
||||
|
||||
`GET /api/test` — health check.
|
||||
|
||||
`GET /api/actor/list?campaign=` → `{status:'ok',actors}`
|
||||
`POST /api/actor/create` — `{name*,campaign*,type?,species?,className?,subclass?,level?,background?,challengeRating?,description?}`
|
||||
`POST /api/actor/update` — `{id*, name?, species?, className?, subclass?, level?, abilityScores?, armorClass?, speed?, proficiencies?, inventory?, traits?, spells?, image?}` — partial, ownership checked
|
||||
`POST /api/actor/upload-image?actor=` — multipart field `image`
|
||||
`POST /api/actor/delete` — `{id}`
|
||||
|
||||
`GET /api/item/list?campaign=` → `{status:'ok',items}`
|
||||
`POST /api/item/create` — `{name*,campaign*,category?,rarity?,quantity?,weight?,properties?,description?}`
|
||||
`POST /api/item/update` — `{id*, name?, category?, rarity?, quantity?, weight?, properties?, description?}` — partial, ownership checked. `''` for `quantity`/`weight` is ignored, like `/item/create`.
|
||||
`POST /api/item/delete` — `{id}`
|
||||
|
||||
### 4.1 Foundry integration (actors, items)
|
||||
|
||||
`dragonroll-foundry/` holds the Foundry VTT module (`scripts/api.js`, loaded by `module.json`) and an
|
||||
optional read-only snapshot bridge (`bridge/server.js`). The module talks to Dragonroll with a
|
||||
per-campaign bearer token, **not** a Dragonroll login: `POST /api/foundry/link/complete` redeems a
|
||||
pairing code, stores its hash on `Campaign.foundrySyncTokenHash` and hands the plain token to Foundry
|
||||
once. Every sync route re-reads the campaign from that hash and rejects payloads whose `worldId` is
|
||||
not `Campaign.foundryWorldId` (`syncCampaign` / `requestMatchesWorld`). CORS is opened for
|
||||
`/api/foundry/sync*` and `/foundry/link/complete` in `src/index.js`, before the app-wide CORS.
|
||||
`dragonroll-foundry/README.md` documents pairing, the bridge and its environment variables.
|
||||
|
||||
| Sync route (token) | Meaning |
|
||||
|---|---|
|
||||
| `POST /sync/snapshot` | `{worldId, actors[], items[], fullSync}` — upserts actors, world items and every item embedded in those actors; a `fullSync` also deletes actors/items that are gone |
|
||||
| `POST /sync/item-snapshot` | `{worldId, items[]}` — live world-item edits, upsert only (never prunes) |
|
||||
| `POST /sync/item-delete` | `{worldId, foundryItemId}` — a world item was deleted |
|
||||
| `GET /sync/characters` | Actors the module applies back into Foundry |
|
||||
| `GET /sync/items` | Items the module applies back into Foundry (creates world items for Dragonroll-authored ones) |
|
||||
| `POST /sync/map` / `POST /sync/map-item` | Store the id mapping after the module creates a document |
|
||||
| `POST /sync/delete` | `{worldId, foundryActorId}` |
|
||||
|
||||
Rules worth knowing before editing this:
|
||||
|
||||
- **Identity** is `foundryActorId` / `foundryItemId` (unique per campaign, partial index so local
|
||||
documents can leave it unset). A document carrying the `dragonroll-foundry.actorId` /
|
||||
`dragonroll-foundry.itemId` flag adopts the matching Dragonroll row.
|
||||
- **Items are deduplicated by name.** Foundry keeps the same gear once per carrier, so one Dragonroll
|
||||
`Item` per name: the first document to claim it keeps the mapping, later copies just return it.
|
||||
`foundryNames` remembers Foundry's names so a Dragonroll rename does not resurrect a duplicate.
|
||||
`services/item-foundry.js` returns `null` for non-gear types (spells, classes, feats, species…),
|
||||
which the sync skips.
|
||||
- **`fullSync` preserves Dragonroll edits** (only new rows are overwritten); live Foundry events
|
||||
overwrite. Item pruning requires the full snapshot, since only it sees world items and actor copies.
|
||||
- `Actor.inventory` stays a flattened copy of the actor's embedded items; it is not linked to `Item`.
|
||||
- `GET /api/foundry/*` (`routes/foundry.js`) is unrelated: a JWT-protected proxy over the read-only
|
||||
bridge, only useful when `FOUNDRY_API_URL` is configured.
|
||||
|
||||
## 5. Frontend
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user