NextDevTpl v3.0.0

NextDevTpl v3.0.0

NextDevTpl 3.x 的首个稳定版本。这个版本在 2.x 可组合项目生成器的基础上，
为独立 SaaS 预置埋点、运营指标、收入与 AI 成本分析，以及可选告警能力。
生成项目继续只保留用户选择的模块、服务适配器和部署文件。

主要更新

运营埋点与来源归因

• 新增类型安全的统一事件入口，覆盖客户端、服务端、API、Action 和后台任务。
• 内置注册、登录、首次价值、订阅、核心动作和失败事件，并保留产品自定义接入点。
• 支持匿名身份、登录身份、UTM、首次来源和最近来源衔接。
• 分析同意、撤回和身份清理使用同一套隐私门禁；默认不采集邮箱、完整 IP、提示词、
  模型原始回复或上传内容。

运营驾驶舱

• 新增可选 operations 模块和 /admin/operations 管理员页面。
• 提供总览、漏斗、留存、产品使用、系统健康、收入和 AI 用量指标。
• 指标明确区分无数据、未配置、查询失败、权限不足和部分覆盖，避免把数据缺口显示成有效的 0。
• 支持按时区聚合和每日快照，陈旧快照不会冒充当前查询结果。

收入、订阅与 AI 毛利

• 收入、MRR、付费转化、续费、流失、退款和支付失败以服务端支付事实为准。
• 订阅升级补差价、事件重放、旧周期事件和首次付费 cohort 使用独立幂等规则。
• AI 适配器返回模型、供应商、Token、耗时和覆盖状态，可按模型、功能、用户和日期估算成本与毛利。
• 无法取得完整用量或价格时标记为 estimated 或 unavailable。

运营告警

• 提供支付失败率、AI 成本和付费转化下降规则。
• 支持连续触发、去重、冷却、恢复和通知历史。
• 通知适配器支持 noop、邮件和签名 Webhook，可接入飞书、Slack、Discord 等入口。
• 告警只观察和通知，不自动退款、封禁用户、修改套餐或关闭服务。

可组合生成与四目标兼容

• analytics 支持 noop、结构化日志、PostHog、GA4 和 Umami。
• alerts 支持 noop、邮件和签名 Webhook；未选择 operations 时整组源码和配置会被删除。
• Server、Docker Compose、Vercel 和 Cloudflare Workers 均纳入运营组合兼容矩阵。
• 生成结果只保留已选源码、依赖、环境变量、数据库 Schema、路由和部署文件。
• 中文 README 作为默认入口，英文 README 可直接切换；生成项目内置中英文运营文档。

安装

需要 Node.js 24 和 pnpm 10：

pnpm dlx create-nextdevtpl@3.0.0 my-app --preset saas --target vercel

生成包含运营看板的自定义项目：

pnpm dlx create-nextdevtpl@3.0.0 my-app \
  --preset custom \
  --modules auth,analytics,operations \
  --target docker \
  --payment stripe \
  --analytics posthog \
  --alerts webhook

从 2.x 升级

生成项目拥有自己的源码，升级不会覆盖业务代码。保留原项目的
nextdevtpl.generated.json，用 3.0.0 生成临时对照项目，审查数据库迁移、环境变量、
服务装配和业务改动后分批合并。迁移前先备份数据库，并在测试环境运行完整门禁。

完整步骤见 docs/升级指南.md。

已知限制

• 每个产品仍需明确接入 first_value.completed 和 core_action.completed，模板无法替产品定义核心价值。
• Cloudflare OpenNext 在 Windows 上可能受到符号链接权限限制，请在 WSL 或 Linux CI 中构建。
• 外部分析、邮件和 Webhook 的实时冒烟依赖对应供应商账号和环境变量。
• 模块和适配器在生成阶段选定；生成项目暂不提供运行时插件市场。
• AI 成本与毛利用于运营判断，数据会标明估算来源和覆盖状态。

验证依据

• 本地测试：48 个测试文件、430 个测试；首次运行中 4 个 Neon 瞬时连接超时用例在隔离复跑中 37/37 通过。
• 生产构建：108 个页面生成成功。
• 生成项目与兼容矩阵：五组官方预设完成安装、迁移、代码检查、类型、生成测试、构建和健康检查，八组结构矩阵通过。
• 发布包：create-nextdevtpl@3.0.0 共 493 个文件，通过必需文件和禁止文件检查。
• WSL Cloudflare 运营组合：八个阶段全部通过，Worker 入口 2,278 bytes、gzip 732 bytes。
• GitHub Actions Compatibility matrix：发布提交的 quality 与四组生成项目任务全部通过后创建正式 tag。