simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
主要改动:

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
This commit is contained in:
Simon
2026-06-15 14:14:58 +08:00
parent 93ba41ed79
commit 364e688382
68 changed files with 1354 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/app/api/agents.py
+15 -18
View File
@@ -36,6 +36,7 @@ from app.models.agent import Agent
from app.schemas.agent import AgentLogin, AgentResponse, AgentStatusUpdate
from app.services.wecom_service import WecomService
from app.utils.response import AppException, ERR_UNAUTHORIZED, success_response
from app.utils.error_codes import ErrorCode
# 速率限制器实例（与 main.py 共享同一配置）
# 移除 env_file=None 参数：slowapi 0.1.9 不支持该参数
@@ -217,24 +218,18 @@ async def agent_login(
logger.warning(
f"企微API不可达，已注册坐席降级放行: user_id={body.user_id}"
)
# P1 修复: 降级放行时，如果 agent 有 password_hash 则必须验证本地密码
if existing_agent and existing_agent.password_hash:
# P0 修复: 降级放行时，如果 agent 已设置密码则必须验证本地密码
if existing_agent:
if existing_agent.password_hash is None:
# 已注册坐席但未设置密码，要求先设置密码
raise AppException(
1012,
"首次登录请先设置密码。管理后台 → 坐席管理 → 设置本地密码"
)
if not body.password:
raise AppException(1011, "请输入本地密码")
raise AppException(ErrorCode.AUTH_PASSWORD_WRONG, "请输入本地密码")
if not bcrypt.checkpw(body.password.encode('utf-8'), existing_agent.password_hash.encode('utf-8')):
raise AppException(1011, "本地密码错误")
# P0-#5: 本地密码认证（企微验证失败时的备用认证）
# 检查是否需要本地密码验证
local_password_verified = False
if body.password and agent and agent.password_hash:
# 验证本地密码
if bcrypt.checkpw(body.password.encode('utf-8'), agent.password_hash.encode('utf-8')):
local_password_verified = True
logger.info(f"本地密码验证通过: user_id={body.user_id}")
else:
# 本地密码错误，拒绝登录
raise AppException(1011, "本地密码错误")
raise AppException(ErrorCode.AUTH_PASSWORD_WRONG, "本地密码错误")
# 1. 查找或创建坐席记录
stmt = select(Agent).where(Agent.user_id == body.user_id)
@@ -571,9 +566,11 @@ async def update_agent_password(
# 如果已有旧密码，验证旧密码
if agent.password_hash:
if not body.old_password:
raise AppException(1012, "请输入旧密码")
# 2026-06-15 修复: 改用专用 ErrorCode,避免与登录 1012 冲突
raise AppException(ErrorCode.AUTH_OLD_PASSWORD_REQUIRED, "请输入旧密码")
if not bcrypt.checkpw(body.old_password.encode('utf-8'), agent.password_hash.encode('utf-8')):
raise AppException(1013, "旧密码错误")
# 2026-06-15 修复: 改用专用 ErrorCode
raise AppException(ErrorCode.AUTH_OLD_PASSWORD_WRONG, "旧密码错误")
# 设置新密码
agent.password_hash = bcrypt.hashpw(body.new_password.encode('utf-8'), bcrypt.gensalt()).decode('utf-8')
backend/app/api/approval.py
+24 -11
View File
@@ -16,23 +16,36 @@ router = APIRouter()
# 审批模板配置（可配置化，后续可存入数据库）
# =============================================================================
# 企微审批模板配置
APPROVAL_TEMPLATES = {
# 模板124 - 资源申请（跳转审批）
"Bs7ucTLPo42dtj8Y1LzBoujijsa6geRWaRxZJjk4X": {
"id": "Bs7ucTLPo42dtj8Y1LzBoujijsa6geRWaRxZJjk4X",
# =============================================================================
# 企微审批模板配置（从环境变量读取）
# =============================================================================
# 环境变量：
# APPROVAL_TEMPLATE_RESOURCE - 资源申请模板ID
# APPROVAL_TEMPLATE_DEVICE - 设备申请模板ID
import os
APPROVAL_TEMPLATE_RESOURCE = os.getenv("APPROVAL_TEMPLATE_RESOURCE", "")
APPROVAL_TEMPLATE_DEVICE = os.getenv("APPROVAL_TEMPLATE_DEVICE", "")
# 动态构建审批模板配置
APPROVAL_TEMPLATES = {}
if APPROVAL_TEMPLATE_RESOURCE:
APPROVAL_TEMPLATES[APPROVAL_TEMPLATE_RESOURCE] = {
"id": APPROVAL_TEMPLATE_RESOURCE,
"name": "资源申请",
"type": "jump", # 跳转审批
"keywords": ["申请资源", "要资源", "申请"],
},
# 模板122 - 设备申请（API提交）
"Bs7ucTGsPuFhxfk8pn8EydxrWxkVetB4JR8Pb6PHS": {
"id": "Bs7ucTGsPuFhxfk8pn8EydxrWxkVetB4JR8Pb6PHS",
}
if APPROVAL_TEMPLATE_DEVICE:
APPROVAL_TEMPLATES[APPROVAL_TEMPLATE_DEVICE] = {
"id": APPROVAL_TEMPLATE_DEVICE,
"name": "设备申请",
"type": "api", # API提交
"keywords": ["申请设备", "要设备", "电脑", "笔记本"],
},
}
}
# =============================================================================
backend/app/config.py
+8
View File
@@ -99,6 +99,14 @@ class Settings(BaseSettings):
# 是否启用 Mock 登录（默认 false，生产环境必须关闭）
mock_login_enabled: bool = False
# ----------------------------------------------------------------------
# 审批模板配置（企微审批应用）
# ----------------------------------------------------------------------
# 资源申请审批模板ID（在企微审批应用设置中获取）
approval_template_resource: str = ""
# 设备申请审批模板ID（在企微审批应用设置中获取）
approval_template_device: str = ""
# ----------------------------------------------------------------------
# Pydantic-settings 配置
# ----------------------------------------------------------------------
backend/app/main.py
+75
View File
@@ -15,7 +15,9 @@ import logging
from contextlib import asynccontextmanager
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi.middleware.cors import CORSMiddleware
from sqlalchemy import text
# 导入配置（读取环境变量）
from app.config import settings
@@ -514,6 +516,79 @@ def create_app() -> FastAPI:
"""
return {"status": "ok", "service": "wecom-it-smart-desk"}
@app.get("/ready", tags=["系统"])
async def readiness_check():
"""就绪检查端点。
检查服务依赖（DB + Redis），不调用企微 API（避免阻塞）。
用于 K8s readinessProbe。
"""
try:
# 检查数据库
from app.database import engine
async with engine.connect() as conn:
await conn.execute(text("SELECT 1"))
db_status = "ok"
except Exception as e:
db_status = f"error: {str(e)}"
try:
# 检查 Redis
from app.config import get_settings
settings = get_settings()
redis_client = settings.create_redis_client()
await redis_client.ping()
redis_status = "ok"
except Exception as e:
redis_status = f"error: {str(e)}"
if db_status == "ok" and redis_status == "ok":
return {"status": "ready", "db": db_status, "redis": redis_status}
else:
return JSONResponse(
status_code=503,
content={"status": "not_ready", "db": db_status, "redis": redis_status}
)
@app.get("/metrics", tags=["系统"])
async def metrics():
"""指标端点。
返回服务运行指标，用于 Prometheus 采集。
"""
import psutil
return {
"status": "ok",
"metrics": {
"cpu_percent": psutil.cpu_percent(interval=0.1),
"memory_percent": psutil.virtual_memory().percent,
"disk_percent": psutil.disk_usage("/").percent,
}
}
@app.get("/version", tags=["系统"])
async def version():
"""版本信息端点。
返回服务版本信息。
"""
import subprocess
try:
git_hash = subprocess.check_output(
["git", "rev-parse", "HEAD"],
cwd=app_root,
text=True
).strip()[:8]
except Exception:
git_hash = "unknown"
return {
"service": "wecom-it-smart-desk",
"version": "1.1.0",
"build": git_hash,
}
# ----------------------------------------------------------------------
# 打印所有已注册的路由（调试用）
# ----------------------------------------------------------------------
backend/app/utils/error_codes.py
+158
View File
@@ -0,0 +1,158 @@
# =============================================================================
# IT智能服务台 — 错误码定义
# =============================================================================
# 说明：统一管理系统错误码，便于前端解析和国际化
# 格式：E{模块}{序号}
# =============================================================================
from enum import Enum
class ErrorCode(str, Enum):
"""系统错误码枚举"""
# --------------------------------------------------------------------------
# 通用错误 (0xxx)
# --------------------------------------------------------------------------
SUCCESS = "E0000" # 成功
UNKNOWN_ERROR = "E0001" # 未知错误
INVALID_PARAMETER = "E0002" # 参数错误
MISSING_PARAMETER = "E0003" # 缺少参数
NOT_FOUND = "E0004" # 资源不存在
UNAUTHORIZED = "E0005" # 未授权
FORBIDDEN = "E0006" # 禁止访问
INTERNAL_ERROR = "E0007" # 内部错误
SERVICE_UNAVAILABLE = "E0008" # 服务不可用
TIMEOUT = "E0009" # 请求超时
# --------------------------------------------------------------------------
# 认证相关 (1xxx)
# --------------------------------------------------------------------------
AUTH_FAILED = "E1001" # 认证失败
AUTH_TOKEN_EXPIRED = "E1002" # Token过期
AUTH_TOKEN_INVALID = "E1003" # Token无效
AUTH_PASSWORD_REQUIRED = "E1012" # 登录:首次登录请先设置密码
AUTH_PASSWORD_WRONG = "E1011" # 登录:本地密码错误
AUTH_OLD_PASSWORD_REQUIRED = "E1015" # 改密:请输入旧密码(2026-06-15 WB反馈 1012 上下文冲突后拆分)
AUTH_OLD_PASSWORD_WRONG = "E1016" # 改密:旧密码错误(2026-06-15 拆分)
# --------------------------------------------------------------------------
# 企微API错误 (2xxx)
# --------------------------------------------------------------------------
WECOM_API_ERROR = "E2001" # 企微API调用失败
WECOM_API_TIMEOUT = "E2002" # 企微API超时
WECOM_TOKEN_INVALID = "E2003" # 企微token无效
WECOM_USER_NOT_FOUND = "E2004" # 企微用户不存在
# --------------------------------------------------------------------------
# 会话/消息错误 (3xxx)
# --------------------------------------------------------------------------
CONVERSATION_NOT_FOUND = "E3001" # 会话不存在
MESSAGE_NOT_FOUND = "E3002" # 消息不存在
MESSAGE_TOO_LONG = "E3003" # 消息过长
CONVERSATION_CLOSED = "E3004" # 会话已关闭
# --------------------------------------------------------------------------
# 坐席错误 (4xxx)
# --------------------------------------------------------------------------
AGENT_NOT_FOUND = "E4001" # 坐席不存在
AGENT_OFFLINE = "E4002" # 坐席不在线
AGENT_BUSY = "E4003" # 坐席忙碌
AGENT_MAX_LOAD = "E4004" # 坐席已达最大接待量
# --------------------------------------------------------------------------
# 审批错误 (5xxx)
# --------------------------------------------------------------------------
APPROVAL_TEMPLATE_NOT_FOUND = "E5001" # 审批模板不存在
APPROVAL_FAILED = "E5002" # 审批提交失败
# --------------------------------------------------------------------------
# 文件上传错误 (6xxx)
# --------------------------------------------------------------------------
FILE_TOO_LARGE = "E6001" # 文件过大
FILE_TYPE_NOT_ALLOWED = "E6002" # 文件类型不允许
FILE_UPLOAD_FAILED = "E6003" # 文件上传失败
# 错误码到 HTTP 状态码的映射
ERROR_CODE_TO_STATUS = {
ErrorCode.SUCCESS: 200,
ErrorCode.INVALID_PARAMETER: 400,
ErrorCode.MISSING_PARAMETER: 400,
ErrorCode.NOT_FOUND: 404,
ErrorCode.UNAUTHORIZED: 401,
ErrorCode.FORBIDDEN: 403,
ErrorCode.INTERNAL_ERROR: 500,
ErrorCode.SERVICE_UNAVAILABLE: 503,
# 认证
ErrorCode.AUTH_FAILED: 401,
ErrorCode.AUTH_TOKEN_EXPIRED: 401,
ErrorCode.AUTH_TOKEN_INVALID: 401,
ErrorCode.AUTH_PASSWORD_REQUIRED: 401,
ErrorCode.AUTH_PASSWORD_WRONG: 401,
ErrorCode.AUTH_OLD_PASSWORD_REQUIRED: 400,
ErrorCode.AUTH_OLD_PASSWORD_WRONG: 400,
# 企微
ErrorCode.WECOM_API_ERROR: 502,
ErrorCode.WECOM_API_TIMEOUT: 504,
ErrorCode.WECOM_TOKEN_INVALID: 401,
ErrorCode.WECOM_USER_NOT_FOUND: 404,
# 会话
ErrorCode.CONVERSATION_NOT_FOUND: 404,
ErrorCode.MESSAGE_NOT_FOUND: 404,
ErrorCode.MESSAGE_TOO_LONG: 400,
ErrorCode.CONVERSATION_CLOSED: 400,
# 坐席
ErrorCode.AGENT_NOT_FOUND: 404,
ErrorCode.AGENT_OFFLINE: 400,
ErrorCode.AGENT_BUSY: 400,
ErrorCode.AGENT_MAX_LOAD: 400,
# 审批
ErrorCode.APPROVAL_TEMPLATE_NOT_FOUND: 404,
ErrorCode.APPROVAL_FAILED: 502,
# 文件
ErrorCode.FILE_TOO_LARGE: 413,
ErrorCode.FILE_TYPE_NOT_ALLOWED: 400,
ErrorCode.FILE_UPLOAD_FAILED: 500,
}
def get_error_message(code: ErrorCode) -> str:
"""获取错误码对应的默认消息"""
messages = {
ErrorCode.SUCCESS: "操作成功",
ErrorCode.UNKNOWN_ERROR: "未知错误，请稍后重试",
ErrorCode.INVALID_PARAMETER: "参数错误",
ErrorCode.MISSING_PARAMETER: "缺少必要参数",
ErrorCode.NOT_FOUND: "资源不存在",
ErrorCode.UNAUTHORIZED: "未授权，请先登录",
ErrorCode.FORBIDDEN: "禁止访问",
ErrorCode.INTERNAL_ERROR: "服务器内部错误",
ErrorCode.SERVICE_UNAVAILABLE: "服务暂时不可用",
ErrorCode.TIMEOUT: "请求超时",
ErrorCode.AUTH_FAILED: "认证失败",
ErrorCode.AUTH_TOKEN_EXPIRED: "登录已过期，请重新登录",
ErrorCode.AUTH_TOKEN_INVALID: "无效的登录凭证",
ErrorCode.AUTH_PASSWORD_REQUIRED: "首次登录请先设置密码",
ErrorCode.AUTH_PASSWORD_WRONG: "密码错误",
ErrorCode.AUTH_OLD_PASSWORD_REQUIRED: "请输入旧密码",
ErrorCode.AUTH_OLD_PASSWORD_WRONG: "旧密码错误",
ErrorCode.WECOM_API_ERROR: "企业微信服务异常",
ErrorCode.WECOM_API_TIMEOUT: "企业微信服务响应超时",
ErrorCode.WECOM_TOKEN_INVALID: "企业微信凭证无效",
ErrorCode.WECOM_USER_NOT_FOUND: "企业微信用户不存在",
ErrorCode.CONVERSATION_NOT_FOUND: "会话不存在",
ErrorCode.MESSAGE_NOT_FOUND: "消息不存在",
ErrorCode.MESSAGE_TOO_LONG: "消息内容过长",
ErrorCode.CONVERSATION_CLOSED: "会话已结束",
ErrorCode.AGENT_NOT_FOUND: "坐席不存在",
ErrorCode.AGENT_OFFLINE: "坐席不在线",
ErrorCode.AGENT_BUSY: "坐席忙碌中",
ErrorCode.AGENT_MAX_LOAD: "坐席已达到最大接待量",
ErrorCode.APPROVAL_TEMPLATE_NOT_FOUND: "审批模板不存在",
ErrorCode.APPROVAL_FAILED: "审批提交失败",
ErrorCode.FILE_TOO_LARGE: "文件过大",
ErrorCode.FILE_TYPE_NOT_ALLOWED: "不支持的文件类型",
ErrorCode.FILE_UPLOAD_FAILED: "文件上传失败",
}
return messages.get(code, "未知错误")
backend/app/utils/logging_config.py
+99
View File
@@ -0,0 +1,99 @@
# =============================================================================
# IT智能服务台 — 日志配置
# =============================================================================
# 说明：统一日志格式，支持 JSON 输出便于日志收集
# =============================================================================
import json
import logging
import sys
from datetime import datetime
from typing import Any
class JSONFormatter(logging.Formatter):
"""JSON 格式日志 formatter"""
def format(self, record: logging.LogRecord) -> str:
"""将日志记录格式化为 JSON"""
log_data: dict[str, Any] = {
"timestamp": datetime.utcnow().isoformat() + "Z",
"level": record.levelname,
"logger": record.name,
"message": record.getMessage(),
"module": record.module,
"function": record.funcName,
"line": record.lineno,
}
# 添加异常信息
if record.exc_info:
log_data["exception"] = self.formatException(record.exc_info)
# 添加额外字段
if hasattr(record, "request_id"):
log_data["request_id"] = record.request_id
if hasattr(record, "user_id"):
log_data["user_id"] = record.user_id
if hasattr(record, "extra"):
log_data.update(record.extra)
return json.dumps(log_data, ensure_ascii=False)
class PlainFormatter(logging.Formatter):
"""普通格式日志 formatter（开发环境使用）"""
def __init__(self):
super().__init__(
fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
datefmt="%Y-%m-%d %H:%M:%S",
)
def setup_logging(level: str = "INFO", json_format: bool = False) -> None:
"""配置日志系统
Args:
level: 日志级别 (DEBUG, INFO, WARNING, ERROR, CRITICAL)
json_format: 是否使用 JSON 格式输出
"""
log_level = getattr(logging, level.upper(), logging.INFO)
# 获取 root logger
root_logger = logging.getLogger()
root_logger.setLevel(log_level)
# 清除现有 handlers
for handler in root_logger.handlers[:]:
root_logger.removeHandler(handler)
# 创建 console handler
console_handler = logging.StreamHandler(sys.stdout)
console_handler.setLevel(log_level)
# 设置 formatter
if json_format:
formatter = JSONFormatter()
else:
formatter = PlainFormatter()
console_handler.setFormatter(formatter)
root_logger.addHandler(console_handler)
# 设置第三方库日志级别
logging.getLogger("uvicorn").setLevel(logging.WARNING)
logging.getLogger("fastapi").setLevel(logging.WARNING)
logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
def get_logger(name: str) -> logging.Logger:
"""获取 logger 实例
Args:
name: logger 名称，通常使用 __name__
Returns:
Logger 实例
"""
return logging.getLogger(name)