API 路由对照表

全量路由

Method	Path	Handler	Auth	额度	状态
POST	/api/v1/auth/register	AuthHandler.Register	-	-	✅
POST	/api/v1/auth/login	AuthHandler.Login	-	-	✅
POST	/api/v1/auth/refresh	AuthHandler.RefreshToken	-	-	✅
GET	/api/v1/auth/oauth/google	OAuthHandler.GoogleLogin	-	-	✅
GET	/api/v1/auth/oauth/google/callback	OAuthHandler.GoogleCallback	-	-	✅
GET	/api/v1/auth/oauth/wechat	OAuthHandler.WechatLogin	-	-	✅
GET	/api/v1/auth/oauth/wechat/callback	OAuthHandler.WechatCallback	-	-	✅
GET	/api/v1/auth/profile	AuthHandler.GetProfile	✅	-	✅
PUT	/api/v1/auth/profile	AuthHandler.UpdateProfile	✅	-	✅
GET	/api/v1/auth/self-profile	AuthHandler.GetSelfProfile	✅	-	✅
PUT	/api/v1/auth/self-profile	AuthHandler.UpdateSelfProfile	✅	-	✅
GET	/api/v1/subscription/usage	SubscriptionHandler.Usage	✅	-	✅
POST	/api/v1/subscription/mock-activate	SubscriptionHandler.MockActivate	✅	-	✅ 演示
GET	/api/v1/persons	PersonHandler.List	✅	-	✅
POST	/api/v1/persons	PersonHandler.Create	✅	-	✅
POST	/api/v1/persons/import-url	ImportHandler.ImportFromURL	✅	-	✅ LLM 抽取草稿
POST	/api/v1/persons/import-text	ImportHandler.ImportFromText	✅	-	✅
POST	/api/v1/persons/import-image	ImportHandler.ImportFromImage	✅	-	✅ multipart
GET	/api/v1/persons/:id	PersonHandler.Get	✅	-	✅
PUT	/api/v1/persons/:id	PersonHandler.Update	✅	-	✅
DELETE	/api/v1/persons/:id	PersonHandler.Delete	✅	-	✅
POST	/api/v1/chat	ChatHandler.SendMessage	✅	Handler 内	✅
POST	/api/v1/chat/stream	ChatHandler.StreamMessage	✅	Handler 内	✅ SSE
GET	/api/v1/chat/sessions	ChatHandler.ListSessions	✅	-	✅
GET	/api/v1/chat/sessions/:id	ChatHandler.GetSession	✅	-	✅
DELETE	/api/v1/chat/sessions/:id	ChatHandler.DeleteSession	✅	-	✅
GET	/api/v1/chat/stats	ChatHandler.Stats	✅	-	✅
POST	/api/v1/strategy/analyze	StrategyHandler.Analyze	✅	Handler 内	✅
POST	/api/v1/strategy/advise	StrategyHandler.Advise	✅	Handler 内	✅
POST	/api/v1/strategy/script	StrategyHandler.Script	✅	Handler 内	✅
GET	/health	--	-	-	✅

---

响应格式

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

列表接口：{ items, total, page, pageSize, totalPages }

---

前后端字段映射

所有字段已在 Phase 1 末期 / Phase 2 初期对齐：

• Auth 响应：{ accessToken, refreshToken, user } — camelCase
• Person / Chat 列表：{ items, total, page, pageSize, totalPages }
• Chat 请求体（流式与非流式）：{ sessionId?, message, personIds?, scenarioType?, model?, locale?, regenerate? }（regenerate: 用上一轮用户话重新生成）
• Strategy 请求体：{ personId/personIds, scenarioType, content/description/goal, strategyThreadId, locale }
• GORM JSON tag 全部 camelCase

---

HTTP 层与 Agent 层如何对接（面向「契约 / 接口」）

组合根：internal/handler/router.go 在进程内构造一个 *agent.System（agent.NewSystem(cfg.AI, recorder, logger, db)），注入到：

Handler	是否调用 Agent	说明
ChatHandler	是	agents.Chat / 非流式收集；组 *agent.AgentContext
StrategyHandler	是	agents.Analyze / Advise / Script
ImportHandler	间接	ImportService 使用 agentSystem.DefaultModel() 做 LLM 抽取，不走 Chat/Runner
AuthHandler / PersonHandler / SubscriptionHandler	否	仅 Service → Repository → DB

与 Agent 的「对外契约」（概念上的接口，便于你对照实现或日后抽象）：

1. 输入：*agent.AgentContext（userID、sessionID、历史消息、关联人物、自我画像、locale、Model、MaxOutputTokens、Redis 线程上下文等，由 Handler 从 DB/Redis 拼装）。
2. 输出（流式）：<-chan agent.StreamChunk（content / agent 名 / error；结束帧可带业务扩展字段如 profileProposal，见 sse.md）。
3. 输出（策略直调）：同上 channel，由 Handler 聚合或边写 SSE。

当前代码里 Handler 依赖的是具体类型 *agent.System，没有单独的 Go interface 包；若要做依赖注入单测或可替换实现，可自行引入例如 type AgentRuntime interface { Chat(...) <-chan agent.StreamChunk; Analyze(...); ... }，由 *agent.System 实现。

前端侧：@shice/api 的 REST 路径与上表一致；流式对话见 streamChat 与 sse.md。权威路径列表以 router.go 为准，本文表应与其同步更新。