feat(guides): add structured image-first editor

lib/guides/calculations.ts

@@ -0,0 +1,11 @@
+export function calculateTeamMetrics(damage: number[], rotationSeconds: number) {
+  const totalDamage = damage.reduce((sum, value) => sum + value, 0);
+  if (!Number.isFinite(rotationSeconds) || rotationSeconds <= 0 || damage.some((value) => !Number.isFinite(value) || value < 0) || totalDamage <= 0) {
+    throw new Error("Team damage and rotation must be positive finite values.");
+  }
+  return {
+    totalDamage,
+    totalDps: totalDamage / rotationSeconds,
+    shares: damage.map((value) => value / totalDamage * 100),
+  };
+}

lib/guides/mutations.ts

@@ -0,0 +1,205 @@
+import "server-only";
+
+import { and, eq, sql } from "drizzle-orm";
+
+import { getDb } from "@/db";
+import {
+  artifactGroups,
+  artifactProfiles,
+  artifactRecommendations,
+  catalogCharacters,
+  catalogSyncJobs,
+  catalogVersions,
+  constellationRecommendations,
+  extraSectionRows,
+  extraSections,
+  guides,
+  guideSections,
+  media,
+  outboxEvents,
+  teamCompositions,
+  teamMembers,
+  weaponRecommendations,
+} from "@/db/schema";
+import {
+  artifactSectionSchema,
+  constellationSectionSchema,
+  createGuideSchema,
+  extraSectionSchema,
+  slugFromCharacterName,
+  teamSectionSchema,
+  updateGuideSchema,
+  weaponSectionSchema,
+} from "@/lib/guides/schemas";
+
+const DEFAULT_SECTIONS = [
+  { kind: "weapon", slug: "weapon", title: "Weapons", sortOrder: 0 },
+  { kind: "artifact", slug: "artifact", title: "Artifacts & Stats", sortOrder: 1 },
+  { kind: "constellations", slug: "constellations", title: "Constellations", sortOrder: 2 },
+  { kind: "team", slug: "team", title: "Team Calc", sortOrder: 3 },
+] as const;
+
+async function emitGuideEvents(tx: Parameters<Parameters<ReturnType<typeof getDb>["transaction"]>[0]>[0], guideId: string, version: number) {
+  await tx.insert(outboxEvents).values([
+    { topic: "directory", aggregateId: guideId, eventType: "directory.updated", payload: { id: guideId, version } },
+    { topic: `page:${guideId}`, aggregateId: guideId, eventType: "page.updated", payload: { id: guideId, version } },
+    { topic: "admin", aggregateId: guideId, eventType: "admin.updated", payload: { id: guideId, version } },
+  ]);
+}
+
+export async function createGuide(input: unknown) {
+  const parsed = createGuideSchema.parse(input);
+  const db = getDb();
+  const [version] = await db.select().from(catalogVersions).where(eq(catalogVersions.active, true)).limit(1);
+  if (!version) throw new Error("กรุณา Sync ข้อมูล Lunaris ก่อนสร้างคู่มือ");
+  const [character] = await db.select().from(catalogCharacters).where(and(eq(catalogCharacters.version, version.version), eq(catalogCharacters.key, parsed.characterKey))).limit(1);
+  if (!character) throw new Error("ไม่พบตัวละครใน Catalog เวอร์ชันปัจจุบัน");
+  const [cover] = await db.select().from(media).where(and(eq(media.id, parsed.coverMediaId), eq(media.status, "ready"))).limit(1);
+  if (!cover) throw new Error("กรุณาอัปโหลดภาพ Guide ให้สำเร็จ");
+  const baseSlug = slugFromCharacterName(character.name, character.key);
+  const [slugCollision] = await db.select({ id: guides.id }).from(guides).where(eq(guides.slug, baseSlug)).limit(1);
+  const slug = slugCollision ? `${baseSlug}-${character.key.toLowerCase()}` : baseSlug;
+
+  return db.transaction(async (tx) => {
+    const [guide] = await tx.insert(guides).values({
+      characterKey: character.key,
+      catalogVersion: version.version,
+      slug,
+      name: character.name,
+      overview: parsed.overview,
+      coverMediaId: parsed.coverMediaId,
+    }).returning();
+    await tx.insert(guideSections).values(DEFAULT_SECTIONS.map((section) => ({ ...section, guideId: guide.id })));
+    await tx.insert(artifactProfiles).values({ guideId: guide.id });
+    await tx.update(media).set({ currentReferenceCount: sql`${media.currentReferenceCount} + 1` }).where(eq(media.id, parsed.coverMediaId));
+    await emitGuideEvents(tx, guide.id, guide.version);
+    return guide;
+  });
+}
+
+async function advanceGuideVersion(tx: Parameters<Parameters<ReturnType<typeof getDb>["transaction"]>[0]>[0], guideId: string, expectedVersion: number) {
+  const [guide] = await tx.update(guides).set({ version: expectedVersion + 1 }).where(and(eq(guides.id, guideId), eq(guides.version, expectedVersion), sql`${guides.trashedAt} is null`)).returning();
+  if (!guide) throw new Error("ข้อมูลถูกแก้ไขจากแท็บอื่น กรุณาโหลดหน้าใหม่");
+  await emitGuideEvents(tx, guide.id, guide.version);
+  return guide;
+}
+
+export async function saveWeapons(guideId: string, input: unknown) {
+  const data = weaponSectionSchema.parse(input);
+  const [guide] = await getDb().select().from(guides).where(eq(guides.id, guideId)).limit(1);
+  if (!guide) throw new Error("ไม่พบ Guide");
+  return getDb().transaction(async (tx) => {
+    const updated = await advanceGuideVersion(tx, guideId, data.expectedVersion);
+    await tx.delete(weaponRecommendations).where(eq(weaponRecommendations.guideId, guideId));
+    if (data.rows.length) await tx.insert(weaponRecommendations).values(data.rows.map((row, sortOrder) => ({ ...row, overallPercent: row.overallPercent?.toString() ?? null, personalPercent: row.personalPercent?.toString() ?? null, guideId, catalogVersion: guide.catalogVersion, sortOrder })));
+    return updated;
+  });
+}
+
+export async function updateGuideBasics(guideId: string, input: unknown) {
+  const data = updateGuideSchema.parse(input);
+  const [current] = await getDb().select().from(guides).where(eq(guides.id, guideId)).limit(1);
+  if (!current) throw new Error("ไม่พบ Guide");
+  const [cover] = await getDb().select().from(media).where(and(eq(media.id, data.coverMediaId), eq(media.status, "ready"))).limit(1);
+  if (!cover) throw new Error("ไม่พบภาพ Guide ที่อัปโหลดแล้ว");
+  return getDb().transaction(async (tx) => {
+    const updated = await advanceGuideVersion(tx, guideId, data.expectedVersion);
+    await tx.update(guides).set({ overview: data.overview, coverMediaId: data.coverMediaId }).where(eq(guides.id, guideId));
+    if (current.coverMediaId !== data.coverMediaId) {
+      await tx.update(media).set({ currentReferenceCount: sql`greatest(${media.currentReferenceCount} - 1, 0)` }).where(eq(media.id, current.coverMediaId));
+      await tx.update(media).set({ currentReferenceCount: sql`${media.currentReferenceCount} + 1` }).where(eq(media.id, data.coverMediaId));
+    }
+    return updated;
+  });
+}
+
+export async function saveArtifacts(guideId: string, input: unknown) {
+  const data = artifactSectionSchema.parse(input);
+  const [guide] = await getDb().select().from(guides).where(eq(guides.id, guideId)).limit(1);
+  if (!guide) throw new Error("ไม่พบ Guide");
+  return getDb().transaction(async (tx) => {
+    const updated = await advanceGuideVersion(tx, guideId, data.expectedVersion);
+    await tx.delete(artifactGroups).where(eq(artifactGroups.guideId, guideId));
+    for (const [sortOrder, group] of data.groups.entries()) {
+      const [created] = await tx.insert(artifactGroups).values({ guideId, name: group.name, sortOrder }).returning();
+      if (group.rows.length) await tx.insert(artifactRecommendations).values(group.rows.map((row, rowOrder) => ({ ...row, percent: row.percent.toString(), groupId: created.id, catalogVersion: guide.catalogVersion, sortOrder: rowOrder })));
+    }
+    await tx.insert(artifactProfiles).values({ guideId, sands: data.sands, goblet: data.goblet, circlet: data.circlet, substats: data.substats, targets: data.targets, talents: data.talents, note: data.note }).onConflictDoUpdate({ target: artifactProfiles.guideId, set: { sands: data.sands, goblet: data.goblet, circlet: data.circlet, substats: data.substats, targets: data.targets, talents: data.talents, note: data.note } });
+    return updated;
+  });
+}
+
+export async function saveConstellations(guideId: string, input: unknown) {
+  const data = constellationSectionSchema.parse(input);
+  return getDb().transaction(async (tx) => {
+    const updated = await advanceGuideVersion(tx, guideId, data.expectedVersion);
+    await tx.delete(constellationRecommendations).where(eq(constellationRecommendations.guideId, guideId));
+    if (data.rows.length) await tx.insert(constellationRecommendations).values(data.rows.map((row) => ({ ...row, cumulativePercent: row.cumulativePercent.toString(), guideId })));
+    return updated;
+  });
+}
+
+export async function saveTeams(guideId: string, input: unknown) {
+  const data = teamSectionSchema.parse(input);
+  const [guide] = await getDb().select().from(guides).where(eq(guides.id, guideId)).limit(1);
+  if (!guide) throw new Error("ไม่พบ Guide");
+  return getDb().transaction(async (tx) => {
+    const updated = await advanceGuideVersion(tx, guideId, data.expectedVersion);
+    await tx.delete(teamCompositions).where(eq(teamCompositions.guideId, guideId));
+    for (const [sortOrder, team] of data.teams.entries()) {
+      const [created] = await tx.insert(teamCompositions).values({ guideId, title: team.title, rotationSeconds: team.rotationSeconds.toString(), combo: team.combo, sortOrder }).returning();
+      await tx.insert(teamMembers).values(team.members.map((member, position) => ({ teamId: created.id, position, catalogVersion: guide.catalogVersion, characterKey: member.characterKey, damage: member.damage.toString() })));
+    }
+    return updated;
+  });
+}
+
+export async function saveExtraSections(guideId: string, input: unknown) {
+  const data = extraSectionSchema.parse(input);
+  return getDb().transaction(async (tx) => {
+    const updated = await advanceGuideVersion(tx, guideId, data.expectedVersion);
+    await tx.delete(guideSections).where(and(eq(guideSections.guideId, guideId), eq(guideSections.kind, "extra")));
+    for (const [sortOrder, section] of data.sections.entries()) {
+      const [createdSection] = await tx.insert(guideSections).values({ guideId, kind: "extra", slug: `extra-${sortOrder + 1}`, title: section.title, enabled: true, sortOrder: 4 + sortOrder }).returning();
+      await tx.insert(extraSections).values({ sectionId: createdSection.id });
+      if (section.rows.length) await tx.insert(extraSectionRows).values(section.rows.map((row, rowOrder) => ({ ...row, percent: row.percent?.toString() ?? null, sectionId: createdSection.id, sortOrder: rowOrder })));
+    }
+    return updated;
+  });
+}
+
+export async function trashGuide(guideId: string) {
+  return getDb().transaction(async (tx) => {
+    const [guide] = await tx.update(guides).set({ trashedAt: new Date(), version: sql`${guides.version} + 1` }).where(eq(guides.id, guideId)).returning();
+    if (!guide) throw new Error("ไม่พบ Guide");
+    await emitGuideEvents(tx, guide.id, guide.version);
+    return guide;
+  });
+}
+
+export async function restoreGuide(guideId: string) {
+  return getDb().transaction(async (tx) => {
+    const [guide] = await tx.update(guides).set({ trashedAt: null, version: sql`${guides.version} + 1` }).where(eq(guides.id, guideId)).returning();
+    if (!guide) throw new Error("ไม่พบ Guide");
+    await emitGuideEvents(tx, guide.id, guide.version);
+    return guide;
+  });
+}
+
+export async function permanentlyDeleteGuide(guideId: string) {
+  return getDb().transaction(async (tx) => {
+    const [guide] = await tx.select().from(guides).where(eq(guides.id, guideId)).limit(1);
+    if (!guide?.trashedAt) throw new Error("Guide ต้องอยู่ในถังขยะก่อนลบถาวร");
+    await tx.delete(guides).where(eq(guides.id, guideId));
+    await tx.update(media).set({ currentReferenceCount: sql`greatest(${media.currentReferenceCount} - 1, 0)` }).where(eq(media.id, guide.coverMediaId));
+    await emitGuideEvents(tx, guide.id, guide.version + 1);
+    return { version: guide.version + 1 };
+  });
+}
+
+export async function enqueueCatalogSync(userId: string) {
+  const [running] = await getDb().select().from(catalogSyncJobs).where(sql`${catalogSyncJobs.status} in ('pending', 'processing')`).limit(1);
+  if (running) return running;
+  const [job] = await getDb().insert(catalogSyncJobs).values({ triggeredById: userId }).returning();
+  return job;
+}

lib/guides/queries.ts

@@ -0,0 +1,109 @@
+import "server-only";
+
+import { and, asc, desc, eq, inArray, isNotNull, isNull } from "drizzle-orm";
+
+import { getDb } from "@/db";
+import {
+  artifactGroups,
+  artifactProfiles,
+  artifactRecommendations,
+  catalogArtifacts,
+  catalogCharacters,
+  catalogSyncJobs,
+  catalogVersions,
+  catalogWeapons,
+  constellationRecommendations,
+  extraSectionRows,
+  guides,
+  guideSections,
+  media,
+  teamCompositions,
+  teamMembers,
+  weaponRecommendations,
+} from "@/db/schema";
+import { publicMediaUrl } from "@/lib/media/storage";
+
+export async function getActiveCatalog() {
+  const db = getDb();
+  const [version] = await db.select().from(catalogVersions).where(eq(catalogVersions.active, true)).limit(1);
+  if (!version) return null;
+  const [characters, weapons, artifacts] = await Promise.all([
+    db.select().from(catalogCharacters).where(eq(catalogCharacters.version, version.version)).orderBy(asc(catalogCharacters.name)),
+    db.select().from(catalogWeapons).where(eq(catalogWeapons.version, version.version)).orderBy(asc(catalogWeapons.name)),
+    db.select().from(catalogArtifacts).where(eq(catalogArtifacts.version, version.version)).orderBy(asc(catalogArtifacts.name)),
+  ]);
+  return {
+    version: version.version,
+    characters: characters.map((item) => ({ ...item, imageUrl: publicMediaUrl(item.imageKey) })),
+    weapons: weapons.map((item) => ({ ...item, imageUrl: publicMediaUrl(item.imageKey) })),
+    artifacts: artifacts.map((item) => ({ ...item, imageUrl: publicMediaUrl(item.imageKey) })),
+  };
+}
+
+export async function listGuideCards(includeTrash = false) {
+  const rows = await getDb()
+    .select({ guide: guides, cover: media })
+    .from(guides)
+    .innerJoin(media, eq(media.id, guides.coverMediaId))
+    .where(includeTrash ? isNotNull(guides.trashedAt) : isNull(guides.trashedAt))
+    .orderBy(asc(guides.sortOrder), asc(guides.name));
+  return rows.map(({ guide, cover }) => ({ ...guide, coverUrl: publicMediaUrl(cover.objectKey) }));
+}
+
+export async function getGuideByCharacterKey(characterKey: string) {
+  const [row] = await getDb()
+    .select({ guide: guides, cover: media })
+    .from(guides)
+    .innerJoin(media, eq(media.id, guides.coverMediaId))
+    .where(and(eq(guides.characterKey, characterKey), isNull(guides.trashedAt)))
+    .limit(1);
+  if (!row) return null;
+  const sections = await getDb().select().from(guideSections).where(eq(guideSections.guideId, row.guide.id)).orderBy(asc(guideSections.sortOrder));
+  return { ...row.guide, coverUrl: publicMediaUrl(row.cover.objectKey), sections };
+}
+
+export async function getPublicGuide(slug: string) {
+  const [row] = await getDb()
+    .select({ guide: guides, cover: media, character: catalogCharacters })
+    .from(guides)
+    .innerJoin(media, eq(media.id, guides.coverMediaId))
+    .innerJoin(catalogCharacters, and(eq(catalogCharacters.version, guides.catalogVersion), eq(catalogCharacters.key, guides.characterKey)))
+    .where(and(eq(guides.slug, slug), isNull(guides.trashedAt)))
+    .limit(1);
+  if (!row) return null;
+  const [sections, weaponRows, groups, profile, constellations, teams] = await Promise.all([
+    getDb().select().from(guideSections).where(and(eq(guideSections.guideId, row.guide.id), eq(guideSections.enabled, true))).orderBy(asc(guideSections.sortOrder)),
+    getDb().select({ recommendation: weaponRecommendations, weapon: catalogWeapons }).from(weaponRecommendations).innerJoin(catalogWeapons, and(eq(catalogWeapons.version, weaponRecommendations.catalogVersion), eq(catalogWeapons.key, weaponRecommendations.weaponKey))).where(eq(weaponRecommendations.guideId, row.guide.id)).orderBy(asc(weaponRecommendations.sortOrder)),
+    getDb().select().from(artifactGroups).where(eq(artifactGroups.guideId, row.guide.id)).orderBy(asc(artifactGroups.sortOrder)),
+    getDb().select().from(artifactProfiles).where(eq(artifactProfiles.guideId, row.guide.id)).limit(1),
+    getDb().select().from(constellationRecommendations).where(eq(constellationRecommendations.guideId, row.guide.id)).orderBy(asc(constellationRecommendations.level)),
+    getDb().select().from(teamCompositions).where(eq(teamCompositions.guideId, row.guide.id)).orderBy(asc(teamCompositions.sortOrder)),
+  ]);
+
+  const artifactRows = groups.length ? await getDb().select({ recommendation: artifactRecommendations, artifact: catalogArtifacts }).from(artifactRecommendations).innerJoin(catalogArtifacts, and(eq(catalogArtifacts.version, artifactRecommendations.catalogVersion), eq(catalogArtifacts.key, artifactRecommendations.firstArtifactKey))).where(inArray(artifactRecommendations.groupId, groups.map((group) => group.id))).orderBy(asc(artifactRecommendations.sortOrder)) : [];
+  const secondKeys = artifactRows.map(({ recommendation }) => recommendation.secondArtifactKey).filter((key): key is string => Boolean(key));
+  const secondArtifacts = secondKeys.length ? await getDb().select().from(catalogArtifacts).where(and(eq(catalogArtifacts.version, row.guide.catalogVersion), inArray(catalogArtifacts.key, secondKeys))) : [];
+  const members = teams.length ? await getDb().select({ member: teamMembers, character: catalogCharacters }).from(teamMembers).innerJoin(catalogCharacters, and(eq(catalogCharacters.version, teamMembers.catalogVersion), eq(catalogCharacters.key, teamMembers.characterKey))).where(inArray(teamMembers.teamId, teams.map((team) => team.id))).orderBy(asc(teamMembers.position)) : [];
+  const extraIds = sections.filter((section) => section.kind === "extra").map((section) => section.id);
+  const extraRows = extraIds.length ? await getDb().select({ row: extraSectionRows, asset: media }).from(extraSectionRows).leftJoin(media, eq(media.id, extraSectionRows.mediaId)).where(inArray(extraSectionRows.sectionId, extraIds)).orderBy(asc(extraSectionRows.sortOrder)) : [];
+
+  return {
+    ...row.guide,
+    coverUrl: publicMediaUrl(row.cover.objectKey),
+    character: { ...row.character, imageUrl: publicMediaUrl(row.character.imageKey) },
+    sections,
+    weapons: weaponRows.map(({ recommendation, weapon }) => ({ ...recommendation, weapon: { ...weapon, imageUrl: publicMediaUrl(weapon.imageKey) } })),
+    artifactGroups: groups.map((group) => ({ ...group, rows: artifactRows.filter(({ recommendation }) => recommendation.groupId === group.id).map(({ recommendation, artifact }) => { const second = secondArtifacts.find((item) => item.key === recommendation.secondArtifactKey); return { ...recommendation, first: { ...artifact, imageUrl: publicMediaUrl(artifact.imageKey) }, second: second ? { ...second, imageUrl: publicMediaUrl(second.imageKey) } : null }; }) })),
+    artifactProfile: profile[0] ?? null,
+    constellations,
+    teams: teams.map((team) => ({ ...team, members: members.filter(({ member }) => member.teamId === team.id).map(({ member, character }) => ({ ...member, character: { ...character, imageUrl: publicMediaUrl(character.imageKey) } })) })),
+    extras: sections.filter((section) => section.kind === "extra").map((section) => ({ ...section, rows: extraRows.filter(({ row: extraRow }) => extraRow.sectionId === section.id).map(({ row: extraRow, asset }) => ({ ...extraRow, imageUrl: asset ? publicMediaUrl(asset.objectKey) : null })) })),
+  };
+}
+
+export async function getLatestCatalogSyncJob() {
+  const [job] = await getDb().select().from(catalogSyncJobs).orderBy(desc(catalogSyncJobs.createdAt)).limit(1);
+  return job ?? null;
+}
+
+export type PublicGuide = NonNullable<Awaited<ReturnType<typeof getPublicGuide>>>;

lib/guides/schemas.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+
+import { calculateTeamMetrics } from "@/lib/guides/calculations";
+import { artifactSectionSchema, teamSectionSchema, weaponSectionSchema } from "@/lib/guides/schemas";
+
+describe("structured guide validation", () => {
+  it("requires at least one weapon percentage", () => {
+    expect(weaponSectionSchema.safeParse({ expectedVersion: 1, rows: [{ weaponKey: "1", refinement: 5, overallPercent: null, personalPercent: null }] }).success).toBe(false);
+    expect(weaponSectionSchema.safeParse({ expectedVersion: 1, rows: [{ weaponKey: "1", refinement: 5, overallPercent: 104, personalPercent: null }] }).success).toBe(true);
+  });
+
+  it("limits artifact main stats to two per slot", () => {
+    const result = artifactSectionSchema.safeParse({ expectedVersion: 1, groups: [], sands: ["EM", "ER", "ATK%"], goblet: [], circlet: [], substats: [], targets: [], talents: [], note: null });
+    expect(result.success).toBe(false);
+  });
+
+  it("requires four unique team members and non-zero damage", () => {
+    const base = { expectedVersion: 1, teams: [{ title: "Test", rotationSeconds: 20, combo: "E > Q", members: ["1", "2", "3", "4"].map((characterKey) => ({ characterKey, damage: 100 })) }] };
+    expect(teamSectionSchema.safeParse(base).success).toBe(true);
+    expect(teamSectionSchema.safeParse({ ...base, teams: [{ ...base.teams[0], members: ["1", "1", "3", "4"].map((characterKey) => ({ characterKey, damage: 100 })) }] }).success).toBe(false);
+  });
+});
+
+describe("Team Calc", () => {
+  it("calculates exact shares and total DPS", () => {
+    expect(calculateTeamMetrics([50, 25, 15, 10], 20)).toEqual({ totalDamage: 100, totalDps: 5, shares: [50, 25, 15, 10] });
+  });
+
+  it("rejects an empty damage rotation", () => {
+    expect(() => calculateTeamMetrics([0, 0, 0, 0], 20)).toThrow();
+  });
+});

lib/guides/schemas.ts

@@ -0,0 +1,114 @@
+import * as z from "zod";
+
+export const guideSectionKinds = ["weapon", "artifact", "constellations", "team"] as const;
+export type GuideSectionKind = (typeof guideSectionKinds)[number];
+
+const percent = z.coerce.number().finite().min(0).max(9999);
+const catalogKey = z.string().trim().min(1).max(64);
+
+export const createGuideSchema = z.strictObject({
+  characterKey: catalogKey,
+  coverMediaId: z.string().uuid(),
+  overview: z.string().trim().min(1).max(500),
+});
+
+export const updateGuideSchema = z.strictObject({
+  expectedVersion: z.number().int().positive(),
+  coverMediaId: z.string().uuid(),
+  overview: z.string().trim().min(1).max(500),
+});
+
+export const weaponSectionSchema = z.strictObject({
+  expectedVersion: z.number().int().positive(),
+  rows: z.array(z.strictObject({
+    weaponKey: catalogKey,
+    refinement: z.number().int().min(1).max(5),
+    overallPercent: percent.nullable(),
+    personalPercent: percent.nullable(),
+  }).refine((row) => row.overallPercent !== null || row.personalPercent !== null, {
+    message: "อาวุธต้องมีเปอร์เซ็นต์อย่างน้อยหนึ่งค่า",
+  })).max(100),
+});
+
+export const mainStatOptions = {
+  sands: ["EM", "ER", "ATK%", "HP%", "DEF%"],
+  goblet: ["EM", "ATK%", "DEF%", "HP%", "Pyro DMG%", "Hydro DMG%", "Cryo DMG%", "Electro DMG%", "Anemo DMG%", "Geo DMG%", "Dendro DMG%", "Physical DMG%"],
+  circlet: ["HP%", "ATK%", "DEF%", "EM", "CRIT Rate%/CRIT DMG%", "Healing Bonus%"],
+} as const;
+
+export const substatOptions = ["CRIT Rate%/CRIT DMG%", "HP%", "ATK%", "DEF%", "EM", "ER"] as const;
+
+export const artifactSectionSchema = z.strictObject({
+  expectedVersion: z.number().int().positive(),
+  groups: z.array(z.strictObject({
+    name: z.string().trim().min(1).max(120),
+    rows: z.array(z.strictObject({
+      firstArtifactKey: catalogKey,
+      secondArtifactKey: catalogKey.nullable(),
+      percent,
+    })).max(50),
+  })).max(12),
+  sands: z.array(z.enum(mainStatOptions.sands)).max(2),
+  goblet: z.array(z.enum(mainStatOptions.goblet)).max(2),
+  circlet: z.array(z.enum(mainStatOptions.circlet)).max(2),
+  substats: z.array(z.enum(substatOptions)).max(substatOptions.length),
+  targets: z.array(z.strictObject({
+    stat: z.string().trim().min(1).max(80),
+    value: z.string().trim().min(1).max(80),
+  })).max(20),
+  talents: z.array(z.strictObject({
+    type: z.enum(["NA", "E", "Q"]),
+    priority: z.number().int().min(1).max(3),
+    level: z.string().trim().max(24).optional(),
+  })).max(3),
+  note: z.string().trim().max(2_000).nullable(),
+});
+
+export const constellationSectionSchema = z.strictObject({
+  expectedVersion: z.number().int().positive(),
+  rows: z.array(z.strictObject({
+    level: z.number().int().min(1).max(6),
+    detail: z.string().trim().min(1).max(2_000),
+    cumulativePercent: percent,
+  })).max(6),
+});
+
+export const teamSectionSchema = z.strictObject({
+  expectedVersion: z.number().int().positive(),
+  teams: z.array(z.strictObject({
+    title: z.string().trim().min(1).max(160),
+    rotationSeconds: z.coerce.number().finite().positive().max(9999),
+    combo: z.string().trim().min(1).max(2_000),
+    members: z.array(z.strictObject({
+      characterKey: catalogKey,
+      damage: z.coerce.number().finite().nonnegative().max(999_999_999_999),
+    })).length(4).refine((members) => new Set(members.map((member) => member.characterKey)).size === 4, {
+      message: "Team ต้องมีตัวละครไม่ซ้ำกัน 4 ตัว",
+    }).refine((members) => members.some((member) => member.damage > 0), {
+      message: "ความเสียหายรวมต้องมากกว่า 0",
+    }),
+  })).max(30),
+});
+
+export const extraSectionSchema = z.strictObject({
+  expectedVersion: z.number().int().positive(),
+  sections: z.array(z.strictObject({
+    title: z.string().trim().min(1).max(160),
+    rows: z.array(z.strictObject({
+      mediaId: z.string().uuid().nullable(),
+      heading: z.string().trim().min(1).max(200),
+      body: z.string().trim().max(2_000),
+      percent: percent.nullable(),
+    })).max(50),
+  })).max(20),
+});
+
+export type WeaponSectionInput = z.output<typeof weaponSectionSchema>;
+export type ArtifactSectionInput = z.output<typeof artifactSectionSchema>;
+export type ConstellationSectionInput = z.output<typeof constellationSectionSchema>;
+export type TeamSectionInput = z.output<typeof teamSectionSchema>;
+
+export function slugFromCharacterName(name: string, key: string): string {
+  const slug = name.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");
+  return slug || `character-${key.toLowerCase()}`;
+}