x
This commit is contained in:
Your Name committed
1 parent
3965f4f4da
commit
70877882b0
82 files changed
+4353
-186
No files matched your search
@@ -0,0 +1,475 @@
|
||||
# Implementation Strategy for Menu Image Fields
|
||||
|
||||
This report outlines the technical analysis and implementation strategy for adding new image fields to the `Menu` and `MenuItem` models in the backend database, shared types, backend API routes, and MCP tools.
|
||||
|
||||
---
|
||||
|
||||
## Summary of Findings
|
||||
|
||||
- **Database Model**: In `apps/backend/prisma/schema.prisma`, `Menu` holds a flat list of `MenuItem` objects via a relation, and a hierarchical JSON `payload`. To support the layout requirements, `Menu` requires `rootImage` (optional `String?`), while `MenuItem` requires `columnImage` and `hoverImage` (both optional `String?`).
|
||||
- **TypeScript Types**: `packages/types/index.ts` exposes interface types `Menu` and `MenuItem` directly from source files, so adding the optional image properties there is straightforward.
|
||||
- **Backend Routes**: `apps/backend/src/routes/menus.ts` defines Elysia routes. The `POST /` and `PUT /:name` endpoints require updating their TypeBox validation schemas (`t.Optional(t.Nullable(t.String()))`) and mapping the new fields in Prisma transactions. `GET` endpoints automatically return these new database fields.
|
||||
- **MCP Server Tools**: `apps/mcp-server/menu-tools.ts` validates `MenuItem` lists via `validateMenuItems` and requires checks for the new image fields. `apps/mcp-server/menu-toolkit.ts` exposes `upsert_menu` and requires updating its input schema properties and input payload mapping.
|
||||
|
||||
---
|
||||
|
||||
## 1. Database Schema & Migration Strategy
|
||||
|
||||
### File: `apps/backend/prisma/schema.prisma`
|
||||
|
||||
#### Existing Code (Lines 638–658)
|
||||
```prisma
|
||||
model Menu {
|
||||
id Int @id @default(autoincrement())
|
||||
name String @unique // e.g., "header", "footer"
|
||||
payload Json?
|
||||
isActive Boolean @default(true)
|
||||
items MenuItem[]
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
}
|
||||
|
||||
model MenuItem {
|
||||
id Int @id @default(autoincrement())
|
||||
menuId Int
|
||||
menu Menu @relation(fields: [menuId], references: [id], onDelete: Cascade)
|
||||
label String
|
||||
url String
|
||||
order Int @default(0)
|
||||
translations MenuItemTranslation[]
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
}
|
||||
```
|
||||
|
||||
#### Proposed Changes
|
||||
Add `rootImage` to the `Menu` model, and `columnImage`/`hoverImage` to the `MenuItem` model:
|
||||
|
||||
```prisma
|
||||
model Menu {
|
||||
id Int @id @default(autoincrement())
|
||||
name String @unique // e.g., "header", "footer"
|
||||
payload Json?
|
||||
isActive Boolean @default(true)
|
||||
rootImage String?
|
||||
items MenuItem[]
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
}
|
||||
|
||||
model MenuItem {
|
||||
id Int @id @default(autoincrement())
|
||||
menuId Int
|
||||
menu Menu @relation(fields: [menuId], references: [id], onDelete: Cascade)
|
||||
label String
|
||||
url String
|
||||
order Int @default(0)
|
||||
columnImage String?
|
||||
hoverImage String?
|
||||
translations MenuItemTranslation[]
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
}
|
||||
```
|
||||
|
||||
### Migration Commands
|
||||
1. **Development Environment**: To generate and apply the SQL migration locally, run:
|
||||
```bash
|
||||
bunx prisma migrate dev --name add_menu_image_fields
|
||||
```
|
||||
*Warning*: Never use `prisma db push` in this project as it bypasses migrations and will lead to local/production schema drift.
|
||||
2. **Production/CI Environment**: To apply the created migration to the production database during deployment, run:
|
||||
```bash
|
||||
bunx prisma migrate deploy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Shared Type Declarations
|
||||
|
||||
### File: `packages/types/index.ts`
|
||||
|
||||
#### Existing Code (Lines 195–208)
|
||||
```typescript
|
||||
export interface MenuItem {
|
||||
id: number
|
||||
label: string
|
||||
url: string
|
||||
order: number
|
||||
translations?: any[]
|
||||
}
|
||||
|
||||
export interface Menu {
|
||||
id: number
|
||||
name: string
|
||||
items: MenuItem[]
|
||||
payload?: any
|
||||
}
|
||||
```
|
||||
|
||||
#### Proposed Changes
|
||||
Update interfaces to expose the optional properties:
|
||||
|
||||
```typescript
|
||||
export interface MenuItem {
|
||||
id: number
|
||||
label: string
|
||||
url: string
|
||||
order: number
|
||||
columnImage?: string | null
|
||||
hoverImage?: string | null
|
||||
translations?: any[]
|
||||
}
|
||||
|
||||
export interface Menu {
|
||||
id: number
|
||||
name: string
|
||||
rootImage?: string | null
|
||||
items: MenuItem[]
|
||||
payload?: any
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Backend Route Changes
|
||||
|
||||
### File: `apps/backend/src/routes/menus.ts`
|
||||
|
||||
Both `POST /` and `PUT /:name` routes must be modified.
|
||||
|
||||
#### A. Route `POST /` (Lines 32–59)
|
||||
|
||||
##### Before
|
||||
```typescript
|
||||
.post("/", async ({ body, set }) => {
|
||||
try {
|
||||
const { name, items } = body as { name: string; items?: { label: string; url: string; order: number }[] };
|
||||
const menu = await prisma.menu.create({
|
||||
data: {
|
||||
name,
|
||||
items: items ? {
|
||||
create: items
|
||||
} : undefined
|
||||
},
|
||||
include: { items: true }
|
||||
});
|
||||
return menu;
|
||||
} catch (err) {
|
||||
console.error(err);
|
||||
set.status = 500;
|
||||
return { error: "Failed to create menu" };
|
||||
}
|
||||
}, {
|
||||
body: t.Object({
|
||||
name: t.String(),
|
||||
items: t.Optional(t.Array(t.Object({
|
||||
label: t.String(),
|
||||
url: t.String(),
|
||||
order: t.Number()
|
||||
})))
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
##### After (Proposed)
|
||||
```typescript
|
||||
.post("/", async ({ body, set }) => {
|
||||
try {
|
||||
const { name, rootImage, items } = body as {
|
||||
name: string;
|
||||
rootImage?: string | null;
|
||||
items?: { label: string; url: string; order: number; columnImage?: string | null; hoverImage?: string | null }[]
|
||||
};
|
||||
const menu = await prisma.menu.create({
|
||||
data: {
|
||||
name,
|
||||
rootImage,
|
||||
items: items ? {
|
||||
create: items
|
||||
} : undefined
|
||||
},
|
||||
include: { items: true }
|
||||
});
|
||||
return menu;
|
||||
} catch (err) {
|
||||
console.error(err);
|
||||
set.status = 500;
|
||||
return { error: "Failed to create menu" };
|
||||
}
|
||||
}, {
|
||||
body: t.Object({
|
||||
name: t.String(),
|
||||
rootImage: t.Optional(t.Nullable(t.String())),
|
||||
items: t.Optional(t.Array(t.Object({
|
||||
label: t.String(),
|
||||
url: t.String(),
|
||||
order: t.Number(),
|
||||
columnImage: t.Optional(t.Nullable(t.String())),
|
||||
hoverImage: t.Optional(t.Nullable(t.String()))
|
||||
})))
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
#### B. Route `PUT /:name` (Lines 60–147)
|
||||
|
||||
##### Before
|
||||
```typescript
|
||||
.put("/:name", async ({ params: { name }, body, set }) => {
|
||||
try {
|
||||
const { items, payload, isActive } = body as {
|
||||
payload?: any;
|
||||
isActive?: boolean;
|
||||
items: { id?: number; label: string; url: string; order: number; translations?: { langCode: string; label: string }[] }[]
|
||||
};
|
||||
let menu = await prisma.menu.findUnique({ where: { name } });
|
||||
|
||||
const updateData: any = {};
|
||||
if (payload !== undefined) updateData.payload = payload;
|
||||
if (isActive !== undefined) updateData.isActive = isActive;
|
||||
|
||||
if (!menu) {
|
||||
menu = await prisma.menu.create({ data: { name, ...updateData } });
|
||||
} else if (Object.keys(updateData).length > 0) {
|
||||
menu = await prisma.menu.update({ where: { name }, data: updateData });
|
||||
}
|
||||
|
||||
await prisma.$transaction(async (tx: any) => {
|
||||
const existingItems = await tx.menuItem.findMany({ where: { menuId: menu!.id } });
|
||||
const existingItemIds = existingItems.map((i: any) => i.id);
|
||||
const payloadItemIds = items.map(i => i.id).filter(id => id != null);
|
||||
const itemsToDelete = existingItemIds.filter((id: number) => !payloadItemIds.includes(id));
|
||||
|
||||
if (itemsToDelete.length > 0) {
|
||||
await tx.menuItem.deleteMany({ where: { id: { in: itemsToDelete } } });
|
||||
}
|
||||
|
||||
for (const item of items) {
|
||||
if (item.id && existingItemIds.includes(item.id)) {
|
||||
await tx.menuItem.update({
|
||||
where: { id: item.id },
|
||||
data: { label: item.label, url: item.url, order: item.order }
|
||||
});
|
||||
if (item.translations?.length) {
|
||||
for (const t of item.translations) {
|
||||
await tx.menuItemTranslation.upsert({
|
||||
where: { menuItemId_langCode: { menuItemId: item.id, langCode: t.langCode } },
|
||||
update: { label: t.label },
|
||||
create: { menuItemId: item.id, langCode: t.langCode, label: t.label }
|
||||
});
|
||||
}
|
||||
}
|
||||
} else {
|
||||
await tx.menuItem.create({
|
||||
data: {
|
||||
menuId: menu!.id,
|
||||
label: item.label,
|
||||
url: item.url,
|
||||
order: item.order,
|
||||
translations: item.translations?.length ? {
|
||||
create: item.translations.map(t => ({
|
||||
langCode: t.langCode,
|
||||
label: t.label
|
||||
}))
|
||||
} : undefined
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
});
|
||||
// ... (retrieval and return logic)
|
||||
}, {
|
||||
body: t.Object({
|
||||
payload: t.Optional(t.Any()),
|
||||
isActive: t.Optional(t.Boolean()),
|
||||
items: t.Array(t.Object({
|
||||
id: t.Optional(t.Number()),
|
||||
label: t.String(),
|
||||
url: t.String(),
|
||||
order: t.Number(),
|
||||
translations: t.Optional(t.Array(t.Object({
|
||||
langCode: t.String(),
|
||||
label: t.String()
|
||||
})))
|
||||
}))
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
##### After (Proposed)
|
||||
```typescript
|
||||
.put("/:name", async ({ params: { name }, body, set }) => {
|
||||
try {
|
||||
const { items, payload, isActive, rootImage } = body as {
|
||||
payload?: any;
|
||||
isActive?: boolean;
|
||||
rootImage?: string | null;
|
||||
items: {
|
||||
id?: number;
|
||||
label: string;
|
||||
url: string;
|
||||
order: number;
|
||||
columnImage?: string | null;
|
||||
hoverImage?: string | null;
|
||||
translations?: { langCode: string; label: string }[]
|
||||
}[]
|
||||
};
|
||||
let menu = await prisma.menu.findUnique({ where: { name } });
|
||||
|
||||
const updateData: any = {};
|
||||
if (payload !== undefined) updateData.payload = payload;
|
||||
if (isActive !== undefined) updateData.isActive = isActive;
|
||||
if (rootImage !== undefined) updateData.rootImage = rootImage;
|
||||
|
||||
if (!menu) {
|
||||
menu = await prisma.menu.create({ data: { name, ...updateData } });
|
||||
} else if (Object.keys(updateData).length > 0) {
|
||||
menu = await prisma.menu.update({ where: { name }, data: updateData });
|
||||
}
|
||||
|
||||
await prisma.$transaction(async (tx: any) => {
|
||||
const existingItems = await tx.menuItem.findMany({ where: { menuId: menu!.id } });
|
||||
const existingItemIds = existingItems.map((i: any) => i.id);
|
||||
const payloadItemIds = items.map(i => i.id).filter(id => id != null);
|
||||
const itemsToDelete = existingItemIds.filter((id: number) => !payloadItemIds.includes(id));
|
||||
|
||||
if (itemsToDelete.length > 0) {
|
||||
await tx.menuItem.deleteMany({ where: { id: { in: itemsToDelete } } });
|
||||
}
|
||||
|
||||
for (const item of items) {
|
||||
if (item.id && existingItemIds.includes(item.id)) {
|
||||
await tx.menuItem.update({
|
||||
where: { id: item.id },
|
||||
data: {
|
||||
label: item.label,
|
||||
url: item.url,
|
||||
order: item.order,
|
||||
columnImage: item.columnImage,
|
||||
hoverImage: item.hoverImage
|
||||
}
|
||||
});
|
||||
if (item.translations?.length) {
|
||||
for (const t of item.translations) {
|
||||
await tx.menuItemTranslation.upsert({
|
||||
where: { menuItemId_langCode: { menuItemId: item.id, langCode: t.langCode } },
|
||||
update: { label: t.label },
|
||||
create: { menuItemId: item.id, langCode: t.langCode, label: t.label }
|
||||
});
|
||||
}
|
||||
}
|
||||
} else {
|
||||
await tx.menuItem.create({
|
||||
data: {
|
||||
menuId: menu!.id,
|
||||
label: item.label,
|
||||
url: item.url,
|
||||
order: item.order,
|
||||
columnImage: item.columnImage,
|
||||
hoverImage: item.hoverImage,
|
||||
translations: item.translations?.length ? {
|
||||
create: item.translations.map(t => ({
|
||||
langCode: t.langCode,
|
||||
label: t.label
|
||||
}))
|
||||
} : undefined
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
});
|
||||
// ... (retrieval and return logic)
|
||||
}, {
|
||||
body: t.Object({
|
||||
payload: t.Optional(t.Any()),
|
||||
isActive: t.Optional(t.Boolean()),
|
||||
rootImage: t.Optional(t.Nullable(t.String())),
|
||||
items: t.Array(t.Object({
|
||||
id: t.Optional(t.Number()),
|
||||
label: t.String(),
|
||||
url: t.String(),
|
||||
order: t.Number(),
|
||||
columnImage: t.Optional(t.Nullable(t.String())),
|
||||
hoverImage: t.Optional(t.Nullable(t.String())),
|
||||
translations: t.Optional(t.Array(t.Object({
|
||||
langCode: t.String(),
|
||||
label: t.String()
|
||||
})))
|
||||
}))
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. MCP Server Tools Adaptations
|
||||
|
||||
### A. File: `apps/mcp-server/menu-tools.ts`
|
||||
|
||||
The `validateMenuItems` helper function needs to allow validating `columnImage` and `hoverImage` when present inside items.
|
||||
|
||||
#### Proposed Change
|
||||
Add validation logic inside the `items.forEach` block:
|
||||
```typescript
|
||||
if (item.columnImage !== undefined && item.columnImage !== null && typeof item.columnImage !== "string") {
|
||||
issues.push(`items[${index}].columnImage must be a string when provided`);
|
||||
}
|
||||
|
||||
if (item.hoverImage !== undefined && item.hoverImage !== null && typeof item.hoverImage !== "string") {
|
||||
issues.push(`items[${index}].hoverImage must be a string when provided`);
|
||||
}
|
||||
```
|
||||
|
||||
### B. File: `apps/mcp-server/menu-toolkit.ts`
|
||||
|
||||
The `upsert_menu` MCP tool schema and handler must be updated to accept and forward the new fields.
|
||||
|
||||
#### Proposed Changes
|
||||
1. **Schema Update (`MENU_TOOL_DEFINITIONS`)**:
|
||||
Under `upsert_menu.inputSchema.properties`, add `rootImage`:
|
||||
```typescript
|
||||
rootImage: { type: "string", description: "Optional image URL for the menu root (optional, nullable)" },
|
||||
```
|
||||
Under `upsert_menu.inputSchema.properties.items.items.properties`, add `columnImage` and `hoverImage`:
|
||||
```typescript
|
||||
columnImage: { type: "string", description: "Optional column image URL for this menu item" },
|
||||
hoverImage: { type: "string", description: "Optional hover image URL for this menu item" },
|
||||
```
|
||||
|
||||
2. **Handler Update (`handleMenuTool`)**:
|
||||
In `case "upsert_menu":`, map `rootImage` into the PUT request payload `body`:
|
||||
```typescript
|
||||
if (params.rootImage !== undefined) {
|
||||
body.rootImage = params.rootImage;
|
||||
} else if (existingMenu?.rootImage !== undefined) {
|
||||
body.rootImage = existingMenu.rootImage;
|
||||
}
|
||||
```
|
||||
Also update the dryRun response preview block to display the rootImage state:
|
||||
```typescript
|
||||
preview: {
|
||||
name: params.name,
|
||||
itemCount: items.length,
|
||||
hasPayload: !!body.payload,
|
||||
isActive: body.isActive,
|
||||
rootImage: body.rootImage // Added preview
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Potential Risks & Mitigation Plans
|
||||
|
||||
1. **Local and Production Environment Schema Mismatch**:
|
||||
- **Risk**: Directly deploying backend code without applying schema changes can lead to runtime crashes due to undefined columns.
|
||||
- **Mitigation**: Schema migrations (`prisma migrate dev`) must be run and verified in local/staging before merging changes to main. In production, migrations must run (`prisma migrate deploy`) prior to starting the new server container instances.
|
||||
2. **Nullable Fields on Client Side**:
|
||||
- **Risk**: Since the new image fields are optional (`String?`), they default to `null` for all existing menus. Client applications (SPA, website storefront, admin dashboard) must render layouts gracefully when these fields are missing.
|
||||
- **Mitigation**: Code on client sides must fallback to default placeholders (like mock assets or empty spaces) when the image URLs are null or empty.
|
||||
3. **Elysia TypeScript Transpilation Sync**:
|
||||
- **Risk**: The backend routes are transpiled into `.js` and `.d.ts` inside the same source directory (`apps/backend/src/routes/`). Discrepancies between `.ts` source edits and build outputs could cause runtime type mismatch or route resolution bugs.
|
||||
- **Mitigation**: A clean backend rebuild (e.g. compiling with TSC/Bun compiler) should be executed right after changes are made to ensure source code and build assets are in perfect alignment.
|
||||
4. **Seed Execution Safety**:
|
||||
- **Risk**: Database seeding in `seed.cjs` upserts menus and menu items. If database constraints are strict, omitting the new columns might fail.
|
||||
- **Mitigation**: In Prisma, optional columns without default values automatically default to `null` and are not required during `create`/`upsert` calls. Thus, `seed.cjs` will not break, but documenting this compatibility is critical.
|
||||
Reference in new issue
Block a user