初始化项目

openspec/specs/api/spec.md

@@ -0,0 +1,47 @@
+# Capability: API (OpenAPI-backed)
+
+## Purpose
+Describe the core HTTP API behavior and constraints. The OpenAPI 3.1 contract lives in `spec/openapi.yaml`.
+
+## Requirements
+
+### Requirement: Health check
+The system SHALL expose a health endpoint for availability checks.
+
+#### Scenario: Health endpoint returns OK
+- **WHEN** a client calls `GET /health`
+- **THEN** the server returns `200`
+
+### Requirement: Authentication
+The system SHALL support email+password registration and login.
+
+#### Scenario: Register then login
+- **WHEN** a user registers with a valid email and password
+- **THEN** the server returns a JWT token
+- **WHEN** the user logs in with the same credentials
+- **THEN** the server returns a JWT token
+
+### Requirement: Public bookmarks visibility
+The system SHALL allow anonymous users to view public bookmarks.
+
+#### Scenario: List public bookmarks without auth
+- **WHEN** a client calls `GET /bookmarks/public` without a token
+- **THEN** the server returns `200` and a list of bookmarks
+
+### Requirement: Private bookmarks visibility
+The system SHALL restrict private bookmark data to authenticated users.
+
+#### Scenario: List my bookmarks requires auth
+- **WHEN** a client calls `GET /bookmarks` without a token
+- **THEN** the server returns an auth error
+- **WHEN** a client calls `GET /bookmarks` with a valid token
+- **THEN** the server returns `200` and the user's bookmarks
+
+### Requirement: Sync (LWW)
+The system SHALL support last-write-wins (LWW) synchronization for folders and bookmarks.
+
+#### Scenario: Push local changes then pull
+- **WHEN** an authenticated client calls `POST /sync/push` with folders/bookmarks
+- **THEN** the server stores the items using LWW semantics
+- **WHEN** the client calls `GET /sync/pull`
+- **THEN** the server returns folders/bookmarks and `serverTime`