Metadata-Version: 2.4
Name: specdb
Version: 1.3.0
Summary: Spec-driven generic database module for Flask applications.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: flask==3.0.3
Requires-Dist: flask-cors==4.0.1
Requires-Dist: sqlalchemy==2.0.36
Requires-Dist: flask-sqlalchemy==3.1.1
Requires-Dist: psycopg[binary]==3.2.3
Requires-Dist: PyYAML==6.0.2
Requires-Dist: python-dotenv==1.0.1

# 后端

## 包（`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 内容，只作为参考资料，不构成兼容承诺

## 快速开始

最小化应用工厂示例：

```python
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`

以可编辑模式安装：

```bash
pip install -e .
```

库接入入口：

```python
from specdb.db_module import DBModuleOptions, init_db_module
```

## 运行

```bash
python app.py
```

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

示例：

```dotenv
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 权限：

```sql
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;
```

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

```sql
ALTER DATABASE web_tools OWNER TO web_tools_user;
```

## 测试

```bash
python scripts/run_tests.py
```

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

## 构建发布包

```bash
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

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

```powershell
$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`。

或者：

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

### PostgreSQL 集成测试（可选）

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

```bash
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：

```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 集成测试：

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

### CI

当前仓库 CI 默认会运行：

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

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