Medusa 事件常量 TSDoc 编写规范：为 core-flows 工作流事件构建可检索的 API 文档-开发者社区

Medusa 事件常量 TSDoc 编写规范：为 core-flows 工作流事件构建可检索的 API 文档

【免费下载链接】medusaThe world's most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa

本文是 Medusa 开源仓库中writing-tsdocs技能体系的事件专项参考指南，围绕 .claude/skills/writing-tsdocs/reference/events.md 展开。它面向需要在packages/core/utils/src/core-flows/events.ts中维护事件常量文档的贡献者，讲解事件常量的 TSDoc 组织方式、@eventPayload、@since、@featureFlag等自定义标签的用法与完整实战示例。读完本文，你将掌握为 Medusa 事件常量编写符合 TypeDoc 输出要求的规范注释，并理解这些注释如何与工作流中的emitEventStep发射逻辑形成对应关系。

事件常量在哪里：core-flows 事件中心

Medusa 的 core-flows（核心工作流）在工作流执行过程中会向外发射领域事件，例如购物车创建、订单下达、履约生成等。这些事件的事件名常量并不散落在各个工作流文件中，而是统一收敛在 packages/core/utils/src/core-flows/events.ts（全文约 1300 行），以"命名空间对象（namespace object）"的形式分组导出：

CartWorkflowEvents—— 购物车相关事件
OrderWorkflowEvents/OrderEditWorkflowEvents—— 订单与订单编辑事件
CustomerWorkflowEvents、UserWorkflowEvents、AuthWorkflowEvents—— 用户与认证事件
ProductWorkflowEvents、ProductVariantWorkflowEvents、ProductCategoryWorkflowEvents等 —— 商品域事件
SalesChannelWorkflowEvents、RegionWorkflowEvents、FulfillmentWorkflowEvents、ShippingOptionWorkflowEvents—— 渠道、区域、履约与配送事件
PaymentEvents、InventoryItemWorkflowEvents、InventoryLevelWorkflowEvents、ReservationItemWorkflowEvents—— 支付与库存事件
TranslationWorkflowEvents—— 翻译事件（特性开关控制）

每个命名空间都是as const导出的常量对象，其成员即事件常量，例如：

export const CartWorkflowEvents = { CREATED: "cart.created", UPDATED: "cart.updated", } as const

事件常量本身是字符串字面量（如"cart.created"），工作流通过emitEventStep步骤引用它们完成发射；而 TSDoc 注释则负责描述"事件在什么时机发出、载荷长什么样"，二者共同构成事件的完整契约。

事件 TSDoc 的核心规则

为事件常量编写 TSDoc 时，需要遵守以下规则（源自 .claude/skills/writing-tsdocs/reference/events.md）：

每个事件常量都必须有文档：用一句话描述该事件的发射时机（"Emitted when ..."）。
必须包含@eventPayload：展示事件发出时携带的数据形状。
新增事件加@since：只有当该事件是本 commit diff 中新增时，才添加@since，版本号来自任务提示（prompt），严禁自行编造。
受特性开关控制的事件加@featureFlag。
命名空间对象本身不强制文档化：除非它缺少描述，且同文件中其他命名空间已经使用了统一的@customNamespace+@category模式，才为它补上；不要给原本没有该模式的文件强行引入。

此外，整个writing-tsdocs技能还有两条总约束（见 .claude/skills/writing-tsdocs/SKILL.md）：只给export导出的项写文档，绝不修改现有 TSDoc 与业务逻辑——写注释是"只增不改"的操作。

事件常量基础格式

事件常量的 TSDoc 块遵循固定的三段式结构：描述、@eventPayload、可选的版本与特性标签：

/** * Emitted when [resource] is [action]. * * @eventPayload * ```ts * { * id, // The ID of the [resource] * } * ``` */ CREATED: "resource.created",

落在真实源码中，CartWorkflowEvents的第一个成员即完全对应此格式（见 events.ts）：

export const CartWorkflowEvents = { /** * Emitted when a cart is created. * * @eventPayload * ```ts * { * id, // The ID of the cart * } * ``` */ CREATED: "cart.created", } as const

事件名的措辞建议与事件字符串一一呼应：常量名CREATED、事件名"cart.created"、描述 "Emitted when a cart is created"，三者在语义上保持一致，方便检索与理解。

@eventPayload：精确描述事件载荷

@eventPayload是事件 TSDoc 中最具信息量的部分，它使用一个 TypeScript 代码块逐行列出事件发射时携带的属性，每个属性后面跟一个内联注释说明含义：

/** * Emitted when the customer in the cart is transferred. * * @eventPayload * ```ts * { * id, // The ID of the cart * customer_id, // The ID of the customer * } * ``` */ CUSTOMER_TRANSFERRED: "cart.customer_transferred",

当载荷中包含非字符串字段时，必须在行内注释中用括号标注其类型，例如(boolean)、(number)、(array)、(object)、(Date)；对于普通的字符串 ID，则省略类型标注。下面的order.fulfillment_created事件是一个典型的多字段、混合类型载荷：

/** * Emitted when an order's fulfillment is created. * * @eventPayload * ```ts * { * order_id, // The ID of the order * fulfillment_id, // The ID of the fulfillment * no_notification, // (boolean) Whether to notify the customer * } * ``` */ FULFILLMENT_CREATED: "order.fulfillment_created",

在 events.ts 中，OrderWorkflowEvents.FULFILLMENT_CREATED的注释与上述示例完全一致，可直接对照学习。

@since：标注新增事件的版本

当事件是当前提交中新增时，添加@since标签记录引入版本。版本号只能来自任务提示，不能自行猜测。放置顺序上，@since应位于@eventPayload之前，让版本信息优先呈现：

/** * Emitted when a translation is created. * * @since 2.14.0 * * @eventPayload * ```ts * { * id, // The ID of the translation * } * ``` */ TRANSLATIONS_CREATED: "translations.created",

仓库中已有大量@since实例，覆盖了多个版本区间：cart.customer_transferred标注@since 2.8.0、shipping-option.created标注@since 2.12.4、translation.created标注@since 2.12.3、inventory-item.created与inventory-level.created标注@since 2.18.0、product-option-value.updated标注@since 2.20.0。当某个事件在后续版本发生载荷变化时，描述中也会补充迁移说明，例如 events.ts 中auth.verification_requested的注释详细说明了 v2.17.0 起的载荷字段变更（移除actor_type、provider_identity_id，重命名provider为code_provider，新增entity_type），并提示旧订阅者必须更新。这种"版本演进说明"同样是高质量事件文档的一部分。

@featureFlag：标注特性开关控制的事件

有些事件只有在启用某个特性开关（feature flag）后才会发射，此时需要在 TSDoc 中追加@featureFlag，并紧跟开关名称。它与@since组合使用时，@since在前、@featureFlag在后：

/** * Emitted when a translation is created. * * @since 2.14.0 * @featureFlag translation * * @eventPayload * ```ts * { * id, // The ID of the translation * } * ``` */ TRANSLATIONS_CREATED: "translations.created",

仓库中的实际案例即 events.ts 的TranslationWorkflowEvents：translation.created、translation.updated、translation.deleted三个事件均同时携带@since 2.12.3与@featureFlag translation。@featureFlag与@since、@eventPayload、@customNamespace等均为 Medusa 在 www/utils/packages/typedoc-config/tsdoc.json 中注册的 TSDoc 自定义标签（该文件基于typedoc/tsdoc.json扩展，共定义了十余个项目专用标签），它们会被 TypeDoc 生成管线识别并在 API 文档中渲染。

命名空间对象的文档化

命名空间对象（如CartWorkflowEvents本身）默认不需要文档——文档的焦点是事件常量。唯一的例外是：当命名空间对象自身缺少描述、且同文件中的其他命名空间已经统一使用了@customNamespace与@category模式时，才为它补充：

/** * @category Cart * @customNamespace Cart */ export const CartWorkflowEvents = {

从源码看，这一模式已在 events.ts 中被一致使用：CartWorkflowEvents标注@category Cart，CustomerWorkflowEvents标注@category Customer，而多个商品子域命名空间共享@category Product，多个配送子域共享@category Fulfillment。@category负责在文档站中归类，@customNamespace则把事件常量归入自定义命名空间展示。遵循"仅在同文件已有该模式时才引入"的约束，可以保证整个文件风格的统一，避免某些命名空间被意外暴露为独立页面。

完整 Before / After 示例

把上述所有规则落在一个完整案例上，改造前后对比如下。

Before —— 无任何注释：

export const OrderWorkflowEvents = { PLACED: "order.placed", CANCELED: "order.canceled", COMPLETED: "order.completed", }

After —— 每个事件常量都补齐 TSDoc：

export const OrderWorkflowEvents = { /** * Emitted when an order is placed. * * @eventPayload * ```ts * { * id, // The ID of the order * } * ``` */ PLACED: "order.placed", /** * Emitted when an order is cancelled. * * @eventPayload * ```ts * { * id, // The ID of the order * } * ``` */ CANCELED: "order.canceled", /** * Emitted when an order is completed. * * @eventPayload * ```ts * { * id, // The ID of the order * } * ``` */ COMPLETED: "order.completed", }

对照 events.ts 中的真实实现可以看到，OrderWorkflowEvents除上述三事件外，还包含UPDATED、ARCHIVED、FULFILLMENT_CREATED、FULFILLMENT_CANCELED、RETURN_REQUESTED、RETURN_RECEIVED、CLAIM_CREATED、EXCHANGE_CREATED、TRANSFER_REQUESTED等事件，全部遵循同一注释模式。

从注释到运行时：事件如何被发射

事件文档并非纸上谈兵——事件常量会直接出现在工作流代码中。以购物车创建为例，packages/core/core-flows/src/cart/workflows/create-carts.ts 中createCartsWorkflow通过parallelize并行执行支付集合刷新与事件发射：

parallelize( refreshPaymentCollectionForCartWorkflow.runAsStep({ input: { cart: cart, }, }), emitEventStep({ eventName: CartWorkflowEvents.CREATED, data: { id: cart.id }, }) )

这里emitEventStep的eventName直接引用CartWorkflowEvents.CREATED，data传入{ id: cart.id }—— 与 TSDoc 中@eventPayload声明的载荷形状严格一致。整个 core-flows 包内emitEventStep被大量工作流复用（如generate-reset-password-token.ts、request-verification.ts、add-shipping-method-to-cart.ts等），因此一份准确的@eventPayload注释，本质上就是对该步骤发射数据的契约声明，读者可以通过它准确判断订阅回调中能拿到哪些字段。

提交前的自检清单

结合 .claude/skills/writing-tsdocs/SKILL.md 中列出的常见错误，为事件常量补齐 TSDoc 后应逐项检查：

每个导出的事件常量都已有描述，且以 "Emitted when ..." 说明发射时机；
每个事件都包含@eventPayload，载荷字段与emitEventStep的实际data一致；
非字符串字段已在行内注释中用(type)标注，字符串 ID 不标注；
@since版本号仅使用任务提示提供的版本，未自行编造；
受特性开关控制的事件已添加@featureFlag；
未给未导出的项、测试文件中的项添加文档；
未修改任何现有 TSDoc 与业务逻辑，只做"只增不改"的注释补充；
属性描述保持在 2 句话以内，不堆砌冗长解释。

遵循本指南维护 packages/core/utils/src/core-flows/events.ts，就能保证 Medusa 事件 API 文档与运行时行为保持同步，让订阅开发者、文档站点生成器与检索系统都能从统一、准确、可检索的事件契约中受益。

【免费下载链接】medusaThe world's most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Medusa 事件常量 TSDoc 编写规范：为 core-flows 工作流事件构建可检索的 API 文档