theswiftera (Bdoss1)

SwiftTok——Swift时代的内容引擎

A. 本地优先 个人指挥中心 斯威夫特伟大/斯威夫特时代 品牌。SwiftTok使用AI（OpenAI或Google Gemini）生成社交媒体内容，管理审批工作流程，并通过各自的API发布到Facebook、Instagram和X（Twitter）。

使用Next.js 15、TypeScript、TailwindCSS、Prisma ORM和本地Postgres数据库构建。

______________________________________________________________________

目录

• 先决条件
• 快速开始
• 环境变量
• AI 服务商
• 项目结构
• 页面和功能
• API路线
• 后台工作者
• 数据库
• 认证
• 内容安全
• 图片上传
• 键盘快捷键
• 深色模式
• 出口与进口
• 测试
• CI/CD
• 数据库备份
• 部署
• 技术栈

______________________________________________________________________

先决条件

• Node.js 18+
• pnpm （推荐）-- npm install -g pnpm
• 码头工人 & Docker Compose （适用于当地Postgres）
• AI API密钥 --OpenAI *或* 谷歌双子座（见 AI 服务商)
• Facebook页面访问令牌 （可选）-用于发布到Facebook
• Instagram商业账号 （可选）-用于发布到Instagram
• X/Twitter API证书 （可选）--用于发布到X

______________________________________________________________________

快速开始

1.克隆存储库

git clone 
cd theswiftera

2.安装依赖项

pnpm install

3.设置环境变量

cp .env.example .env

编辑 .env 并填写您的值（请参阅 环境变量 在......下面

4.启动本地数据库

pnpm db:up

这运行 docker compose up -d，在端口5432上启动Postgres 16容器。

5.运行数据库迁移

pnpm prisma:migrate

这将创建中定义的所有表 prisma/schema.prisma.

6.为数据库添加种子（可选但推荐）

pnpm prisma:seed

Seeds 12提示模板，涵盖所有支柱/音调组合和默认应用程序设置。

7.启动开发服务器

pnpm dev

打开 http://localhost:3000 访问SwiftTok。

8.启动后台worker（可选）

在单独的终端中：

pnpm worker

该工作人员每30秒轮询一次数据库中的预定发布作业，并将其发布到Facebook、Instagram或X上。

______________________________________________________________________

环境变量

核心

AI 服务商

OpenAI（当 AI_PROVIDER=openai)

\*仅在以下情况下需要 AI_PROVIDER=openai

谷歌双子座（当 AI_PROVIDER=gemini)

\*仅在以下情况下需要 AI_PROVIDER=gemini

社交媒体

工人

速率限制

认证

看 .env.example 查看带有默认值的完整列表。

______________________________________________________________________

AI 服务商

SwiftTok支持两个AI后端，用于内容生成和标签建议。在它们之间切换 AI_PROVIDER 环境变量——无需更改代码。

OpenAI（默认）

使用GPT-4o-mini（或您配置的任何型号）生成文本，使用DALL-E 3生成图像。

AI_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini

获取API密钥： platform.openai.com.

谷歌双子座

使用Gemini 1.5 Flash（或任何Gemini型号）生成文本。

AI_PROVIDER=gemini
GEMINI_API_KEY=AIza...
GEMINI_MODEL=gemini-1.5-flash

获取API密钥： aistudio.google.com.

可用的Gemini型号：

笔记：

• 两个提供商共享相同的内容管道：无论哪个提供商处于活动状态，都会应用阻止的单词过滤和严格模式审核。
• 图像生成（DALL-E）仅适用于OpenAI。如果使用Gemini，图像上传仍然有效，但AI图像生成被禁用。
• 所有重试逻辑、温度和令牌设置都可以为每个提供程序独立配置。

______________________________________________________________________

项目结构

theswiftera/
├── .github/workflows/
│   └── ci.yml                   # CI/CD pipeline (lint, typecheck, test, build)
├── prisma/
│   ├── schema.prisma            # Data model (7 models, 6 enums)
│   └── seed.ts                  # Database seeder
├── scripts/
│   ├── backup.sh                # Database backup script
│   └── restore.sh               # Database restore script
├── src/
│   ├── __tests__/               # Test suite (Vitest)
│   ├── app/
│   │   ├── page.tsx             # Dashboard — analytics & stats
│   │   ├── studio/page.tsx      # Studio — AI content generation
│   │   ├── review/page.tsx      # Review — approve/reject content
│   │   ├── calendar/page.tsx    # Calendar — scheduling view
│   │   ├── history/page.tsx     # History — posted/failed log
│   │   ├── settings/page.tsx    # Settings — config & templates
│   │   ├── login/page.tsx       # Login page (when auth enabled)
│   │   ├── layout.tsx           # Root layout with theme & toasts
│   │   ├── globals.css          # TailwindCSS + dark mode variables
│   │   └── api/                 # API routes
│   │       ├── auth/            # NextAuth.js auth endpoints
│   │       ├── generate/        # Content generation (OpenAI or Gemini)
│   │       ├── content/         # Content CRUD + bulk/import/export/autosave
│   │       ├── calendar/        # Auto-build scheduling
│   │       ├── facebook/        # Facebook configuration
│   │       ├── hashtags/        # AI-powered hashtag generation
│   │       ├── upload/          # Image upload
│   │       ├── templates/       # Prompt template CRUD
│   │       ├── settings/        # App settings
│   │       ├── stats/           # Dashboard statistics
│   │       └── rate-limit/      # API rate limit tracking
│   ├── components/
│   │   ├── nav.tsx              # Navigation bar
│   │   ├── facebook-preview.tsx # Facebook post preview
│   │   ├── theme-provider.tsx   # Dark mode provider
│   │   ├── theme-toggle.tsx     # Dark mode toggle button
│   │   └── ui/                  # Reusable UI components
│   ├── lib/
│   │   ├── ai/
│   │   │   ├── openai.ts        # OpenAI implementation (generateVariants, generateHashtags, generateImage)
│   │   │   ├── gemini.ts        # Google Gemini implementation (generateVariants, generateHashtags)
│   │   │   ├── provider.ts      # Provider abstraction — routes to OpenAI or Gemini via AI_PROVIDER
│   │   │   ├── moderation.ts    # OpenAI Moderation API (Strict Mode)
│   │   │   ├── prompts.ts       # Brand system prompts, pillar/tone context, CTA styles
│   │   │   └── retry.ts         # Exponential backoff retry helper
│   │   ├── facebook/            # Facebook Graph API client & publisher
│   │   ├── instagram/           # Instagram Graph API publisher
│   │   ├── x/                   # X/Twitter OAuth 1.0a publisher
│   │   ├── auth.ts              # NextAuth.js configuration
│   │   ├── config.ts            # Centralized configuration module
│   │   ├── logger.ts            # Structured logging (Pino)
│   │   ├── prisma.ts            # Prisma client singleton
│   │   ├── rate-limiter.ts      # API rate limiting middleware
│   │   └── validation.ts        # Zod validation schemas
│   ├── middleware.ts             # Auth middleware
│   └── worker.ts                # Background publish worker
├── vitest.config.ts              # Test configuration
├── docker-compose.yml            # Local Postgres container
├── .env.example                  # Environment variable template
└── package.json                  # Scripts & dependencies

______________________________________________________________________

页面和功能

仪表板(/)

主页显示了内容引擎的概述：

• 统计卡 --项目总数、已发布计数、待审核、计划
• 14天活动图 --显示每日创建内容与发布内容的条形图
• 按支柱分类的内容 --饼图分解了5个品牌支柱的内容

工作室(/studio)

人工智能驱动的内容创建工作区：

1. 选择一项 支柱 （兄弟情谊、领导力、幽默、创业、家庭）
2. 选择一项 音调 （领袖、幽默、反思、建设者、会所）
3. 选择一个 平台 （脸书、Instagram、X）
4. 可选择输入 话题 专注的一代
5. 点击 生成 使用配置的AI提供程序创建内容变体（失败时自动重试）
6. 使用预览每个变体 Facebook预览 看看发布后会是什么样子
7. 将变体另存为草稿或直接批准
8. AI标签建议 --为任何变体自动生成相关标签
9. 图片上传 --将图片附加到帖子中，以获得更丰富的内容
10. AI图像生成 --通过DALL-E 3生成宣传图片（仅限OpenAI）

回顾(/review)

内容审批工作流程：

• 在可滚动列表中查看所有待审核的项目
• 单一行动 --单独批准、拒绝或标记项目以供审查
• 批量操作 --使用复选框选择多个项目，然后一次全部批准/拒绝
• Facebook预览 --切换任何项目的真实预览
• 草稿自动保存 --键入时，编辑会自动保存
• 键盘快捷键 --高级用户导航（请参见 键盘快捷键)

日历(/calendar)

每日日程安排视图：

• 查看按时间排列的所有已安排和已发布的项目
• 自动生成日历 --在高峰参与时间（上午9点至晚上9点）自动安排已批准的内容
• 拖动项目以重新排序

历史(/history)

所有发布和失败内容的时间表：

• 按日期排序，带有状态徽章（已发布/失败）
• 导出为JSON --将整个内容历史记录作为结构化数据下载
• 导出到CSV --下载为电子表格兼容文件

设置(/settings)

具有多个部分的配置中心：

• 审批模式 --切换内容在发布前是否需要手动批准
• 汽车帖子 --启用/禁用已批准内容的自动发布
• 每日发布目标 --设定每天要发布的帖子数量
• 严格模式和屏蔽词 -内容安全控制（使用OpenAI Moderation API）
• Facebook 页面 --使用页面ID和访问令牌连接您的Facebook页面
• 提示模板 --完整的CRUD编辑器，用于按支柱/音调组合创建、编辑和删除提示模板
• API费率限制 -使用彩色进度条直观显示API使用情况
• 导入内容 --上传JSON文件以批量导入内容项作为草稿

______________________________________________________________________

API路线

所有突变终点均受到以下保护：

• Zod验证 --请求体模式经过严格验证
• 速率限制 --内存中每IP速率限制器（可通过以下方式配置 API_RATE_LIMIT_PER_MINUTE)
• 结构化日志记录 --所有操作均通过Pino记录

______________________________________________________________________

后台工作者

工人(src/worker.ts)处理向所有平台的计划发布：

pnpm worker

它是如何工作的：

1. 每30秒轮询一次数据库（可通过以下方式配置 WORKER_POLL_INTERVAL_MS)
2. 查找具有以下条件的计划作业 runAt <= now 批量（可通过配置 WORKER_BATCH_SIZE)
3. 通往正确平台发布者（Facebook、Instagram或X）的路线
4. 跟踪API呼叫计数以了解速率限制
5. 关于成功：将内容标记为 POSTED
6. 失败时：使用可配置的指数回退重试（默认值：1m、5m、15m）
7. 最大重试次数后：将内容标记为 FAILED

所有配置都是通过环境变量进行的——请参阅 .env.example.

______________________________________________________________________

数据库

模式

定义于 prisma/schema.prisma 有7个型号和6个菜单：

模型：

• Setting --应用程序范围设置（审批模式、自动发布、严格模式、屏蔽词、每日目标）
• FacebookPage --已存储的Facebook页面凭据
• PromptTemplate --每个支柱/音调组合的自定义生成提示
• ContentItem --具有完整状态跟踪功能的社交媒体帖子
• PublishJob --具有重试状态的计划发布作业
• RateLimit -置换形式API调用跟踪

内容的状态生命周期：

DRAFT → READY_FOR_REVIEW → APPROVED → SCHEDULED → POSTED
                                              ↘ FAILED

有用的命令

______________________________________________________________________

认证

身份验证是 可选的 默认情况下禁用。要启用：

1. 集 AUTH_ENABLED=true 在 .env
2. 集 NEXTAUTH_SECRET 转换为随机字符串(openssl rand -base64 32)
3. 集 ADMIN_PASSWORD 输入您想要的密码
4. 可选择更改 ADMIN_USERNAME （默认值： admin)

启用后，所有页面都需要登录。API路由和登录页面被排除在身份验证检查之外。

______________________________________________________________________

内容安全

SwiftTok包括多层内容安全，无论哪个AI提供商处于活动状态，都适用：

1. 被屏蔽的单词 --在“设置”中配置的逗号分隔列表。在返回结果之前，任何包含被阻止单词的生成变体都会被自动删除。
2. OpenAI调节API --何时 严格模式 在设置中启用，所有生成的变体都会根据OpenAI的审核端点进行检查。标记的内容被过滤掉。即使使用Gemini进行发电，此检查也适用。
3. Zod验证 -所有API输入都经过严格验证，以防止格式错误的数据进入数据库。

______________________________________________________________________

图片上传

通过工作室或 /api/upload 端点：

• 支持JPEG、PNG、GIF和WebP格式
• 可通过以下方式配置最大文件大小 UPLOAD_MAX_FILE_SIZE_MB （默认值：10MB）
• 图像存储在 public/uploads/
• 返回可以附加到任何内容项的URL路径

AI图像生成 （仅限OpenAI）：

当 AI_PROVIDER=openai，工作室还支持通过DALL-E 3生成图像，并通过DALL-E 2创建上传图像的变体。

______________________________________________________________________

键盘快捷键

查看页面支持高级用户的键盘导航：

______________________________________________________________________

深色模式

SwiftTok在导航栏中包含一个暗模式切换。使用 next-themes 随着 class 策略，支持三种模式：

• 光 --默认明亮主题
• 黑暗 --调整HSL变量的深色主题
• 系统 --遵循您的操作系统偏好

______________________________________________________________________

出口与进口

出口

从 历史 页面：

• 导出JSON --将所有已发布/失败的项目下载为 .json
• 导出CSV --下载作为 .csv 文件

导入

从 设置 页面，上传一个JSON文件：

[
  {
    "caption": "Your post text here",
    "pillar": "LEADERSHIP",
    "tone": "LEADER",
    "hashtags": ["SwiftTheGreat", "Leadership"]
  }
]

有效值：

• pillar: BROTHERHOOD, LEADERSHIP, HUMOR, ENTREPRENEURSHIP, FAMILY
• tone: LEADER, FUNNY, REFLECTIVE, BUILDER, CLUBHOUSE
• platform （可选）： FACEBOOK, INSTAGRAM, X
• postType （可选）： TEXT, LINK, IMAGE
• status （可选）：导入的项目默认为 DRAFT

项目以以下方式导入 DRAFT 在发布之前，请查看状态。

______________________________________________________________________

测试

SwiftTok使用 维测试 用于使用React测试库进行组件测试。

# Run all tests
pnpm test

# Run in watch mode
pnpm test:watch

# Run with coverage
pnpm test:coverage

测试文件位于 src/__tests__/ 并涵盖：

• Zod验证模式
• 配置模块
• 速率限制器逻辑
• 重试机制

______________________________________________________________________

CI/CD

GitHub Actions工作流在推送时自动运行 main/develop 对于pull请求：

1. 棉绒 --运行ESLint
2. 类型检查 --跑步 tsc --noEmit
3. 测试 --运行Vitest测试套件
4. 构建 --使用真正的Postgres服务容器构建Next.js应用程序

看 .github/workflows/ci.yml 对于完整配置。

______________________________________________________________________

数据库备份

手动备份

pnpm db:backup

在中创建带时间戳、gzip压缩的SQL转储 ./backups/。自动删除超过30天的备份。

恢复

pnpm db:restore backups/swifttok_20260218_120000.sql.gz

______________________________________________________________________

部署

Vercel（推荐）

1. 将您的存储库推送到GitHub
2. 导入项目 维塞尔
3. 在Vercel仪表板中设置环境变量：

- DATABASE_URL --使用托管的Postgres（例如Neon、Supabase、Railway） - AI_PROVIDER — openai 或 gemini - OPENAI_API_KEY 或 GEMINI_API_KEY （取决于供应商） - NEXTAUTH_SECRET （如果启用了身份验证） - 所有其他必需变量来自 .env.example

1. Vercel将自动检测Next.js并配置构建

注： 后台工作程序必须单独运行。将其作为独立进程部署在Railway、Render或VPS上。

铁路

1. 在上创建新项目 铁路
2. 添加PostgreSQL服务
3. 从GitHub仓库添加服务（用于Next.js应用程序）
4. 使用start命令从同一存储库中添加另一个服务 pnpm worker （为工人）
5. 为两个服务设置环境变量

Docker（自托管）

# Build the Next.js app
pnpm build

# Start production server
pnpm start

# Start the worker in a separate process
pnpm worker

对于生产，使用PM2这样的流程管理器：

pm2 start npm --name "swifttok-web" -- start
pm2 start npx --name "swifttok-worker" -- tsx src/worker.ts

生产清单

• \[\]设置 NODE_ENV=production
• \[\]使用带SSL的托管PostgreSQL数据库
• \[\]设置 AI_PROVIDER 以及相应的API密钥(OPENAI_API_KEY 或 GEMINI_API_KEY)
• \[\]设置一个强大的 NEXTAUTH_SECRET
• \[\]启用 AUTH_ENABLED=true 如果可公开访问
• \[\]设置 ADMIN_PASSWORD 使用强密码
• \[\]配置社交媒体API凭据（Facebook、Instagram、X）
• \[\]设置自动数据库备份
• \[\]设置 LOG_LEVEL=info 或 warn
• \[\]使用SSL配置反向代理（nginx/Caddy）

______________________________________________________________________

技术栈