Audlis Docs

Appearance

本文档记录 Audlis 流量获取体系的实现、配置和验证方法：站内 SEO 基础、Pinterest 自动化社交分发、生命周期邮件、创作者口碑循环、Fediverse 社区增长与内容营销。

涉及六个路线图阶段：

  • Path 1：SEO 基础修复 — 让搜索引擎和社交平台能正确索引、预览产品页。
  • Path 2：Pinterest SEO — 把 AI mockup 产品自动分发到多个主题 Board，并启用 Rich Pins。
  • Path 3：生命周期邮件优化 — 首次购买标记 VIP、弃购邮件带图+折扣码、新品系列通知 VIP 订阅者。
  • Path 4：创作者口碑循环 — 创作者主页分享、推荐返利、排行榜、购买后社交引导。
  • Path 5：Fediverse 社区增长 — Trending on Fediverse、创作者联邦广播、跨站运营清单。
  • Path 6：内容营销 + AI 辅助 — Studio Journal 博客、AI Studio 教程、llms.txt 优化。

1. SEO 基础（Path 1） ​

1.1 动态产品 Sitemap ​

产品页是 Audlis 最重要的 SEO 页面。@astrojs/sitemap 只包含静态路由；产品页通过独立的动态 sitemap 暴露给搜索引擎。

  • 入口文件：src/pages/sitemap-products.xml.ts
  • 数据源：D1 products 表中 status = 'active' 的商品
  • 输出字段：
    • <loc>：产品 canonical URL
    • <lastmod>：基于 created_at，兼容 D1 的字符串、秒级/毫秒级时间戳
    • <changefreq>：weekly
    • <priority>：0.8
    • <image:image> / <image:loc>：产品主图，最多 5 张（用于 Google Images）

命名空间：

xml
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">

1.2 robots.txt ​

  • 文件：public/robots.txt
  • 已排除路径：/admin、/api/、/login、/register、/account、/checkout、/cart
  • 指向的 Sitemap：
    • https://shop.audlis.com/sitemap-index.xml（Astro 自动生成的静态页 sitemap）
    • https://shop.audlis.com/sitemap-products.xml（动态产品 sitemap）
    • https://shop.audlis.com/sitemap-blog.xml（博客 sitemap，见 Path 6）

1.3 Canonical / Open Graph / Twitter Card ​

所有页面共用 src/layouts/MainLayout.astro，默认注入：

  • <link rel="canonical" href="...">
  • Open Graph：og:type、og:url、og:title、og:description、og:image、og:locale
  • Twitter Card：twitter:card、twitter:site、twitter:title、twitter:description、twitter:image

产品页 src/pages/products/[slug].astro 会覆盖 title / description / image，并额外注入：

  • Schema.org Product JSON-LD（含 price、availability、aggregateRating）
  • Open Graph 产品价格标签（用于 Pinterest Rich Pins）：
    • og:price:amount
    • og:price:currency
    • og:availability
    • product:brand
    • product:condition

1.4 网站分析 ​

MainLayout.astro 支持两种分析工具，通过环境变量启用：

工具环境变量说明
PlausiblePLAUSIBLE_DOMAIN可选 PLAUSIBLE_SCRIPT_URL，默认 https://plausible.io/js/script.js
Cloudflare Web AnalyticsCF_ANALYTICS_TOKENbeacon token

生产环境已在 wrangler.toml 中设置：

toml
[vars]
PLAUSIBLE_DOMAIN = "shop.audlis.com"

1.5 验证方式 ​

  1. 访问 https://shop.audlis.com/sitemap-products.xml，确认返回 XML 且包含活跃产品。
  2. 访问 https://shop.audlis.com/robots.txt，确认 Disallow 路径与 Sitemap 链接正确。
  3. 查看任意产品页源码，确认 canonical、OG、Twitter Card、JSON-LD 存在。
  4. 查看页面源码底部，确认 Plausible <script defer data-domain="shop.audlis.com"> 已加载。

2. Pinterest SEO（Path 2） ​

2.1 自动发 Pin 流程 ​

AI mockup 系列发布完成后，src/lib/ai-mockup/publisher.ts 会调用 src/lib/social/distribute.ts，将产品自动分发到 Pinterest / Instagram / X。

Pinterest 调用链：

publishCompletedRun
  └── distributeToSocialPlatforms
        ├── generateSocialCaptions  (LLM 生成 SEO 关键词丰富的文案)
        ├── loadPinterestBoards     (读取主题 Board 配置)
        ├── selectBoardForProduct   (按关键词匹配 Board)
        └── postToPinterest         (Pinterest API v5 /pins)

每一次尝试都会写入 social_posts 表，方便审计和排查。

2.2 多主题 Board 路由 ​

默认只支持一个 PINTEREST_BOARD_ID，所有产品都发到一个 Board。现在支持按主题自动路由到多个 Board。

配置方式 ​

后台 SiteSettings → Pinterest Themed Boards 中维护 JSON 数组：

json
[
  { "id": "123", "name": "Audlis Studio", "keywords": [] },
  { "id": "124", "name": "Minimalist Art", "keywords": ["minimalist", "minimal", "simple", "clean"] },
  { "id": "125", "name": "Botanical Prints", "keywords": ["botanical", "plant", "floral", "nature"] },
  { "id": "126", "name": "Coastal Decor", "keywords": ["coastal", "beach", "ocean", "sea"] }
]

匹配逻辑 ​

src/lib/social/pinterest-boards.ts 中的 selectBoardForProduct：

  1. 把产品名称 + 系列主题拼接成文本，拆分为单词。
  2. 对每个 Board 的 keywords 打分：
    • 完整单词匹配 +2 分
    • 子串匹配 +1 分
  3. 选择得分最高的 Board。
  4. 无匹配时回退到默认 pinterest_board_id。

默认主题模板 ​

数据库迁移 src/db/migrations/029_pinterest_boards.sql 会预置 6 个主题：

  • Audlis Studio
  • Minimalist Art
  • Botanical Prints
  • Coastal Decor
  • Abstract Wall Art
  • Celestial & Space

预置模板中的 id 为空字符串，使用前必须在后台填入真实的 Pinterest Board ID。

2.3 Rich Pins ​

Pinterest Rich Pins 会自动从产品页抓取结构化数据，在 Pin 上显示价格、库存、品牌等信息。

Audlis 产品页已经提供两种格式：

  1. Schema.org Product JSON-LD（src/pages/products/[slug].astro）
  2. Open Graph 产品标签（新增）

申请步骤：

  1. 访问 Pinterest Rich Pins Validator。
  2. 输入任意产品 URL，例如 https://shop.audlis.com/products/stardust-summer-01。
  3. 验证通过后，点击 Apply，等待 Pinterest 审批。

2.4 视频 Pin / Idea Pin ​

src/lib/social/pinterest.ts 已扩展为支持 videoUrl：

  • 有 videoUrl 时，使用 media_source.source_type = 'video_url'
  • 无 videoUrl 时，回退到图片 Pin

当前 AI mockup 发布流程主要产出静态 mockup 图片，因此默认仍发布图片 Pin。当营销素材或 AI Studio 视频链路接入产品发布流程后，可把视频 URL 传入 DistributeInput.videoUrl，直接升级为视频 Pin。

3. 生命周期邮件优化（Path 3） ​

3.1 邮件列表与订阅 ​

Footer 订阅表单（src/components/Footer.astro）通过 POST /api/newsletter/subscribe 写入 email_preferences 表，并立即发送欢迎邮件。

  • 文件：src/pages/api/newsletter/subscribe.ts
  • 功能：
    • 写入 email_preferences（marketing_opt_in = 1）
    • 异步发送欢迎邮件 sendWelcomeEmail

3.2 首次购买自动标记 VIP ​

支付成功后，src/pages/api/webhooks/stripe.ts 调用 markEmailAsVip，将买家邮箱标记为 is_vip = 1。

sql
-- email_preferences 表
is_vip INTEGER DEFAULT 0

3.3 弃购邮件优化 ​

src/lib/lifecycle-mailer.ts 中的 cart_abandonment 模板现在包含：

  • 产品主图：从 products.images 读取第一张图并拼接为绝对 URL
  • 折扣码：读取 app_config.lifecycle_cart_discount_code，配置后会在邮件中显示

在后台 SiteSettings → 弃购邮件折扣码 中设置折扣码，例如 WELCOME10。

3.4 新品系列通知 VIP ​

当 AI mockup 系列发布完成时（src/lib/ai-mockup/publisher.ts），系统会为所有 is_vip = 1 且未退订的订阅者创建 new_collection 生命周期触发器。

Cron worker 处理这些触发器并发送新品系列邮件：

  • 邮件主题：Audlis 新系列：{theme}
  • 邮件内容：展示最多 4 个新产品的图片、名称、价格
  • 链接带 ?ref=audlis_email_newcollection 用于追踪

cron-worker/index.ts 中 new_collection 的时间窗口：

ts
new_collection: { delayMs: 0, expiryMs: 7 * 24 * 60 * 60 * 1000 }

3.5 生命周期触发器类型 ​

类型触发时机延迟过期
cart_abandonment加入购物车1 小时7 天
checkout_started开始结账30 分钟2 天
post_purchase_followup完成购买2 小时14 天
review_request订单送达1 天30 天
new_collectionAI mockup 系列发布立即7 天

4. 创作者口碑循环（Path 4） ​

4.1 创作者主页分享 ​

每个启用 ActivityPub 的创作者都有公开主页 /u/{handle}，顶部提供：

  • 带 ?ref={handle} 追踪参数的分享链接（复制按钮）
  • Pinterest / X(Twitter) / Facebook 一键分享

分享 URL 示例：

https://shop.audlis.com/u/audrey?ref=audrey

当新用户通过该链接访问并注册时，ref 会被带入注册页，最终写入 user.referred_by_user_id。

4.2 创作者推荐返利 ​

被推荐创作者的前 3 笔合格销售，会给推荐人额外 5% 佣金。

数据链路：

文件职责
src/db/migrations/031_creator_referrals.sql新增 user.referred_by_user_id、creator_referral_bonuses 表、默认配置键
src/pages/api/auth/[...auth].ts注册时读取 body.ref，解析为 user id 后写入 referredByUserId
src/pages/register.astro + SignUpForm.tsx从 URL ?ref= 读取并透传给注册接口
src/lib/royalty.tsaccrueCreatorReferralBonus：支付成功后生成返利记录；promoteEligibleRoyalties 同时处理返利表
src/pages/api/webhooks/stripe.ts订单支付成功后调用 accrueCreatorReferralBonus
src/lib/payouts.ts月度打款时从 royalty_ledger 和 creator_referral_bonuses 汇总可支付金额

配置键（可在后台 SiteSettings 或 SQL 调整）：

键默认值含义
creator_referral_bonus_bps500返利比例（500 bps = 5%）
creator_referral_max_orders3每个被推荐创作者最多返利的订单数
royalty_refund_window_days14退款观察期，期满后返利进入可支付状态

4.3 创作者排行榜 ​

/discover 页面顶部 SSR 渲染“本月最热创作者”：

  • 统计最近 30 天 royalty_ledger 中按创作者聚合的销售额（gross_cents）和销量
  • 仅展示已启用联邦身份、有 handle 的创作者
  • 卡片显示头像、handle、公开作品数、销售额
  • 点击跳转 /u/{handle}?ref={handle}

实现位置：

  • 查询：src/pages/discover.astro（server-side）
  • 渲染：src/components/CreatorLeaderboard.astro

4.4 购买后社交分享引导 ​

订单完成页 src/pages/success.astro 新增卡片：

  • 文案引导用户在 Instagram 上 @audlis 标记我们
  • 展示 10% 折扣码 SOCIAL10 和复制按钮
  • 页面 SSR 时会自动在 discounts 表中插入/忽略该折扣码，确保 checkout 可核销

结账页 src/components/CheckoutForm.tsx 已补全折扣码输入框，可输入 SOCIAL10 享受 10% 折扣。

4.5 验证方式 ​

  1. 访问 /u/{handle}，确认分享链接包含 ?ref={handle}，复制按钮工作。
  2. 通过 ?ref={handle} 注册新用户，检查 user.referred_by_user_id 是否指向推荐人。
  3. 完成一笔使用他人商用设计的订单，确认 creator_referral_bonuses 出现一条 accrued 记录。
  4. 访问 /discover，确认顶部展示“本月最热创作者”。
  5. 完成一笔订单后访问 /success?order_id=...，确认出现 SOCIAL10 折扣码并能复制。

5. Fediverse 社区增长（Path 5） ​

Audlis 是全球少数把完整 ActivityPub 实现做成产品功能的电商平台。Path 5 把联邦能力从“协议层”推进到“增长层”。

5.1 Trending on Fediverse（已上线） ​

/discover 页面新增 “Trending on the Fediverse” 区块：

  • 统计最近 30 天 ap_interactions 中 Like / Announce 最多的公开设计
  • 仅展示 visibility IN ('public','commercial')、moderation_state='ok'、status='ready' 的作品
  • 卡片显示封面（/api/designs/{id}）、创作者 handle、喜欢数、转发数
  • 点击跳转 /discover/{id} 详情页

实现位置：

  • 查询：src/pages/discover.astro（server-side）
  • 渲染：src/components/FediverseTrending.astro

5.2 创作者联邦广播（已实现） ​

创作者把作品从 private 切到 public / commercial 时，src/lib/ap/broadcast.ts:federationBroadcastDesignIfEnabled 会自动：

  1. 检查 app_config.ap_autobroadcast_designs（默认 true）
  2. 如果创作者启用了联邦身份，用其 creator actor 签名广播；否则用服务号 @audlis
  3. 组装 Create{Image|Video|Audio} Activity，写入 ap_delivery_queue
  4. Cron worker 按目标实例 sharedInbox 去重后投递

产品（AI mockup 系列）同样走 federationBroadcastProductIfEnabled，由服务号广播。

5.3 联邦订阅通知（已实现） ​

  • 站内用户 follow 远程创作者后，src/lib/ap/outbox-pull.ts 每小时轮询对方 outbox
  • 发现新的 Create 活动时，向所有关注者写入 new_work 通知（ap_notifications）

5.4 Fediverse 推广运营清单（人工执行） ​

以下不需要代码，按此清单执行：

动作说明
在 mastodon.social / pawoo.net / mas.to 发帖用 @audlis@shop.audlis.com 服务号发“电商类 Fediverse 账号在这里”的自我介绍，附 /discover 链接
互相关注设计类实例搜索 #pixelart #generativeart #posterdesign 标签下的活跃创作者并 follow（Phase 3 已支持 outbound follow）
每周精选转发从 Trending on Fediverse 挑 1–2 个作品，用服务号写推荐语并 announce
跨站设计挑战赛用 #AudlisChallenge 标签发起主题赛；参赛作品要求发布时 tag 该标签，服务号汇总转发

5.5 验证方式 ​

  1. 访问 /discover，确认 “Trending on the Fediverse” 区块出现（需要 ap_interactions 有数据）。
  2. 把一个设计从 private 改为 public，确认 ap_delivery_queue 出现 pending 行，且 cron 处理后变为 sent。
  3. 从 Mastodon 上 follow @audlis@shop.audlis.com，确认 ap_follows 出现 inbound active 记录，且收到 Accept。
  4. 在 Mastodon 上喜欢/转发一个 Audlis 作品，确认 ap_interactions 和 ap_notifications 有对应记录。

6. 内容营销 + AI 辅助（Path 6） ​

6.1 Studio Journal 博客 ​

/blog 是 Audlis 的内容营销阵地（Studio Journal），承载 SEO 长尾流量。

架构：

文件职责
src/data/blog/posts.ts文章数据源（双语静态数据，slug / title / excerpt / sections / keywords）
src/pages/blog/index.astro文章列表页（SSR，按日期倒序）
src/pages/blog/[slug].astro文章页（SSR，含 Article JSON-LD + "Shop the Look" 产品网格）
src/pages/sitemap-blog.xml.ts博客 sitemap，已加入 robots.txt

产品链接：文章页按 keywords 从 D1 匹配活跃产品（name/tags LIKE 匹配），渲染 4 个 "Shop the Look" 卡片；无匹配时回退到最新 4 个产品。

已发布文章：

  1. autumn-color-palette-ideas — 10 组秋季配色（wall art / apparel 关键词）
  2. style-minimalist-wall-art — 极简墙画家居搭配指南
  3. design-first-pod-product-audlis — AI Studio 新手教程（引导注册 + 发布作品赚版税）

新增文章：在 posts.ts 追加一个条目即可，列表页、文章路由、sitemap、llms.txt 全部自动生效。

6.2 llms.txt 优化 ​

src/pages/llms.txt.ts 面向 AI 搜索引擎（Perplexity、ChatGPT、Claude 等）提供结构化品牌知识：

  • Product Catalog：动态从 D1 读取全部活跃产品（名称、价格、URL）
  • Creator Marketplace：/discover、/studio、创作者主页说明
  • Guides & Tutorials：自动列出全部博客文章
  • Federation：ActivityPub 联邦身份说明

6.3 站外视频（人工执行） ​

YouTube / TikTok 制作过程视频不需要代码：

  • 录屏 AI Studio 从提示词到 mockup 的完整过程（5 分钟以内）
  • 标题带搜索词："How AI designs a custom t-shirt" / "AI 如何设计一件 T 恤"
  • 描述区放 /studio 和对应博客教程链接

6.4 验证方式 ​

  1. 访问 /blog，确认 3 篇文章按日期倒序展示。
  2. 打开任意文章，确认页面含 Article JSON-LD、"Shop the Look" 产品卡片和 AI Studio CTA。
  3. 访问 /sitemap-blog.xml，确认包含 /blog 和全部文章 URL。
  4. 访问 /llms.txt，确认 Guides & Tutorials 段落列出全部文章。
  5. Footer COMPANY 列出现 "Journal / 灵感与教程" 链接。

7. 相关数据表与配置键 ​

数据表 ​

  • products：商品主数据，包括 slug、status、images、created_at
  • social_posts：记录每次社交平台发布尝试（平台、post_id、caption、image_url、link_url、status、error）
  • email_preferences：邮件订阅者（email、marketing_opt_in、is_vip、locale）
  • marketing_lifecycle_triggers：生命周期邮件触发队列
  • app_config：存储 toggles、API token、board 映射、折扣码等配置
  • user.referred_by_user_id：记录邀请人，用于创作者推荐返利
  • creator_referral_bonuses：创作者推荐返利明细（状态：accrued / eligible / paid / refunded / void）
  • royalty_ledger：设计商用授权销售版税明细
  • ap_interactions：联邦 Like / Announce 互动明细（Trending on Fediverse 数据源）
  • ap_follows：联邦关注关系（inbound / outbound）
  • ap_delivery_queue：联邦出站投递队列

app_config 键 ​

键用途
social_autopost_pinterest是否自动发布到 Pinterest（'true' / 'false'）
pinterest_access_tokenPinterest OAuth token
pinterest_board_id默认 Board ID
pinterest_boards主题 Board 映射 JSON
social_autopost_instagram是否自动发布到 Instagram
social_autopost_twitter是否自动发布到 X/Twitter
lifecycle_cart_discount_code弃购邮件中显示的折扣码
creator_referral_bonus_bps创作者推荐返利比例（默认 500 = 5%）
creator_referral_max_orders每个被推荐创作者最多返利的订单数（默认 3）
ap_autobroadcast_designs设计发布时是否自动联邦广播（默认 true）
ap_autobroadcast_products产品上架时是否自动联邦广播（默认 true）

环境变量 ​

变量用途
PINTEREST_ACCESS_TOKENPinterest API OAuth token
PINTEREST_BOARD_ID默认 Board ID（fallback）
PLAUSIBLE_DOMAINPlausible 分析域名
CF_ANALYTICS_TOKENCloudflare Web Analytics beacon token
RESEND_API_KEYResend 邮件发送 API key
AP_DOMAINActivityPub 对外域名（默认 shop.audlis.com）

8. 故障排查 ​

8.1 Sitemap 返回空 ​

  • 检查 D1 products 表中是否有 status = 'active' 的商品。
  • 检查 images 字段是否为有效 JSON 数组。

8.2 Pinterest 没有自动发 Pin ​

  • 确认 PINTEREST_ACCESS_TOKEN 已配置。
  • 确认默认 PINTEREST_BOARD_ID 或 pinterest_boards 中至少有一个非空 Board ID。
  • 确认 social_autopost_pinterest 为 'true'。
  • 查询 social_posts 表的 status = 'failed' 行，查看 error 字段。

8.3 Rich Pins 验证失败 ​

  • 使用 Pinterest Validator 时确保产品页是 200，且不是登录/注册页。
  • 查看页面源码，确认 JSON-LD Product 和 OG 价格标签存在。
  • 价格/库存字段必须有有效值，不能是空字符串。

8.4 产品都发到同一个 Board ​

  • 检查 pinterest_boards JSON 是否已保存到 app_config。
  • 检查每个 Board 的 id 是否已替换为真实 Pinterest Board ID。
  • 检查产品名称/主题是否命中了目标 Board 的 keywords。

8.5 VIP 没收到新品系列邮件 ​

  • 确认 email_preferences.is_vip = 1 且 marketing_opt_in != 0。
  • 确认 AI mockup 系列发布成功（ai_mockup_runs.stage = 'completed'）。
  • 查询 marketing_lifecycle_triggers 中 trigger_type = 'new_collection' 的记录。
  • 确认 cron worker 正常运行并处理触发器。

8.6 弃购邮件没有产品图或折扣码 ​

  • 检查触发器的 product_id 是否对应有效 products 行。
  • 检查 products.images 是否为有效 JSON 数组。
  • 检查 app_config.lifecycle_cart_discount_code 是否已设置。

Synergy Books · SYS-BOOK Series

Copyright © 2026 yunyi yan