# Stow Go API（开发中）

当前实现匿名会话、Item 创建/列表/详情/编辑/软删除，以及关键词搜索。使用 PostgreSQL 和 `pg_trgm` 建表；向量搜索需要服务器安装 `pgvector` 后再增加相应迁移。AI Worker、图片上传和云同步仍在开发。

数据库业务表统一使用 `stow_` 前缀，字段使用 `snake_case` 命名；业务表的主键 `id` 使用 `VARCHAR(36)` 存储 UUID 字符串，并由数据库检查格式。Go 结构体类型名不加 `Stow` 前缀，导出字段使用 Go 惯用的大驼峰写法。HTTP JSON 字段保持现有 `snake_case` 接口约定。

HTTP 层使用 Gin。所有响应统一为 `{"code":"ok","message":"success","data":...}`；失败时 `code` 为错误标识、`message` 为可读提示、`data` 为 `null`，同时返回对应的 HTTP 状态码。删除成功返回 HTTP 200 和同样的响应结构。

从 `backend/` 目录启动本地依赖与 API：

```sh
docker compose up -d
export DATABASE_URL='postgres://stow:stow_dev@localhost:5432/stow?sslmode=disable'
go run ./cmd/migrate
go run ./cmd/api
```

验证：

```sh
curl http://localhost:8080/v1/health
curl -X POST http://localhost:8080/v1/session/anonymous
```

所有 `/v1/items` 与 `/v1/search` 请求需要 `Authorization: Bearer <access_token>`。开发环境数据库密码只用于本地 Compose；生产部署需要单独配置私有数据库、TLS、对象存储和密钥管理。