chore: 整理项目结构，清理归档文件，更新部署配置

backend/tests/conftest.py

@@ -63,7 +63,7 @@ def _visit_jsonb_as_json(element, compiler, **kw):
 import pytest
 import pytest_asyncio
 from httpx import ASGITransport, AsyncClient
-from sqlalchemy import event
+from sqlalchemy import event, select
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.pool import StaticPool
 
@@ -88,9 +88,10 @@ from app.models.agent_note import AgentNote
 import starlette.config as _starlette_config
 
 
-def _read_file_utf8(self, file_name):
+def _read_file_utf8(self, file_name, encoding=None):
     """强制以 UTF-8 编码读 .env,避免 Windows GBK 默认编码触发 UnicodeDecodeError。"""
     result = {}
+    # 始终使用 UTF-8 编码，忽略传入的 encoding 参数
     with open(file_name, encoding='utf-8') as f:
         for line in f:
             line = line.strip()
@@ -513,3 +514,69 @@ def create_test_agent(
         current_load=0,
         max_load=5,
     )
+
+
+async def login_test_agent(
+    client,
+    db_session,
+    user_id: str = "test_agent_001",
+    name: str = "测试坐席",
+) -> str:
+    """创建带 agent 角色的测试坐席并返回 Bearer token。
+
+    做什么：
+    1. 创建 Agent 记录（如果不存在则创建）
+    2. 确保 user_roles 表中有 agent 角色记录
+    3. 调用 /agents/login 获取 token
+    为什么：RBAC 权限检查需要 agent 角色才能执行 invite/leave/recall 等操作，
+    仅创建 Agent 记录不足，必须插入 UserRole 关联。
+
+    Args:
+        client: httpx 异步测试客户端
+        db_session: 数据库会话
+        user_id: 坐席企微 UserID
+        name: 坐席名称
+
+    Returns:
+        str: Bearer token 字符串
+    """
+    from app.models.role import Role
+    from app.models.user_role import UserRole
+
+    # 1. 确保 agent 角色存在（如果 roles 表中还没有预设角色）
+    stmt = select(Role).where(Role.name == "agent")
+    result = await db_session.execute(stmt)
+    agent_role = result.scalars().first()
+
+    if not agent_role:
+        agent_role = Role(
+            name="agent",
+            display_name="坐席",
+            description="IT 坐席角色",
+            permissions=[],
+        )
+        db_session.add(agent_role)
+        await db_session.flush()
+
+    # 2. 确保 UserRole 关联存在
+    ur_stmt = select(UserRole).where(
+        UserRole.employee_id == user_id,
+        UserRole.role_id == agent_role.id,
+    )
+    ur_result = await db_session.execute(ur_stmt)
+    if not ur_result.scalars().first():
+        db_session.add(UserRole(
+            employee_id=user_id,
+            role_id=agent_role.id,
+            source="manual",
+            assigned_by="test_fixture",
+        ))
+        await db_session.flush()
+
+    # 3. 调用登录 API 获取 token
+    response = await client.post("/agents/login", json={
+        "user_id": user_id,
+        "name": name,
+    })
+    data = response.json()
+    return data["data"]["token"]