@portaki/module-sections 1.0.0

package/backend/pom.xml

@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>app.portaki.module</groupId>
+  <artifactId>sections-backend</artifactId>
+  <version>0.1.0</version>
+  <packaging>jar</packaging>
+
+  <name>Sections module (Java backend)</name>
+  <description>Gateway handlers and persistence for the Portaki sections editorial module.</description>
+
+  <properties>
+    <java.version>21</java.version>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>app.portaki</groupId>
+      <artifactId>portaki-module-sdk</artifactId>
+      <version>0.6.0</version>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-context</artifactId>
+      <version>6.2.5</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-jdbc</artifactId>
+      <version>6.2.5</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+      <version>2.18.2</version>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.14.0</version>
+        <configuration>
+          <release>${java.version}</release>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>

package/backend/src/main/java/app/portaki/module/sections/SectionsGatewayModule.java

@@ -0,0 +1,251 @@
+package app.portaki.module.sections;
+
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.time.Instant;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Component;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import app.portaki.sdk.gateway.GatewayModuleContext;
+import app.portaki.sdk.gateway.PortakiCommandHandler;
+import app.portaki.sdk.gateway.PortakiQueryHandler;
+import app.portaki.sdk.module.PortakiModule;
+
+@Component
+@PortakiModule("sections")
+public class SectionsGatewayModule {
+
+    private final JdbcTemplate jdbc;
+    private final ObjectMapper objectMapper;
+
+    public SectionsGatewayModule(JdbcTemplate jdbc, ObjectMapper objectMapper) {
+        this.jdbc = jdbc;
+        this.objectMapper = objectMapper;
+    }
+
+    @PortakiQueryHandler(value = "sections.list", scope = "property:read")
+    public Map<String, Object> listSections(Map<String, Object> params, GatewayModuleContext ctx) {
+        UUID tenantId = ctx.tenantIdInternal();
+        UUID propertyId = UUID.fromString(ctx.propertyId());
+        List<Map<String, Object>> rows =
+                jdbc.query(
+                        """
+                        SELECT id, sort_order, title_fr, title_en, content_fr, content_en, updated_at
+                        FROM t_e_module_sections_item
+                        WHERE tenant_id = ? AND property_id = ?
+                        ORDER BY sort_order ASC, created_at ASC
+                        """,
+                        (rs, rowNum) -> toSectionRow(rs),
+                        tenantId,
+                        propertyId);
+        return Map.of("sections", rows);
+    }
+
+    @PortakiCommandHandler(value = "sections.section.save", scope = "host:property:write")
+    public void saveSection(Map<String, Object> params, GatewayModuleContext ctx) {
+        UUID tenantId = ctx.tenantIdInternal();
+        UUID propertyId = UUID.fromString(ctx.propertyId());
+        String idRaw = stringParam(params, "id");
+        UUID id = idRaw == null || idRaw.isBlank() ? UUID.randomUUID() : UUID.fromString(idRaw);
+        String titleFr = stringParam(params, "titleFr");
+        String titleEn = stringParam(params, "titleEn");
+        JsonNode contentFr = readJsonParam(params, "contentFr");
+        JsonNode contentEn = readJsonParam(params, "contentEn");
+        int sortOrder = intParam(params, "sortOrder", nextSortOrder(tenantId, propertyId, id));
+
+        if (titleFr == null || titleFr.isBlank()) {
+            throw new IllegalArgumentException("title_fr_required");
+        }
+        if (titleEn == null || titleEn.isBlank()) {
+            titleEn = titleFr;
+        }
+
+        boolean exists =
+                Boolean.TRUE.equals(
+                        jdbc.queryForObject(
+                                """
+                                SELECT EXISTS(
+                                  SELECT 1 FROM t_e_module_sections_item
+                                  WHERE id = ? AND tenant_id = ? AND property_id = ?
+                                )
+                                """,
+                                Boolean.class,
+                                id,
+                                tenantId,
+                                propertyId));
+
+        if (exists) {
+            jdbc.update(
+                    """
+                    UPDATE t_e_module_sections_item
+                    SET title_fr = ?, title_en = ?, content_fr = ?::jsonb, content_en = ?::jsonb,
+                        sort_order = ?, updated_at = ?
+                    WHERE id = ? AND tenant_id = ? AND property_id = ?
+                    """,
+                    titleFr,
+                    titleEn,
+                    jsonOrNull(contentFr),
+                    jsonOrNull(contentEn),
+                    sortOrder,
+                    Instant.now(),
+                    id,
+                    tenantId,
+                    propertyId);
+        } else {
+            jdbc.update(
+                    """
+                    INSERT INTO t_e_module_sections_item (
+                      id, tenant_id, property_id, sort_order, title_fr, title_en,
+                      content_fr, content_en, created_at, updated_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?::jsonb, ?::jsonb, ?, ?)
+                    """,
+                    id,
+                    tenantId,
+                    propertyId,
+                    sortOrder,
+                    titleFr,
+                    titleEn,
+                    jsonOrNull(contentFr),
+                    jsonOrNull(contentEn),
+                    Instant.now(),
+                    Instant.now());
+        }
+
+    }
+
+    @PortakiCommandHandler(value = "sections.section.delete", scope = "host:property:write")
+    public void deleteSection(Map<String, Object> params, GatewayModuleContext ctx) {
+        UUID tenantId = ctx.tenantIdInternal();
+        UUID propertyId = UUID.fromString(ctx.propertyId());
+        String idRaw = stringParam(params, "id");
+        if (idRaw == null || idRaw.isBlank()) {
+            throw new IllegalArgumentException("id_required");
+        }
+        UUID id = UUID.fromString(idRaw);
+        int deleted =
+                jdbc.update(
+                        """
+                        DELETE FROM t_e_module_sections_item
+                        WHERE id = ? AND tenant_id = ? AND property_id = ?
+                        """,
+                        id,
+                        tenantId,
+                        propertyId);
+        if (deleted == 0) {
+            throw new IllegalArgumentException("section_not_found");
+        }
+    }
+
+    @PortakiCommandHandler(value = "sections.reorder", scope = "host:property:write")
+    public void reorder(Map<String, Object> params, GatewayModuleContext ctx) {
+        UUID tenantId = ctx.tenantIdInternal();
+        UUID propertyId = UUID.fromString(ctx.propertyId());
+        Object raw = params.get("orderedIds");
+        if (!(raw instanceof List<?> list) || list.isEmpty()) {
+            throw new IllegalArgumentException("ordered_ids_required");
+        }
+        int order = 0;
+        for (Object item : list) {
+            if (item == null) {
+                continue;
+            }
+            UUID id = UUID.fromString(item.toString());
+            jdbc.update(
+                    """
+                    UPDATE t_e_module_sections_item
+                    SET sort_order = ?, updated_at = ?
+                    WHERE id = ? AND tenant_id = ? AND property_id = ?
+                    """,
+                    order++,
+                    Instant.now(),
+                    id,
+                    tenantId,
+                    propertyId);
+        }
+    }
+
+    private Map<String, Object> toSectionRow(ResultSet rs) throws SQLException {
+        Map<String, Object> row = new HashMap<>();
+        row.put("id", rs.getObject("id", UUID.class).toString());
+        row.put("sortOrder", rs.getInt("sort_order"));
+        row.put("titleFr", rs.getString("title_fr"));
+        row.put("titleEn", rs.getString("title_en"));
+        row.put("contentFr", parseJsonColumn(rs.getString("content_fr")));
+        row.put("contentEn", parseJsonColumn(rs.getString("content_en")));
+        Instant updatedAt = rs.getObject("updated_at", Instant.class);
+        if (updatedAt != null) {
+            row.put("updatedAt", updatedAt.toString());
+        }
+        return row;
+    }
+
+    private Object parseJsonColumn(String raw) {
+        if (raw == null || raw.isBlank()) {
+            return null;
+        }
+        try {
+            return objectMapper.readValue(raw, Object.class);
+        } catch (JsonProcessingException e) {
+            return null;
+        }
+    }
+
+    private int nextSortOrder(UUID tenantId, UUID propertyId, UUID exceptId) {
+        Integer max =
+                jdbc.queryForObject(
+                        """
+                        SELECT COALESCE(MAX(sort_order), -1)
+                        FROM t_e_module_sections_item
+                        WHERE tenant_id = ? AND property_id = ? AND id <> ?
+                        """,
+                        Integer.class,
+                        tenantId,
+                        propertyId,
+                        exceptId);
+        return max == null ? 0 : max + 1;
+    }
+
+    private static String stringParam(Map<String, Object> params, String key) {
+        Object v = params.get(key);
+        return v == null ? null : v.toString();
+    }
+
+    private static int intParam(Map<String, Object> params, String key, int defaultValue) {
+        Object v = params.get(key);
+        if (v == null) {
+            return defaultValue;
+        }
+        if (v instanceof Number n) {
+            return n.intValue();
+        }
+        return Integer.parseInt(v.toString());
+    }
+
+    private JsonNode readJsonParam(Map<String, Object> params, String key) {
+        Object v = params.get(key);
+        if (v == null) {
+            return null;
+        }
+        return objectMapper.valueToTree(v);
+    }
+
+    private String jsonOrNull(JsonNode node) {
+        if (node == null || node.isNull()) {
+            return null;
+        }
+        try {
+            return objectMapper.writeValueAsString(node);
+        } catch (JsonProcessingException e) {
+            throw new IllegalArgumentException("invalid_json", e);
+        }
+    }
+}

package/backend/src/main/java/app/portaki/module/sections/SectionsModuleBackendConfiguration.java

@@ -0,0 +1,8 @@
+package app.portaki.module.sections;
+
+import org.springframework.context.annotation.ComponentScan;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@ComponentScan(basePackageClasses = SectionsGatewayModule.class)
+public class SectionsModuleBackendConfiguration {}

package/backend/target/maven-archiver/pom.properties

@@ -0,0 +1,3 @@
+artifactId=sections-backend
+groupId=app.portaki.module
+version=0.1.0

package/backend/target/maven-status/maven-compiler-plugin/compile/default-compile/createdFiles.lst

@@ -0,0 +1,2 @@
+app/portaki/module/sections/SectionsGatewayModule.class
+app/portaki/module/sections/SectionsModuleBackendConfiguration.class

package/backend/target/maven-status/maven-compiler-plugin/compile/default-compile/inputFiles.lst

@@ -0,0 +1,2 @@
+/Users/cyrilcolinet/Documents/Projects/PortakiApp/Repositories/portaki-modules/modules/sections/backend/src/main/java/app/portaki/module/sections/SectionsGatewayModule.java
+/Users/cyrilcolinet/Documents/Projects/PortakiApp/Repositories/portaki-modules/modules/sections/backend/src/main/java/app/portaki/module/sections/SectionsModuleBackendConfiguration.java

package/db/README.md

@@ -0,0 +1,8 @@
+# Schéma `sections`
+
+- **Propriété** : module `sections` (`app.portaki.module.sections`).
+- **Source de vérité** : `schema.sql` dans ce dossier.
+- **Application aujourd’hui** : copie versionnée dans `portaki-api/.../db/migration/V58__module_sections_items.sql` (Flyway unique sur la base core).
+- **Cible** : job **Atlas** / `portaki-module-migrator` (schéma Postgres dédié ou préfixe module) — voir `portaki-internal-docs/MODULE_PLATFORM_PREPARATION.md`.
+
+Ne pas ajouter d’entités JPA pour ce module dans `portaki-api` : persistance dans `backend/` uniquement.

package/db/schema.sql

@@ -0,0 +1,18 @@
+-- Canonical DDL for module `sections` (review in portaki-modules).
+-- Runtime: copied to portaki-api Flyway until Atlas module migrator exists.
+
+CREATE TABLE t_e_module_sections_item (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id UUID NOT NULL REFERENCES t_e_tenants (id),
+    property_id UUID NOT NULL REFERENCES t_e_properties (id) ON DELETE CASCADE,
+    sort_order INT NOT NULL DEFAULT 0,
+    title_fr TEXT NOT NULL DEFAULT '',
+    title_en TEXT NOT NULL DEFAULT '',
+    content_fr JSONB,
+    content_en JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX t_e_module_sections_item_property_idx
+    ON t_e_module_sections_item (tenant_id, property_id);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@portaki/module-sections",
+  "version": "1.0.0",
+  "description": "Portaki module — editorial sections (TipTap)",
+  "license": "AGPL-3.0",
+  "type": "module",
+  "main": "./src/index.tsx",
+  "scripts": {
+    "lint": "echo \"no lint yet\""
+  },
+  "dependencies": {
+    "@portaki/module-sdk": "0.5.0",
+    "@portaki/sdk": "^0.5.0",
+    "@tiptap/core": "^3.0.0",
+    "@tiptap/html": "^3.0.0",
+    "@tiptap/starter-kit": "^3.0.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "typescript": "^5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PortakiApp/portaki-modules.git",
+    "directory": "modules/sections"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/portaki.module.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://raw.githubusercontent.com/PortakiApp/portaki-sdk/main/schema/module.v1.json",
+  "id": "sections",
+  "name": {
+    "fr": "Sections éditoriales",
+    "en": "Editorial sections"
+  },
+  "description": {
+    "fr": "Blocs de contenu riches (TipTap) pour le carnet d’accueil invité.",
+    "en": "Rich content blocks (TipTap) for the guest welcome book."
+  },
+  "version": "1.0.0",
+  "author": {
+    "name": "Portaki",
+    "url": "https://portaki.app",
+    "type": "official"
+  },
+  "icon": "file-text",
+  "type": "official",
+  "tags": ["editorial", "content", "sections"],
+  "portakiVersionMin": "1.0.0",
+  "requiresHostSdk": "0.6.0",
+  "license": "AGPL-3.0",
+  "repository": "https://github.com/PortakiApp/portaki-modules",
+  "scopes": [
+    "stay:read",
+    "property:read",
+    "host:property:read",
+    "host:property:write"
+  ],
+  "queries": [
+    {
+      "name": "sections.list",
+      "description": {
+        "fr": "Liste des sections du logement.",
+        "en": "Property editorial sections."
+      },
+      "scope": "property:read"
+    }
+  ],
+  "commands": [
+    {
+      "name": "sections.section.save",
+      "description": {
+        "fr": "Créer ou mettre à jour une section.",
+        "en": "Create or update a section."
+      },
+      "scope": "host:property:write"
+    },
+    {
+      "name": "sections.section.delete",
+      "description": {
+        "fr": "Supprimer une section.",
+        "en": "Delete a section."
+      },
+      "scope": "host:property:write"
+    },
+    {
+      "name": "sections.reorder",
+      "description": {
+        "fr": "Réordonner les sections.",
+        "en": "Reorder sections."
+      },
+      "scope": "host:property:write"
+    }
+  ],
+  "hostSurfaces": [
+    {
+      "type": "property-workspace-tab",
+      "pathSegment": "sections",
+      "label": { "fr": "Sections", "en": "Sections" },
+      "icon": "file-text"
+    }
+  ],
+  "config": {
+    "defaults": {},
+    "fields": []
+  },
+  "catalog": {
+    "tagline": {
+      "fr": "Composez votre carnet section par section.",
+      "en": "Build your welcome book section by section."
+    },
+    "npmPackage": "@portaki/module-sections",
+    "npmUrl": "https://www.npmjs.com/package/@portaki/module-sections",
+    "javaArtifact": "app.portaki.module:sections-backend:0.1.0"
+  }
+}

package/src/components/SectionsGuestView.tsx

@@ -0,0 +1,68 @@
+'use client'
+
+import type { JSONContent } from '@tiptap/core'
+import { generateHTML } from '@tiptap/html'
+import StarterKit from '@tiptap/starter-kit'
+import { usePortakiQuery } from '@portaki/sdk'
+import type { LangCode } from '@portaki/module-sdk'
+import { ModuleSection } from '@portaki/module-sdk'
+
+type SectionRow = {
+  id: string
+  sortOrder: number
+  titleFr: string
+  titleEn: string
+  contentFr: unknown
+  contentEn: unknown
+}
+
+type ListResponse = {
+  sections: SectionRow[]
+}
+
+const htmlExtensions = [StarterKit]
+
+function contentToHtml(raw: unknown): string {
+  if (raw == null) return ''
+  try {
+    const doc = (typeof raw === 'string' ? JSON.parse(raw) : raw) as JSONContent
+    return generateHTML(doc, htmlExtensions)
+  } catch {
+    return ''
+  }
+}
+
+export function SectionsGuestView({ lang }: { lang: LangCode }) {
+  const { data, isLoading, isError } = usePortakiQuery<ListResponse>('sections.list', {})
+
+  if (isLoading) {
+    return (
+      <ModuleSection>
+        <p className="text-sm opacity-70">{lang === 'fr' ? 'Chargement…' : 'Loading…'}</p>
+      </ModuleSection>
+    )
+  }
+
+  if (isError || !data?.sections?.length) {
+    return null
+  }
+
+  return (
+    <div className="space-y-10">
+      {data.sections.map((section) => {
+        const title = lang === 'en' ? section.titleEn || section.titleFr : section.titleFr
+        const html = contentToHtml(lang === 'en' ? section.contentEn : section.contentFr)
+        return (
+          <ModuleSection key={section.id} title={title}>
+            {html ? (
+              <div
+                className="portaki-sections-prose text-[15px] leading-relaxed [&_h1]:text-2xl [&_h2]:text-xl [&_h3]:text-lg [&_p]:my-2 [&_ul]:my-2 [&_ol]:my-2"
+                dangerouslySetInnerHTML={{ __html: html }}
+              />
+            ) : null}
+          </ModuleSection>
+        )
+      })}
+    </div>
+  )
+}

package/src/index.tsx

@@ -0,0 +1,17 @@
+import type { ModuleContext } from '@portaki/module-sdk'
+import { definePortakiModule } from '@portaki/module-sdk'
+
+import { SectionsGuestView } from './components/SectionsGuestView'
+
+export default definePortakiModule({
+  id: 'sections',
+  label: { fr: 'Sections', en: 'Sections' },
+  description: {
+    fr: 'Contenus éditoriaux du carnet d’accueil.',
+    en: 'Welcome book editorial content.',
+  },
+  version: '1.0.0',
+  icon: 'file-text',
+  navSlot: 'section',
+  render: ({ lang }: ModuleContext) => <SectionsGuestView lang={lang} />,
+})