MemeMeow/openspec/specs/api-access-policy/spec.md

Purpose

为单机部署的 FastAPI 服务提供最小必要的接口暴露控制和请求频率保护，不引入用户登录、角色或多租户权限系统。

Requirements

Requirement: 保护模式必须限制非白名单接口

启用保护模式时，系统 MUST 只放行配置白名单中的规范化路径，其余接口 MUST 返回 403。关闭保护模式时，接口按各自的业务校验正常处理。

Scenario: 请求白名单接口

• WHEN 保护模式开启且请求路径在白名单中
• THEN 系统继续执行该接口

Scenario: 请求非白名单接口

• WHEN 保护模式开启且请求路径不在白名单中
• THEN 系统返回 403，不执行接口副作用

Requirement: 限流必须按客户端执行

启用限流时，系统 MUST 按客户端 IP 在配置时间窗口内限制请求次数，超限请求 MUST 返回 429 和 Retry-After。限流器故障时不得泄露秘密或绕过业务授权；降级行为必须由配置明确。

Scenario: 请求未超限

• WHEN 客户端在时间窗口内未超过限制
• THEN 请求正常进入业务接口

Scenario: 请求超限

• WHEN 客户端达到配置的最大请求数
• THEN 系统返回 429 并包含重试等待时间

Requirement: 系统不得提供 Web 用户认证假象

本期系统 MUST 不提供 Streamlit 用户登录、注册、密码管理、Cookie 会话或角色权限接口；保护模式和限流不得被描述为用户身份认证。

Scenario: 客户端访问业务接口

• WHEN 客户端未提供用户登录凭证但满足保护模式和限流条件
• THEN 系统按公开单机服务处理请求，不要求登录