lislgosms/docs/phase-1-engineering-skeleton-plan.md

阶段 1 工程骨架实施计划

目标

让前端原型、NestJS API、Go CMPP Gateway 和基础设施具备稳定启动、构建、测试和文档入口，为阶段 2 到阶段 8 的业务开发提供工程底座。

实施步骤

1. 文档与阶段门

   • 创建阶段 1 计划和进度记录。
   • 明确阶段 1 不实现完整业务，只建立工程骨架。

2. 前端工程边界

   • 当前 React + TypeScript + Vite 原型暂时保留在仓库根目录。
   • 第一版继续保留短信业务和账户计费入口，彩信入口保持待开发或后续隐藏。
   • 后续如迁移到 web/，需单独做无行为变化迁移。

3. NestJS API 骨架

   • 创建 api/package.json、tsconfig.json、src/main.ts、src/app.module.ts。
   • 配置健康检查接口。
   • 配置 Swagger/OpenAPI 文档入口。
   • 配置环境变量读取。
   • 保留阶段 0 BullMQ Spike 脚本。

4. Prisma 与数据库流程

   • 创建 api/prisma/schema.prisma。
   • 建立 prisma generate 和迁移命令入口。
   • 阶段 1 只定义基础连接和首批占位模型，不展开完整业务表。

5. Go Gateway 骨架

   • 保留阶段 0 gocmpp 适配、追踪器、重连状态机和 Spike 测试。
   • 增加健康检查 HTTP server 入口。
   • 明确 Gateway 只做 CMPP 连接、提交、submit resp、回执、上行事件回传。

6. 基础设施

   • 创建 infra/docker-compose.yml，覆盖 PostgreSQL、Redis、MinIO。
   • 创建 .env.example，列出 web/api/gateway/infra 的必要变量。
   • 当前 Windows 本地可用 Redis portable；Linux/容器环境以 Docker Compose 为准。

7. 统一验证命令

   • 根目录保留前端 npm run build。
   • 增加 API 构建命令。
   • 保留 npm run spike:contracts、npm run spike:bullmq、npm run spike:gateway。
   • 阶段 1 完成时执行全套验证。

验收标准

• 前端：npm run build 通过。
• API：cd api && npm run build 通过，健康检查和 Swagger 入口代码存在。
• Gateway：npm run spike:gateway 通过。
• 队列契约：npm run spike:contracts 通过。
• BullMQ Spike：npm run spike:bullmq 通过。
• 基础设施：infra/docker-compose.yml 包含 PostgreSQL、Redis、MinIO。
• Prisma：api/prisma/schema.prisma 存在，API package 提供 prisma:generate 和迁移命令。
• 文档：docs/phase-1-engineering-skeleton-progress.md 记录每一步验证结果。