feat: cleanup_duplicates.py + Flex Query period warning

.github/workflows/docker-publish.yml

@@ -7,6 +7,12 @@ on:
       - staging
     tags:
       - "v*"
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Branch or tag to build"
+        required: false
+        default: "staging"
 
 jobs:
   build-and-push:
@@ -20,21 +26,21 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Extract metadata
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
           images: ghcr.io/${{ github.repository }}
           tags: |
@@ -44,7 +50,7 @@ jobs:
             type=raw,value=latest,enable={{is_default_branch}}
 
       - name: Build and push
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
         with:
           context: .
           platforms: linux/amd64,linux/arm64

CLAUDE.md

@@ -92,6 +92,7 @@ C'est la source de vérité durable : attachée au code, visible dans l'historiq
 - Branches : `fix/<sujet>`, `feat/<sujet>`, `refactor/<sujet>`
 - Commits : `fix:`, `feat:`, `refactor:`, `chore:` — message court, impératif
 - PRs : isolées par concern, une PR = un fix
+- Merge strategy : merge commit uniquement (squash et rebase désactivés sur GitHub) — évite la divergence staging/main
 - CI build l'image sur push `main` → pas de tag manuel nécessaire pour `latest`
 
 ## 5. Findings d'audit
@@ -126,9 +127,13 @@ Tester avec les vraies APIs en mode lecture d'abord (`GET /api/v1/activities`),
 ## 7. CI / déploiement
 
 ```
-push main → GitHub Actions build linux/amd64 + linux/arm64
-           → push ghcr.io/flowcool/ghostfolio-ibkr-sync:latest
-           → Portainer poll repo infra → redéploie le container
+push main    → GitHub Actions build linux/amd64 + linux/arm64
+             → push ghcr.io/flowcool/ghostfolio-ibkr-sync:latest
+             → Portainer poll repo infra → redéploie le container
+
+push staging → GitHub Actions build linux/amd64 + linux/arm64
+             → push ghcr.io/flowcool/ghostfolio-ibkr-sync:staging
+             → tester manuellement sur le NAS avant merge sur main
 ```
 
 Pour switcher vers l'image du fork (PRs toutes mergées — à faire) :

README.md

@@ -48,6 +48,25 @@ Multi-arch image (linux/amd64 and linux/arm64). New images are published automat
 1. On the same Flex Queries page, click **Create** under **Activity Flex Query**
 2. Give it a name like `Ghostfolio Sync - Individual`
 3. Set the period to **Last 365 Calendar Days**
+
+   > **⚠️ Critical — do not use a shorter period (e.g. Last Month, Last Quarter)**
+   >
+   > The sync script relies on the 365-day window to match opening and closing trades.
+   > A shorter period causes two classes of silent failures:
+   >
+   > - **Missing sells**: a sell trade within the period whose matching buy is outside the
+   >   window will be skipped without error (the script sees only a closing trade with no
+   >   corresponding open and drops it to avoid creating phantom short positions).
+   > - **Silent re-imports on period change**: if you later switch to 365 days, all trades
+   >   from the gap period will look new to the dedup system — creating duplicates for any
+   >   trades you had previously entered manually or synced under a different period.
+   >
+   > **Recovery if you already used a shorter period:**
+   > The script ships with `cleanup_duplicates.py`. Run it in dry-run mode first
+   > (`python cleanup_duplicates.py`), then with `--apply` once you have verified the
+   > output. It patches existing manual entries with their IBKR trade ID so future syncs
+   > recognise them, and removes the duplicate IBKR-synced copies.
+
 4. Select the following sections and fields:
 
 **Account Information:**