「插了个花」微信小程序业务后端服务。基于 NestJS + PostgreSQL(Prisma) + Redis(BullMQ)， AI 能力对接第三方 OpenAI 兼容中转站，图片存储阿里云 OSS。
完整架构设计见
docs/architecture.md。 当前为 P0 脚手架：目录结构与模块骨架已就绪，各业务接口按阶段（P1~P7）逐步实现。
- NestJS 11 / TypeScript
- Prisma + PostgreSQL
- BullMQ + Redis（AI 异步任务）
- 微信小程序
code2session+ JWT - 第三方 OpenAI 兼容中转站（可插拔
AiProvider） - 阿里云 OSS / 本地 data URL 存储（可插拔
StorageProvider）
本地 API 固定连接当前电脑上的 PostgreSQL 和 Redis。数据库通过只读 pg_dump
完整复制 dev 的 schema、表数据和迁移记录；复制完成后的增删改查、Prisma 迁移、
验证码、登录态和 BullMQ 队列都只写本机。
短信、微信、AI 和 OSS 保留 dev 配置并真实调用。这不会修改 dev PostgreSQL 或 dev Redis，但会真实发送短信、产生 AI 费用，并可能向 dev OSS 写入文件。
# 1. 安装依赖
pnpm install
# 2. 首次使用时创建本地运行配置
Copy-Item .env.example .env
# 将安全保存的 dev 短信/微信/AI/OSS配置填入 .env。
# 需要真实调用这些 dev 服务时，将 ALLOW_REMOTE_SERVICES 改为 true。
# 如需直连 dev 数据库或 Redis，也必须显式启用该开关。
# 3. 单独创建 dev 数据库只读来源配置
Copy-Item .env.dev.source.local.example .env.dev.source.local
notepad .env.dev.source.local
# 只填写 DEV_DATABASE_URL；不要把该连接串放入 .env、README 或 Git。
# 4. 生成 Prisma Client，启动专用本地 PostgreSQL + Redis
pnpm prisma:generate
pnpm infra:up
# 5. 确保本地 API 已停止，然后完整刷新本地 dev 副本
pnpm db:clone-dev -- --replace-local
# 6. 启动本地 API
pnpm start:dev克隆命令的安全顺序为：
- 校验目标严格等于
localhost:55432/flower_local，源地址必须是远程 PostgreSQL。 - 对 dev 执行两次只读表统计，并在中间运行
pg_dump；dev 有行数变化时停止。 - 验证 dump 后备份当前本地库到
.local/db-backups/。 - 将 dev dump 恢复到临时本地库，核对每张表的行数，再仅对临时库执行迁移。
- 验证成功后切换为
flower_local，清空专用本地 Redis，并删除临时 dev dump。
任何导出、归档校验、恢复或迁移失败都不会替换原本地数据库。数据库切换期间若进程 意外中断，可在 API 停止时运行：
pnpm db:clone-dev -- --recover-previous-local刷新 dev 副本会覆盖当前 flower_local。命令会先生成被 Git 忽略的本地回滚备份，
但仍应在刷新前确认本地测试数据不再需要。
- API：
http://localhost:3001/api - Swagger：
http://localhost:3001/api/docs - Web：
http://localhost:3000，接口固定为http://localhost:3001/api - 管理端预留：
http://localhost:3002 - PostgreSQL：
127.0.0.1:55432/flower_local - Redis：
127.0.0.1:56379
需要在本地复现线上 Nginx 反代和大文件上传时，先启动 API，再运行：
pnpm gateway:up本地网关地址为 http://localhost:8080/api，上传请求体上限为 60m。管理端联调时将
NEXT_PUBLIC_API_BASE_URL 设置为 http://localhost:8080/api 并重启管理端。
# 修改 Prisma schema 后，仅在本地创建和验证迁移
pnpm prisma:migrate
# 查看本地数据库
pnpm prisma:studio
# 创建本地管理员
pnpm admin:create -- --username localadmin
# 停止容器但保留数据
pnpm infra:downDEV_DATABASE_URL 只有 db:clone-dev 会读取，API、Studio、seed、admin create、
db push 和本地迁移都继续使用 DATABASE_URL。
ALLOW_REMOTE_SERVICES=false 是安全默认值：PostgreSQL 和 Redis 必须使用本地地址，
AI 必须使用 mock、存储必须使用 minio，且远程服务凭据必须留空。只有明确需要
直连 dev 数据库、Redis、AI、OSS、短信或微信服务时，才将它设为 true；这些调用
可能修改共享数据、发送短信、产生费用或向 dev OSS 写入文件。
只有确定要删除完整本地副本和 Redis 时才运行 pnpm infra:reset；该命令会删除
命名卷。已有的 flowers-postgres:5432 和 redis:6379 不属于本项目的专用
Compose 环境，不应修改或删除。
- 提交 API/Web 代码和 Prisma migration，由 dev 部署流程执行
prisma migrate deploy。 - 素材、字典等确需发布的数据必须写成幂等、可审查的数据脚本。
- 本地用户、帖子、作品、测试账号和数据库 dump 永远不得整体恢复到 dev。
src/
├─ main.ts # 入口：全局前缀 api、校验管道、Swagger、CORS
├─ app.module.ts # 根模块：装配 Config/Prisma/Storage + 各业务模块
├─ app.controller.ts # 健康检查
├─ config/ # 环境变量加载与校验
├─ common/ # 守卫 / 装饰器 / 拦截器 / 过滤器 / 通用 DTO
├─ prisma/ # PrismaModule + PrismaService
├─ storage/ # 存储适配层（OSS / 本地 data URL）
├─ wechat/ # 微信内容安全审核（供广场）
└─ modules/
├─ auth/ # 微信登录 + JWT (P1)
├─ users/ # 用户资料 (P2)
├─ works/ # 作品 + 创作日历 (P3)
├─ ai/ # image2 / cutout 任务 (P5)
├─ upload/ # 图片上传 (P5)
├─ materials/ # 自定义花材 (P6)
└─ plaza/ # 分享广场 + 内容审核 (P4)
prisma/schema.prisma # 数据模型
compose.yaml # 本地 PostgreSQL / Redis
| 阶段 | 内容 |
|---|---|
| P0 ✅ | 脚手架：工程骨架 + 模块结构 + 基础设施 |
| P1 | 微信 code2session + JWT + 全局守卫 |
| P2 | 用户资料 GET/PATCH /users/me |
| P3 | 作品 CRUD + 日历聚合 |
| P5 | AiProvider(中转站) + BullMQ + OSS + image2/cutout |
| P6 | 自定义花材 |
| P4 | 广场 + 微信内容审核 |
| P7 | 限流 / 日志 / 部署加固 |
pnpm start:dev # 开发（热重载）
pnpm build # 编译
pnpm lint # 代码检查
pnpm test # 单测
pnpm prisma:studio # 可视化查看数据库
pnpm infra:down # 停止本地基础设施，保留数据卷