api

Imported from zwh8800/phosche (internal/api/AGENTS.md). Install upstream with npx skills add zwh8800/phosche --skill api. Copyright stays with the author.

internal/api

REST API 层，基于 chi 路由器实现所有 HTTP 接口。

目录结构

• router.go — 路由注册、中间件栈配置、健康检查
• search.go — 全文搜索端点（POST /api/search）
• photos.go — 照片时间线查询（GET /api/photos）+ 孤儿文档清理
• photo_detail.go — 单张照片详情（GET /api/photos/*）
• filters.go — 筛选选项聚合（GET /api/filters）
• stats.go — 统计信息（GET /api/stats）
• jwt.go — JWT 认证中间件（从 cookie 提取 email，已弃用，保留备用）
• auth.go — 认证中间件（从 X-Token-User-Email header 提取 email）+ context key 定义
• *_test.go — 对应测试文件

接口

• PhotoSearcher — 搜索服务接口（Search、GetFilters、GetStats）
• Indexer — 索引服务接口（GetPhoto、DeletePhoto）

中间件栈

注册顺序：Logger → Recoverer → Timeout(30s) → CORS → HeaderAuth

HeaderAuth 从 X-Token-User-Email header 提取 email 注入 context（上游网关已校验 JWT 并注入此 header）。 JWTAuth（从 access_token cookie 提取 email）已弃用，保留备用。

认证

所有请求都会经过 HeaderAuth，通过 UserEmailFromContext(r.Context()) 获取用户 email。 未认证时 email 为空字符串，只返回公开照片。

路由

所有 API 端点以 /api/ 为前缀，/health 和 /photos/* 除外。