| name | quantsage-go-datasource-conventions |
| description | Use when modifying QuantSage backend datasource code, browserfetch integrations, datasource tests, or related docs under apps/server, especially in internal/domain/datasource and internal/infra/browserfetch. |
quantsage-go-datasource-conventions
目标
统一 QuantSage 后端数据源相关改动的工程约束，减少目录越界、职责混乱和验证遗漏。
何时使用
满足任一情况时使用本 skill：
- 修改
apps/server/internal/domain/datasource/**
- 修改
apps/server/internal/infra/browserfetch/**
- 新增或调整数据源 parser、watcher、source、smoke test
- 调整数据源契约、抓取链路、回退逻辑、验证命令或相关文档
工作目录
- Go 代码、测试、lint、build：优先在
apps/server 下执行
- 跨应用联调：优先走根目录
make
- 不要在仓库根误跑
go test ./...
数据源改动约束
目录与职责
- 先看
apps/server/internal/domain/datasource
- 优先复用已有查询模型、错误码和
browserfetch 基础设施
parser 只做解析和标准化，不混入浏览器动作watcher / browserfetch 负责页面动作、监听和抓取过程List* / Stream* 职责边界要清晰，不要把流式接口伪装成一次性接口
Go 代码规范
- 公开函数/接口改动时同步补中文注释
- 错误统一用
fmt.Errorf("操作描述: %w", err) 包装
- 涉及 IO、DB、浏览器、外部调用的函数，第一个参数传
context.Context
- 对排障、日志和链路追踪有价值的核心入参：
进入调用链后尽早通过
infra/log.AddInfo(...) 这类日志 KV 方法写入 ctx
- KV 字段只放稳定、可序列化、业务可读的关键信息，例如
ts_code、index_code、market、job_name
- 不要把这条规则理解成随意
context.WithValue(...) 塞业务对象；大对象、敏感信息或临时中间结果都不应放进去
- 不要忽略有意义的错误返回
- 需要有完善的中文注释
browserfetch 约束
- 优先复用
Run、RunWithActions、ObserveResponses
- 站点如果对页面加载、子 tab、Cookie、懒加载敏感：
先补 smoke test，再改实现
- 修改抓取行为时：
优先补最小真实烟雾测试和对应单测
如果目标站点是百度财经或同类强前端耦合页面：
- REQUIRED SUB-SKILL: 使用
baidu-browserfetch-pitfalls
验证要求
后端改动至少执行与范围匹配的验证：
make test- 必要时加
make race
- 必要时加
make build
- 如果只在
apps/server 局部验证，也要至少跑对应 go test -timeout 120s ...
- 浏览器抓取或外站改动：补最小 smoke test
如果因为环境限制没跑某项验证，交付时必须明确写出：
文档同步
以下变更通常要同步文档：
- 新增或修改数据源
- 修改后端 API、任务流、配置项、调度行为
- 修改浏览器抓取策略、验证方式或本地运行方式
- 新增真实 smoke test、联调入口或关键排障结论
优先检查：
README.mddocs/architecture/*.mddocs/superpowers/specs/*.mddocs/superpowers/plans/*.md
如果本次改动形成长期规则，再考虑回写 AGENTS.md。
禁止项
- 不要手动编辑
go.sum
- 不要为了单次任务随意新增第三方依赖，除非用户明确确认
- 不要在根目录自创和
Makefile 冲突的新验证约定
- 不要把临时日志、调试残留、取消掉的
t.Skip(...) 留在测试里
交付时最少说明
- 改了什么
- 为什么这么改
- 跑了哪些验证
- 哪些没验证
- 是否更新了文档；如果没更，理由是什么
