feat(mail): mail history query for the dashboard

IMail::GetMailHistory and CountMailHistory return mail rows as stored,
deleted mail included, newest first, with the sender's and receiver's
accounts. Filters: character (sent or received), account, text in the
subject, body or a name (LIKE wildcards matched literally), state
(unread, read, attachment waiting, claimed, deleted) and whether to
include deleted mail. MySQL and SQLite share the SQL (MailSql.h).

Check: parity test ParitySeeded.Mail (GetMailHistory).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

dDatabase/GameDatabase/ITables/IMail.h

@@ -3,7 +3,9 @@
 
 #include <cstdint>
 #include <optional>
+#include <string>
 #include <string_view>
+#include <vector>
 
 #include "dCommonVars.h"
 #include "NiQuaternion.h"
@@ -12,6 +14,50 @@
  
 class IMail {
 public:
+	// A mail row as stored, for the dashboard (deleted mail included)
+	struct MailRecord {
+		uint64_t id{};
+		LWOOBJID senderId{};          // 0: from the game or the dashboard
+		std::string senderName;
+		uint32_t senderAccountId{};   // 0 when the sender isn't a character (or it was deleted)
+		LWOOBJID receiverId{};
+		std::string receiverName;
+		uint32_t receiverAccountId{};
+		int64_t timeSent{};
+		std::string subject;
+		std::string body;
+		LWOOBJID attachmentId{};
+		LOT attachmentLot{};          // 0 once the attachment was claimed (attachmentCount stays)
+		LWOOBJID attachmentSubkey{};
+		int32_t attachmentCount{};
+		std::string attachmentConfig;
+		bool read{};
+		int64_t deletedAt{};          // when the player deleted it; 0: not deleted
+	};
+
+	enum class eMailState : uint8_t {
+		ANY,
+		UNREAD,     // not deleted
+		READ,       // not deleted
+		ATTACHMENT, // an attachment waits to be claimed
+		CLAIMED,    // the attachment was claimed
+		DELETED     // deleted by the player
+	};
+
+	struct MailQuery {
+		LWOOBJID characterId{};   // sent or received by this character (0: anyone)
+		uint32_t accountId{};     // sent or received by a character of this account (0: anyone)
+		std::string search;       // text in the subject, body or a name
+		eMailState state{ eMailState::ANY };
+		bool includeDeleted{ true };
+		uint32_t offset{};
+		uint32_t limit{ 100 };
+	};
+
+	// Mail rows matching the query, newest first
+	virtual std::vector<MailRecord> GetMailHistory(const MailQuery& query) = 0;
+	virtual uint64_t CountMailHistory(const MailQuery& query) = 0;
+
 	// Insert a new mail into the database.
 	virtual void InsertNewMail(const MailInfo& mail) = 0;
 

dDatabase/GameDatabase/ITables/MailSql.h

@@ -0,0 +1,42 @@
+#ifndef MAILSQL_H
+#define MAILSQL_H
+
+#include <string>
+
+#include "IMail.h"
+
+// The dashboard's mail history query, shared by the MySQL and SQLite backends (they differ only in how LIKE patterns are
+// built). Every filter binds its parameters whether it is on or off, so one argument list fits every query:
+// characterId x3, accountId x3, search, then the search pattern x4.
+namespace MailSql {
+	inline std::string Select() {
+		return "SELECT m.id, m.sender_id, m.sender_name, m.receiver_id, m.receiver_name, m.time_sent, m.subject, m.body, m.attachment_id, "
+			"m.attachment_lot, m.attachment_subkey, m.attachment_count, m.attachment_config, m.was_read, m.deleted_at, "
+			"COALESCE(s.account_id, 0) AS sender_account, COALESCE(r.account_id, 0) AS receiver_account "
+			"FROM mail AS m LEFT JOIN charinfo AS s ON m.sender_id <> 0 AND s.id = m.sender_id LEFT JOIN charinfo AS r ON r.id = m.receiver_id";
+	}
+
+	// `like` is the pattern for "contains ?", e.g. CONCAT('%', ?, '%') or '%' || ? || '%'
+	inline std::string Where(const IMail::MailQuery& q, const std::string& like) {
+		using eMailState = IMail::eMailState;
+		std::string where = " WHERE 1 = 1";
+		where += q.characterId == 0 ? " AND (? = 0 AND ? = 0 AND ? = 0)" : " AND (? <> 0 AND (m.sender_id = ? OR m.receiver_id = ?))";
+		where += q.accountId == 0 ? " AND (? = 0 AND ? = 0 AND ? = 0)"
+			: " AND (? <> 0 AND (m.receiver_id IN (SELECT id FROM charinfo WHERE account_id = ?) OR m.sender_id IN (SELECT id FROM charinfo WHERE account_id = ?)))";
+		const auto has = [&like](const char* column) { return std::string(column) + " LIKE " + like + " ESCAPE '!'"; };
+		where += q.search.empty() ? " AND (? = '' AND ? = '' AND ? = '' AND ? = '' AND ? = '')"
+			: " AND (? <> '' AND (" + has("m.subject") + " OR " + has("m.body") + " OR " + has("m.sender_name") + " OR " + has("m.receiver_name") + "))";
+		switch (q.state) {
+		case eMailState::UNREAD: where += " AND m.was_read = 0 AND m.deleted_at = 0"; break;
+		case eMailState::READ: where += " AND m.was_read <> 0 AND m.deleted_at = 0"; break;
+		case eMailState::ATTACHMENT: where += " AND m.attachment_lot > 0 AND m.attachment_count > 0"; break;
+		case eMailState::CLAIMED: where += " AND m.attachment_lot = 0 AND m.attachment_count > 0"; break;
+		case eMailState::DELETED: where += " AND m.deleted_at <> 0"; break;
+		case eMailState::ANY: break;
+		}
+		if (!q.includeDeleted) where += " AND m.deleted_at = 0";
+		return where;
+	}
+}
+
+#endif  //!MAILSQL_H