fix(encryption): explain preflight failures with notebook context

Author: tamlok

changes.md

@@ -1,6 +1,7 @@
 # Changes
 ## Unreleased
 * Fix note encryption failing with "Not found" when the notebook has an empty Git sync directory
+* Explain encryption preflight failures with notebook locations and localized guidance for unreadable sync metadata or conflicting key files
 * Remove buffer reload logging and log external file changes only at debug level to avoid log-viewing feedback at normal log levels
 * Keep the custom title bar Close icon visible on hover in Dreamy and Jadeite themes
 * Match the United Entry icon color to the other main toolbar icons, including live theme changes

libs/vxcore

@@ -5877,6 +5877,30 @@ This will re-scan all files and rebuild the metadata cache from the filesystem.<
         <source>Encrypt Note</source>
         <translation>ノートを暗号化</translation>
     </message>
+    <message>
+        <source>Cannot check encryption key conflicts in the notebook's local Git sync data (vx_notebook/vx_sync). Check folder permissions and repair the local sync repository before retrying. Do not delete encryption.vne or Git history.</source>
+        <translation>ノートブックのローカル Git 同期データ（vx_notebook/vx_sync）の暗号鍵の競合を確認できません。フォルダーのアクセス権を確認し、ローカル同期リポジトリを修復してから再試行してください。encryption.vne や Git の履歴を削除しないでください。</translation>
+    </message>
+    <message>
+        <source>The notebook key file (vx_notebook/encryption.vne) has an unresolved sync conflict. Back up the notebook and resolve that conflict before retrying. Do not delete the key file or merge its contents as text.</source>
+        <translation>ノートブックの鍵ファイル（vx_notebook/encryption.vne）に未解決の同期競合があります。ノートブックをバックアップし、その競合を解決してから再試行してください。鍵ファイルを削除したり、内容をテキストとしてマージしたりしないでください。</translation>
+    </message>
+    <message>
+        <source>Master-password source notebook: %1</source>
+        <translation>マスターパスワードの提供元ノートブック: %1</translation>
+    </message>
+    <message>
+        <source>Could not prepare note encryption.
+
+Notebook: %1
+
+%2</source>
+        <translation>ノートの暗号化を準備できませんでした。
+
+ノートブック: %1
+
+%2</translation>
+    </message>
     <message>
         <location line="-60"/>
         <source>Select notes from one notebook at a time.</source>

src/data/core/translations/vnote_ja.ts

@@ -5877,6 +5877,30 @@ This will re-scan all files and rebuild the metadata cache from the filesystem.<
         <source>Encrypt Note</source>
         <translation>加密笔记</translation>
     </message>
+    <message>
+        <source>Cannot check encryption key conflicts in the notebook's local Git sync data (vx_notebook/vx_sync). Check folder permissions and repair the local sync repository before retrying. Do not delete encryption.vne or Git history.</source>
+        <translation>无法检查笔记本本地 Git 同步数据（vx_notebook/vx_sync）中的加密密钥冲突。请检查文件夹权限并修复本地同步仓库后重试。请勿删除 encryption.vne 或 Git 历史记录。</translation>
+    </message>
+    <message>
+        <source>The notebook key file (vx_notebook/encryption.vne) has an unresolved sync conflict. Back up the notebook and resolve that conflict before retrying. Do not delete the key file or merge its contents as text.</source>
+        <translation>笔记本密钥文件（vx_notebook/encryption.vne）存在未解决的同步冲突。请先备份笔记本并解决该冲突，然后重试。请勿删除密钥文件或以文本方式合并其内容。</translation>
+    </message>
+    <message>
+        <source>Master-password source notebook: %1</source>
+        <translation>主密码来源笔记本：%1</translation>
+    </message>
+    <message>
+        <source>Could not prepare note encryption.
+
+Notebook: %1
+
+%2</source>
+        <translation>无法准备笔记加密。
+
+笔记本：%1
+
+%2</translation>
+    </message>
     <message>
         <location line="-60"/>
         <source>Select notes from one notebook at a time.</source>

src/data/core/translations/vnote_zh_CN.ts

@@ -237,11 +237,33 @@ VxCoreError NotebookExplorer2::prepareNotebookEncryption(const QString &p_notebo
     p_errorMessage = tr("The note encryption services are unavailable.");
     return VXCORE_ERR_NOT_INITIALIZED;
   }
-  const auto fail = [&](VxCoreError p_error, const QString &p_message = QString()) {
-    p_errorMessage = !p_message.isEmpty() ? p_message
-                     : p_error == VXCORE_ERR_ENCRYPTION_AUTH_FAILED
-                         ? tr("Unable to unlock: incorrect password or damaged key data")
-                         : QString::fromUtf8(vxcore_error_message(p_error));
+  const auto fail = [&](VxCoreError p_error, const QString &p_message = QString(),
+                        const QString &p_sourceId = QString()) {
+    QString message;
+    if (p_error == VXCORE_ERR_ENCRYPTION_SYNC_STATE) {
+      message = tr("Cannot check encryption key conflicts in the notebook's local Git sync data "
+                   "(vx_notebook/vx_sync). Check folder permissions and repair the local sync "
+                   "repository before retrying. Do not delete encryption.vne or Git history.");
+    } else if (p_error == VXCORE_ERR_SYNC_CONFLICT) {
+      message = tr("The notebook key file (vx_notebook/encryption.vne) has an unresolved sync "
+                   "conflict. Back up the notebook and resolve that conflict before retrying. "
+                   "Do not delete the key file or merge its contents as text.");
+    } else if (p_error == VXCORE_ERR_ENCRYPTION_AUTH_FAILED) {
+      message = tr("Unable to unlock: incorrect password or damaged key data");
+    } else {
+      message = p_message.isEmpty() ? QString::fromUtf8(vxcore_error_message(p_error)) : p_message;
+    }
+    const auto location = [&](const QString &p_id) {
+      const auto path = notebooks->buildAbsolutePath(p_id, QString());
+      return path.isEmpty() ? p_id : QDir::toNativeSeparators(path);
+    };
+    QString notebook = location(p_notebookId);
+    if (!p_sourceId.isEmpty() && p_sourceId != p_notebookId) {
+      notebook +=
+          QLatin1Char('\n') + tr("Master-password source notebook: %1").arg(location(p_sourceId));
+    }
+    p_errorMessage =
+        tr("Could not prepare note encryption.\n\nNotebook: %1\n\n%2").arg(notebook, message);
     return p_error;
   };
   const auto unlock = [&](const QString &p_id, const QString &p_name) {
@@ -257,7 +279,9 @@ VxCoreError NotebookExplorer2::prepareNotebookEncryption(const QString &p_notebo
     passwordText.fill(QChar(0));
     passwordText.clear();
     p_progress.setLabelText(tr("Unlocking notebook..."));
-    return m_viewAreaController->unlockNoteEncryption(p_id, password);
+    const auto error = m_viewAreaController->unlockNoteEncryption(p_id, password);
+    return error == VXCORE_OK || error == VXCORE_ERR_CANCELLED ? error
+                                                               : fail(error, QString(), p_id);
   };
 
   VxCoreError statusError = VXCORE_OK;
@@ -272,8 +296,7 @@ VxCoreError NotebookExplorer2::prepareNotebookEncryption(const QString &p_notebo
     const QString name = notebooks->getNotebookConfig(p_notebookId)
                              .value(QLatin1String(vxcore::kJsonKeyName))
                              .toString();
-    const auto error = unlock(p_notebookId, name);
-    return error == VXCORE_OK || error == VXCORE_ERR_CANCELLED ? error : fail(error);
+    return unlock(p_notebookId, name);
   }
 
   struct Source {
@@ -326,7 +349,7 @@ VxCoreError NotebookExplorer2::prepareNotebookEncryption(const QString &p_notebo
     if (!source.unlocked) {
       const auto error = unlock(source.id, source.label);
       if (error != VXCORE_OK) {
-        return error == VXCORE_ERR_CANCELLED ? error : fail(error);
+        return error;
       }
     }
   } else {
@@ -375,7 +398,7 @@ VxCoreError NotebookExplorer2::prepareNotebookEncryption(const QString &p_notebo
   }
   p_progress.setLabelText(tr("Preparing the notebook key..."));
   p_setup = m_viewAreaController->prepareNoteEncryption(p_notebookId, sourceId, password);
-  return p_setup.isValid() ? VXCORE_OK : fail(p_setup.m_error, p_setup.m_errorMessage);
+  return p_setup.isValid() ? VXCORE_OK : fail(p_setup.m_error, p_setup.m_errorMessage, sourceId);
 }
 
 NewNoteResult NotebookExplorer2::createEncryptedNote(const NewNoteInput &p_input) {