reglow 0.3.0__py3-none-any.whl

reglow/README.md

@@ -0,0 +1,162 @@
+# Reglow Python 后端基础库
+
+> **包名**：`reglow` | **版本**：0.3.0 | **Python**：>=3.12
+
+## 概述
+
+`reglow` 是基于 FastAPI + SQLAlchemy 2.0（async）的全栈后台基础库，提供 19 个即用业务模块，通过 `pip install -e .` 安装后可直接导入使用。
+
+## 目录结构
+
+```
+reglow/
+├── core/                    # 框架核心层
+│   ├── config.py            # Settings 配置（pydantic-settings，自动读 .env）
+│   ├── database.py          # 异步引擎/会话/Base/AutoBigInt/Mixin
+│   ├── security.py          # 密码哈希、JWT 签发/验证
+│   ├── dependencies.py      # get_current_employee / PermissionChecker
+│   ├── redis_client.py      # Redis 客户端
+│   ├── cache.py             # 缓存封装
+│   ├── rate_limit.py        # 限流
+│   ├── sms.py               # 短信发送
+│   ├── observability.py     # 健康检查路由
+│   └── logging_config.py    # 日志配置
+│
+├── common/                  # 跨模块共享层
+│   ├── response.py          # ApiResponse[T] / PageData[T] 统一响应
+│   ├── exceptions.py        # AppException / ErrorCode 枚举
+│   ├── exception_handler.py # 全局异常处理注册
+│   ├── middleware.py        # 中间件注册（CORS/日志/i18n）
+│   └── i18n.py              # 国际化（Accept-Language 头）
+│
+└── modules/                 # 业务模块层（19 个模块）
+    ├── auth/                # 认证（登录/注册/验证码/Token刷新）
+    ├── employee/            # 员工管理
+    ├── user/                # 用户管理（注册用户，区别于员工）
+    ├── role/                # 角色管理（含数据范围）
+    ├── menu/                # 菜单管理（树形）
+    ├── dept/                # 部门管理（树形）
+    ├── post/                # 岗位管理
+    ├── dict/                # 字典管理（类型+数据）
+    ├── config/              # 参数配置
+    ├── log/                 # 日志（登录+操作）
+    ├── material/            # 素材中心（图片/视频/文件）
+    ├── agreement/           # 协议管理
+    ├── notice/              # 通知公告
+    ├── message/             # 系统消息+模板+收件箱
+    ├── article/             # 文章管理（含分类+文集）
+    ├── photo/               # 照片管理（含分类+相册）
+    ├── video/               # 视频管理（含分类+视频集）
+    ├── ai/                  # AI（对话/图片生成/视频生成）
+    └── customer_service/    # 智能客服（知识库/会话/SDK）
+```
+
+## 模块六层架构
+
+每个模块遵循统一的分层结构，依赖单向向下：
+
+```
+model.py        ORM 实体（继承 Base + Mixin）
+    ↑
+schema.py       Pydantic 契约（CreateRequest / UpdateRequest / Response）
+    ↑
+repository.py   数据访问层（AsyncSession，find_/create_/update_）
+    ↑
+service.py      业务逻辑层（编排 repository，抛 AppException）
+    ↑
+controller.py   接口控制层（APIRouter + 权限校验 + ApiResponse）
+    ↑
+router.py       路由导出（from .controller import router）
+```
+
+## 安装
+
+```bash
+# 可编辑模式（开发）
+cd reglow && pip install -e .
+```
+
+## 使用
+
+```python
+# main.py — 消费方应用入口
+from fastapi import FastAPI, APIRouter
+from reglow.common.middleware import register_middlewares
+from reglow.common.exception_handler import register_exception_handlers
+
+# 导入需要的模块路由
+from reglow.modules.auth.router import router as auth_router
+from reglow.modules.employee.router import router as employee_router
+# ... 按需导入
+
+app = FastAPI(title="My App")
+register_middlewares(app)
+register_exception_handlers(app)
+
+admin_api = APIRouter(prefix="/admin/api/v1")
+admin_api.include_router(auth_router)
+admin_api.include_router(employee_router)
+app.include_router(admin_api)
+```
+
+## 核心基础设施
+
+### 统一响应
+
+```python
+from reglow.common.response import ApiResponse, PageData
+
+# 成功
+return ApiResponse.success(data)
+return ApiResponse.success(PageData(items=..., total=..., page=1, size=20))
+
+# 失败
+return ApiResponse.fail("操作失败")
+```
+
+### 异常处理
+
+```python
+from reglow.common.exceptions import AppException, ErrorCode
+
+raise AppException(ErrorCode.NOT_FOUND, "留言不存在", 404)
+raise AppException(ErrorCode.BAD_REQUEST, "参数错误", 400)
+```
+
+### 权限校验
+
+```python
+from reglow.core.dependencies import PermissionChecker, get_current_employee
+
+@router.get("/feedbacks", dependencies=[Depends(PermissionChecker("business:feedback:list"))])
+async def list_feedbacks(db: AsyncSession = Depends(get_db)):
+    ...
+```
+
+### 数据库模型
+
+```python
+from reglow.core.database import AutoBigInt, Base, TimestampMixin, SoftDeleteMixin
+from sqlalchemy import Column, String
+
+class Feedback(TimestampMixin, SoftDeleteMixin, Base):
+    __tablename__ = "biz_feedback"
+    id = Column(AutoBigInt, primary_key=True, autoincrement=True)
+    name = Column(String(100), nullable=False, comment="名称")
+```
+
+## 配置（.env）
+
+```env
+APP_NAME=MyApp
+DEBUG=True
+DB_DRIVER=sqlite          # 或 mysql
+DB_NAME=myapp
+JWT_SECRET=your-secret
+REDIS_URL=redis://localhost:6379/0
+```
+
+## 参考文档
+
+- [Reglow 基础库改造与集成手册](../reglow-docs/content/2.tutorials/3.framework-intro/Reglow基础库改造与集成小白实操手册.md)
+- [reglow-app/backend 示例项目](../reglow-app/backend/)

reglow/common/__init__.py

@@ -0,0 +1 @@
+"""Common - 跨模块共享"""

reglow/common/exception_handler.py

@@ -0,0 +1,205 @@
+"""全局异常处理器 - 一个兜底，万事大吉"""
+import logging
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError
+
+from reglow.common.exceptions import AppException
+from reglow.common.exceptions import ErrorCode
+from reglow.common.i18n import get_locale_from_request, translate
+
+logger = logging.getLogger(__name__)
+
+_ERROR_MSG = {
+    "zh-CN": {
+        "missing": "字段不能为空",
+        "value_error.missing": "字段不能为空",
+        "string_type": "请输入字符串",
+        "int_type": "请输入整数",
+        "float_type": "请输入数字",
+        "bool_type": "请输入布尔值",
+        "list_type": "请输入列表",
+        "string_too_short": "长度不能少于 {min_length} 个字符",
+        "string_too_long": "长度不能超过 {max_length} 个字符",
+        "int_too_small": "值不能小于 {ge}",
+        "int_too_big": "值不能大于 {le}",
+        "float_too_small": "值不能小于 {ge}",
+        "float_too_big": "值不能大于 {le}",
+        "greater_than_equal": "值不能小于 {ge}",
+        "less_than_equal": "值不能大于 {le}",
+        "pattern_regex": "格式不正确",
+        "value_error": "{error}",
+        "json_invalid": "JSON 格式不正确",
+        "url_parsing": "URL 格式不正确",
+        "missing_sole": "字段不能为空",
+    },
+    "en-US": {
+        "missing": " is required",
+        "value_error.missing": " is required",
+        "string_type": " must be a string",
+        "int_type": " must be an integer",
+        "float_type": " must be a number",
+        "bool_type": " must be a boolean",
+        "list_type": " must be a list",
+        "string_too_short": " length must be at least {min_length} characters",
+        "string_too_long": " length must be at most {max_length} characters",
+        "int_too_small": " must be greater than or equal to {ge}",
+        "int_too_big": " must be less than or equal to {le}",
+        "float_too_small": " must be greater than or equal to {ge}",
+        "float_too_big": " must be less than or equal to {le}",
+        "greater_than_equal": " must be greater than or equal to {ge}",
+        "less_than_equal": " must be less than or equal to {le}",
+        "pattern_regex": " format is invalid",
+        "value_error": ": {error}",
+        "json_invalid": "Invalid JSON format",
+        "url_parsing": " URL format is invalid",
+        "missing_sole": " is required",
+    },
+}
+
+_FIELD_NAME = {
+    "zh-CN": {
+        "name": "名称",
+        "code": "编码",
+        "type": "类型",
+        "icon": "图标",
+        "path": "路径",
+        "component": "组件",
+        "permission": "权限标识",
+        "sort": "排序",
+        "status": "状态",
+        "description": "描述",
+        "remark": "备注",
+        "username": "用户名",
+        "password": "密码",
+        "new_password": "新密码",
+        "real_name": "真实姓名",
+        "nickname": "昵称",
+        "phone": "手机号",
+        "email": "邮箱",
+        "sms_code": "短信验证码",
+        "captcha_key": "验证码key",
+        "captcha_code": "验证码",
+        "slide_x": "滑动位置",
+        "employee_no": "工号",
+        "gender": "性别",
+        "dept_id": "部门",
+        "superior_id": "直属上级",
+        "role_ids": "角色",
+        "post_ids": "岗位",
+        "employment_type": "用工类型",
+        "job_level": "职级",
+        "job_title": "职称",
+        "entry_date": "入职日期",
+        "work_status": "在职状态",
+        "avatar": "头像",
+        "data_scope": "数据范围",
+        "menu_ids": "菜单列表",
+        "dept_ids": "部门列表",
+        "parent_id": "父级",
+        "visible": "是否显示",
+        "cache": "是否缓存",
+        "label": "标签",
+        "value": "值",
+        "source": "来源",
+        "group_ids": "分组",
+        "key": "键名",
+        "content": "内容",
+        "agreement_type": "协议类型",
+    },
+    "en-US": {
+        "name": "Name",
+        "code": "Code",
+        "type": "Type",
+        "icon": "Icon",
+        "path": "Path",
+        "component": "Component",
+        "permission": "Permission",
+        "sort": "Sort",
+        "status": "Status",
+        "description": "Description",
+        "remark": "Remark",
+        "username": "Username",
+        "password": "Password",
+        "new_password": "New password",
+        "real_name": "Real name",
+        "nickname": "Nickname",
+        "phone": "Phone",
+        "email": "Email",
+        "sms_code": "SMS code",
+        "captcha_key": "Captcha key",
+        "captcha_code": "Captcha code",
+        "slide_x": "Slide position",
+    },
+}
+
+
+def _translate_validation_error(error: dict, locale: str = "zh-CN") -> str:
+    """将单个 Pydantic 错误翻译为当前语言"""
+    err_type = error.get("type", "")
+    loc = error.get("loc", ())
+    field = str(loc[-1]) if loc else ""
+    field_name = _FIELD_NAME.get(locale, _FIELD_NAME["zh-CN"]).get(field, field)
+    ctx = error.get("ctx", {})
+
+    if err_type == "value_error":
+        custom_msg = error.get("msg", "")
+        if custom_msg and not custom_msg.startswith(("Value error", "Assertion failed")):
+            return f"{field_name}: {custom_msg}"
+        return f"{field_name}: {ctx.get('error', translate('common.validation_failed', locale))}"
+
+    template = _ERROR_MSG.get(locale, _ERROR_MSG["zh-CN"]).get(err_type)
+    if template:
+        try:
+            msg = template.format(**ctx)
+        except (KeyError, IndexError):
+            msg = template
+        return f"{field_name}{msg}"
+
+    return f"{field_name}: {error.get('msg', translate('common.validation_failed', locale))}"
+
+
+async def app_exception_handler(request: Request, exc: AppException):
+    """统一处理业务异常"""
+    locale = get_locale_from_request(request)
+    return JSONResponse(
+        status_code=exc.http_status,
+        content={"code": exc.code, "msg": translate(exc.msg, locale), "data": None},
+    )
+
+
+async def validation_exception_handler(request: Request, exc: ValidationError):
+    """统一处理 Pydantic 验证异常 - 多语言友好提示"""
+    errors = exc.errors()
+    locale = get_locale_from_request(request)
+    logger.warning(
+        "[Validation] %s %s errors=%s",
+        request.method,
+        request.url.path,
+        errors,
+    )
+    msg = translate("common.validation_failed", locale) if not errors else _translate_validation_error(errors[0], locale)
+    return JSONResponse(
+        status_code=422,
+        content={"code": ErrorCode.PARAM_ERROR, "msg": msg, "data": None},
+    )
+
+
+async def global_exception_handler(request: Request, exc: Exception):
+    """兜底 - 处理所有未预期的异常"""
+    logger.error(f"未预期错误: {exc}", exc_info=True)
+    locale = get_locale_from_request(request)
+    return JSONResponse(
+        status_code=500,
+        content={"code": ErrorCode.UNKNOWN, "msg": translate("common.server_error", locale), "data": None},
+    )
+
+
+def register_exception_handlers(app):
+    """注册所有异常处理器"""
+    app.add_exception_handler(AppException, app_exception_handler)
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)
+    app.add_exception_handler(ValidationError, validation_exception_handler)
+    app.add_exception_handler(Exception, global_exception_handler)

reglow/common/exceptions.py

@@ -0,0 +1,136 @@
+"""统一异常码体系 - 按模块分段"""
+from enum import IntEnum
+
+
+class ErrorCode(IntEnum):
+    """统一错误码 - 前端拿到 code 就知道具体什么错误"""
+
+    # 通用 1000-1999
+    SUCCESS = 0
+    UNKNOWN = 1000
+    PARAM_ERROR = 1001
+    NOT_FOUND = 1002
+
+    # 认证 2000-2999
+    UNAUTHORIZED = 2000
+    TOKEN_EXPIRED = 2001
+    FORBIDDEN = 2002
+
+    # 员工 3000-3999
+    EMPLOYEE_NOT_FOUND = 3000
+    EMPLOYEE_USERNAME_EXISTS = 3001
+    EMPLOYEE_PHONE_EXISTS = 3002
+    EMPLOYEE_PASSWORD_ERROR = 3003
+    EMPLOYEE_DISABLED = 3004
+
+    # 角色 4000-4999
+    ROLE_NOT_FOUND = 4000
+    ROLE_CODE_EXISTS = 4001
+    ROLE_IN_USE = 4002
+
+    # 菜单 4100-4199
+    MENU_NOT_FOUND = 4100
+    MENU_HAS_CHILDREN = 4101
+
+    # 部门 4200-4299
+    DEPT_NOT_FOUND = 4200
+    DEPT_HAS_CHILDREN = 4201
+    DEPT_HAS_EMPLOYEES = 4202
+
+    # 岗位 4300-4399
+    POST_NOT_FOUND = 4300
+    POST_CODE_EXISTS = 4301
+    POST_IN_USE = 4302
+
+    # 字典 5000-5999
+    DICT_TYPE_NOT_FOUND = 5000
+    DICT_CODE_EXISTS = 5001
+    DICT_TYPE_IN_USE = 5002
+    DICT_SYSTEM_PROTECTED = 5003  # 系统内置字典禁止修改/删除
+
+    # 素材 6000-6999
+    MATERIAL_NOT_FOUND = 6000
+    MATERIAL_UPLOAD_FAILED = 6001
+    MATERIAL_GROUP_NOT_FOUND = 6002
+
+    # 配置 7000-7999
+    CONFIG_NOT_FOUND = 7000
+    CONFIG_KEY_EXISTS = 7001
+
+    # 通知 8000-8999
+    NOTICE_NOT_FOUND = 8000
+    SMS_SEND_FAILED = 8001
+
+    # 日志 9000-9999
+    LOG_NOT_FOUND = 9000
+
+    # 协议 9100-9199
+    AGREEMENT_NOT_FOUND = 9100
+    AGREEMENT_CODE_EXISTS = 9101
+    AGREEMENT_NOT_PUBLISHED = 9102
+    AGREEMENT_ALREADY_AGREED = 9103
+    AGREEMENT_HISTORY_NOT_FOUND = 9104
+    AGREEMENT_HISTORY_HAS_USERS = 9105
+    AGREEMENT_HAS_USERS = 9106
+    AGREEMENT_NEEDS_RECONFIRM = 9107
+
+    # 用户 9200-9299
+    USER_NOT_FOUND = 9200
+    USER_PHONE_EXISTS = 9201
+    USER_EMAIL_EXISTS = 9202
+    USER_PASSWORD_ERROR = 9203
+    USER_DISABLED = 9204
+
+    # 文章 9300-9399
+    ARTICLE_NOT_FOUND = 9300
+    ARTICLE_CATEGORY_NOT_FOUND = 9310
+    ARTICLE_CATEGORY_CODE_EXISTS = 9311
+    ARTICLE_CATEGORY_IN_USE = 9312
+    ARTICLE_COLLECTION_NOT_FOUND = 9320
+    ARTICLE_COLLECTION_NOT_EMPTY = 9321
+
+    # 相册/照片 9400-9499
+    ALBUM_NOT_FOUND = 9400
+    ALBUM_NOT_EMPTY = 9401
+    PHOTO_NOT_FOUND = 9410
+    PHOTO_COVER_EXISTS = 9411
+
+    # 视频 9500-9599
+    VIDEO_NOT_FOUND = 9500
+    VIDEO_CATEGORY_NOT_FOUND = 9510
+    VIDEO_CATEGORY_CODE_EXISTS = 9511
+    VIDEO_CATEGORY_IN_USE = 9512
+    VIDEO_COLLECTION_NOT_FOUND = 9520
+    VIDEO_COLLECTION_NOT_EMPTY = 9521
+
+    # 智能客服 9600-9699
+    CS_CONFIG_NOT_FOUND = 9600
+    CS_KB_NOT_FOUND = 9610
+    CS_CHUNK_NOT_FOUND = 9620
+    CS_SESSION_NOT_FOUND = 9630
+    CS_CONFIG_INACTIVE = 9640
+    CS_EMBEDDING_FAILED = 9650
+
+
+class AppException(Exception):
+    """应用异常 - 业务代码只管 raise，不管怎么返回"""
+
+    def __init__(self, code: ErrorCode, msg: str | None = None, http_status: int = 400):
+        self.code = code
+        self.msg = msg or code.name
+        self.http_status = http_status
+
+
+class NotFoundException(AppException):
+    def __init__(self, msg: str = "资源不存在"):
+        super().__init__(ErrorCode.NOT_FOUND, msg, 404)
+
+
+class UnauthorizedException(AppException):
+    def __init__(self, msg: str = "未登录"):
+        super().__init__(ErrorCode.UNAUTHORIZED, msg, 401)
+
+
+class ForbiddenException(AppException):
+    def __init__(self, msg: str = "无权限"):
+        super().__init__(ErrorCode.FORBIDDEN, msg, 403)

reglow/common/i18n.py

@@ -0,0 +1,77 @@
+"""轻量国际化工具"""
+from typing import Any
+
+DEFAULT_LOCALE = "zh-CN"
+SUPPORTED_LOCALES: set[str] = {"zh-CN", "en-US"}
+
+_MESSAGES: dict[str, dict[str, str]] = {
+    "zh-CN": {
+        "common.success": "操作成功",
+        "common.fail": "操作失败",
+        "common.server_error": "服务器内部错误",
+        "common.validation_failed": "参数校验失败",
+        "auth.login_success": "登录成功",
+        "auth.logout_success": "退出成功",
+        "auth.captcha_error": "验证码错误",
+        "auth.slide_verify_failed": "滑动验证失败，请重试",
+        "auth.sms_sent": "验证码发送成功",
+    },
+    "en-US": {
+        "common.success": "Success",
+        "common.fail": "Failed",
+        "common.server_error": "Internal server error",
+        "common.validation_failed": "Validation failed",
+        "auth.login_success": "Login successful",
+        "auth.logout_success": "Logout successful",
+        "auth.captcha_error": "Invalid verification code",
+        "auth.slide_verify_failed": "Slide verification failed, please try again",
+        "auth.sms_sent": "Verification code sent",
+    },
+}
+
+
+def register_locale(locale: str, messages: dict[str, str]) -> None:
+    """注册新的语言或追加翻译消息。
+
+    如果 locale 已存在，messages 会合并到已有翻译中（新 key 覆盖旧 key）。
+    如果 locale 不存在，则新增该语言。
+    """
+    SUPPORTED_LOCALES.add(locale)
+    if locale in _MESSAGES:
+        _MESSAGES[locale].update(messages)
+    else:
+        _MESSAGES[locale] = messages
+
+
+def add_messages(locale: str, messages: dict[str, str]) -> None:
+    """向已有语言追加翻译消息（register_locale 的别名）"""
+    register_locale(locale, messages)
+
+
+def normalize_locale(value: str | None) -> str:
+    if not value:
+        return DEFAULT_LOCALE
+    locale = value.split(",", 1)[0].split(";", 1)[0].strip()
+    if locale in SUPPORTED_LOCALES:
+        return locale
+    lower = locale.lower()
+    if lower.startswith("en"):
+        return "en-US"
+    if lower.startswith("zh"):
+        return "zh-CN"
+    return DEFAULT_LOCALE
+
+
+def get_locale_from_request(request: Any) -> str:
+    headers = getattr(request, "headers", {}) or {}
+    return normalize_locale(headers.get("X-Locale") or headers.get("Accept-Language"))
+
+
+def translate(key: str, locale: str = DEFAULT_LOCALE, **params: Any) -> str:
+    current = normalize_locale(locale)
+    text = _MESSAGES.get(current, {}).get(key) or _MESSAGES[DEFAULT_LOCALE].get(key) or key
+    return text.format(**params) if params else text
+
+
+def translate_request(request: Any, key: str, **params: Any) -> str:
+    return translate(key, get_locale_from_request(request), **params)