绿茶上位：主播女王 - Web 项目

项目概述

这是一个基于 React + Express.js + MongoDB 的游戏应用，支持实时聊天、角色扮演等功能。本项目新增了完整的短信验证登陆系统，用户信息存储在 MongoDB 中。

通用剧本系统：剧本定义与用户进度存 MongoDB（scripts / user_scripts 集合）。每个剧本的配置（世界观、世界书、角色列表、用户表单等）以 JSON 存在 config 字段，预设 prompt 可存于 config.preset。浮光跃金为首个实例：首页进入后首次需填写角色信息（姓名、年龄、外貌/立绘、入圈途径、发展方向、签约公司），提交后 AI 根据填写内容生成个性化开场白，再进入聊天；开场白与聊天统一走 /api/fuguang/stream（mode: "opening" / mode: "chat"）。对话中 AI 可输出 【章节：xxx】 标记，后端解析并记录章节，前端同步展示当前章节。

项目结构

web/
├── cwei-app/                    # 前端应用（React + TypeScript）
│   ├── src/
│   │   ├── pages/
│   │   │   ├── login/           # 登陆页面
│   │   │   ├── game/            # 游戏页面
│   │   │   └── whales/          # 鲸鱼相关页面
│   │   ├── services/
│   │   │   ├── auth.ts          # 认证 API 客户端
│   │   │   └── emojis.ts        # 表情包仓库 API（/api/emojis）
│   │   └── app.tsx              # 应用入口
│   ├── vite.config.ts           # Vite 配置
│   ├── .env.development         # 开发环境配置
│   └── .env.production          # 生产环境配置
│
├── cwei-server/                 # 后端服务（Node.js + Express）
│   ├── src/
│   │   ├── routes/
│   │   │   ├── auth.js          # 认证路由 (新)
│   │   │   ├── chat.js          # 聊天路由
│   │   │   ├── emojis.js        # 表情包列表 GET /api/emojis
│   │   │   ├── tts.js           # TTS 路由
│   │   │   └── ...
│   │   ├── utils/
│   │   │   ├── db.js            # MongoDB 连接 (新)
│   │   │   ├── users.js         # 用户数据操作 (新)
│   │   │   ├── jwt.js           # JWT 认证
│   │   │   ├── sms.js           # 短信服务
│   │   │   ├── codeStore.js     # 验证码存储
│   │   │   └── ...
│   │   ├── config/
│   │   │   └── index.js         # 配置管理
│   │   ├── constants/
│   │   │   └── ttsVoices.js     # TTS 音色 ID 与名称映射
│   │   └── app.js               # 应用入口
│   ├── package.json             # 依赖配置
│   └── .env                     # 环境变量
│
├── .env.example                 # 环境变量模板 (新)
├── QUICK_START.md               # 快速启动指南 (新)
├── SMS_AUTH_GUIDE.md            # 短信认证详细文档 (新)
├── TESTING_GUIDE.md             # 测试指南 (新)
├── IMPLEMENTATION_SUMMARY.md    # 实现总结 (新)
└── README.md                    # 本文件

快速开始

1. 环境准备

系统要求:

Node.js 16+
MongoDB 5.0+
npm 或 yarn

安装 MongoDB (macOS):

brew install mongodb-community
brew services start mongodb-community

或使用 Docker:

docker run -d -p 27017:27017 --name mongodb mongo:latest

2. 配置环境

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 配置 MongoDB 和其他服务
# 重要配置：
# - MONGODB_URI: MongoDB 连接字符串
# - JWT_SECRET: JWT 密钥
# - SMS 相关配置（如果需要真实短信）

如需在后端日志中输出模型完整回复（调试用），可在 .env 增加：

LOG_MODEL_OUTPUT=1
LOG_MODEL_OUTPUT_MAX_CHARS=4000

3. 启动后端服务

cd cwei-server
npm install
npm run dev

预期输出:

✓ MongoDB 连接成功: cwei
✓ MongoDB 集合初始化完成
[cwei-server] Running on http://localhost:3001

4. 启动前端应用

cd cwei-app
npm install
npm run dev

然后访问 http://localhost:5173

核心功能

认证系统

API 端点

方法	路由	描述	认证
POST	`/api/auth/send_code`	发送短信验证码	✗
POST	`/api/auth/verify_code`	验证码验证并登陆	✗
GET	`/api/auth/user_info`	获取用户信息	✓

使用流程

1. 用户输入手机号
   └→ POST /api/auth/send_code
      └→ 生成 6 位验证码
      └→ 发送短信（或开发模式打印）

2. 用户输入验证码
   └→ POST /api/auth/verify_code
      └→ 验证通过
      └→ 自动创建/检索用户
      └→ 生成 JWT token

3. 获取用户信息
   └→ GET /api/auth/user_info (需要 Bearer token)
      └→ 返回用户详细信息

用户数据模型

{
  "_id": ObjectId,              // MongoDB ID
  "user_id": "user_xxx",        // 全局唯一用户 ID
  "phone": "13800138000",       // 手机号（唯一索引）
  "status": 1,                  // 账户状态：1=正常, 0=禁用
  "registered_type": "phone",   // 注册类型
  "register_time": ISODate(),   // 注册时间
  "created_at": ISODate(),      // 创建时间
  "updated_at": ISODate(),      // 更新时间
  "deleted_at": null            // 删除时间（null=未删除）
}

表情包（emoji）数据模型

emoji 集合用于存储表情包元数据，图片文件存储在腾讯云 COS。

字段	类型	说明
id	Number	自增主键
description	String	描述（文件名去掉扩展名，如「先睡了.jpg」→「先睡了」）
url	String	腾讯云 COS 访问地址
name	String	名称（文件名去掉扩展名）

上传本地表情包目录到 COS 并写入 DB（需配置 COS_SECRET_ID、COS_SECRET_KEY、COS_BUCKET、COS_REGION）：

cd cwei-server
npm run upload-emojis
# 或指定目录（如 Downloads 下的表情包）：
node src/scripts/upload_emojis_to_cos.js "/Users/wangxinyu/Downloads/表情包"

浮光跃金：若需将 MongoDB 中 world_book.entries[id=54] 的「角色总览」解析为结构化角色数组并写入 scripts(script_id=fuguang).config.characters，可执行：

cd cwei-server
node src/scripts/update_fuguang_characters_from_worldbook_entry_54.js

浮光跃金（娱乐圈模拟）+ 通用剧本系统

浮光跃金作为通用剧本系统的首个实例：剧本定义与用户进度存 MongoDB，首次进入需填写角色信息，AI 根据填写内容生成个性化开场白后进入聊天。

数据库：scripts 集合存剧本定义（含 config：世界观、世界书、角色列表、用户表单配置）；可选字段 script_types 为多类型字符串拼接（如 "古代，都市，民国"），用于 /api/fuguang/stream 中 background、music、subject 的 RAG 检索过滤。user_scripts 集合存用户进度（form_data、status、session_id、chapters、current_chapter）
流程：进入页 → 若未填表或 status=created 则展示信息填写（setup）→ 保存后进入开场白过渡（opening，流式生成）→ 聊天（chat）；回访且 status=playing 则直接进入聊天
预设与世界书：沿用 presetPrompts.js 与 fuguangWorldInfo.js，世界书可从 script.config.world_book.entries 注入。presetPrompts.js 会优先从仓库根目录的 泰拉战纪专用预设.json 加载 SillyTavern 预设，所有使用 getPresetMessages 的剧本/角色聊天路由（如 /api/chat、/api/roles/.../chat、/api/whales/.../chat、/api/fuguang/stream 等）都会共享这一预设；若该文件不存在，则自动回退为内置预设。/api/fuguang/stream 在做世界书关键词扫描时，会对 assistant 的 JSON 输出提取 narratives，将其中的 role + content 拼接后参与匹配。
章节：AI 输出中的 【章节：章节名】 会被解析并写入 user_scripts.chapters，聊天顶部展示当前章节

统一流式接口（SSE）：

开场白：POST /api/fuguang/stream，body 传 { mode: "opening", message: "请生成开场白。", sessionId: null }（需登录且已 save-character）。服务端会生成新的 session_id，并在流结束后写入 user_scripts（status=playing、chapters/current_chapter）。
聊天：POST /api/fuguang/stream，body 传 { mode: "chat", message, sessionId }（mode 可省略，默认 chat）。服务端会在 done 事件里按需返回 { currentChapter, chapters } 用于前端同步章节。
模型输出落盘：每次 /api/fuguang/stream 流式结束后，服务端会将模型完整回复以原始文本写入 cwei-server/src/routes/fuguang-model-output/ 目录，文件名格式为 {时间}_{opening|chat}_{sessionId}.txt，便于调试与留档。

数据与配置：

cwei-server/src/data/fuguang/character-data.json：世界观与世界书（种子写入 scripts 后由 DB 提供）
表单与角色列表由 scripts 集合中 script_id=fuguang 的 config.user_form、config.characters 定义（其中立绘 options 支持 voice_id，保存角色信息时会一并存入 user_scripts.form_data.voice_id）
特效素材：MySQL dreamelse.material_effect 表可经 init_material_effect.js 建表并加索引，经 migrate_material_effect.js 迁移至 MongoDB material_effect 集合（见 cwei-server/src/scripts/）

方寸喵居（TinyMeowAbode）资源

首页「选择今晚去哪里」区域有「方寸喵居」卡片，点击进入云养猫模拟游戏。游戏已完整迁移至 cwei-app/public/meow-abode/，非 iframe 嵌入。

仅已登录用户可进入：未登录访问会跳转回首页。存档、日记、照片、meta 自动同步到后端 MongoDB（meow_abode_saves 集合）。

若需将游戏资源上传到 COS（可选，用于 CDN 加速）：

cd cwei-server
npm run upload-meow-abode
# 上传完成后，编辑 cwei-app/public/meow-abode/config.js，将 __MEOW_ASSET_BASE__ 设为 COS Base URL

花园世界

生活区「花园世界」：种花、浇水、收获的轻量养成玩法。支持玫瑰、郁金香、向日葵三种花卉，浇水促进生长，花开后收获获得金币，可购买更多种子。存档存储在 MongoDB garden_world_saves 集合。

测试 API

使用 cURL 测试

发送验证码:

curl -X POST http://localhost:3001/api/auth/send_code \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "13800138000"}'

验证并登陆:

curl -X POST http://localhost:3001/api/auth/verify_code \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "13800138000", "code": "123456"}'

获取用户信息:

curl http://localhost:3001/api/auth/user_info \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

使用 Postman 测试

导入本仓库提供的 Postman Collection，或参考 TESTING_GUIDE.md 手动创建。

文档

📖 QUICK_START.md - 详细的快速启动指南
📖 SMS_AUTH_GUIDE.md - 短信认证系统完全文档
📖 TESTING_GUIDE.md - 全面的测试指南和示例
📖 IMPLEMENTATION_SUMMARY.md - 实现细节总结
📖 docs/fuguang-api.md - 浮光跃金 fuguang.js 代码结构与 API 解析
⚙️ .env.example - 环境变量配置模板

配置说明

MongoDB 配置

# 本地 MongoDB
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=cwei

# MongoDB Atlas (云端)
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/cwei

JWT 配置

# 生成强密钥
openssl rand -base64 32

# 设置密钥（改为实际值，生产环境很重要）
JWT_SECRET=your-strong-secret-key-here
JWT_EXPIRES_IN=604800  # 7 天（秒）

SMS 配置

# 阿里云短信配置（可选）
ALIYUN_SMS_ACCESS_KEY_ID=your_key
ALIYUN_SMS_ACCESS_KEY_SECRET=your_secret
ALIYUN_SMS_SIGN_NAME=your_sign_name
ALIYUN_SMS_TEMPLATE_CODE=your_template_code
SMS_CODE_EXPIRE_SECONDS=300  # 验证码过期时间（秒）

OpenRouter（角色聊天）

角色聊天使用 OpenRouter 调用大模型。在 cwei-server/.env 中配置：

OPENROUTER_API_KEY=your_openrouter_api_key
# 可选：OPENROUTER_MODEL、OPENROUTER_BASE_URL；浮光流式采样见 OPENROUTER_TEMPERATURE/TOP_P/PRESENCE_PENALTY/FREQUENCY_PENALTY（.env.example）

若角色聊天返回 403：通常表示 OpenRouter API Key 无效、已过期、或当前账户/密钥无权访问所选模型。请在 OpenRouter 控制台检查密钥有效性与模型权限后重试。

开发指南

后端开发

cd cwei-server

# 开发模式（热重载）
npm run dev

# 生产环境
npm start

前端开发

cd cwei-app

# 开发模式
npm run dev

# 构建
npm run build

# 预览构建结果
npm run preview

添加新的 API 路由

创建新路由文件 cwei-server/src/routes/myroute.js
在 cwei-server/src/routes/index.js 中注册路由
需要认证的路由使用 authMiddleware 中间件

import { authMiddleware } from '../utils/jwt.js';

router.get('/protected', authMiddleware, (req, res) => {
  // req.user 包含 JWT payload
  res.json({ userId: req.user.uid });
});

依赖

后端主要依赖

express - Web 框架
mongodb - MongoDB 驱动
jsonwebtoken - JWT 认证
axios - HTTP 客户端
dotenv - 环境变量管理
@alicloud/dysmsapi - 阿里云短信 API

前端主要依赖

react - UI 框架
typescript - 类型检查
vite - 构建工具
scss - 样式预处理器

常见问题

MongoDB 连接失败

✗ MongoDB 连接失败: connect ECONNREFUSED 127.0.0.1:27017

解决方案:

检查 MongoDB 是否运行：mongosh
检查 MONGODB_URI 配置是否正确
如果使用 Docker，检查容器是否启动

验证码不显示

验证码在开发模式会打印到控制台，应该看到：

[SMS-DEV] 验证码 -> 13800138000: 123456

如果没有看到，检查：

请求是否成功（检查响应状态）
服务器日志输出

Token 过期

默认 token 有效期为 7 天，过期后需要重新登陆。可通过 JWT_EXPIRES_IN 修改。

安全建议

开发环境

✓ 默认配置可用于开发
✓ 验证码打印到控制台便于调试

生产环境

✗ 必须更改 JWT_SECRET
✗ 必须配置真实的 MongoDB 连接
✗ 必须配置真实的 SMS 服务凭证
✗ 必须启用 HTTPS
✗ 建议添加 API 速率限制
✗ 建议实现 CORS 安全策略
✗ 建议添加请求日志和监控
✗ 建议实现备份和恢复策略

部署

本地部署（开发）

已通过 npm run dev 完成，服务运行在 http://localhost:3001

Docker 部署

# 创建 Dockerfile
docker build -t cwei-server .

# 运行
docker run -d \
  -p 3001:3001 \
  -e MONGODB_URI=mongodb://mongodb:27017 \
  -e JWT_SECRET=your-secret \
  --link mongodb:mongodb \
  cwei-server

云端部署（Heroku/Vercel）

参考各平台的部署文档，主要注意：

设置环境变量
配置 MongoDB 连接字符串
配置 JWT Secret

贡献指南

Fork 项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

许可证

MIT License - 详见 LICENSE 文件

支持

📖 查看 SMS_AUTH_GUIDE.md 了解认证系统
📖 查看 TESTING_GUIDE.md 了解如何测试
📖 查看 QUICK_START.md 快速开始
💬 提交 Issue 报告问题
💬 提交 PR 贡献代码

更新日志

v1.1.0 (2024-01-17)

✨ 实现短信验证登陆系统
✨ 集成 MongoDB 用户存储
📖 添加完整文档和测试指南
🔐 实现 JWT 认证中间件
🐛 修复用户查询逻辑

v1.0.0 (初始版本)

基础的游戏框架
聊天功能
角色扮演系统

最后更新: 2024-01-17 维护者: [Your Name]

Name		Name	Last commit message	Last commit date
.vscode		.vscode
cwei-app		cwei-app
cwei-server		cwei-server
docs		docs
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
CHAR_CHAT_ENHANCEMENTS.md		CHAR_CHAT_ENHANCEMENTS.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
MESSAGE-SYSTEM-README.md		MESSAGE-SYSTEM-README.md
MONGODB_REMOTE_CONFIG.md		MONGODB_REMOTE_CONFIG.md
MONGODB_SETUP_SUMMARY.md		MONGODB_SETUP_SUMMARY.md
MessageRenderer.tsx		MessageRenderer.tsx
PLAN.md		PLAN.md
QUICK_START.md		QUICK_START.md
README.md		README.md
SMS_AUTH_GUIDE.md		SMS_AUTH_GUIDE.md
TESTING_GUIDE.md		TESTING_GUIDE.md
VERIFICATION_CODE_FIX.md		VERIFICATION_CODE_FIX.md
a.md		a.md
b.md		b.md
generate-sprites.js		generate-sprites.js
lihui.md		lihui.md
message-demo.html		message-demo.html
message-types.ts		message-types.ts
另一种人生_PRD_v7.0.docx		另一种人生_PRD_v7.0.docx
泰拉战纪专用预设.json		泰拉战纪专用预设.json
角色立绘补充方案.md		角色立绘补充方案.md

Latest commit

History

Folders and files

Repository files navigation