import copy import re from datetime import datetime from typing import Any from jinja2 import Environment, FileSystemLoader, Template from app.common.constant import GenConstant from app.config.path_conf import TEMPLATE_DIR from app.config.setting import settings from app.utils.common_util import CamelCaseUtil, SnakeCaseUtil, compute_menu_route_first_segment from app.utils.string_util import StringUtil from .gen_util import GenUtils from .schema import ( GenTableColumnOutSchema, GenTableOutSchema, ) from .template_safety import ( column_type_base, escape_template_text, html_attr, pick_sqlalchemy_type, safe_ident, safe_python_type, vue_label, ) # 哨兵文本：用于「用哨兵值渲染同一模板，得到结构骨架」的落盘前比对 # （见 template_safety.assert_python_structure / assert_text_structure） SENTINEL_TEXT = "__SAFE_TEXT__" # 自由文本字段：哨兵化只针对它们（保证结构比对有意义）；标识符/类型/开关/长度等 # 必须保持真实值，否则模板分支会与骨架不一致，产生误报 _SENTINEL_TABLE_TEXT_FIELDS = ("table_name", "table_comment", "function_name", "business_name", "sub_table_name", "description") _SENTINEL_COLUMN_TEXT_FIELDS = ("column_comment", "dict_type") class Jinja2TemplateUtil: """模板处理工具类 """ @classmethod def normalize_db_column_type_for_mapping(cls, column_type: str | None) -> str: """与 ``GenUtils.get_db_type`` 一致地去掉 COLLATE / UNSIGNED，便于与 ``DB_TO_SQLALCHEMY`` 键匹配。 参数: - column_type (str | None): 原始列类型字符串。 返回: - str: 规范化后的类型片段；空输入返回空字符串。 """ ct = (column_type or "").strip() if not ct: return "" collate_pattern = re.compile(r"\s+COLLATE\s+", re.IGNORECASE) if collate_pattern.search(ct): ct = collate_pattern.split(ct)[0].strip() unsigned_pattern = re.compile(r"\s+UNSIGNED", re.IGNORECASE) if unsigned_pattern.search(ct): ct = unsigned_pattern.sub("", ct).strip() return ct # 项目路径 FRONTEND_PROJECT_PATH = "frontend/web" BACKEND_PROJECT_PATH = "backend" # 环境对象 _env = None @classmethod def get_env(cls): """获取模板环境对象。 参数: - 无 返回: - Environment: Jinja2 环境对象。 """ try: if cls._env is None: cls._env = Environment( loader=FileSystemLoader(TEMPLATE_DIR), autoescape=False, # 自动转义HTML trim_blocks=True, # 删除多余的空行 lstrip_blocks=True, # 删除行首空格 keep_trailing_newline=True, # 保留行尾换行符 enable_async=True, # 开启异步支持 ) cls._env.filters.update( { "camel_to_snake": SnakeCaseUtil.camel_to_snake, "snake_to_camel": CamelCaseUtil.snake_to_camel, "get_sqlalchemy_type": cls.get_sqlalchemy_type, "python_to_ts_type": cls.python_type_to_ts_type, # 模板内按上下文安全化（详见 template_safety.py）： # 绝大多数值已在 prepare_context 统一处理，模板里可按需显式调用 "py_text": escape_template_text, "py_ident": safe_ident, "py_type": safe_python_type, "vue_label": vue_label, # 静态 HTML 属性值：实体转义（展示保真，不用 \uXXXX） "html_attr": html_attr, }, ) return cls._env except Exception as e: raise RuntimeError(f"初始化Jinja2模板引擎失败: {e}") @classmethod def get_template(cls, template_path: str) -> Template: """获取模板。 参数: - template_path (str): 模板路径。 返回: - Template: Jinja2 模板对象。 异常: - TemplateNotFound: 模板未找到时抛出。 """ return cls.get_env().get_template(template_path) @classmethod def business_name_to_slug(cls, business_name: str | None) -> str: """业务路径可含斜杠（如 ``demo/subdir``）用于目录与路由前缀； Python 函数/方法名仅使用最后一段并规范为合法 snake_case 片段。 参数: - business_name (str | None): 业务路径或名称。 返回: - str: 用于 Python 标识的 slug，默认 entity。 """ s = (business_name or "").strip().strip("/") if not s: return "entity" if "/" in s: s = s.split("/")[-1] s = re.sub(r"[^a-zA-Z0-9_]", "_", s) if not s: return "entity" if s[0].isdigit(): s = "_" + s return s @classmethod def business_name_to_path(cls, business_name: str | None) -> str: """把 business_name 规范为可用于目录/路由的多段路径（保留 `/`）。 约定：`business_name` 允许 `a/b/c` 表示多级菜单目录。 - 目录/路由：使用完整多段 - 文件名/route_name：使用最后一段 slug（见 `business_name_to_slug`） 参数: - business_name (str | None): 业务路径或名称。 返回: - str: 多段路径字符串（小写 slug），默认 entity。 """ s = (business_name or "").strip().strip("/") if not s: return "entity" # 每段都做一次轻度规范（与 schema 的 slug 规则一致：a-z0-9_） segs = [] for raw in [p for p in s.split("/") if p]: seg = re.sub(r"[^a-zA-Z0-9_]", "_", raw).lower() seg = re.sub(r"_+", "_", seg).strip("_") or "entity" if seg[0].isdigit(): seg = "_" + seg segs.append(seg) return "/".join(segs) if segs else "entity" @classmethod def safe_render_schema(cls, gen_table: GenTableOutSchema) -> GenTableOutSchema: """构造「仅用于模板渲染」的安全副本。 生成物是会被执行/被构建链消费的源码（``.py`` 会被 ``app/core/discover.py`` 启动时 import）， 因此所有用户可控文本必须按所处上下文安全化后才能进模板。此处统一处理， 避免逐个模板/逐个字段遗漏；``autoescape=True`` 不适用（会把生成的代码本身转义坏）。 **从 schema 进入模板的值按四类显式处理**（实现见 template_safety.py）： 1. 字符串类（注释/描述/功能名/表名…）→ ``escape_template_text``（``\\uXXXX``，仅用于字符串/注释上下文）； 2. 标识符类（列名/类名/模块名/python_field）→ ``safe_ident``（含关键字与保留字排除）； 3. 代码位置类（SQLAlchemy 类型、长度/精度）→ ``pick_sqlalchemy_type``：**只从常量白名单派生**，不接收自由文本； 4. 路径类（包名/模块名/业务路径/文件名）→ slug/白名单规范化（``business_name_to_path`` 等），不含 ``..`` 与分隔符。 展示位置（``.vue`` 文本节点与静态属性）另有 ``vue_label``/``html_attr``：HTML 实体转义，保真且不破坏标记结构。 参数: - gen_table (GenTableOutSchema): 原始生成配置（不会被修改）。 返回: - GenTableOutSchema: 深拷贝并按上下文安全化后的副本。 """ safe_table = copy.deepcopy(gen_table) cls._sanitize_schema_in_place(safe_table, set()) return safe_table @classmethod def sentinel_render_schema(cls, gen_table: GenTableOutSchema) -> GenTableOutSchema: """构造「哨兵值」副本：自由文本换成固定哨兵（空值保持为空），用于生成结构骨架。 与 :meth:`safe_render_schema` 的区别：这里不追求可展示/可用，只要求**结构中性**—— 值里不含任何可能改变模板分支或语法结构的字符。用它渲染同一模板得到的 AST/行结构 即为「该模板的规范骨架」，落盘前与真实产物比对（见 template_safety 的结构闸门）。 参数: - gen_table (GenTableOutSchema): 已安全化的渲染配置。 返回: - GenTableOutSchema: 自由文本字段被替换为哨兵的深拷贝。 """ sentinel_table = copy.deepcopy(gen_table) cls._sentinelize_schema_in_place(sentinel_table, set()) return sentinel_table @classmethod def _sentinelize_schema_in_place(cls, table: GenTableOutSchema, seen: set[int]) -> None: """就地哨兵化自由文本字段（标识符/类型/开关/长度保持不变），带环保护。""" if table is None or id(table) in seen: return seen.add(id(table)) for field in _SENTINEL_TABLE_TEXT_FIELDS: if hasattr(table, field): setattr(table, field, _sentinelize_value(getattr(table, field))) for column in table.columns or []: cls._sentinelize_column_in_place(column, seen) if table.pk_column is not None: cls._sentinelize_column_in_place(table.pk_column, seen) if table.sub_table is not None: cls._sentinelize_schema_in_place(table.sub_table, seen) @staticmethod def _sentinelize_column_in_place(column: GenTableColumnOutSchema, seen: set[int]) -> None: """就地哨兵化字段级自由文本（列名/类型/长度等保持原值）。""" if column is None or id(column) in seen: return seen.add(id(column)) for field in _SENTINEL_COLUMN_TEXT_FIELDS: if hasattr(column, field): setattr(column, field, _sentinelize_value(getattr(column, field))) @classmethod def iter_free_text_values(cls, gen_table: GenTableOutSchema) -> list[str]: """枚举本次渲染里会进入模板的**自由文本值**（与哨兵化字段一一对应，按同样顺序）。 供 ``.vue``/``.ts`` 的行结构比对使用：把真实值与哨兵都抹成占位符后再逐行比较。 参数: - gen_table (GenTableOutSchema): 已安全化的渲染配置。 返回: - list[str]: 非空自由文本值列表。 """ values: list[str] = [] seen: set[int] = set() def walk(table: GenTableOutSchema) -> None: if table is None or id(table) in seen: return seen.add(id(table)) for field in _SENTINEL_TABLE_TEXT_FIELDS: text = getattr(table, field, None) if text: values.append(str(text)) for column in table.columns or []: collect_column(column) if table.pk_column is not None: collect_column(table.pk_column) if table.sub_table is not None: walk(table.sub_table) def collect_column(column: GenTableColumnOutSchema) -> None: if column is None or id(column) in seen: return seen.add(id(column)) for field in _SENTINEL_COLUMN_TEXT_FIELDS: text = getattr(column, field, None) if text: values.append(str(text)) walk(gen_table) return values @classmethod def iter_render_dynamic_values(cls, gen_table: GenTableOutSchema) -> list[str]: """返回真实产物里可能出现的**所有动态文本形态**（原值 / 转义值 / 展示形态）。 供 ``.vue``/``.ts`` 的行结构比对把动态部分抹成占位符：同一个值可能以 ``escape_template_text``（JS 字符串）、``html_attr``（静态属性）、``vue_label``（文本节点） 三种形态出现，三者都要抹掉，否则会与骨架产生假阳性。 参数: - gen_table (GenTableOutSchema): 已安全化的渲染配置。 返回: - list[str]: 动态文本形态列表。 """ tokens: list[str] = [] for value in cls.iter_free_text_values(gen_table): text = str(value) tokens.extend([text, escape_template_text(text), html_attr(text), vue_label(text)]) return tokens @classmethod def _sanitize_schema_in_place(cls, table: GenTableOutSchema, seen: set[int]) -> None: """就地安全化一张表（表级文本 + 全部字段 + 子表），带环保护。 参数: - table (GenTableOutSchema): 待处理的安全副本（会被修改）。 - seen (set[int]): 已处理对象 id 集合（主/子表互相引用时防重入）。 返回: - None """ if table is None or id(table) in seen: return seen.add(id(table)) # 落进字符串字面量/注释/文档字符串的文本 table.table_name = escape_template_text(table.table_name) table.table_comment = escape_template_text(table.table_comment) table.function_name = escape_template_text(table.function_name) # 落进标识符位置的值（类名 / 模块名 / 包名 / 外键列名） table.class_name = safe_ident(table.class_name, default="") table.module_name = safe_ident(table.module_name, default="") table.package_name = safe_ident(table.package_name, default="") table.sub_table_fk_name = safe_ident(table.sub_table_fk_name, default="") # 业务名允许 a/b 多段，且参与目录派生，按文本处理即可（派生见 prepare_context） table.business_name = escape_template_text(table.business_name) table.sub_table_name = escape_template_text(table.sub_table_name) for column in table.columns or []: cls._sanitize_column_in_place(column, seen) # pk_column 通常就是 columns 里的同一个对象（见 set_pk_column），必须靠 seen 去重， # 否则同一字段被转义两次（\u0027 → \u005cu0027），产物里的文本会变形 if table.pk_column is not None: cls._sanitize_column_in_place(table.pk_column, seen) if table.sub_table is not None: cls._sanitize_schema_in_place(table.sub_table, seen) @staticmethod def _sanitize_column_in_place(column: GenTableColumnOutSchema, seen: set[int]) -> None: """就地安全化单个字段：列名/类型注解按标识符处理，注释/字典类型按文本转义。 参数: - column (GenTableColumnOutSchema): 待处理的安全副本（会被修改）。 - seen (set[int]): 已处理对象 id 集合（同一字段被 columns 与 pk_column 同时引用时防重复转义）。 返回: - None """ if column is None or id(column) in seen: return seen.add(id(column)) column.column_name = safe_ident(column.column_name, default="") column.python_type = safe_python_type(column.python_type) column.python_field = safe_ident(column.python_field, default="") column.column_comment = escape_template_text(column.column_comment) column.dict_type = escape_template_text(column.dict_type) @classmethod def prepare_context(cls, gen_table: GenTableOutSchema) -> dict[str, Any]: """准备模板变量。 参数: - gen_table (GenTableOutSchema): 生成表的配置信息。 返回: - Dict[str, Any]: 模板上下文字典。 """ # 处理options为None的情况 # if not gen_table.options: # raise ValueError('请先完善生成配置信息') # 目录/文件名派生值仍按原始业务名计算，保证既有产物路径不变； # 其余进入模板的内容一律取安全副本（详见 template_safety.py）。 business_name_raw = (gen_table.business_name or "").strip() business_path = cls.business_name_to_path(business_name_raw) business_name_slug = cls.business_name_to_slug(business_name_raw) gen_table = cls.safe_render_schema(gen_table) class_name = gen_table.class_name or "" package_name = (gen_table.package_name or "").strip() module_name = (gen_table.module_name or "").strip() business_name = (gen_table.business_name or "").strip() function_name = gen_table.function_name or "" # 生成规则（对齐 module_example/demo）： # - 分系统根：package_name = module_xxx # - 目录固定为：module_xxx / module_name（不再额外使用业务名作为目录层级） # - 权限前缀固定为：module_xxx:module_name（操作在模板里再拼 :query/:create...） permission_prefix = ":".join([s for s in [package_name, module_name] if s]) api_route_prefix = cls.get_api_route_prefix(package_name) _cols = gen_table.columns or [] table_column_names = frozenset(c.column_name for c in _cols if getattr(c, "column_name", None)) has_dict_column = any(getattr(c, "dict_type", None) for c in _cols) has_image_column = any(getattr(c, "html_type", None) == "imageUpload" for c in _cols) has_json_column = any(getattr(c, "python_type", None) == "dict" for c in _cols) sub_class_name = "" sub_model_class_name = "" sub_rel_list_name = "" parent_rel_name = "" if gen_table.sub and gen_table.sub_table: st = gen_table.sub_table scn = (st.class_name or GenUtils.convert_class_name(gen_table.sub_table_name or "")).strip() sub_class_name = scn sub_model_class_name = f"{scn}Model" sub_rel_list_name = f"{SnakeCaseUtil.camel_to_snake(scn)}_list" parent_rel_name = SnakeCaseUtil.camel_to_snake(gen_table.class_name or "") context = { "table_name": gen_table.table_name or "", "table_comment": gen_table.table_comment or "", "function_name": function_name if StringUtil.is_not_empty(function_name) else "【请填写功能名称】", "class_name": class_name, "module_name": module_name, "business_name": business_name, "business_path": business_path, "business_file": business_name_slug, "business_name_slug": business_name_slug, "base_package": cls.get_package_prefix(package_name), "package_name": package_name, "plugin_name": package_name.removeprefix("module_"), "menu_route_first_segment": cls.get_menu_route_first_segment(gen_table), "datetime": datetime.now().strftime("%Y-%m-%d %H:%M:%S"), "pk_column": gen_table.pk_column, "model_import_list": cls.get_model_import_list(gen_table), "schema_import_list": cls.get_schema_import_list(gen_table), "permission_prefix": permission_prefix, "api_route_prefix": api_route_prefix, "columns": gen_table.columns or [], "table_column_names": table_column_names, "table": gen_table, "dicts": cls.get_dicts(gen_table), "db_type": settings.DATABASE_TYPE, "column_not_add_show": GenConstant.COLUMNNAME_NOT_ADD_SHOW, "column_not_edit_show": GenConstant.COLUMNNAME_NOT_EDIT_SHOW, "parent_menu_id": int(gen_table.parent_menu_id) if gen_table.parent_menu_id else None, "is_sub_entity": False, "sub_class_name": sub_class_name, "sub_model_class_name": sub_model_class_name, "sub_module_name": (gen_table.sub_table.module_name if gen_table.sub and gen_table.sub_table else ""), "sub_rel_list_name": sub_rel_list_name, "parent_rel_name": parent_rel_name, "parent_list_rel_name": "", "parent_table_name": "", "parent_model_class_name": "", # 数据表实际主键列名（用于生成前端行键等；ModelMixin 仍默认带 id 字段） "pk_column_name": (gen_table.pk_column.column_name if gen_table.pk_column else None) or "id", "parent_pk_column_name": (gen_table.pk_column.column_name if gen_table.pk_column else None) or "id", "sub_table_fk_name": "", "has_dict_column": has_dict_column, "has_image_column": has_image_column, "has_json_column": has_json_column, } return context @classmethod def get_menu_route_first_segment(cls, gen_table: GenTableOutSchema) -> str: """前端页面路由首段（与写入菜单 ``route_path`` 第一段一致）：始终为 ``module_xxx``。""" pid = int(gen_table.parent_menu_id) if gen_table.parent_menu_id is not None else None return compute_menu_route_first_segment( pid, gen_table.package_name or "", gen_table.module_name, ) @classmethod def prepare_sub_render_context(cls, parent: GenTableOutSchema, sub: GenTableOutSchema) -> dict[str, Any]: """子表业务代码渲染上下文（与主表同模块、独立业务目录）。 参数: - parent (GenTableOutSchema): 主表配置。 - sub (GenTableOutSchema): 子表配置。 返回: - dict[str, Any]: 子表模板上下文字典。 """ ctx = cls.prepare_context(sub) # 父表字段同样进入模板（parent_* / relationship 实参），必须取自安全副本 parent_safe = cls.safe_render_schema(parent) sub_safe = cls.safe_render_schema(sub) scn = (sub_safe.class_name or GenUtils.convert_class_name(sub_safe.table_name or "")).strip() ctx["is_sub_entity"] = True ctx["parent_class_name"] = parent_safe.class_name or "" ctx["parent_model_class_name"] = f"{parent_safe.class_name}Model" ctx["parent_table_name"] = parent_safe.table_name or "" ctx["parent_pk_column_name"] = (parent_safe.pk_column.column_name if parent_safe.pk_column else None) or "id" ctx["parent_rel_name"] = SnakeCaseUtil.camel_to_snake(parent_safe.class_name or "parent") ctx["parent_list_rel_name"] = f"{SnakeCaseUtil.camel_to_snake(scn)}_list" ctx["sub_table_fk_name"] = (parent_safe.sub_table_fk_name or "").strip() ctx["model_import_list"] = cls.get_model_import_list(sub_safe, is_sub_entity=True) ctx["schema_import_list"] = cls.get_schema_import_list(sub_safe) return ctx @classmethod def get_template_list(cls): """获取主表模板列表。 参数: - 无 返回: - List[str]: 模板路径列表。 """ templates = [ "python/controller.py.jinja2", "python/service.py.jinja2", "python/crud.py.jinja2", "python/schema.py.jinja2", "python/model.py.jinja2", "python/__init__.py.jinja2", "python/package_init.py.jinja2", "python/plugin.toml.jinja2", "ts/api.ts.jinja2", "vue/index.vue.jinja2", ] return templates @classmethod def get_sub_table_template_list(cls): """获取子表模板列表（仅 model / schema / __init__，不含 controller/service/crud/vue/api）。 参数: - 无 返回: - List[str]: 子表模板路径列表。 """ return [ "python/model.py.jinja2", "python/schema.py.jinja2", "python/__init__.py.jinja2", ] @classmethod def get_file_name(cls, template: str, gen_table: GenTableOutSchema): """根据模板生成文件名。 参数: - template (str): 模板路径字符串。 - gen_table (GenTableOutSchema): 生成表的配置信息。 返回: - str: 模板生成的文件名。 异常: - ValueError: 当无法生成有效文件名时抛出。 """ package_name = (gen_table.package_name or "").strip() module_name = (gen_table.module_name or "").strip() if not package_name: raise ValueError(f"无法为模板 {template} 生成文件名：包名未设置") if not module_name: raise ValueError(f"无法为模板 {template} 生成文件名：模块名未设置") # 目录固定为：module_xxx/{module_name} backend_base = f"{cls.BACKEND_PROJECT_PATH}/app/plugin/{package_name}" frontend_view_base = f"{cls.FRONTEND_PROJECT_PATH}/src/views/{package_name}" frontend_api_base = f"{cls.FRONTEND_PROJECT_PATH}/src/api/{package_name}" backend_dir = f"{backend_base}/{module_name}" view_dir = f"{frontend_view_base}/{module_name}" api_path = f"{frontend_api_base}/{module_name}.ts" template_mapping = { "controller.py.jinja2": f"{backend_dir}/controller.py", "service.py.jinja2": f"{backend_dir}/service.py", "crud.py.jinja2": f"{backend_dir}/crud.py", "schema.py.jinja2": f"{backend_dir}/schema.py", "model.py.jinja2": f"{backend_dir}/model.py", "__init__.py.jinja2": f"{backend_dir}/__init__.py", "package_init.py.jinja2": f"{backend_base}/__init__.py", "plugin.toml.jinja2": f"{backend_base}/plugin.toml", "api.ts.jinja2": api_path, "index.vue.jinja2": f"{view_dir}/index.vue", } # 查找匹配的模板路径 for key, path in template_mapping.items(): if key in template: return path # 遍历完所有映射都没找到匹配项，才抛出异常 raise ValueError(f"未找到模板 '{template}' 的路径映射") @classmethod def get_package_prefix(cls, package_name: str) -> str: """获取包前缀。 参数: - package_name (str): 包名。 返回: - str: 包前缀。 """ # 修复：当包名中不存在'.'时，直接返回原包名 return package_name[: package_name.rfind(".")] if "." in package_name else package_name @classmethod def get_schema_import_list(cls, gen_table: GenTableOutSchema): """获取 schema 模板所需的 Python 导入语句集合。 参数: - gen_table (GenTableOutSchema): 生成表配置（含主子表列）。 返回: - set[str]: 导入语句字符串集合。 """ columns = gen_table.columns or [] import_list = set() has_datetime_import = False has_date_import = False has_time_import = False for column in columns: # 处理datetime类型的导入 if column.python_type and column.python_type in GenConstant.TYPE_DATE: if column.python_type == "datetime": has_datetime_import = True elif column.python_type == "date": has_date_import = True elif column.python_type == "time": has_time_import = True elif column.python_type == GenConstant.TYPE_DECIMAL: import_list.add("from decimal import Decimal") if gen_table.sub and gen_table.sub_table and gen_table.sub_table.columns: sub_columns = gen_table.sub_table.columns or [] for sub_column in sub_columns: # 处理datetime类型的导入 if sub_column.python_type and sub_column.python_type in GenConstant.TYPE_DATE: if sub_column.python_type == "datetime": has_datetime_import = True elif sub_column.python_type == "date": has_date_import = True elif sub_column.python_type == "time": has_time_import = True elif sub_column.python_type == GenConstant.TYPE_DECIMAL: import_list.add("from decimal import Decimal") # 添加datetime导入 if has_datetime_import: import_list.add("from datetime import datetime") if has_date_import: import_list.add("from datetime import date") if has_time_import: import_list.add("from datetime import time") return import_list @classmethod def get_model_import_list(cls, gen_table: GenTableOutSchema, *, is_sub_entity: bool = False) -> list[str]: """获取 model 模板所需的 Python 导入语句列表（含合并后的 sqlalchemy 导入）。 参数: - gen_table (GenTableOutSchema): 生成表配置。 - is_sub_entity (bool): 是否为子表独立生成（含外键与 relationship）。 返回: - list[str]: 导入语句列表。 """ columns = gen_table.columns or [] import_list = set() has_datetime_import = False has_date_import = False has_time_import = False # 基类 ModelMixin/UserMixin 已定义的列，无需导入 SQLAlchemy 类型 _BASE_MODEL_COLUMNS = { "id", "uuid", "created_time", "updated_time", "created_id", "updated_id", "is_deleted", "deleted_time", "deleted_id", } for column in columns: if column.column_name in _BASE_MODEL_COLUMNS: # id 列类型与基类主键(Integer)不一致时（如 MySQL bigint 自增/雪花 ID）， # 模板会显式覆盖 id 字段，此处需补上对应 SQLAlchemy 类型的导入； # 其余基类字段（uuid/审计字段等）由 ModelMixin/UserMixin 提供，无需导入 if column.column_name == "id" and column.is_pk: pk_type_import = cls.get_sqlalchemy_type(column).split("(")[0].strip() if pk_type_import and pk_type_import != "Integer": import_list.add(f"from sqlalchemy import {pk_type_import}") continue if column.column_type: data_type = cls.get_db_type(column.column_type) if data_type in GenConstant.COLUMNTYPE_GEOMETRY: import_list.add("from geoalchemy2 import Geometry") import_list.add(f"from sqlalchemy import {StringUtil.get_mapping_value_by_key_ignore_case(GenConstant.DB_TO_SQLALCHEMY, data_type)}") # 处理datetime类型的导入 if column.python_type and column.python_type in GenConstant.TYPE_DATE: if column.python_type == "datetime": has_datetime_import = True elif column.python_type == "date": has_date_import = True elif column.python_type == "time": has_time_import = True # 处理Decimal类型的导入 elif column.python_type == GenConstant.TYPE_DECIMAL: import_list.add("from decimal import Decimal") # 子实体独立生成时才需要外键导入（主表仅声明 relationship，无需 ForeignKey；子表列的 SQLAlchemy # 类型由其自身模型渲染时通过 columns 循环导入） if is_sub_entity: import_list.add("from sqlalchemy import ForeignKey") # 添加datetime导入 if has_datetime_import: import_list.add("from datetime import datetime") if has_date_import: import_list.add("from datetime import date") if has_time_import: import_list.add("from datetime import time") merged = cls.merge_same_imports(list(import_list), "from sqlalchemy import") if gen_table.sub or is_sub_entity: merged.append("from sqlalchemy.orm import relationship") return merged @classmethod def get_db_type(cls, column_type: str) -> str: """获取数据库字段类型。 参数: - column_type (str): 字段类型字符串。 返回: - str: 数据库类型（去除长度等修饰）。 """ # 移除 COLLATE 子句（处理带引号和不带引号的情况，不区分大小写） collate_pattern = re.compile(r"\s+COLLATE\s+", re.IGNORECASE) if collate_pattern.search(column_type): column_type = collate_pattern.split(column_type)[0].strip() # 移除 UNSIGNED 标记（不区分大小写） unsigned_pattern = re.compile(r"\s+UNSIGNED", re.IGNORECASE) if unsigned_pattern.search(column_type): column_type = unsigned_pattern.sub("", column_type).strip() # 处理PostgreSQL数组类型（如 integer[], text[]） if "[]" in column_type: return "array" # 提取基本类型：走严格基名提取（只允许 [A-Za-z][A-Za-z0-9_ ]*，剔除 unsigned 等修饰词）， # 不直接 split 原始文本，避免把括号前的任意内容当作类型名带出去 return column_type_base(column_type) @classmethod def merge_same_imports(cls, imports: list[str], import_start: str) -> list[str]: """合并相同的导入语句。 参数: - imports (list[str]): 导入语句列表。 - import_start (str): 导入语句的起始字符串。 返回: - list[str]: 合并后的导入语句列表。 """ merged_imports = [] imports_ = [] for import_stmt in imports: if import_stmt.startswith(import_start): imported_items = import_stmt.split("import")[1].strip() imports_.extend(imported_items.split(", ")) else: merged_imports.append(import_stmt) if imports_: # 去重并过滤空字符串，然后用逗号连接 unique_imports = [item for item in imports_ if item] if len(unique_imports) > 0: merged_datetime_import = f"{import_start} {', '.join(unique_imports)}" merged_imports.append(merged_datetime_import) return merged_imports @classmethod def get_dicts(cls, gen_table: GenTableOutSchema): """获取字典列表。 参数: - gen_table (GenTableOutSchema): 生成表的配置信息。 返回: - str: 以逗号分隔的字典类型字符串。 """ columns = gen_table.columns or [] dicts = set() cls.add_dicts(dicts, columns) # 处理sub_table为None的情况 if gen_table.sub_table is not None: # 处理sub_table.columns为None的情况 sub_columns = gen_table.sub_table.columns or [] cls.add_dicts(dicts, sub_columns) return ", ".join(dicts) @classmethod def add_dicts(cls, dicts: set[str], columns: list[GenTableColumnOutSchema]) -> None: """添加字典类型到集合。 参数: - dicts (set[str]): 字典类型集合。 - columns (list[GenTableColumnOutSchema]): 字段列表。 返回: - set[str]: 更新后的字典类型集合。 """ for column in columns: super_column = column.super_column if column.super_column is not None else "0" dict_type = column.dict_type or "" html_type = column.html_type or "" if ( super_column != "1" and StringUtil.is_not_empty(dict_type) and StringUtil.equals_any_ignore_case( html_type, [ GenConstant.HTML_SELECT, GenConstant.HTML_RADIO, GenConstant.HTML_CHECKBOX, ], ) ): dicts.add(f"'{dict_type}'") @classmethod def get_permission_prefix(cls, module_name: str | None, business_name: str | None) -> str: """获取权限前缀。 参数: - module_name (str | None): 模块名。 - business_name (str | None): 业务名。 返回: - str: 权限前缀字符串。 """ mn = (module_name or "").strip() bn = (business_name or "").strip().replace("/", ":") if not bn: return mn return f"{mn}:{bn}" @classmethod def python_type_to_ts_type(cls, python_type: str | None) -> str: """将列上的 Python 类型（`get_db_type` + `DB_TO_PYTHON` 映射结果）转为前端 TS 类型片段。 与 JSON 序列化习惯一致：Decimal、日期时间多为字符串；dict/list 用宽松类型。 参数: - python_type (str | None): Python 类型名。 返回: - str: 前端 TypeScript 类型片段。 """ if not python_type or not str(python_type).strip(): return "string" p = str(python_type).strip() mapping: dict[str, str] = { "int": "number", "float": "number", "bool": "boolean", "Decimal": "string", "date": "string", "time": "string", "datetime": "string", "timedelta": "string", "dict": "Record", "list": "unknown[]", "bytes": "string", "str": "string", } return mapping.get(p, "string") @classmethod def get_api_route_prefix(cls, module_name: str | None) -> str: """获取前端 API 路径首段，与 `discover` 中插件路由前缀一致（`module_xxx` → `xxx`）。 参数: - module_name (str | None): 模块名，如 ``module_example``。 返回: - str: 路由前缀，如 ``example``。 """ if not module_name: return "" if module_name.startswith("module_"): return module_name[7:] return module_name @classmethod def get_sqlalchemy_type(cls, column: Any) -> str: """获取 SQLAlchemy 类型（**代码位置** → 一律由常量白名单派生，见 template_safety）。 类型名只能来自 ``GenConstant.DB_TO_SQLALCHEMY`` 的值，长度/精度只能来自 ``column_length.isdigit()`` 或 ``column_type`` 括号内的**数字捕获**； 不再使用 ``column_type.split("(")[1]`` 这类字符串切分（会把任意内容带进产物）。 参数: - column (Any): 列对象或列类型字符串。 返回: - str: SQLAlchemy 类型字符串（如 ``String(64)`` / ``Numeric(10,2)`` / ``DateTime``）。 """ column_type: Any = column column_length: Any = None if hasattr(column, "column_type"): column_type = getattr(column, "column_type", "") or "" column_length = getattr(column, "column_length", None) or None # 先按既有口径去掉 COLLATE / UNSIGNED，便于与常量表的键匹配 column_type = cls.normalize_db_column_type_for_mapping(column_type) return pick_sqlalchemy_type(column_type, column_length) def _sentinelize_value(value: Any) -> Any: """把非空文本替换为哨兵文本（空值/None 原样保留，避免改变模板的真值分支）。 参数: - value (Any): 原始值。 返回: - Any: 哨兵文本或原值。 """ if value is None: return None text = str(value) return SENTINEL_TEXT if text else text