doodle-store/README.md

Doodle Store

独立于 doodle-mini 的 pnpm Monorepo，用于维护统一业务后端、后续管理后台和用户 Web 网站。小程序源码与 CloudBase 兼容函数仍在 doodle-mini，两个项目通过 HTTPS API 协作。

当前范围

当前已完成基础工程、本地数据库、小程序登录鉴权及分类服务：

• apps/server：可运行的 NestJS 服务，已接入日志、中间件、Swagger、微信静默登录、JWT 与真实账户检查，提供本人摘要、分类查询/管理、题型列表/详情与组合筛选和数据库就绪接口。
• packages/contracts：公开响应、登录请求/结果、本人摘要、分类与安全错误类型，不包含数据库模型或私有实现。
• packages/asset-sync：本地云存储备份同步七牛的独立 Node.js 工具，支持预演、校验、重试，头像与其他资源共用公开空间。
• apps/admin、apps/web：仅预留目录与说明，尚未选择或安装前端框架。
• 本地 PostgreSQL 18.6 Docker 开发环境已启动，13 张表及初始配置已创建，并于 2026-10-15 与最新 SQL 复核一致；Prisma 与微信登录已接入，七牛、其他业务及生产部署待实施。

本地使用

先按 本地数据库说明 配置根 .env，执行 pnpm infra:up。默认数据库地址为 127.0.0.1:5434，开发库为 doodle_dev。图片等资源直接使用七牛，本地仅启动 PostgreSQL。生产与按需测试的安排见 v3.5 开发与部署环境方案。

使用 Node.js 24.20.0 与 pnpm 11.24.0。如使用 fnm，可在本目录执行 fnm use --install-if-missing。

pnpm install --frozen-lockfile
pnpm build
pnpm dev

默认地址为 http://127.0.0.1:8800/api/v1/health。该接口只证明服务进程可以处理 HTTP 请求，不代表数据库、文件存储或业务系统已经可用。

pnpm dev 在服务监听成功后显示完整 Swagger 地址（默认 http://127.0.0.1:8800/api-docs），并使用系统默认浏览器自动打开一次。热更新不会重复打开；关闭 Swagger 时不打开。链接按实际 HOST/PORT 生成，建议使用输出的 IP 地址，避免 localhost 解析到其他项目。

可在 apps/server/.env 中配置 PORT、HOST，变量示例见 apps/server/.env.example。未配置时使用安全的本地默认值。不要提交真实 .env 或密钥。

JWT_SECRET 必须配置为至少 32 字节的独立密钥，本机开发密钥已生成。Swagger 默认开发开启：http://127.0.0.1:8800/api-docs，生产未显式配置时关闭；其他设置与账户查询接入边界见 Server 基础设置。

微信小程序配置在 apps/server/.env 中填写 WECHAT_MINI_APP_ID 和 WECHAT_MINI_APP_SECRET。两项均为启动必填；DATABASE_URL 同样必须配置。真实 AppSecret 仅由服务端持有，不提交仓库。

pnpm check        # 格式、代码检查、类型检查、构建与测试
pnpm test:db      # 独立临时数据库中的登录/鉴权/分类测试，结束后清理
pnpm build        # 按工作区依赖顺序构建
pnpm start        # 运行已构建的服务端
pnpm format       # 格式化源码与配置

目录

apps/
  server/         NestJS 服务端
  admin/          后续管理后台，当前仅占位
  web/            后续用户网站，当前仅占位
packages/
  asset-sync/     云存储备份同步七牛的独立脚本
  contracts/      可公开的接口类型
deploy/           后续部署说明，当前未部署
infra/            本地 PostgreSQL Docker 配置
docs/             工程初始化与接入边界说明

每个实际应用与包声明自己的依赖。工作区内部使用 workspace:*，按应用独立构建、发布；不要求后台、网站与 API 同时上线。暂不引入 Turborepo、Nx、Redis、队列或微服务。

数据库模型、密钥和未来私有生成/绘制逻辑只能由服务端持有，不能放进公共契约包供前端导入。小程序不直接依赖本仓库源码或本地工作区包。

登录请求、恢复错误码、数据库基线及联调边界见 服务端登录接入说明。

分类公开/管理 API、本地导入工具及本批 6 条分类的导入结果见 分类接口与数据导入。

51 条旧题型数据已导入本地库，预览文件仍待迁移；导入工具、异常年级和计数对账见 题型数据导入说明。

题型查询支持分类、审核年级、年龄段、Tag、最新/热门、运营标记和分页，见 题型查询接口说明。

现有功能迁移的权威方案见 docs/云服务端迁移方案.md，小程序产品规划与历史设计仍保留在 doodle-mini。本仓库的初始化说明见 docs/初始化说明.md。

云存储备份同步七牛

独立脚本项目位于 packages/asset-sync，配置入口为该目录的 .env，已填写本地 cloud_backup 源目录。pnpm assets:sync 默认只预演；填写七牛 AK/SK 与 bucket 后，使用 pnpm assets:sync --apply --only assets/previews 同步题型预览。支持保留相对路径、同内容跳过、冲突保护、有限重试和报告；头像与其他资源共用 QINIU_BUCKET 公开空间。该工具不修改业务数据库或自动替换旧 cloud 引用。