RTNN

RTNN 是一套面向 AI 协作交付的全栈模板 monorepo。它不是 demo 仓库，目标是沉淀一套可派生、可验收、可部署、可继续回流演进的正式模板工程。

模板定位

• apps/backend/
  • NestJS 模板后端内核，也是唯一后端契约源
• apps/admin/
  • Next.js 管理后台
• apps/app/
  • Next.js 移动端前台
• apps/weapp/
  • Taro + React 小程序端
• packages/
  • 共享配置、共享类型、共享 schema、API SDK
• docs/
  • 模板使用文档与工程文档
• scripts/
  • 模板初始化、契约、发布、smoke 与运行时脚本

模板最小承诺

正式提供：

• 以 backend 为唯一事实源的接口、权限、OpenAPI、shared contract 与 SDK 链路
• 面向 admin / app / weapp 的正式消费端骨架，而不是示例页集合
• 单根 .env 驱动的初始化方式，各端运行时变量按目标自动派生
• 面向 AI 协作的规则入口、skills 目录、MCP 配置和工程协作元数据
• 模板初始化校验、后端发布基线校验、消费端交付烟测

明确不承诺：

• demo 示例模块、假导航、占位页面、平行契约定义
• 多套根级 env 体系、端内散落 env 文件
• 仓库级 lockfile 提交策略
• 没有明确消费面的展示型能力

快速开始

pnpm install
pnpm run bootstrap
pnpm run dev:web

按需启动小程序：

pnpm run dev:weapp
pnpm run dev:weapp:h5

默认端口：

• backend: http://localhost:5100
• admin: http://localhost:5101
• app: http://localhost:5102
• weapp h5: http://localhost:5103

派生业务项目

推荐把当前仓库作为上游模板源码仓复制或 fork 成业务源码仓，再在业务仓内执行：

pnpm run template:init -- --project-id=acme --brand-name=ACME
pnpm run template:init -- --project-id=acme --brand-name=ACME --rewrite-source --package-scope=acme

其中：

• template:init 统一编排根级 .env 初始化
• template:init 会同时生成业务仓 .rtnn/project.json 骨架
• --rewrite-source 会同步改源码中的项目名、workspace scope 和静态引用
• 业务项目应直接持有完整源码，不再推荐“薄实例目录 + 资产刷新”模式

环境与依赖策略

• 根级 .env 是模板初始化参数唯一来源
• 根级 .env.example 是模板参数参考样板，不再维护各端 .env*
• TEMPLATE_TESTING_DATABASE_URL / TEMPLATE_PRODUCTION_DATABASE_URL 仅用于业务仓与 deploy 仓衔接远程环境，不参与本地开发
• 仓库采用 latest-first 策略，故意不提交 pnpm-lock.yaml
• 若业务仓需要可重现安装，应在自己的仓库中恢复 lockfile 策略

三仓发布模型

当前主线采用三类仓库协作，不要求业务项目必须使用固定仓库名：

• rtnn
  • 上游模板源码仓
• 派生后的业务源码仓
  • 持有完整业务源码
  • 拥有 testing / production 的构建、发版和验收主线
  • 用 .rtnn/project.json 固化仓库角色、部署仓绑定与环境映射
• 独立部署执行仓
  • 可采用 rtnn-deploy 这类实现
  • 只负责 deploy / rollback / smoke

固定规则：

• 业务仓 main -> testing 自动发布
• 业务仓 v* tag 只产出 production 候选镜像
• 业务仓手动执行 promote-production 发起正式发布
• 上游模板仓 rtnn 默认不直接拥有任何业务环境发布权
• rtnn 保留 release-images / promote-production 作为模板源码的一部分，但只有 project.role=business-source 的业务仓会真正执行它们
• deploy 仓生成运行事实报告，业务仓用 pnpm run release:status 只读校验线上状态，并用显式 sync/PR 准备命令写回 .rtnn/project.json liveState
• 具体业务项目的最终收口台账应维护在业务源码仓；模板仓只保留通用验收入口和事实边界，不记录某个项目的线上版本事实。

验收入口

pnpm run check:quick
pnpm run check:backend-release
pnpm run check:template-bootstrap
pnpm run check:template-derivation
pnpm run check:client-release
pnpm run profile:doctor
pnpm run check:release-candidate
pnpm run release:status -- --facts-file /tmp/rtnn-runtime-facts.json
pnpm run release:status -- --facts-file /tmp/rtnn-runtime-facts.json --summary-md --output /tmp/rtnn-release-status.json
pnpm run release:status:ci -- --facts-file /tmp/rtnn-runtime-facts.json --output-dir /tmp/rtnn-release-status
pnpm run release:production-readiness -- --deploy-version v1.0.0 --source-sha <sha>
pnpm run release:prepare-live-state-pr:ci -- --facts-file /tmp/rtnn-runtime-facts.json --environment testing --no-push
pnpm run release:check-runtime-freshness -- --facts-file /tmp/rtnn-runtime-facts.json
pnpm run smoke:admin
pnpm run check

• check:quick：不主动启动 PostgreSQL，覆盖 lint、typecheck、admin UI 规则、模板中立性与契约漂移。
• check:backend-release：会在本地数据库配置下启动 PostgreSQL，执行测试 schema 残留预检、backend 发布基线、integration/e2e 并行隔离检查与测试后残留审计。
• check:release-candidate：发布候选入口，覆盖模板派生、契约、backend 发布门禁；设置 RTNN_RUN_UI_SMOKE=true 后追加多端 UI smoke。
• check:client-release：客户端发布链路统一检查入口，覆盖 release facts 解析、client liveState、release status、liveState PR 准备、surface gate 与相关脚本测试。
• profile:doctor：读取 .rtnn/project.json 和 project profile，输出启用服务、客户端构建目标、警告与接入风险，适合业务仓初次接入或配置回归检查。
• release:status：回答“线上是否最新”的只读统一入口，输出稳定 status/code/findings，支持 --summary-md 和 --output 供 CI/PR comment 消费；不写回 .rtnn/project.json。
• release:production-readiness：production promote 前置只读门禁，校验 v* tag、source sha、业务仓 metadata、production 手动发布策略，并可选用 testing runtime facts 确认 testing 为 fresh。
• release:check-runtime-freshness：底层 runtime freshness gate，读取部署仓 runtime facts，判断 .rtnn/project.json liveState 是否代表线上实际版本；只读不写，写回仍使用 release:sync-live-state。
• release:prepare-live-state-pr：CI 用 liveState-only PR 准备入口，只允许改写 .rtnn/project.json liveState，不提交、不推送、不创建 PR。
• release:status:ci：GitHub Actions / deploy 回调入口，运行 release:status 并写出 JSON、Markdown、GitHub outputs 和 step summary。
• release:prepare-live-state-pr:ci：liveState-only PR 编排入口，负责 branch/commit/push/可选 PR；写回逻辑仍由 release:prepare-live-state-pr 控制。
• .github/workflows/sync-live-state.yml：从 deploy 仓 workflow artifact 下载 runtime facts，并选择只读检查或准备 liveState-only PR；状态判断必须使用机器字段 status/code，code 语义见 docs/operations/release-status-codes.md。
• Admin 发布中心可通过 RTNN_RELEASE_STATUS_FILE 或 RELEASE_STATUS_FILE 读取 release:status JSON 摘要，只展示 status/code/findings 派生状态，不解析英文 message。
• smoke:*:ui：CI 中使用 Playwright Chromium；Codex App 普通本地页面核验优先使用内置 Browser，不为普通本地验收安装 Chromium；显式设置 RTNN_RUN_UI_SMOKE=true 时缺浏览器会失败。
• check：本地完整质量门禁，覆盖静态检查、模板派生、契约、backend 发布门禁与多端构建。

AI 协作入口

• .claude/skills/
  • 唯一维护的 skills 源目录
• .agents/
  • 兼容其他 agent 入口的镜像与元数据
• .mcp.json
  • MCP 配置
• CLAUDE.md
  • 唯一规则来源
• AGENTS.md
  • 多 agent 入口提示

文档入口

• 文档入口
• 快速开始
• 模板最小承诺
• 模板中立性边界
• 业务源码仓模型
• 仓库关系与触发拓扑
• 部署边界
• 部署契约
• 部署仓库方案