"""文档详细说明：doc_document 新增 description。

Revision ID: 0007_document_description
Revises: 0006_document_organization
Create Date: 2026-08-16

变更要点：
1. doc_document 新增 description（TEXT，可空）。
2. 用途：管理员在"查看"对话框右侧维护详细说明，普通用户在表格
   操作列"说明"按钮 Tip 与查看对话框中阅读。
3. 不参与全文检索（search_text 不包含该字段），仅作人工备注展示。
"""

from __future__ import annotations

from collections.abc import Sequence

from alembic import op
import sqlalchemy as sa


revision: str = "0007_document_description"
down_revision: str | None = "0006_document_organization"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None


_TABLE = "doc_document"
_COLUMN = "description"


def _existing_columns(table: str) -> set[str]:
    inspector = sa.inspect(op.get_bind())
    return {item["name"] for item in inspector.get_columns(table)}


def upgrade() -> None:
    if _COLUMN not in _existing_columns(_TABLE):
        op.add_column(
            _TABLE,
            sa.Column(_COLUMN, sa.Text(), nullable=True),
        )


def downgrade() -> None:
    if _COLUMN in _existing_columns(_TABLE):
        op.drop_column(_TABLE, _COLUMN)