Web_BLS_Heartbeat_Server/.trae/skills/bls-backend-component-builder/SKILL.md

---
name: "bls-backend-component-builder"
description: "生成与本仓库一致的 Kafka→处理→DB→Redis 错误链路后端组件脚手架。Invoke when用户说：开始构建BLS后端组件。"
triggers:
  - "开始构建BLS后端组件"
actions:
  - id: "collect-inputs"
    title: "收集生成参数"
    outputs:
      - "newProjectDir"
      - "projectName"
      - "kafka.topics"
      - "kafka.groupId"
      - "inputSchema"
      - "db.type"
      - "db.schemaName"
      - "db.tableOrCollection"
      - "transformRules"
      - "redis.errorQueue"
    steps:
      - "默认 newProjectDir = ../<projectName>（与当前仓库同级）。"
      - "默认 projectName = BLS_<业务名>_Processor。"
      - "默认 kafka.topics = [<业务Topic>]，groupId = <projectName>。"
      - "inputSchema 描述 Kafka message.value 解码后的 JSON 结构（字段、类型、必填、枚举）。"
      - "db.type 默认 postgresql；如改为 mysql/mongodb，需同步调整 db 层实现。"
      - "db.schemaName/tableOrCollection 指定落库位置与结构。"
      - "transformRules 描述清洗、映射、归一化、补缺、派生字段规则。"
      - "redis.errorQueue 默认 <projectName>:errors（用于可重试错误队列）。"
  - id: "scaffold-project"
    title: "生成项目骨架（同架构同产物）"
    steps:
      - "创建 newProjectDir，并复制本仓库的 package.json、package-lock.json、vite.config.js、scripts/、src/、test/、.eslintrc.cjs、.gitignore、ecosystem.config.cjs、.env.example。"
      - "将本 Skill 自带的 assets/skill/ 复制为 newProjectDir/skill/（作为新项目的标准约束文件与可移植模板集合）。"
      - "在 newProjectDir/src/config/config.js 基于 config.example.js 生成运行配置，并将 kafka.topics/groupId/clientId、db、redis 按参数写入。"
      - "确保构建产物入口与 PM2 启动脚本一致：dist/index.* 与 ecosystem.config.cjs 的 script 字段一致。"
  - id: "implement-kafka-ingestion"
    title: "配置 Kafka 订阅与解码"
    steps:
      - "在 newProjectDir/src/kafka/consumer.js 复用 ConsumerGroupStream 模式，订阅 kafka.topics。"
      - "保持 encoding 为 buffer，并在 processor 中按 UTF-8 解码为 JSON。"
      - "如生产者启用压缩/封装（gzip/brotli/deflate），在 processor 解包逻辑中保持兼容。"
  - id: "implement-processor"
    title: "实现解析/校验/转换/批处理写入"
    steps:
      - "在 newProjectDir/src/processor/ 生成 <Business>Processor（可沿用 HeartbeatProcessor 命名模式）。"
      - "实现四段式处理：unpackMessage -> validateData -> transformData -> processBatch。"
      - "validateData 按 inputSchema 强校验：缺字段、类型不符、枚举越界直接判失败。"
      - "transformData 按 transformRules 进行字段映射、清洗、派生字段生成。"
      - "processBatch 使用批量队列与 batchTimeout/batchSize 控制吞吐；写入失败要降级逐条写入并记录失败记录。"
  - id: "implement-db"
    title: "实现数据库 Schema 与持久化"
    steps:
      - "在 newProjectDir/src/db/ 复用 DatabaseManager 连接池模式。"
      - "在 initTables 中创建 db.schemaName 与目标表/集合结构；为高频写入表添加必要索引。"
      - "对高频时序数据按天分区：复用 scripts/db/020_partitioning_auto_daily.sql 的策略，必要时修改表名与分区键。"
      - "写入接口提供：batchInsert(events) 返回 insertedCount 与 failedRecords。"
  - id: "implement-redis-errors"
    title: "实现错误上报与可重试队列"
    steps:
      - "保留现有 Redis 心跳与控制台日志 Key 约定（项目心跳、${projectName}_项目控制台）。"
      - "新增错误队列 Key：<projectName>:errors（LIST）存储可重试错误记录 JSON。"
      - "错误记录建议字段：errorId、firstSeenAt、lastSeenAt、attempts、topic、partition、offset、rawData、reason、stack。"
      - "当 decode/validate/transform/db_write 失败且可重试时：RPUSH <projectName>:errors <json> 并同时写控制台日志。"
      - "在 newProjectDir/src/retry/ 增加 RetryWorker：BLPOP <projectName>:errors，按策略重放（调用 Processor 的单条处理入口），失败则回队列并 attempts+1。"
      - "提供人工干预：支持将错误记录移动到 <projectName>:errors:dead（超过最大 attempts）并保留查询入口。"
  - id: "wiring-entry"
    title: "串联入口与运行生命周期"
    steps:
      - "在 newProjectDir/src/index.js 复用现有启动顺序：Redis -> Stats -> DB -> Processor -> Kafka Consumers。"
      - "保证任何启动/运行异常都写入 Redis 控制台日志（info/warn/error）。"
      - "在 stop() 中优雅停止：停止 Stats、停止 Kafka、断开 DB、断开 Redis。"
  - id: "build-package-deploy"
    title: "构建、打包与部署"
    steps:
      - "在 newProjectDir/package.json 保持 npm run build 产出 dist/。"
      - "PM2：提供 ecosystem.config.cjs（或从 assets/skill/templates/ecosystem.config.js 复制）并指向 dist 入口。"
      - "Docker：提供 Dockerfile 与 docker-compose.yml（可直接从 assets/skill/templates 复制）。"
      - "CI/CD：在 assets/skill/templates 中补充 pipeline 示例（如 GitHub Actions），执行 lint/test/build。"
  - id: "verification"
    title: "验证与交付"
    steps:
      - "执行 npm test、npm run lint、npm run build，确保通过。"
      - "执行 scripts/db/smokeTest.js 与 scripts/redis/smokeTest.js（如存在）验证外部依赖可用。"
      - "输出交付清单：.env.example、ecosystem.config.cjs、skill/、dist/ 构建产物。"
---

# BLS 后端组件构建 Skill

## 触发

当用户说出以下语句时，启用本 Skill：

- 开始构建BLS后端组件

## 目标

快速生成一个与当前仓库相同架构、相同运行环境、相同构建产物（dist/）的数据处理服务，新项目允许变化点仅包括：

- Kafka 订阅 Topic 不同
- Kafka 原始数据结构不同
- 目标数据库 Schema 不同
- 中间处理/转换/清洗/业务流程不同

同时必须具备：

- 错误捕获并写入 Redis
- 从 Redis 读取错误并进行重试/人工介入的处理链路

## 输出约定

- 新项目目录：newProjectDir
- 代码目录：src/
- 构建产物：dist/
- 约束与模板资产：skill/
- 运维资产：ecosystem.config.cjs、Dockerfile、docker-compose.yml、.env.example

## 使用示例（对话风格）

用户：

开始构建BLS后端组件：业务=xxx，Topic=yyy，数据结构=zzz，落库=postgresql 表=aaa，转换规则=bbb。

本 Skill 需要生成：

- 统一骨架 + 可替换的 Processor / DB Schema / Redis 错误队列

## 内置约束文件与模板

本 Skill 内置并随 Skill 发布的约束/模板文件位于：

- assets/skill/
- assets/skill/templates/

其中包含（与原有约束文件一致）：

- CONSTRAINTS.md（目录结构、代码规范、约束）
- KAFKA_PRODUCER.md（生产者对接）
- REDIS_ERROR_HANDLING.md（Redis 错误上报与监控）
- DATABASE_DESIGN.md（数据库设计约束）
- templates/.env.example、templates/ecosystem.config.js、templates/Dockerfile、templates/docker-compose.yml、templates/OPENAPI_TEMPLATE.yaml

生成新项目时，必须将上述文件原样复制到新项目根目录下的 skill/ 目录，以保证可移植性与一致性。

## 生成后的项目使用要点

- 约束文件入口：newProjectDir/skill/CONSTRAINTS.md
- 环境变量模板：newProjectDir/skill/templates/.env.example
- PM2 模板：newProjectDir/skill/templates/ecosystem.config.js
- Docker 模板：newProjectDir/skill/templates/Dockerfile、newProjectDir/skill/templates/docker-compose.yml

建议在新项目根目录执行：

- 复制环境变量模板到根目录：cp skill/templates/.env.example .env
- 复制 PM2 模板到根目录：cp skill/templates/ecosystem.config.js ecosystem.config.cjs