Medusa 事件常量 TSDoc 编写规范为 core-flows 工作流事件构建可检索的 API 文档【免费下载链接】medusaThe worlds 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。命名空间对象本身不强制文档化除非它缺少描述且同文件中其他命名空间已经使用了统一的customNamespacecategory模式才为它补上不要给原本没有该模式的文件强行引入。此外整个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.tsexport 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 orders 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 的TranslationWorkflowEventstranslation.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 CartCustomerWorkflowEvents标注category Customer而多个商品子域命名空间共享category Product多个配送子域共享category Fulfillment。category负责在文档站中归类customNamespace则把事件常量归入自定义命名空间展示。遵循仅在同文件已有该模式时才引入的约束可以保证整个文件风格的统一避免某些命名空间被意外暴露为独立页面。完整 Before / After 示例把上述所有规则落在一个完整案例上改造前后对比如下。Before —— 无任何注释export const OrderWorkflowEvents { PLACED: order.placed, CANCELED: order.canceled, COMPLETED: order.completed, }After —— 每个事件常量都补齐 TSDocexport 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.CREATEDdata传入{ 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 worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Medusa 事件常量 TSDoc 编写规范：为 core-flows 工作流事件构建可检索的 API 文档
Medusa 事件常量 TSDoc 编写规范为 core-flows 工作流事件构建可检索的 API 文档【免费下载链接】medusaThe worlds 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。命名空间对象本身不强制文档化除非它缺少描述且同文件中其他命名空间已经使用了统一的customNamespacecategory模式才为它补上不要给原本没有该模式的文件强行引入。此外整个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.tsexport 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 orders 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 的TranslationWorkflowEventstranslation.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 CartCustomerWorkflowEvents标注category Customer而多个商品子域命名空间共享category Product多个配送子域共享category Fulfillment。category负责在文档站中归类customNamespace则把事件常量归入自定义命名空间展示。遵循仅在同文件已有该模式时才引入的约束可以保证整个文件风格的统一避免某些命名空间被意外暴露为独立页面。完整 Before / After 示例把上述所有规则落在一个完整案例上改造前后对比如下。Before —— 无任何注释export const OrderWorkflowEvents { PLACED: order.placed, CANCELED: order.canceled, COMPLETED: order.completed, }After —— 每个事件常量都补齐 TSDocexport 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.CREATEDdata传入{ 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 worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考