first commit

openspec/changes/init-promptcr-platform/specs/backend-access/spec.md

@@ -0,0 +1,42 @@
+# 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** 不存在白名单之外的中间件，新增依赖均有理由说明