chore(release): v0.5.0-beta 发版准备

主要改动:

backend 业务:
- feat(error-codes): 统一错误码表 E1011/E1012 拆码
  - E1011 AUTH_PASSWORD_WRONG: 本地密码错误
  - E1012 AUTH_FIRST_LOGIN_PASSWORD_REQUIRED: 首次登录请先设置密码
  - E1015 AUTH_OLD_PASSWORD_REQUIRED: 改密需要旧密码
  - E1016 AUTH_OLD_PASSWORD_WRONG: 旧密码错误
- fix(agents): P0 降级放行时,如坐席已注册但未设密码,正确 raise 1012
  (修复前会撞 1011 本地密码错误,与场景不符)
- feat(approval): 审批模块 (T审批/A审批)
- feat(config): approval_template_resource / approval_template_device 配置
- feat(main): /ready, /metrics, /version 端点(K8s 友好)

backend 测试:
- test(agents): 新增 test_agents.py — 3 个 Fix-4 降级登录测试
  - 错误密码拒绝
  - 缺密码拒绝
  - 正确密码通过
  pytest tests/test_agents.py → 3/3 通过
- test(conftest): 模块级 mock + slowapi 限流重置 + UTF-8 patch
  解决 Windows pytest GBK 读 .env 失败 + 降级路径无法测试

仓库治理:
- chore(gitignore): 排除 .workbuddy/memory/(workbuddy 本地记忆)
- chore(docs): 重命名两份 IT 文档(前缀加智能区分版本)

部署与文档:
- docs: RELEASE_NOTES_v0.5.0-beta.md / dashboard.html / 需求-发版预览页面
- docs: 部署、架构、PRD、安全、评审报告等同步 v0.5.0-beta
- deploy-server: 打包脚本、nginx、docker-compose 版本号 bump

前端 (frontend-h5 / frontend-agent / frontend-admin / frontend-portal):
- index.html / package.json 版本号与构建号 bump

自动验收(RELEASE_NOTES L100-104):
- [x] pytest tests/test_agents.py -v → 3 passed
- [x] grep Bs7ucT backend frontend-h5 frontend-agent → 无输出
- [x] grep AppException(101[123]) backend → 仅 1 处(登录场景 1012)
- [ ] npm run build (frontend-h5 / frontend-agent) → 合并后跑

后续: 合并 feature/t-1-t4-merge → main,tag v0.5.0-beta

backend/tests/conftest.py

@@ -33,6 +33,32 @@ from app.models.quick_reply_template import QuickReplyTemplate
 from app.models.agent_note import AgentNote
 
 
+# =============================================================================
+# 2026-06-15 修复: monkey-patch starlette.config.Config 强制 UTF-8 读 .env
+# 原因: Windows pytest 默认 GBK 读 .env 会 UnicodeDecodeError(0xb0 字节)
+# 必须在 conftest 顶部应用,否则 reset_rate_limiter 等 autouse fixture
+# 提前 import app 模块触发 .env 读取时会失败
+# =============================================================================
+import starlette.config as _starlette_config
+
+
+def _read_file_utf8(self, file_name):
+    """强制以 UTF-8 编码读 .env,避免 Windows GBK 默认编码触发 UnicodeDecodeError。"""
+    result = {}
+    with open(file_name, encoding='utf-8') as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+            if '=' in line:
+                k, v = line.split('=', 1)
+                result[k.strip()] = v.strip().strip('"').strip("'")
+    return result
+
+
+_starlette_config.Config._read_file = _read_file_utf8
+
+
 # =============================================================================
 # SQLite 内存数据库引擎
 # =============================================================================
@@ -184,6 +210,70 @@ def mock_redis() -> MockRedis:
     return MockRedis()
 
 
+# =============================================================================
+# 模块级 Mock 外部服务（让子测试可覆盖其行为）
+# =============================================================================
+# 2026-06-15 修复: 把 WecomService / AIService mock 提升到模块级
+# 原因: client fixture 内的局部 mock 无法被测试内 `with patch.object(...)` 覆盖
+#       → 降级登录测试(需让企微 API "不可达")无法触发降级分支
+# 修复: 新增 mock_wecom_instance fixture,测试通过它改写 side_effect
+#       client fixture 改用模块级 mock,改写对当前请求立即生效
+# =============================================================================
+mock_wecom_module = AsyncMock()
+mock_wecom_module.send_message.return_value = {"errcode": 0, "errmsg": "ok"}
+
+
+async def _mock_get_user_info_default(user_id: str, **kwargs):
+    """默认的企微 get_user_info 行为:返回动态生成的用户名。
+
+    测试可通过 mock_wecom_instance.get_user_info.side_effect = ... 改写。
+    """
+    return {
+        "user_id": user_id,
+        "name": f"用户{user_id}",
+        "department": "测试部",
+        "avatar": "",
+    }
+
+
+mock_wecom_module.get_user_info.side_effect = _mock_get_user_info_default
+mock_wecom_module.get_department_users.return_value = []
+
+mock_ai_module = AsyncMock()
+mock_ai_module.generate_response.return_value = "这是AI的模拟回复"
+
+
+@pytest.fixture
+def mock_wecom_instance():
+    """暴露模块级 WecomService mock 实例,让测试可改写其行为(模拟降级等)。
+
+    使用示例 — 触发降级登录路径:
+        async def fail(*args, **kwargs):
+            raise Exception("企微 API 不可达")
+        mock_wecom_instance.get_user_info.side_effect = fail
+        # ...发起请求后,用 try/finally 恢复原 side_effect
+    """
+    return mock_wecom_module
+
+
+@pytest.fixture(autouse=True)
+def reset_rate_limiter():
+    """每个测试前后重置 slowapi 限流器状态,避免 IP 限流干扰测试。
+
+    背景: /agents/login 限流 10/min per IP,pytest 连续跑多个测试会撞 429。
+    """
+    from app.api.agents import limiter as agents_limiter
+    try:
+        agents_limiter._storage.reset()
+    except Exception:
+        pass
+    yield
+    try:
+        agents_limiter._storage.reset()
+    except Exception:
+        pass
+
+
 @pytest_asyncio.fixture
 async def client(db_session: AsyncSession, mock_redis: MockRedis) -> AsyncGenerator[AsyncClient, None]:
     """提供 FastAPI 异步测试客户端。"""
@@ -194,6 +284,9 @@ async def client(db_session: AsyncSession, mock_redis: MockRedis) -> AsyncGenera
     async def _override_get_redis():
         return mock_redis
 
+    # 注: 2026-06-15 UTF-8 monkey-patch 已提升到 conftest 模块级,见文件顶部
+    # 原因: reset_rate_limiter 等 autouse fixture 提前 import 触发 .env 读取
+
     from app.main import create_app
     from app.database import get_db
 
@@ -210,24 +303,11 @@ async def client(db_session: AsyncSession, mock_redis: MockRedis) -> AsyncGenera
             # 为什么：测试中不应调用真实企微API/AI大模型
             # 怎么做：patch 类构造函数，返回配置了默认返回值的 mock 对象
             # ------------------------------------------------------------------
-            mock_wecom = AsyncMock()
-            # 企微消息发送：默认成功
-            mock_wecom.send_message.return_value = {"errcode": 0, "errmsg": "ok"}
-            # 企微通讯录查询：动态返回（根据传入的 user_id 生成对应的名称）
-            # 为什么：坐席登录时会调用 get_user_info 获取员工姓名
-            # 如果返回固定名字，登录接口会用 mock 名字覆盖请求中的 name 参数
-            async def _mock_get_user_info(user_id: str, **kwargs):
-                return {
-                    "user_id": user_id,
-                    "name": f"用户{user_id}",
-                    "department": "测试部",
-                    "avatar": "",
-                }
-            mock_wecom.get_user_info.side_effect = _mock_get_user_info
-            mock_wecom.get_department_users.return_value = []
-
-            mock_ai = AsyncMock()
-            mock_ai.generate_response.return_value = "这是AI的模拟回复"
+            # 使用模块级 mock_wecom_module / mock_ai_module（2026-06-15 修复）
+            # 原因: 模块级 mock 允许测试通过 mock_wecom_instance fixture 改写行为
+            #       例如降级登录测试改 side_effect = raise Exception("企微不可达")
+            mock_wecom = mock_wecom_module
+            mock_ai = mock_ai_module
 
             # Patch WecomService 类（端点函数中会新建实例）
             # 注意：只 patch 模块中实际引用的名字