Magent Docs
V1.0.1

数据模型设计

V1.0.1 数据模型架构概览与 TypeScript 类型定义

V1.0.1 数据模型设计文档

架构概览

┌─────────────────────────────────────────────────────────────────┐
│                         业务流程                                 │
│  需求层 → 策略层 → 编排层 → 执行层 → 反馈层                        │
│  (User)   (Campaign) (Task)  (Execute) (Feedback)               │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                         顶层实体 (L0)                            │
├──────────┬──────────┬──────────┬──────────┬────────────────────┤
│ BrandDNA │ UserReq  │ Campaign │   Task   │ PerformanceReport  │
│          │ Input    │          │          │                    │
└────┬─────┴────┬─────┴────┬─────┴────┬─────┴─────────┬──────────┘
     │          │          │          │               │
     ▼          ▼          ▼          ▼               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    共享业务实体 (shared.ts)                      │
│  Persona | Goal | MarketingEvent | MarketingChannel | Offer等   │
└────────────────────────────────┬────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────┐
│                     基础类型 (base.ts)                           │
│     Money | TimeRange | FileRef | Date | 审计字段                │
└─────────────────────────────────────────────────────────────────┘

模块依赖关系

文件依赖顶层实体职责
base.ts-纯技术/领域无关的基础类型
shared.tsbase.ts-跨模块共享的业务实体和枚举
brand.tsbase.tsBrandDNA品牌画像/DNA 定义
user.tsbase.ts, shared.tsRequirement用户需求输入(需求层)
campaign.tsbase.ts, shared.tsCampaign营销活动定义(策略层)
tasks.tsbase.ts, shared.tsTask执行任务定义(编排层)
feedback.tsbase.tsPerformance绩效报告(反馈层)

基础类型层 (base.ts)

提供与业务无关的、纯技术性的基础类型,所有模块可复用。

类型说明示例
DateISO 日期时间字符串"2026-01-05T10:29:00Z"
TimeRange时间范围{ startAt, endAt }
Money金额(最小货币单位){ currency: "USD", amount: 1050 }
FileRef文件/资产引用{ id, name, uri, mimeType, size }
CollectionRef集合引用{ id, name }
ProductRef产品引用{ id, title }
Timestamps审计时间戳{ createdAt, updatedAt }


共享业务实体层 (shared.ts)

存放被多个业务模块引用的核心业务概念,避免循环依赖和重复定义。

枚举类型

枚举使用模块
Channelwebsite | ads | emails | social | project_managementcampaign, tasks
FunnelStageawareness | consideration | conversion | retentiontasks
Goalincrease_brand_awareness | drive_traffic_to_website | ...user, campaign
RequestStatustodo | in_progress | done | pauseduser, campaign
DiscountTypeorder_discount | product_discount | shipping_discountuser
DiscountMethodcode | automaticuser
DiscountValueTypefixed_amount | percentageuser

业务实体

实体说明使用场景
Persona用户画像Campaign、Requirement
MarketingEvent营销事件Campaign、Requirement
GoalInput营销目标输入Campaign、Requirement
OfferDiscount优惠折扣(完整版)Requirement
OfferRef优惠引用(轻量版)Task、Campaign
CreativeConcept创意概念Requirement


需求层 (user.ts) - Requirement

顶层实体结构

Requirement
├── id: string
├── title: string                    // 需求标题
├── startAt: Date                    // 开始时间
├── dueDate?: Date                   // 截止日期
├── assigneeId?: string              // 负责人
├── brandId: string                  // 所属品牌 ID
├── campaignIds?: string[]           // 关联的营销活动 ID
├── target?: Target                  // 目标与受众(可选)
├── source?: Source                  // 资源与商业输入(可选)
├── execution?: Execution            // 执行计划(可选)
├── rawQuery: { text, files[] }      // 原始用户输入
├── createdAt: Date
└── updatedAt: Date


策略层 (campaign.ts) - Campaign

顶层实体结构

Campaign
├── id: string
├── name: string                     // 活动名称
├── type: Type                       // 活动类型
├── status: RequestStatus            // 状态
├── startAt: Date                    // 开始时间
├── endAt: Date                      // 结束时间
├── assigneeId?: string              // 负责人
├── brandId: string                  // 所属品牌 ID
├── requirementId?: string           // 所属需求 ID
├── taskIds?: string[]               // 关联的任务 ID
├── budget?: Money                   // 预算
├── plan?: Plan                      // 营销规划(可选)
├── createdAt: Date
└── updatedAt: Date


编排层 (tasks.ts) - Task

顶层实体结构

Task
├── id: string
├── taskType: string                 // 任务类型
├── title: string                    // 任务标题
├── category?: Category              // 任务分类
├── channel?: Channel                // 渠道
├── funnelStage?: FunnelStage        // 漏斗阶段
├── campaignId?: string              // 营销活动 ID
├── delivery: Delivery               // 分发与排期
├── content: Content                 // 内容生产
├── workflow: Workflow               // 工作流协作
├── integrations?: Integrations      // 连接依赖
├── shop?: Shop                      // 商品与优惠
├── creditsCost: number              // 预估积分消耗
├── result?: Result                  // 执行结果
├── createdAt: Date
└── updatedAt: Date

任务类型 (taskType)

类型说明
content_generate内容生成(图/视频/文案/多模态)
social_publish社媒发布/分发
ad_campaign广告投放
web_build网站/页面内容制作
crm_outreach冷邮件/邮件触达
gen_and_publish生成并发布

任务状态 (Status)

状态说明
todo待处理
in_progress进行中
scheduled已排期
published已发布
done已完成
blocked被阻塞
failed失败
canceled已取消


反馈层 (feedback.ts) - Performance

顶层实体结构

Performance
├── id: string
├── campaignId: string               // 所属营销活动
├── taskIds: string[]                // 数据来源任务
├── startAt: Date                    // 统计开始时间
├── endAt: Date                      // 统计结束时间
├── postsCount: number               // 内容条目数量
├── status: OutputStatus             // 执行状态
├── comparison?: Baseline            // 对比基准
├── channels: Channels               // 渠道表现指标
├── createdAt: Date
└── updatedAt: Date

各渠道指标

渠道指标
Instagramreach, follows, interactions
EmailsopenRate, ctr, clickRate
Meta Adsspend, reach, impressions, clicks, ctr
Blog Postviews, avgTime


品牌 DNA (brand.ts) - BrandDNA

顶层实体结构

BrandDNA
├── id: string
├── name: string                     // 品牌名
├── description?: string             // 品牌描述
├── lang: string                     // 默认语言
├── otherLangs?: string[]            // 其他语言
├── logo?: FileRef                   // Logo
├── industries?: string[]            // 行业
├── salesType?: SalesType            // 销售类型
├── personality?: string[]           // 品牌性格标签
├── competitors?: CompetitorRef[]    // 竞品列表
├── marketingEvents?: MarketingEvent[] // 营销事件
├── audience?: Audience              // 受众与市场
├── core?: Core                      // 品牌内核
├── visual?: Visual                  // 品牌视觉
├── products?: Products              // 品牌产品
├── seo?: SEO                        // SEO 基础
├── contentStrategy?: ContentStrategy // 内容策略
├── createdAt: Date
└── updatedAt: Date


设计决策说明

1. 分层原则

L0 顶层实体 → 业务聚合根,独立存储
L1 子模块   → 逻辑分组,嵌套在 L0 内

2. 类型提升规则

提升到条件示例
base.ts技术性、领域无关、无业务语义Money, TimeRange, FileRef
shared.ts被 ≥2 个业务模块引用的业务实体Persona, Goal, MarketingChannel
保持原位仅在单一模块内使用TaskWorkflow, BrandVisualSystem

3. 状态枚举不统一的原因

枚举所属模块语义
RequestStatusshared需求生命周期:todo → in_progress → done
Statustasks任务执行状态:需要 scheduled/published/failed 等细粒度
OutputStatusfeedback产出发布状态:聚焦发布相关状态

结论:不强行统一,因为业务语义不同。

4. 引用 vs 完整对象

  • 引用类型XxxRef):用于跨模块关联,避免数据冗余
  • 完整类型:用于模块内部,需要完整信息时

On this page