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

name, description, triggers, actions

name	description	triggers	actions
bls-backend-component-builder	生成与本仓库一致的 Kafka→处理→DB→Redis 错误链路后端组件脚手架。Invoke when用户说：开始构建BLS后端组件。	开始构建BLS后端组件	id title outputs steps collect-inputs 收集生成参数 newProjectDir projectName kafka.topics kafka.groupId inputSchema db.type db.schemaName db.tableOrCollection transformRules redis.errorQueue 默认 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 title steps scaffold-project 生成项目骨架（同架构同产物） 创建 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 title steps implement-kafka-ingestion 配置 Kafka 订阅与解码 在 newProjectDir/src/kafka/consumer.js 复用 ConsumerGroupStream 模式，订阅 kafka.topics。 保持 encoding 为 buffer，并在 processor 中按 UTF-8 解码为 JSON。 如生产者启用压缩/封装（gzip/brotli/deflate），在 processor 解包逻辑中保持兼容。 id title steps implement-processor 实现解析/校验/转换/批处理写入 在 newProjectDir/src/processor/ 生成 <Business>Processor（可沿用 HeartbeatProcessor 命名模式）。 实现四段式处理：unpackMessage -> validateData -> transformData -> processBatch。 validateData 按 inputSchema 强校验：缺字段、类型不符、枚举越界直接判失败。 transformData 按 transformRules 进行字段映射、清洗、派生字段生成。 processBatch 使用批量队列与 batchTimeout/batchSize 控制吞吐；写入失败要降级逐条写入并记录失败记录。 id title steps implement-db 实现数据库 Schema 与持久化 在 newProjectDir/src/db/ 复用 DatabaseManager 连接池模式。 在 initTables 中创建 db.schemaName 与目标表/集合结构；为高频写入表添加必要索引。 对高频时序数据按天分区：复用 scripts/db/020_partitioning_auto_daily.sql 的策略，必要时修改表名与分区键。 写入接口提供：batchInsert(events) 返回 insertedCount 与 failedRecords。 id title steps implement-redis-errors 实现错误上报与可重试队列 保留现有 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 title steps wiring-entry 串联入口与运行生命周期 在 newProjectDir/src/index.js 复用现有启动顺序：Redis -> Stats -> DB -> Processor -> Kafka Consumers。 保证任何启动/运行异常都写入 Redis 控制台日志（info/warn/error）。 在 stop() 中优雅停止：停止 Stats、停止 Kafka、断开 DB、断开 Redis。 id title steps build-package-deploy 构建、打包与部署 在 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 title steps verification 验证与交付 执行 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