#业务模块开发指南

本文介绍如何开发 SFMC 业务模块，涵盖脚手架初始化、目录结构、命名规范、本地联调、Manifest 配置以及发布流程。

#1. 快速开始

使用官方脚手架初始化模块仓库：

pnpm dlx @sfmc-bds/create-module@latest

向导将提示配置以下内容：

• 模块 ID（kebab-case）：如 teleport、economy
• 显示名称（Display Name）：如 通用经济
• npm Scope：个人或团队 scope（如 @alice）
• 功能选型：是否包含 SQLite 数据库支持

进入模块目录并安装依赖、执行类型检查：

cd my-feature
pnpm install && pnpm run typecheck

#2. 命名规范

为避免模块冲突，模块各位置的命名约定如下：

#3. 开发工作流

开发业务模块的常规流程如下：

#1. 编写与静态检查

编码过程中通过 TypeScript 与 ESLint 保障代码质量：

pnpm run typecheck    # 检查 SAPI 类型与 SDK 契约
pnpm run lint         # 检查消息规范、导入路径与权限规则

#2. 挂接到本地测试服务器（Link）

将本地模块软链接到测试服务器（SFMC_ROOT）进行联调：

# 方式 A：在 VS Code 扩展中点击 "SFMC: Link to SFMC Root"
# 方式 B：在服务端终端执行命令
sfmc mod install my-feature --from dir:D:/WorkSpace/my-feature --link
sfmc mod enable my-feature

#3. 实时监听与热重载（Watch & Reload）

在 VS Code / Cursor 中点击扩展侧边栏的 SFMC: Start Watch。每次保存 sapi/src/ 中的代码，扩展会自动增量编译并通知 BDS 热重载。

#4. 发布到 npm 与社区索引

测试验证完成后，即可发布上线：

# 发布到 npm（需公开访问）
pnpm publish --access public

# 向 sfmc-modules 仓库的 index.json 提交 PR 登记模块

#4. 模块目录结构

my-feature/
├── package.json               # 依赖声明与 npm exports
├── .vscode/
│   ├── extensions.json        # 推荐扩展（SFMC Module, ESLint 等）
│   └── settings.json          # 编辑器配置
├── eslint.config.js           # 集成 @sfmc-bds/eslint-plugin
├── sapi/
│   ├── manifest.json          # 模块契约声明
│   ├── tsconfig.json          # 面向 SAPI 环境的 TypeScript 配置
│   └── src/
│       └── index.ts           # 模块入口（ModuleRegistry.register）

#SDK 常用导入路径

#5. Manifest 配置与语义元数据

在 sapi/manifest.json 中声明模块的基础标识、权限和依赖。推荐声明 v3 语义元数据（semantic 字段），便于工具和控制面板识别模块行为：

目前 v3 尚无独立公开的 JSON Schema，示例中不设置 $schema：

{
  "schemaVersion": 3,
  "id": "feature-economy",
  "name": "核心经济系统",
  "configKey": "economy",
  "requires": [],
  "permissions": ["db:read:wallet", "db:write:wallet"],
  "services": {
    "provides": [{ "name": "economy.transfer" }],
    "requires": []
  },
  "semantic": {
    "configKeys": ["economy.initial_balance", "economy.currency_name"],
    "dependsOn": [],
    "events": {
      "emits": ["economy:balanceChanged"],
      "listens": ["world.afterEvents.playerJoin"]
    },
    "dbTables": [
      {
        "name": "wallets",
        "columns": ["player_xuid", "balance", "updated_at"]
      }
    ],
    "publicApi": [
      {
        "symbol": "transfer",
        "description": "跨玩家转账接口",
        "params": [
          { "name": "fromPlayer", "type": "string", "required": true },
          { "name": "toPlayer", "type": "string", "required": true },
          { "name": "amount", "type": "number", "required": true }
        ],
        "returns": { "type": "boolean", "description": "转账是否成功" }
      }
    ]
  }
}

#语义字段说明

• configKeys：该模块读取或监听的配置键列表。
• events.emits / listens：该模块触发或监听的事件名。
• dbTables：该模块创建和使用的 SQLite 数据表与核心字段。
• publicApi：对外暴露的公共 API 接口描述，供下游调用者参考。

#版本兼容说明

• 兼容 v2：schemaVersion: 2 的模块仍可正常运行，系统加载时会自动填充缺省的 semantic 结构。
• 容错处理：若 semantic 中可选字段格式不规范，系统仅在控制台输出警告，不会阻断模块加载。
• 更多字段规则与权限语法请参考 Manifest 契约规范。

#6. 相关文档

• API 速查手册 (Cheatsheet) — 常用 API 接口与代码范例
• Manifest 契约规范 — 清单字段完整定义与权限语法
• 验证与调试策略 — 静态检查、本地联调与 BDS 运行验收
• ESLint 规则说明 — 代码风格与边界约束
• 发布你的模块 — 版本打标与 npm 发布指南