# Spec: backend-access

## ADDED Requirements

### Requirement: RESTful API 与 CLI 等价接入
系统 SHALL 提供 FastAPI RESTful API 与 Typer CLI 两种等价调用方式；对同一实验配置，二者 MUST 产生等价的执行结果与一致的落库结构。

#### Scenario: API 与 CLI 等价
- **WHEN** 分别通过 API 与 CLI 下发同一实验配置
- **THEN** 二者落库结构一致、执行结果等价

### Requirement: API 作为前端唯一数据源
API SHALL 承担 Web 前端的数据源职责：前后端分离，前端只通过 API 与后端交互；API MUST NOT 返回任何 HTML；前端 MUST NOT 直连数据库；接入层 MUST NOT 跨层直接写库绕过服务层。

#### Scenario: 前端仅经 API 取数
- **WHEN** 前端任意页面加载数据或下发指令
- **THEN** 全部经由 RESTful API JSON 交互，无模板渲染混排

### Requirement: 本地与 Docker 两种启动方式
系统 SHALL 支持两种运行方式：本地开发（后端一条命令、前端一条命令分别启动）；Docker（`docker compose up` 一条命令拉起 PostgreSQL + 后端 + 前端，PostgreSQL 数据 volume 持久化，容器重建不丢实验数据）。

#### Scenario: Docker 一键拉起
- **WHEN** 执行 `docker compose up`
- **THEN** db + backend + frontend(nginx) 全部启动，浏览器访问即可使用

#### Scenario: 容器重建数据不丢
- **WHEN** 删除并重建容器后重新启动
- **THEN** 历史实验数据仍在（volume 持久化）

### Requirement: CLI 冒烟实验
CLI SHALL 支持一条命令跑通小规模冒烟实验（如 1 模型 × L1 × 1 commit × 1 重复）。

#### Scenario: 冒烟实验
- **WHEN** 通过 CLI 下发 1×1×1×1 配置
- **THEN** 生成 1 个实验单元并执行落库

### Requirement: 基础设施白名单
系统 MUST NOT 引入消息队列（RabbitMQ/Kafka）、Redis、Kubernetes 等未列明中间件；允许且仅允许 Docker/docker-compose、PostgreSQL、Nginx（仅托管前端静态文件与反向代理）。新增第三方依赖前须在代码注释或文档中说明理由。

#### Scenario: 依赖检查
- **WHEN** 审查部署与依赖清单
- **THEN** 不存在白名单之外的中间件，新增依赖均有理由说明