文化共创 MVP

面向非遗文化共创的本地 MVP，覆盖推荐、Agent 助手、AI 创作、知识库、社区、数字艺术、版权收益和后台审核。

本地运行

npm install
npm run mysql:up
npm run db:generate
npm run db:migrate
npm run db:seed
npm run dev

默认地址：

前端：http://127.0.0.1:5173
API：http://127.0.0.1:8787

如果已有开发库曾通过 prisma db push 建表且数据需要保留，不要直接重置数据库。确认库结构与 prisma/schema.prisma 一致后，可先执行：

npx prisma migrate resolve --applied 20260528000100_init

新库和后续结构变更优先使用 Prisma migration（数据库结构变更脚本）管理；npm run db:push 仅保留为本地开发兜底，不作为主流程。

环境变量

复制 .env.example 到 .env 后配置：

NODE_ENV="development"
PORT="8787"
DATABASE_URL="mysql://culture_user:culture_password@localhost:3306/culture_co_creation"
JWT_SECRET="replace-with-at-least-32-random-characters"
JWT_EXPIRES_IN="8h"
CORS_ORIGIN="http://127.0.0.1:5173"
ENABLE_DEMO_AUTH="true"
ALLOW_DEMO_MUTATIONS="false"
SEED_USER_PASSWORD="culture-demo-2026"
AI_PROVIDER="deepseek"
DEEPSEEK_API_KEY=""
DEEPSEEK_BASE_URL="https://api.deepseek.com"
DEEPSEEK_MODEL="deepseek-v4-flash"
OPENAI_API_KEY=""
OPENAI_BASE_URL="https://api.openai.com/v1"
OPENAI_TEXT_MODEL="gpt-4.1-mini"
OPENAI_IMAGE_MODEL="gpt-image-1"
IMAGE_PROVIDER="qwen"
DASHSCOPE_API_KEY=""
QWEN_IMAGE_BASE_URL="https://dashscope.aliyuncs.com"
QWEN_IMAGE_MODEL="qwen-image-2.0-pro"
QWEN_IMAGE_SIZE="1024*1024"
AI_REQUEST_TIMEOUT_MS="30000"
AI_RATE_LIMIT_WINDOW_MS="60000"
AI_RATE_LIMIT_MAX="12"

服务端通过 dotenv 加载 .env。不要把真实 API Key、数据库密码或生产 JWT_SECRET 提交到仓库或写入日志。

比赛提交与部署材料

PROJECT-COMPETITION.md：比赛答辩/提交说明，覆盖背景痛点、产品定位、创新闭环、商业模式、上线运营和风险边界。
DEPLOYMENT.md：部署、健康检查、日志、备份、回滚和上线前检查清单。
Dockerfile 与 compose.production.example.yml：用于比赛演示或小范围试用的容器化示例，不包含真实密钥。

数据库初始化

项目默认使用 MySQL。若本机没有可用 MySQL，可先启动 Docker Desktop，再执行：

npm run mysql:up

新建或空数据库推荐流程：

npm run db:generate
npm run db:migrate
npm run db:seed

部署或 CI 环境推荐使用：

npm run db:deploy
npm run db:seed

注意：npm run db:seed 会清空并重建演示数据，只适合新库、测试库、比赛演示库或明确允许重置的环境；已有业务数据的生产库不要直接执行。

prisma/migrations/20260528000100_init/migration.sql 是当前初始迁移。prisma/full-import.sql 仅作为历史全量导入参考，不替代 Prisma migration。

测试库隔离

E2E（端到端测试，从浏览器模拟真实用户流程）和 Vitest 集成测试默认读取 .env.test，避免写入日常开发库。

推荐使用一键准备脚本：

npm run test:prepare

该脚本会在缺少 .env.test 时自动复制 .env.test.example，启动本地 MySQL，等待健康检查，创建 DATABASE_URL 指向的测试库，并执行 Prisma client 生成、migration 和种子数据。为避免误清开发库，脚本会拒绝数据库名不包含 test 的配置。

npm test 会先执行测试库预检：确认 .env.test 存在、DATABASE_URL 指向测试库，并验证 MySQL 可连接。如果 Docker 未启动、测试库不存在，或 culture_user 没有测试库权限，命令会直接失败并输出可执行修复提示，不会把环境问题伪装成测试通过。

如需手动执行，可按以下步骤：

复制测试环境示例：

Copy-Item .env.test.example .env.test

创建独立测试库：

npm run mysql:up
docker compose -p culture-co-creation exec mysql mysql -uroot -proot_password -e "CREATE DATABASE IF NOT EXISTS culture_co_creation_test DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; GRANT ALL PRIVILEGES ON culture_co_creation_test.* TO 'culture_user'@'%'; FLUSH PRIVILEGES;"

对测试库执行迁移和种子数据：

$env:DATABASE_URL="mysql://culture_user:culture_password@localhost:3306/culture_co_creation_test"
npm run db:deploy
npm run db:seed
Remove-Item Env:DATABASE_URL

.env.test 已被 .gitignore 忽略，只提交 .env.test.example。

当前闭环

注册、登录、退出：前端保存 JWT，后端通过 Authorization: Bearer 验证。
写操作鉴权：发布、评论、保存、收藏、投稿、收益登记、提现申请默认要求真实登录 token。
Demo auth：本地可用于展示；写接口默认仍拒绝 demo 身份，除非显式设置 ALLOW_DEMO_MUTATIONS=true。
后台权限：后台指标、审核和提现处理接口要求 reviewer 或 admin。
AI Provider：支持 OpenAI Responses 与 DeepSeek Chat Completions；DeepSeek 模式只做真实文本生成/改写。
图片 Provider：支持 Qwen-Image 与 OpenAI 图片生成；配置 IMAGE_PROVIDER="qwen" 和 DASHSCOPE_API_KEY 后，AI 创作图像模式会调用通义万相真实生图。
Agent 助手：#/agent 通过 /api/ai/agent 调用真实 AI，按项目模块输出执行步骤、建议动作、风险提醒和缺失配置。
AI 请求保护：生成接口会读取 API Key、执行请求超时、校验 Provider 返回结构，并只记录 Provider、模型、耗时和失败类型，不输出密钥。
图像边界：DeepSeek 不提供图片生成时，前端明确显示“图像方案生成”，不会伪装成真实图片。
社区：发布、评论、点赞、收藏、分享均落库。
数字艺术：点赞、收藏、分享均落库；不提供二级交易、收益承诺或金融化功能。
知识库：用户投稿落库，并进入 manual_review 审核队列。
版权权益：补齐“版权凭证申请 → 审核中 → 已确权 → 收益待结算 → 提现申请中 → 已处理/已驳回”状态流。
收益提现：仅做登记和人工处理状态，不接入真实支付，不承诺收益到账。

验证命令

npm run test:prepare
npm run typecheck
npm run lint
npm run test
npm run build
npm run test:e2e

npm run test:e2e 使用 Playwright，覆盖注册、登录、发布社区动态、新增评论、保存 AI 作品和提交提现申请。首次运行若缺少浏览器运行时，请先执行：

npx playwright install chromium

生产部署前检查清单

NODE_ENV=production。
ENABLE_DEMO_AUTH=false，关闭 demo 用户注入。
ALLOW_DEMO_MUTATIONS=false，禁止 demo 身份写入。
JWT_SECRET 使用至少 32 位强随机字符串，不能使用示例占位符。
DATABASE_URL 指向真实生产 MySQL，且账号权限最小化。
CORS_ORIGIN 设置为真实前端域名；多个域名用英文逗号分隔。
使用 npm run db:deploy 应用 migration，不在生产库执行 db:push。
真实 API Key 只放在部署平台密钥或服务器环境变量中，不提交到 Git。
提现、版权凭证和收益展示保持 MVP 边界：仅登记流程状态，不代表支付到账、外部登记机关证明或收益承诺。

已知限制

当前系统仍是本地 MVP，没有生产级审计、风控和运维告警。
版权凭证为平台内流程记录，不等同外部登记机关证明。
提现处理为状态登记，不触发真实支付或财务结算。
prisma db push 仅作为本地开发兜底；团队协作和部署应使用 migration。
Prisma seed 配置已迁移到 prisma.config.ts；后续升级 Prisma 7 时仍需单独评估 CLI 与配置字段兼容性。
Docker 仅提供本地 MySQL 服务；生产部署还需补充镜像构建、反向代理、TLS、日志和备份策略。