docs: Task #9 — finalize ONBOARDING.md + add IT-SETUP.md

- ONBOARDING.md (Hebrew, lawyer-facing): corrected install URL (.vsto), ribbon group name (Marcus-Law), first-run flow (open from ribbon), added the four feature sections, troubleshooting table, file locations, support channels - IT-SETUP.md (English, admin-facing): runner provisioning, codesign cert generation + Infisical storage + Gitea Actions secrets, GPO push of the public cert to attorney machines, nginx config for ClickOnce serving, per-user API key provisioning, release procedure, URL protocol install, monitoring + off-boarding + troubleshooting playbook Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 15:55:43 +03:00
parent f6d0c2bced
commit 5aa98d2d3a
2 changed files with 247 additions and 36 deletions
@@ -0,0 +1,175 @@
+# IT setup guide — Marcus-Law OutlookAddin
+
+Audience: IT admin. Walks you through deploying the ClickOnce installer, distributing the code-signing certificate via GPO, provisioning per-user EspoCRM API keys, and operating the add-in for the 10 attorneys at Marcus-Law.
+
+## Prerequisites
+
+- Windows AD domain (`marcus-law.local`) with GPO push to all attorney machines.
+- EspoCRM admin access on `https://crm.prod.marcus-law.co.il`.
+- SSH access to `platform.dev.marcus-law.co.il` for serving the ClickOnce artifacts.
+- Mattermost webhook for release notifications (`#git-verelasim`).
+- Infisical project `outlook-addin` for storing secrets.
+
+## 1. Build infrastructure
+
+### Windows CI runner (one-time)
+
+A Windows 11 Pro VM on Coolify hosts the Gitea Actions runner. It needs:
+
+- **Visual Studio Build Tools 2022** with workloads:
+  - `Microsoft.VisualStudio.Workload.Office` (for the VSTO MSBuild targets)
+  - `Microsoft.VisualStudio.Workload.ManagedDesktop` (for WPF)
+- **Windows SDK 10.0.22621** (for `signtool.exe`).
+- **.NET Framework 4.8 Developer Pack** (`mage.exe`).
+- **WSL Ubuntu** (for the `rsync` step of the publish job).
+- **Gitea act_runner** registered as a Windows service with label `windows`.
+
+### Code-signing certificate
+
+The runner needs a code-signing certificate in `Cert:\CurrentUser\My`. Generate a self-signed cert once:
+
+```powershell
+$cert = New-SelfSignedCertificate `
+  -Subject "CN=Marcus-Law OutlookAddin" `
+  -Type CodeSigningCert `
+  -CertStoreLocation Cert:\CurrentUser\My `
+  -NotAfter (Get-Date).AddYears(3) `
+  -KeyAlgorithm RSA `
+  -KeyLength 2048
+$thumbprint = $cert.Thumbprint
+$pfxPassword = ConvertTo-SecureString -String "<generated-password>" -Force -AsPlainText
+Export-PfxCertificate -Cert $cert -FilePath C:\codesign.pfx -Password $pfxPassword
+Export-Certificate  -Cert $cert -FilePath C:\codesign.cer   # public part — for GPO push
+```
+
+Store these in Infisical `/outlook-addin/`:
+
+| Key | Value |
+|---|---|
+| `CODESIGN_THUMBPRINT` | The cert thumbprint (40 hex chars) |
+| `CODESIGN_PFX_BASE64` | `[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\codesign.pfx"))` |
+| `CODESIGN_PASSWORD` | The PFX password |
+| `PLATFORM_DEV_SSH_KEY` | Base64 of the rsync target's ed25519 private key |
+| `MATTERMOST_WEBHOOK_RELEASES` | Incoming webhook URL for `#git-verelasim` |
+
+In Gitea (`Settings → Actions → Secrets`), add four secrets that reference Infisical:
+
+- `CODESIGN_THUMBPRINT`
+- `PLATFORM_DEV_SSH_KEY`
+- `MATTERMOST_WEBHOOK_RELEASES`
+
+(The PFX itself is imported once on the runner; the workflow only uses the thumbprint.)
+
+## 2. Deploy the certificate via GPO
+
+The ClickOnce installer refuses to launch unless the publishing certificate is in **Trusted Publishers** on each attorney's machine. Use GPO to push it.
+
+1. Copy `codesign.cer` to `\\marcus-law.local\SYSVOL\marcus-law.local\Scripts\certs\codesign.cer`.
+2. Open **Group Policy Management Console** → edit a GPO scoped to the attorney OU.
+3. Navigate to:
+   `Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies`
+4. Right-click **Trusted Publishers → Import…** and pick `codesign.cer`.
+5. Repeat under **Trusted Root Certification Authorities** (self-signed cert).
+6. Force update everywhere:
+   ```powershell
+   Invoke-Command -ComputerName (Get-ADComputer -Filter * -SearchBase "OU=Attorneys,DC=marcus-law,DC=local").Name -ScriptBlock { gpupdate /force }
+   ```
+7. Verify on one attorney machine:
+   ```powershell
+   certutil -store -user TrustedPublisher | findstr /C:"Marcus-Law OutlookAddin"
+   ```
+
+## 3. nginx — serve the ClickOnce artifacts
+
+On `platform.dev.marcus-law.co.il`, add `/etc/nginx/sites-available/outlook-addin.conf`:
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name platform.dev.marcus-law.co.il;
+    ssl_certificate     /etc/letsencrypt/live/platform.dev.marcus-law.co.il/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/platform.dev.marcus-law.co.il/privkey.pem;
+
+    location /outlook-addin/ {
+        alias /var/www/outlook-addin/;
+        autoindex off;
+        types {
+            application/x-ms-application application;
+            application/x-ms-manifest    manifest;
+            application/octet-stream     vsto;
+            application/octet-stream     deploy;
+        }
+        add_header Cache-Control "no-cache, must-revalidate";
+    }
+}
+```
+
+```bash
+sudo mkdir -p /var/www/outlook-addin
+sudo chown -R www-data:www-data /var/www/outlook-addin
+sudo ln -s /etc/nginx/sites-available/outlook-addin.conf /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+The CI runner pushes new versions here on every `v*` tag via the publish job.
+
+## 4. EspoCRM API key provisioning
+
+Per attorney:
+
+1. EspoCRM admin → **Administration → Users → Create**.
+2. **User Type:** API User (or a Regular User with the "API" role).
+3. **Username:** mail prefix (e.g. `chaim` for `chaim@marcus-law.co.il`).
+4. **Role:** at least: read Contact / Case / Account / Lead / Email; create Email; read EmailAddress.
+5. Save, then **Generate API Key**. Copy it.
+6. Store under Infisical `/outlook-addin/users/<email>` (or send via a 1-time link service).
+
+Send the attorney a personal email matching the ONBOARDING.md template, with their per-user key.
+
+## 5. Release procedure (each new version)
+
+1. Tag the commit on `main`:
+   ```bash
+   git tag v1.0.0
+   git push origin v1.0.0
+   ```
+2. Gitea Actions builds Release, signs, generates the ClickOnce artifacts, rsyncs to platform.dev, and posts to `#git-verelasim`.
+3. Smoke-test from a clean attorney machine (or a Windows 11 sandbox):
+   - Browse to `https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto`.
+   - The ClickOnce installer should run with **no security warning**. If you see "Unknown Publisher", the GPO cert hasn't propagated to that machine.
+   - First-run Settings → enter creds → Test Connection green.
+   - Send a test email to a known contact, hit "תייק ל-EspoCRM", confirm it appears in the EspoCRM activity stream.
+4. If a release goes badly, push a new tag with a fix; ClickOnce will roll all users forward automatically on their next Outlook start.
+
+## 6. URL protocol handler (optional)
+
+To make EspoCRM "Compose email" links open Outlook with the case pre-filled:
+
+1. After the ClickOnce install, run as the user:
+   ```powershell
+   & "$env:LOCALAPPDATA\Apps\OutlookAddinProtocolHandler\install-protocol.ps1"
+   ```
+2. Verify: `start outlookaddin://compose?caseId=<id>` should open a new Outlook composer with the case pre-populated. (Outlook must be already running so the named pipe is up.)
+3. To uninstall the registration: `uninstall-protocol.ps1`.
+
+## 7. Monitoring
+
+- **CI status** — Mattermost `#git-verelasim`, plus Gitea Actions UI.
+- **Server-side filing** — EspoCRM internal logs (`data/logs/espo-*.log`) for `/api/v1/MailRouter/file` calls.
+- **Client-side errors** — when an attorney reports an issue, ask them to send `%LOCALAPPDATA%\MarcusLaw\OutlookAddin\logs\addin-<date>.log`. Logs roll daily, retained 14 days.
+
+## 8. Off-boarding (attorney leaves)
+
+1. In EspoCRM admin, delete or disable the API User.
+2. Their `creds.dat` on the laptop is DPAPI-encrypted with their Windows user profile — wiping the profile (or the laptop) is enough.
+3. No central state to remove beyond EspoCRM.
+
+## 9. Troubleshooting playbook
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Install dialog says "Unknown Publisher" | GPO cert hasn't reached the machine | `gpupdate /force`, then `certutil -store -user TrustedPublisher` to confirm |
+| Add-in installs but ribbon group is missing | `Microsoft.VSTORuntime.4.0` missing | ClickOnce normally pulls it; if Office < 2019, install [VSTO 4 Runtime](https://www.microsoft.com/download/details.aspx?id=48217) manually |
+| Mass 401s after a renewal | API keys were rotated | Send new keys, ask users to re-open Settings and paste them |
+| Retry queue is growing | EspoCRM unreachable, or 5xx errors | Check EspoCRM health; once it's back, the processor drains the queue on its 30-second loop |
+| User says "categories disappeared" | They are local to that PC. If they reinstall Outlook on a new machine, categories don't sync (MAPI limitation) | Re-file is harmless — server-side dedups on `messageId` (409 returned, counted as success) |
@@ -2,63 +2,99 @@

 ## מה זה התוסף?

-תוסף ל-Outlook שמאפשר לתייק מיילים ל-EspoCRM ישירות מתוך Outlook, בלי להעתיק/להדביק או להגדיר BCC.
+תוסף ל-Outlook שמאפשר לתייק מיילים ל-EspoCRM ישירות מתוך Outlook, בלי להעתיק/להדביק או להגדיר BCC. ארבע יכולות עיקריות:
+
+1. **תיוק מייל קיים** — סמן מייל, לחץ "תייק ל-EspoCRM", בחר תיק/לקוח.
+2. **סרגל צד** — כשפותחים מייל, צד ימין מציג איזה לקוח/תיק קשור לשולח.
+3. **כתיבת מייל מתיק** — חלון מייל חדש מקבל כתובת+נושא לפי תיק נבחר, ומתויק אוטומטית כששולחים.
+4. **סנכרון תיקיות** — Outlook יסמן או יתייק לבד מיילים שנכנסים לתיקיות שבחרת לנטר.

 ## דרישות

- Windows 10 או Windows 11
+- Windows 10 / Windows 11
 - Outlook desktop (Microsoft 365 / Office 2021 / Office 2019)
- חיבור אינטרנט
- API key אישי ב-EspoCRM (תקבל מהאדמין)
+- .NET Framework 4.8 (כבר מותקן בכל הגרסאות הנתמכות)
+- חיבור אינטרנט ל-`crm.prod.marcus-law.co.il`
+- שם משתמש + API key אישי ב-EspoCRM (תקבל מהאדמין בנפרד)

 ## התקנה (5 דקות)

-1. סגור את Outlook לגמרי (`File → Exit`, או יציאה דרך System Tray).
-2. פתח את הלינק: **https://platform.dev.marcus-law.co.il/outlook-addin/setup.exe**
-3. לחץ "Install" בחלונית שתיפתח.
-4. ההתקנה תיגמר תוך 30 שניות. אם רואים שגיאת "Unknown Publisher" — פנה לאדמין (חסר אישור הצוות).
-5. פתח את Outlook. תראה ב-Ribbon תפריט חדש בשם "EspoCRM".
+1. סגור את Outlook לגמרי (`File → Exit`).
+2. פתח את הלינק במייל שהאדמין שלח: **https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto**
+3. ייפתח דיאלוג ClickOnce. לחץ **Install**.
+4. ההתקנה תיגמר תוך 30 שניות. אם רואים אזהרת "Unknown Publisher" — **אל תאשר**, פנה לאדמין; חסר אישור הצוות במחשב.
+5. פתח את Outlook. בלשונית **Home** של תיבת הדואר תופיע קבוצה חדשה בשם **Marcus-Law** עם שני כפתורים.

 ## הגדרה ראשונית

-1. בפעם הראשונה ש-Outlook ייפתח, ייפתח חלון "ברוך הבא ל-EspoCRM Add-in".
-2. **כתובת השרת** — מולא מראש: `https://crm.prod.marcus-law.co.il`
-3. **שם משתמש** — כתובת המייל שלך (לדוגמה `chaim@marcus-law.co.il`).
-4. **API Key** — הדבק את ה-key שקיבלת מהאדמין (נראה כמו `a1b2c3d4e5f6...`).
-5. לחץ "Test Connection". סימן ✓ ירוק = הכל עובד.
-6. לחץ "Save & Continue".
+1. בפעם הראשונה שתלחץ על "תייק ל-EspoCRM" יישאל אותך התוסף אם לפתוח הגדרות. ענה **כן**.
+2. בחלון ההגדרות, טאב **כללי**:
+   - **כתובת שרת EspoCRM** — מולא מראש: `https://crm.prod.marcus-law.co.il`
+   - **שם משתמש** — כתובת המייל שלך (לדוגמה `chaim@marcus-law.co.il`).
+   - **מפתח API** — הדבק את ה-key שקיבלת מהאדמין (נראה כמו `a1b2c3d4e5f6…`).
+   - **שפת ממשק** — עברית (ברירת מחדל) או English.
+3. לחץ **בדוק חיבור**. אם רואים "התחברות תקינה — משתמש: …" בירוק, הכל עובד.
+4. לחץ **שמור**. החלון ייסגר והתוסף יתחבר.

 ## שימוש יומיומי

-### תיוק מייל לתיק
- בחר מייל אחד או יותר ברשימה.
- לחץ "**File to EspoCRM**" ב-Ribbon.
- חפש את שם התיק או הלקוח, בחר, לחץ "File".
- המייל יקבל קטגוריה צבעונית "Filed: <שם>" בעמודת הצבע ב-Outlook.
+### תיוק מייל קיים
+1. סמן מייל אחד או יותר ב-Inbox (אפשר Ctrl-click או Shift-click).
+2. בלשונית **Home**, לחץ "**תייק ל-EspoCRM**".
+3. ייפתח חלון חיפוש — הקלד 2+ אותיות של שם תיק / לקוח / איש קשר.
+4. סמן את התיק הנכון ולחץ **תייק**. המייל יקבל קטגוריה "Filed: <שם>" בעמודת הצבע.
+5. אם השולח לא קיים ב-CRM, לחץ "**צור איש קשר חדש מהשולח**" כדי להוסיף אותו ולתייק אליו באותה פעולה.

-### מי הלקוח?
- כשפותחים מייל, סיידבר ימני יופיע עם פרטי הלקוח/התיק (אם קיים ב-EspoCRM).
- לחץ "Open in EspoCRM" כדי לעבור ישירות לתיק.
+### סרגל "פרטי תיק" (צד ימין)
+- ברגע שתפתח מייל יופיע סרגל ימני קטן עם איש הקשר, החברה ו-5 התיקים האחרונים.
+- **תייק לתיק הזה** — מתייק לתיק הראשון ברשימה.
+- **תייק למקום אחר** — פותח את חלון החיפוש הרגיל.
+- **פתח ב-EspoCRM** — פותח את כרטיס איש הקשר בדפדפן.

-### כתיבת מייל חדש מתוך תיק
- ב-EspoCRM, פתח תיק → לחץ "Email this case".
- Outlook ייפתח עם כתובת + נושא ממולאים אוטומטית.
+### כתיבת מייל מתיק
+1. פתח חלון מייל חדש (New Email).
+2. בלשונית **Message**, לחץ "**כתוב מתיק**".
+3. חפש ובחר תיק. התוסף ימלא אוטומטית את כתובת הנמען (איש קשר ראשי בתיק) ויוסיף בכותרת מספר תיק בסוגריים מרובעים, וקישור לתיק בסוף הגוף.
+4. כתוב ושלח. **כשתשלח, המייל יתויק אוטומטית** לאותו תיק ב-EspoCRM, בלי שתצטרך לעשות שום דבר נוסף.

-### סנכרון אוטומטי של תיקייה
- לחץ "**Settings**" ב-Ribbon → טאב "Folders".
- סמן את התיקיות שאתה רוצה לנטר (לדוגמה Inbox/Smith Family).
- בחר "Auto-file when confident" או "Notify only".
- מיילים שייכנסו לתיקיות האלו יסומנו/יתויקו אוטומטית.
+### סנכרון אוטומטי של תיקיות
+1. בלשונית **Home** לחץ "**הגדרות**" → טאב **תיקיות**.
+2. סמן את התיקיות שאתה רוצה לנטר (לדוגמה Inbox / לקוחות / כהן).
+3. בחר מצב:
+   - **התרעה בלבד** — Outlook יסמן את המייל ב-Categories עם "Needs filing" כדי שתראה ידנית.
+   - **תיוק אוטומטי** — התוסף יתייק לבד, רק אם הוא בטוח שהשולח הוא אותו לקוח (התאמה יחידה, חד-משמעית).
+4. שמור. מהרגע הזה, כל מייל שמגיע לתיקיות האלה יעבור עיבוד מיידי.
+
+### עדכון התוסף
+- אין צורך להתקין מחדש. ClickOnce בודק עדכונים אוטומטית פעם בשבוע.
+- אם רוצים לכפות עדכון: **File → Options → Add-ins → Click-Once Add-ins** או פשוט סגור ופתח את Outlook כעבור 7 ימים.

 ## בעיות נפוצות

 | בעיה | פתרון |
 |---|---|
-| Ribbon "EspoCRM" לא מופיע | File → Options → Add-ins → לוודא ש-MarcusLaw.OutlookAddin פעיל |
-| "401 Unauthorized" | API key לא נכון או הוחלף — פנה לאדמין |
-| "EspoCRM unreachable" | בדוק חיבור לאינטרנט; המיילים יישמרו בתור ויתויקו כשהחיבור יחזור |
-| Outlook איטי אחרי התקנה | סגור וטען מחדש את Outlook |
+| קבוצת "Marcus-Law" לא מופיעה ב-Ribbon | File → Options → Add-ins → לוודא ש-`MarcusLaw.OutlookAddin` פעיל; אם לא — Add → Browse → בחר ב-`MarcusLaw.OutlookAddin.vsto` |
+| "התוסף עדיין לא מוגדר" | פתח את ההגדרות והזן URL/שם משתמש/API key |
+| "מפתח ה-API נדחה" | API key לא נכון או הוחלף — פנה לאדמין לקבל key חדש |
+| "שגיאת חיבור לשרת" | אין אינטרנט או ה-CRM לא זמין — המיילים יישמרו בתור ויתויקו אוטומטית כשהחיבור יחזור |
+| תיוק לקח הרבה זמן | בדוק את כרטיסיית **Diagnostics** בהגדרות; ייתכן שהשרת איטי או שיש תור גדול ב-`%LOCALAPPDATA%\MarcusLaw\OutlookAddin\retry-queue\` |
+| Outlook איטי אחרי התקנה | סגור וטען מחדש את Outlook; אם נמשך, פנה לאדמין |
+
+## איפה נשמרים הקבצים?
+
+- **לוגים** — `%LOCALAPPDATA%\MarcusLaw\OutlookAddin\logs\addin-YYYYMMDD.log`
+- **הגדרות** — `%APPDATA%\MarcusLaw\OutlookAddin\settings.json`
+- **תור ניסיונות חוזרים** — `%LOCALAPPDATA%\MarcusLaw\OutlookAddin\retry-queue\*.json`
+- **API key** — `%APPDATA%\MarcusLaw\OutlookAddin\creds.dat` (מוצפן DPAPI; לא ניתן לקרוא בלי המשתמש שלך)

 ## דיווח על בעיה

-ב-Settings → טאב "Diagnostics" → לחץ "Send Diagnostic Logs". יווצר קובץ zip ב-`%TEMP%`. שלח אותו לאדמין.
+1. שלח מייל ל-`it@marcus-law.co.il`.
+2. צרף את התיקייה `%LOCALAPPDATA%\MarcusLaw\OutlookAddin\logs\` בלחיצה ימנית → Send to → Compressed (zipped) folder.
+3. תאר במשפט אחד מה ניסית לעשות ומה ראית במקום.
+
+## תמיכה
+
+- **Mattermost** — ערוץ `#תמיכה-טכנית` (לשאלות מהירות)
+- **מייל** — `it@marcus-law.co.il`
+- **שעות פתוחות** — יום שני 9:00–17:00, יום שלישי 9:00–13:00 בשבועיים הראשונים אחרי השקה