fix: split message type into normalized label + raw code

The scraper was writing a normalized type label ("text"/"unknown"/...) into
Message.type, but the column was Integer, so the storage layer coerced it to
NULL and the raw code was only recoverable from raw_json. Align with design
§4.3, which specifies two fields: `type` (normalized enum) and `type_raw`
(original code).

- Model (Message): type -> String(32) normalized label; add type_raw Integer
  for the raw upstream type code.
- Scraper: _normalize_message sets both `type` (label) and `type_raw`
  (coerced int from messageType/type); _is_divider now checks raw -2.
- Repos: type_raw joins _INT_FIELDS; Message.type stored as-is (string).
- Migration 96975050fa79: add type_raw + alter type Integer->String(32),
  wrapped in batch_alter_table so it runs on SQLite and MySQL.
- env.py: enable render_as_batch on SQLite (dev/test) for portable batch
  migrations; MySQL still uses direct ALTER.
- Tests updated end-to-end (scraper, repos, models).

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

yunke-server/app/db/models.py

@@ -351,7 +351,12 @@ class Message(Base):
         String(128), nullable=True
     )  # @chatroom id; NULL/empty = direct message
     is_send: Mapped[bool | None] = mapped_column(Boolean, nullable=True)  # mine/isSend
-    type: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    type: Mapped[str | None] = mapped_column(
+        String(32), nullable=True
+    )  # normalized enum label (text/image/voice/.../unknown); see design §4.3
+    type_raw: Mapped[int | None] = mapped_column(
+        Integer, nullable=True
+    )  # original upstream type code (e.g. WeChat 1=text, -2=divider)
     text: Mapped[str | None] = mapped_column(Text, nullable=True)  # content/text
     file_url: Mapped[str | None] = mapped_column(String(1024), nullable=True)
     file_th_url: Mapped[str | None] = mapped_column(String(1024), nullable=True)

yunke-server/app/scraper/wechat.py

@@ -190,6 +190,34 @@ async def scrape_wechat_friends(
 # ===========================================================================
 
 
+def _coerce_int_or_none(value: Any) -> int | None:
+    """Coerce a possibly-string numeric value to ``int``; ``None`` preserved.
+
+    Mirrors :func:`app.storage.repos._coerce_int` so the scraper can emit a
+    ready-to-store ``type_raw`` int and check raw type codes (e.g. the ``-2``
+    divider drop) without depending on the storage layer (the scraper has no
+    DB dependency by design). A non-numeric value (``"text"`` / ``None`` /
+    missing) returns ``None``.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    if isinstance(value, str):
+        s = value.strip()
+        if not s:
+            return None
+        try:
+            return int(s)
+        except ValueError:
+            return None
+    return None
+
+
 async def _fetch_msg_page(
     client: YunkeClient,
     *,
@@ -245,9 +273,13 @@ def _normalize_message(record: dict[str, Any]) -> dict[str, Any]:
     """Map one upstream ``msg/chats`` record to the ``Message`` column shape.
 
     Adds ``channel="wechat"`` and preserves the original record under
-    ``raw_json``. The ``type`` field is normalized via
-    :func:`normalize_wechat_type` to a stable enum string; the raw code is
-    still recoverable from ``raw_json`` for the persistence layer.
+    ``raw_json``. Per design §4.3 the message type is carried as TWO fields:
+
+    * ``type`` — the normalized enum label (``"text"`` / ``"unknown"`` / ...)
+      via :func:`normalize_wechat_type`.
+    * ``type_raw`` — the original upstream type code (``messageType`` falling
+      back to ``type``), coerced to ``int | None`` so the raw code survives
+      end-to-end without round-tripping through ``raw_json``.
 
     ``None``-safe: missing fields become ``None`` rather than raising, so a
     partial payload does not break the whole scrape. Value coercion
@@ -281,6 +313,7 @@ def _normalize_message(record: dict[str, Any]) -> dict[str, Any]:
         "room_id": record.get("roomid"),
         "is_send": is_send,
         "type": normalize_wechat_type(raw_type),
+        "type_raw": _coerce_int_or_none(raw_type),
         "text": record.get("text"),
         "file_url": record.get("file"),
         "file_th_url": record.get("fileTh"),
@@ -305,15 +338,19 @@ def _normalize_message(record: dict[str, Any]) -> dict[str, Any]:
 
 
 def _is_divider(record: dict[str, Any]) -> bool:
-    """True iff this record is a date-divider (``type``/``messageType`` == -2).
+    """True iff this record is a date-divider (raw type code ``-2``).
 
     These are not real messages — the upstream inserts them as visual date
     bars in the chat UI — and must never be yielded or persisted. Per the
-    Task 1.6 spec we drop a record when EITHER ``type`` or ``messageType`` is
+    Task 1.6 spec we drop a record when EITHER ``messageType`` or ``type`` is
     ``-2``; all other unknown codes pass through.
+
+    The check is on the RAW code (not the normalized label) so the drop
+    decision is robust against any future change to
+    :func:`normalize_wechat_type`'s label vocabulary.
     """
-    return normalize_wechat_type(record.get("messageType")) == "divider" or (
-        normalize_wechat_type(record.get("type")) == "divider"
+    return _coerce_int_or_none(record.get("messageType")) == -2 or (
+        _coerce_int_or_none(record.get("type")) == -2
     )
 
 

yunke-server/app/storage/repos.py

@@ -23,9 +23,9 @@ dict (see :func:`_coerce_bool`, :func:`_coerce_int`):
   ``1`` / ``"1"`` / ``True`` -> ``True``; ``0`` / ``"0"`` / ``False`` ->
   ``False``; ``None`` preserved.
 * ``gender``: ``"0"`` / ``"1"`` / ``"2"`` (str) -> ``int`` when not ``None``.
-* ``type`` (Message): coerced to ``int``; a non-numeric string (e.g. a
-  normalized type label like ``"text"``) collapses to ``None`` — the raw code
-  is still recoverable from ``raw_json``.
+* ``type_raw`` (Message): the raw upstream type code, coerced to
+  ``int | None``. ``Message.type`` is a normalized label string and is
+  stored as-is (no int coercion).
 * Timestamps (``last_chat_time`` / ``timestamp`` / ``last_update`` / ...):
   passed through as-is (ms-epoch ``int`` or ``None``).
 * ``raw_json``: the original record dict, preserved verbatim. When the input
@@ -72,7 +72,7 @@ _BOOL_FIELDS: frozenset[str] = frozenset(
 _INT_FIELDS: frozenset[str] = frozenset(
     {
         "gender",
-        "type",
+        "type_raw",
         "pic_type",
         "friend_state",
         "delete_flag",
@@ -118,8 +118,7 @@ def _coerce_int(value: Any) -> int | None:
 
     ``"2"`` -> ``2``; ``2`` -> ``2``; ``0``/``"0"`` -> ``0``; ``None`` ->
     ``None``. A non-numeric string (e.g. ``"text"``) returns ``None`` — the
-    caller (Message.type) treats that as "no value", and the raw code is still
-    recoverable from ``raw_json``.
+    caller (e.g. Message.type_raw) treats that as "no value".
     """
     if value is None:
         return None
@@ -287,9 +286,10 @@ async def upsert_customers(session: AsyncSession, recs: list[dict[str, Any]]) ->
 async def upsert_messages(session: AsyncSession, recs: list[dict[str, Any]]) -> int:
     """Batch idempotent upsert for :class:`Message` (PK = ``msg_id``).
 
-    Applies the documented coercions (``is_send``/``is_del`` -> bool, ``type``
-    -> int). Returns the number of records processed (input length); the DB
-    collapses duplicate ``msg_id`` values to one row.
+    Applies the documented coercions (``is_send``/``is_del`` -> bool,
+    ``type_raw`` -> int). ``Message.type`` is the normalized label string and
+    is stored as-is. Returns the number of records processed (input length);
+    the DB collapses duplicate ``msg_id`` values to one row.
 
     .. note::
        For M1 the ``Message`` model maps to a single physical ``message``