specdb 1.3.0

Spec-driven generic database module for Flask applications.

后端

包（specdb）

当前发布状态：

• specdb 1.3.0 是当前稳定发布版本。
• specdb 1.0.0 是首个稳定版基线，1.1.0、1.2.0 和 1.3.0 在其上继续补齐可长期冻结的主包能力。
• 本次里程碑的发布说明见 docs/release/RELEASE_NOTES_1.3.0.md。
• 当前未解决的稳定性问题见 docs/maintenance/STABILITY_ISSUES.md。

1.3.0 新增并冻结了正式安装层入口：

• specdb.install.install_schema
• specdb.install.install_suite
• specdb.install.install_seed
• specdb.install.load_seed_bundle
• specdb.install.install_seed_file
• specdb.install.reset_dev_database
• specdb.install.verify_installation

模板资产的稳定公开入口则包括：

• specdb.list_templates
• specdb.get_template
• specdb.get_template_suite
• specdb.get_template_suite_install_plan
• specdb.get_template_suite_seed_sets

当前发布面的默认理解是：

• README 里出现的导入入口，视为主包稳定承诺
• 契约文档里定义的接口，视为主包稳定承诺
• examples/ 和文档中的示例路径、示例 seed 内容，只作为参考资料，不构成兼容承诺

快速开始

最小化应用工厂示例：

from flask import Flask

from specdb.db_module import DBModuleOptions, init_db_module


def create_app() -> Flask:
    app = Flask(__name__)
    app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///example.sqlite3"
    app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
    init_db_module(
        app,
        options=DBModuleOptions(
            db_url_prefix="/api/db",
            blueprint_name="db",
            enable_ops_routes=True,
            enable_restore_routes=True,
        ),
    )
    return app

可直接运行的示例：

• examples/minimal_app.py
• examples/production_app.py
• examples/README.md

以可编辑模式安装：

pip install -e .

库接入入口：

from specdb.db_module import DBModuleOptions, init_db_module

运行

python app.py

本地 .env 会自动从仓库根目录 .env 或 backend/.env 读取。 如果 shell 环境变量已经显式设置，则仍以显式环境变量为准。

示例：

APP_ENV=development
FLASK_DEBUG=0
DATABASE_URL=postgresql+psycopg://web_tools_user:your_password@127.0.0.1:5432/web_tools

生产配置

配置项	是否必需	说明
APP_ENV	建议设置	部署环境建议设为 production；未设置时默认按 production 处理。
DATABASE_URL	生产环境必需	SQLAlchemy 数据库连接串。
DB_MODULE_URL_PREFIX	否	DB 模块路由前缀，默认 /api/db。
DB_MODULE_BLUEPRINT_NAME	否	Blueprint 作用域键，默认 db。
DB_MODULE_ENABLE_OPS_ROUTES	否	是否启用 /ops/* 路由。
DB_MODULE_ENABLE_RESTORE_ROUTES	否	是否启用 /ops/* 下的恢复接口。
DB_MODULE_REQUIRE_OPS_AUTH	可选覆盖	未显式声明开发/测试环境时，启用 ops 路由默认要求 ops_auth_callback；可用此项显式覆盖。
CORS_ORIGINS	否	允许的 CORS 来源；空值表示不返回 CORS 头。
OPS_JOB_LEASE_SECONDS	否	长时间运行的 ops 任务租约时长。

运维接口鉴权边界

• CRUD 路由（/table、/data、/templates）与 /ops/* 路由是分离的。
• 未声明环境时默认按更安全的口径处理：启用 ops 路由时要求 ops_auth_callback。
• 只有显式开发/测试环境，或显式设置 DB_MODULE_REQUIRE_OPS_AUTH=false 时，才允许无 ops_auth_callback。
• 如果不需要 ops 路由，建议直接通过 DB_MODULE_ENABLE_OPS_ROUTES=false 禁用。
• 如果不需要恢复接口，也建议同时关闭 DB_MODULE_ENABLE_RESTORE_ROUTES。

本地 PostgreSQL 配置

最小化本地配置步骤：

1. 创建数据库 web_tools
2. 创建或指定一个数据库用户，例如 web_tools_user
3. 在 backend/.env 中把 DATABASE_URL 指向该数据库

如果应用可以连接数据库，但在建表阶段报 InsufficientPrivilege，请在目标数据库内授予 schema 权限：

GRANT CONNECT ON DATABASE web_tools TO web_tools_user;
GRANT USAGE, CREATE ON SCHEMA public TO web_tools_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO web_tools_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO web_tools_user;

或者直接把数据库所有者设为该用户：

ALTER DATABASE web_tools OWNER TO web_tools_user;

测试

python scripts/run_tests.py

测试目录说明见 tests/README.md。

构建发布包

python scripts/build_package.py
python scripts/verify_package.py

预期产物：

• package_dist/specdb-<version>-py3-none-any.whl
• package_dist/specdb-<version>.tar.gz

scripts/verify_package.py 默认会使用严格的隔离虚拟环境进行校验。 当前也会一并验收：

• specdb
• specdb.install
• specdb.db_templates
• 根包导出的安装层 helper 与模板 helper

如果是离线本地验证，可以显式启用宽松模式：

$env:VERIFY_ALLOW_SYSTEM_SITE_PACKAGES='1'
python scripts/verify_package.py

版本变更记录见 CHANGELOG.md。 手工发布校验流程可参考 .github/workflows/release.yml。 发布说明可基于 docs/release/RELEASE_TEMPLATE.md 起草。 scripts/build_package.py 在生成产物前也会校验 pyproject.toml 版本与 CHANGELOG.md 是否一致。 稳定版升级说明见 docs/release/UPGRADE_1.3.0.md。 发布检查清单见 docs/release/RELEASE_CHECKLIST.md。

或者：

python -m unittest discover -s tests -p "test_*.py" -v

PostgreSQL 集成测试（可选）

如果本地配置解析出的数据库连接是 PostgreSQL，python scripts/run_tests.py 会自动带上 PostgreSQL 集成测试。你也可以显式开启：

export RUN_PG_TESTS=1
export DATABASE_URL_PG=postgresql+psycopg://user:pass@127.0.0.1:5432/dbname
python scripts/run_tests.py

PowerShell：

$env:RUN_PG_TESTS='1'
$env:DATABASE_URL_PG='postgresql+psycopg://user:pass@127.0.0.1:5432/dbname'
python scripts/run_tests.py

如果 DATABASE_URL 指向 PostgreSQL，但你仍想强制跳过 PostgreSQL 集成测试：

$env:RUN_PG_TESTS='0'
python scripts/run_tests.py

CI

当前仓库 CI 默认会运行：

• 后端单元测试 / API 测试
• 前端 lint
• 前端构建

PostgreSQL 集成测试在 CI 中是可选项，只有在仓库配置了 DATABASE_URL_PG 密钥时才会运行。