discipline/rounds/round-10-demand-api-flywheel.md
📑 本页目录
轮次记录 · Round 10 · 企业需求 API + 飞轮验证（H21 首测）
1. 目标与选题
- 用户指令：开始 Round 10。
- 选题（来自 round-07 §7 候选 3 与 09-value-chain §10 路线图）：需求报告 / API（企业）+ 飞轮验证，即 L5 变现阶段 3；完成标准 = 企业 API 管道就绪、 H21 首次检验（先注册后计分）、H20 基线明确。
- 约束：无 Stripe 凭据 → 与 Round 9 相同的「配置驱动 + 诚实状态」： 企业 trial key 免费限流，full 层待付费接入，不把登记伪造成付费客户。
2. 背景与相关文献
- 学科资产：09-value-chain.md（L5 阶段 3、数据飞轮 §8、H20/H21 §7）； 06-evidence.md（先注册后计分）；许愿池（Round 5/6，需求直接观测通道）。
- 产品参考：Sensor Tower / Apptopia 企业定价（$999+/月）→ 锚点 $299/月（~1/3）。
3. 框架变更（Decision）
| # | 决策 | 落点 |
|---|---|---|
| D45 | 需求报告数据层：聚合许愿池/出生检测/信号/趋势/预测为结构化 JSON；报告只追加版本化 | app/forecasting/demand_report.py、data/reports/demand-reports.jsonl |
| D46 | 企业 API：登记即发 trial key（免费、100 次/日限流）；full 层待付费；用量独立记录不污染埋点 | app/enterprise_api.py、data/api/usage.jsonl |
| D47 | 飞轮验证脚本：H21 操作化为指标 A（结构化覆盖率）/B（时间切片），设正式检验门槛（≥30 愿望且 ≥3 多愿望簇），样本不足如实 pending | scripts/flywheel.py、data/flywheel/ |
| D48 | 埋点事件扩展：ent_view/ent_register 先登记 | app/analytics_api.py _EVENTS |
| D49 | 每周 cron 增加需求报告与飞轮检查（周六 digest→demand→flywheel） | crontab |
4. 实践产物与结果
- 需求报告：首份
demand-report-2026-08-10.json生成（7 愿望 / 2 缺口 / 3 出生 watchlist 领域 / 6 信号领域 / 5 上升榜）；公开摘要与全文分层。 - 企业 API：register / report / signals / usage / status 全链路本地验证通过 （trial key 限流 100 次/日；无 key=摘要、有 key=全文；坏 key 401；signals 需 key）。
- 飞轮验证：
scripts/flywheel.py首跑 —— H21 pending（7 愿望 / 1 多愿望簇， 门槛 30 / 3），指标 A 结构化覆盖率 28.6%，如实记录为「口径可用性，不代表飞轮成立」； H20 collecting（数据自 Round 8 起积累，检验起点 ≥1 季度）。 - 页面：
/enterprise（价值主张 + 数据内容表 + 定价 + 登记表单 + 实时 Public 样例 + API 文档 + curl 示例 + 诚实声明）。 - 假设登记：H21 首测记录写入 knowledge/hypotheses.md（pending + 基线）。
5. 评估
- 达标：企业 API 管道端到端可测；需求报告结构化、可追溯（sources 时间戳）； H21/H20 检验口径先注册、基线如实记录、不伪造结论。
- 未达标：full 层付费与历史切片、推送等为规划项（docs/11 §5 待接入清单）。
6. 未决问题
- Q21 历史切片：企业需要按周/月历史报告（当前只留最新 + 存档 JSONL）。
- Q22 企业推送：需求簇新缺口出现时的 webhook 通知（full 层）。
- Q23 飞轮正式检验启动：愿望量达 30 条 / 3 簇后运行 flywheel 自动切换 testable。
7. 下一轮建议（Round 11 候选）
- 英文产品 UI 化：趋势雷达/预测看板双语（承接 /en 流量，Round 8 遗留，最优先）。
- Stripe/SMTP 真实接入：docs/10 §6 与 docs/11 §5 清单落地（依赖外部凭据）。
- 历史切片 + 企业推送：Q21/Q22 落地，完善企业数据产品。
8. 版本号与 changelog
- 版本：v0.9 → v0.10。Changelog 见 rounds/README.md。