HTTP 接口（威科夫跟踪）

说明：本页描述的是开发者 / 脚本 / 第三方集成使用的 REST 路径，不是面向终端用户的产品功能说明。日常新建跟踪、结案、维护日/周记录、AI 补录等，请在站内威科夫跟踪页面完成，无需也不应要求普通用户直接调用 HTTP。

/api/stock-wyckoff/* 的路径、鉴权与请求/响应字段。鉴权与战术信号 HTTP 接口写入方式一致。字段业务含义见威科夫趋势。

受众与定位：下列接口（含 GET 单条会话含子表、PATCH 会话/结案、DELETE 会话、日/周子表的 POST / PATCH / DELETE 等）均为程序化调用说明，供自建工具、自动化与对接参考，不是面向终端用户的产品功能入口。日常操作请用站内威科夫跟踪（前端虽调用相同路由，本文档读者请按开发者视角使用）。
下文仅列调用所需的路径、方法与字段；业务含义（如主阶段枚举）见威科夫趋势。服务端校验规则、排序实现、级联删除等以运行时代码为准。

鉴权（写入类接口）

需登录或携带凭据，支持：站内 Cookie 会话；请求头 Authorization: Bearer <JWT 或个人中心 API Key>；或查询参数 api_key=<API Key>（与战术信号写入方式一致）。未通过时 HTTP 401，响应体含错误说明。
管理员限制：凭据为个人中心 API Key（无论放在 Bearer 还是 api_key）时，威科夫写入类接口仅允许管理员账号（与站内约定 userId = 1 一致）；非管理员将返回 HTTP 403。使用站内登录的 JWT（Cookie 或 Bearer）时，按登录用户身份校验，不要求管理员。

GET会话列表

/api/stock-wyckoff/sessions
公开读取（无需凭据）。默认不包含已删除会话。

参数	类型	说明
`status`	string	默认 `all`。`open`：进行中；`closed`：已结案
`code`	string	按股票代码（数字前缀/全码）或简称子串筛选
`phase`	string	默认 `all`。主阶段枚举：`unclassified`、`transition`、`accumulation`、`markup`、`distribution`、`markdown`；`nocategory`（或 `_null`）表示未分类/空
`user_scope`	string	`all`（默认）、`watchlist_only`（自选股）、`position_only`（持仓）。后两者须登录，否则 `401`
`review_due`	string	`1` / `true` / `due`：已到观察日——含未设置「下次观察日」的会话，以及已设置且该日不晚于当前日历日（北京时间）的会话。`before` / `not_due` / `future` / `later`：未到观察日——仅已设置「下次观察日」且该日晚于当前日历日（北京时间）的会话
`limit` / `offset`	number	分页；默认 limit=50，最大 200；offset 默认 0
`sort` / `order`	string	`order` 为 `asc` 或 `desc`（未传时默认 `desc`）。`sort` 未传时默认 `priority`（优先级 0～100 降序，默认 50）。可显式取值：`priority`、`entry_date`（进入日）、`next_review_at`（下次观察日）、`lowest_volume_trade_date`（最低量日）、`ended_at`（结束时间）、`cyq_spread_ratio`（集中度比例）、`fundamental_score`（基本面 0～20，未打分为 NULL）、`close_vs_entry_pct`（相对进日涨跌幅，跨页内存排序）、`circulating_market_cap_yi`（流通市值亿，跨页内存排序）。非法 `sort` 回退为 `priority`

成功：success: true，data.sessions 为数组， data.pagination 含 total、limit、offset、hasMore。单条字段为 camelCase（含代码、名称、priority、进入日、主阶段、nextReviewAt / nextReviewSetAt、最新日摘要等，以实际响应为准）。

GET单条会话（含日记录、周记录）

/api/stock-wyckoff/sessions/[id]
[id] 为会话 id（数字字符串）。公开读取。data.session 为会话详情；data.dailyRows、data.weeklyRows 为子表列表（排序以响应为准）。可能含 wyckoffAutoClose 等辅助字段。

POST新建会话（纳入跟踪）

/api/stock-wyckoff/sessions
需鉴权（Cookie / Authorization: Bearer / ?api_key=）。集成侧常见写入：创建一条「威科夫跟踪」会话，用于后续日/周记录与 AI 补录（与站内「新建跟踪」等价）。

业务约束：同一 code 在库中仅允许一条进行中（ended_at 为空）会话；若该股已有未结案跟踪，返回 409，需先结案再建。

请求体：Content-Type: application/json。字段名区分大小写，均为下划线命名（与 PATCH 会话一致）。

字段	必填	类型	说明
`code`	是	string	A 股 6 位证券代码（数字）。服务端会规范化（如去空格）；须通过校验，否则 `400`（提示「须为 6 位数字」）。与列表筛选一致，不含市场后缀。
`entry_date`	是	string	进入跟踪的锚定交易日，格式 `YYYY-MM-DD`（日历日，按 UTC 日期存库）。非法格式 `400`。用于日/周记录时间范围与展示「进入日」。
`stock_name`	否	string \| null	股票简称。若服务端能根据 `code` 从行情库解析到名称，则以解析结果为准；仅当解析不到时，才使用本字段（非空则写入，最长约 100 字符）。可省略或传 `null`。
`current_primary_phase`	否	string \| null	会话主阶段（慢变量），用于列表着色与 AI `align_flag` 对照。合法取值：`unclassified`、`transition`、`accumulation`、`markup`、`distribution`、`markdown`；也可传空字符串表示未指定。语义见威科夫趋势。若省略、`null` 或仅空白，服务端默认写入 `transition`。传入非法字符串则 `400`。
`source`	否	string \| null	会话来源标记，便于统计（如 `low_vol_30d`、`manual`）。最长 32 字符；可省略或 `null`。
`entry_close_price`	否	number \| string \| null	进入日收盘价（元），用于区间涨跌幅等展示。须为有限正数，且 ≤ 1e8；可传数字或数字字符串。非法则 `400`。省略、`null` 或空字符串表示不写入（进入价列为空，后续可 PATCH 补）。

成功：HTTP 200，success: true，data.session 为新建会话对象（camelCase，含 id、code、stockName、entryDate、currentPrimaryPhase、entryClosePrice、status、时间戳等，与 GET 单条结构一致）。

错误：401 未鉴权；400 参数不合法（见响应 error 文案）；409 该股已有进行中会话；500 服务端异常。

示例（最小可用）：
POST /api/stock-wyckoff/sessions Content-Type: application/json { "code": "600000", "entry_date": "2026-04-01", "current_primary_phase": "accumulation", "source": "manual", "entry_close_price": 10.55 }

PATCH更新会话 / 结案

/api/stock-wyckoff/sessions/[id]
需鉴权。可更新 stock_name、current_primary_phase、source、summary_note；fundamental_score（0～20 整数或 null 清除）、fundamental_note（简要说明或 null）；next_review_at（YYYY-MM-DD 或 null 清除「下次观察日」）；priority_delta 为 1 或 -1 时在 0～100 范围内上/下调整优先级各 1 点；传 "close": true 结案（已结案则 400）；传 "reopen": true 将已结案恢复为进行中（未结案则 400；同代码已另有进行中会话则 409）。不可与 close 同传。可选 end_reason。

POSTAI 基本面打分（20 点 checklist）

公共实现：/api/stock-fundamental-score/ai-score，请求体 { "target": "wyckoff_session", "id": "<会话 id>" }，鉴权与下述威科夫专用路径一致。

兼容入口：/api/stock-wyckoff/sessions/[id]/ai-fill-fundamental
需写入鉴权（与威科夫其它 AI 补录一致）。内部与公共接口相同，调用 DeepSeek 按内置「终极 20 点」框架生成 fundamental_score / fundamental_note 并写回会话。

DELETE删除会话

DELETE /api/stock-wyckoff/sessions/[id] — 需鉴权；软删会话及其子数据（以服务端行为为准）。

POST新增日记录

/api/stock-wyckoff/sessions/[id]/daily
需鉴权；已结案不可新增。同一交易日唯一，冲突 409。

请求体：trade_date（必填）、supply_demand、align_flag、primary_phase_hint、wyckoff_sub_tags（字符串数组，须符合服务端白名单）、wyckoff_events（结构事件缩写数组，最多 2 个，须符合服务端白名单）、evidence_note（字段取值集合以校验错误信息为准）。

成功：data.daily、data.wyckoffAutoClose（若有）。

PATCH更新日记录

/api/stock-wyckoff/daily/[dailyId] — 需鉴权；[dailyId] 为日记录 id。已结案不可改。可部分更新上述业务字段。

DELETE删除日记录

DELETE /api/stock-wyckoff/daily/[dailyId] — 需鉴权；已结案不可删。成功可含 data.wyckoffAutoClose。

POST新增周记录

/api/stock-wyckoff/sessions/[id]/weekly
需鉴权；已结案不可新增。week_end_date 为该周最后交易日，须不早于会话进入日；同一周唯一，冲突 409。其余字段与日记录对应（日期字段为 week_end_date）。

成功：data.weekly、data.sessionPhaseSync（若有）、data.wyckoffAutoClose（若有）。

PATCH更新周记录

/api/stock-wyckoff/weekly/[weeklyId] — 需鉴权；已结案不可改。不可改 week_end_date（避免与唯一约束冲突）。

成功：data.weekly、data.sessionPhaseSync（若有）、data.wyckoffAutoClose（若有）。

DELETE删除周记录

DELETE /api/stock-wyckoff/weekly/[weeklyId] — 需鉴权；已结案不可删。成功可含 data.sessionPhaseSync。

站点/运维用接口（一般集成可忽略）

下列接口多为站内页或定时脚本使用；若仅对接 CRUD 与 AI 补录，可跳过。

POST `/api/stock-wyckoff/sync-cyq-cache`

需鉴权。从服务端配置的行情数据源刷新威科夫相关筹码类缓存。请求体可选会话 id 列表；返回含更新条数、调用次数、警告等（以响应为准）。依赖服务端环境与密钥配置。

POST `/api/stock-wyckoff/ground-volume-scan`

需鉴权。地量扫描并可能写入新会话。请求体可选交易日、算法标识；响应结构随版本变化，以实际 JSON 为准。

POST `/api/stock-wyckoff/import-holdings`

需鉴权。从当前用户持仓批量建议进入日并创建会话。可选 lookback_trading_days 等参数（以路由校验为准）。

GET `/api/stock-wyckoff/sessions/suggest-entry?code=…`

需鉴权。返回建议进入日、参考价等（字段以响应为准）。失败时多为 success: false（HTTP 状态码以实际为准）。

GETAI 补录队列（日 / 周）

/api/stock-wyckoff/sessions/ai-fill-daily-queue、/api/stock-wyckoff/sessions/ai-fill-weekly-queue
返回待补录的会话列表与 todayYmd、batchObservationLeadDays（默认 2）。批量补录时：若已设置「下次观察日」next_review_at，仅当今天已到达「观察日前第 N 个自然日（含）」之后才纳入队列（日/周队列口径一致）；未设置观察日则仍可按「日记/周记尚未跟上行情」等条件进入队列。当前多为公开读取，若对外暴露请在网关层做访问控制。

POSTAI 补录（日记录 / 周记录）

/api/stock-wyckoff/sessions/[id]/ai-fill-daily、/api/stock-wyckoff/sessions/[id]/ai-fill-weekly
需鉴权；仅进行中会话；依赖服务端 AI 与行情数据。日线：缺日则创建；本批行情窗口最后交易日若已有行则整行按 AI 覆盖（含 evidence_note），manual_remark_history 不写入、保持原值；窗口内其它已存在日不更新。周线已存在周一般不覆盖。成功响应含生成条数、跳过、错误摘要、提示词副本（若有）、阶段同步摘要、自动结案探测等——字段名以实际 JSON 为准。周线补录另含 promptCsvPayload（csvText + 结构化 rows），与提交给模型的周线 CSV 一致，便于核对调试。

curl 示例（新建会话）（将 YOUR_BASE_URL、YOUR_API_KEY 替换为实际值）：

curl -X POST "YOUR_BASE_URL/api/stock-wyckoff/sessions?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"600000","entry_date":"2026-04-16","source":"low_vol_30d","current_primary_phase":"transition","entry_close_price":10.5}'