create-bubbles 0.1.25 → 0.1.26

package/template-vp-monorepo-react-nestjs/AGENTS.md

@@ -1,16 +1,12 @@
-<!--VITE PLUS START-->
+## 目录说明
 
-# Using Vite+, the Unified Toolchain for the Web
+- 修改文件前，须从文件所在目录逐级向上查找并阅读相关的 `AGENTS.md`（如存在），并遵循其中的说明。
 
-This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, and it invokes Vite through `vp dev` and `vp build`. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
+## 按需规则
 
-Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.dev/guide/.
+根据当前任务匹配下表，在执行相关操作前读取对应规则；命中多项时分别读取。不要预先加载整个 `.agents/rules/` 目录；任务范围变化时补读新命中的规则。
 
-## Review Checklist
-
-- [ ] Run `vp install` after pulling remote changes and before getting started.
-- [ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
-- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
-- [ ] If setup, runtime, or package-manager behavior looks wrong, run `vp env doctor` and include its output when asking for help.
-
-<!--VITE PLUS END-->
+| 适用条件                                                       | 规则文件                              |
+| -------------------------------------------------------------- | ------------------------------------- |
+| 新增、修改或重构前后端代码                                     | [代码设计](.agents/rules/代码设计.md) |
+| 定义或调整前后端接口类型、返回类型，或新增、修改、抽取公用方法 | [共享代码](.agents/rules/共享代码.md) |

package/template-vp-monorepo-react-nestjs/apps/server/.agents/rules/error-handling.md

@@ -0,0 +1,84 @@
+# Server 错误处理规则
+
+本规则供 AI 修改 `apps/server` 时执行。
+
+## 默认策略
+
+如果客户端不需要特定错误码、文案或 HTTP 状态：
+
+- 不要 `catch`。
+- 不要手动包装成 `AppException`。
+- 让异常直接向上冒泡。
+- 由 `GlobalExceptionFilter` 统一记录日志并返回 `COMMON.INTERNAL_SERVER_ERROR` 和 HTTP 500。
+
+```ts
+// 正确：没有特殊输出要求，直接交给全局异常过滤器
+const user = await this.userRepository.findById(userId)
+```
+
+本项目实际使用的是全局异常过滤器 `GlobalExceptionFilter`，业务代码不要重复实现统一错误响应。
+
+## 什么时候使用 AppException
+
+只有以下情况使用 `AppException`：
+
+1. 客户端需要识别明确的业务错误，例如账号已存在、登录失效、资源不存在。
+2. 外部依赖失败必须明确返回模块级 HTTP 503。
+3. 需要返回安全的字段错误 `details`。
+
+```ts
+if (!user) {
+  throw new AppException(USER_ERRORS.NOT_FOUND)
+}
+```
+
+模块错误定义在对应的 `*.errors.ts`：
+
+```ts
+export const USER_ERRORS = {
+  NOT_FOUND: {
+    code: 'USER.NOT_FOUND',
+    publicMessage: '用户不存在',
+    status: HttpStatus.NOT_FOUND,
+  },
+} as const satisfies Record<string, AppErrorDefinition>
+```
+
+错误码必须全局唯一、采用大写 `模块.错误名称` 格式。公开文案不得包含堆栈、SQL、Redis 数据、连接信息、令牌或底层错误文本。HTTP 401 必须设置 `bearerChallenge: true`。
+
+## 基础设施错误
+
+默认让数据库、Redis 和第三方 SDK 的未知异常交给全局过滤器处理。
+
+只有明确要求返回模块级 503 时，才在最接近依赖的边界转换一次：
+
+```ts
+try {
+  return await operation()
+} catch (cause: unknown) {
+  if (cause instanceof AppException) {
+    throw cause
+  }
+
+  throw new AppException(USER_ERRORS.SERVICE_UNAVAILABLE, { cause })
+}
+```
+
+不要：
+
+- 在每个数据库或 Redis 调用后添加 `.catch()`。
+- 外层已经转换错误，内层再次包装。
+- 捕获后只记录日志再抛出；全局过滤器已负责 5xx 日志。
+- 把整个业务流程包装成 503，导致程序错误被伪装成服务不可用。
+
+`catch` 仅用于错误语义转换、事务回滚、资源清理、重试或明确降级。
+
+## 相关文件
+
+- `src/common/exceptions/app.exception.ts`：`AppException`。
+- `src/common/error/common.error.ts`：公共错误。
+- `src/modules/*/*.errors.ts`：模块错误。
+- `src/common/filters/global-exception.filter.ts`：统一异常处理。
+- `test/error-catalog.spec.ts`：错误码校验。
+
+新增错误目录后，将其加入 `error-catalog.spec.ts`，然后运行 `vp check`、`vp test` 和 `vp run build`。如果检查被无关的既有问题阻塞，只报告问题，不要擅自批量修改无关文件。

package/template-vp-monorepo-react-nestjs/apps/server/.env.development

@@ -23,3 +23,63 @@ REDIS_DB=0
 SESSION_TOKEN_PEPPER=EfN6+CbfvlXkxp9SeTkFpziHPtr0/krxZItsjqUCc7AnbH9cmnDXNSFeNpa78Z42
 SESSION_IDLE_TTL_SECONDS=7200
 SESSION_ABSOLUTE_TTL_SECONDS=604800
+
+
+#MINIO
+STORAGE_ENDPOINT=http://127.0.0.1:9000
+STORAGE_REGION=us-east-1
+STORAGE_ACCESS_KEY_ID=minio
+STORAGE_SECRET_ACCESS_KEY=minio123456
+STORAGE_BUCKET=uploads
+
+# ==================== BullMQ 基础连接 ====================
+
+# BullMQ 使用的 Redis 主机地址；本地开发通常为 localhost
+QUEUE_REDIS_HOST=localhost
+# Redis 服务端口；Redis 默认端口为 6379
+QUEUE_REDIS_PORT=6379
+# Redis ACL 用户名；留空表示使用 Redis 的 default 用户
+QUEUE_REDIS_USERNAME=
+# Redis 密码；生产环境应通过安全方式注入，不要提交真实密码
+QUEUE_REDIS_PASSWORD=ml
+# Redis 逻辑数据库编号；使用 DB 1，避免与默认 DB 0 的数据混在一起
+QUEUE_REDIS_DB=1
+# BullMQ 在 Redis 中创建键时使用的统一前缀
+# 用于区分不同项目和环境，例如开发、测试、生产环境
+QUEUE_PREFIX=bubbles:development:queue
+
+
+# ==================== Worker 开关 ====================
+
+# 当前 NestJS 进程是否启动 BullMQ Worker 并消费任务
+# true：既可以投递任务，也会执行任务
+# false：只投递任务，不在当前进程中执行任务
+QUEUE_WORKER_ENABLED=true
+
+
+# ==================== 默认任务策略 ====================
+
+# 单个任务最多尝试执行的总次数
+# 3 表示首次执行失败后最多再重试 2 次，共执行最多 3 次
+QUEUE_DEFAULT_ATTEMPTS=3
+
+# 任务失败后的重试退避基础延迟，单位为毫秒
+# 1000 表示基础延迟为 1 秒
+# 实际是固定延迟还是指数递增，取决于代码中的 backoff 类型配置
+QUEUE_BACKOFF_DELAY_MS=1000
+
+# 已完成任务记录的最长保留时间，单位为秒
+# 86400 秒等于 24 小时，超过后可从 Redis 中清理
+QUEUE_COMPLETED_AGE_SECONDS=86400
+
+# Redis 中最多保留的已完成任务记录数量
+# 即使任务未超过保留时间，也只保留最近约 1000 条
+QUEUE_COMPLETED_COUNT=1000
+
+# 失败任务记录的最长保留时间，单位为秒
+# 604800 秒等于 7 天，便于排查近期失败原因
+QUEUE_FAILED_AGE_SECONDS=604800
+
+# Redis 中最多保留的失败任务记录数量
+# 防止失败记录持续累积，占用过多 Redis 内存
+QUEUE_FAILED_COUNT=5000

package/template-vp-monorepo-react-nestjs/apps/server/.env.production

@@ -18,3 +18,19 @@ REDIS_HOST=localhost
 REDIS_PORT=6379
 REDIS_PASSWORD=ml
 REDIS_DB=0
+
+# BullMQ 队列
+# 下面两个 YOUR_... 都只是占位值，必须由部署配置或 Secret 替换
+QUEUE_REDIS_HOST=YOUR_QUEUE_REDIS_HOST
+QUEUE_REDIS_PORT=6379
+QUEUE_REDIS_USERNAME=
+QUEUE_REDIS_PASSWORD=YOUR_PRODUCTION_QUEUE_REDIS_PASSWORD
+QUEUE_REDIS_DB=0
+QUEUE_PREFIX=bubbles:production:queue
+QUEUE_WORKER_ENABLED=true
+QUEUE_DEFAULT_ATTEMPTS=3
+QUEUE_BACKOFF_DELAY_MS=1000
+QUEUE_COMPLETED_AGE_SECONDS=86400
+QUEUE_COMPLETED_COUNT=1000
+QUEUE_FAILED_AGE_SECONDS=604800
+QUEUE_FAILED_COUNT=5000

package/template-vp-monorepo-react-nestjs/apps/server/AGENTS.md

@@ -0,0 +1,9 @@
+# Server
+
+## 开发规范
+
+关于错误定义、异常抛出、`catch` 边界和全局异常处理，请阅读 [Server 错误处理规则](./.agents/rules/error-handling.md)。
+
+## 变更说明
+
+- 用户主要从事前端开发。每次完成更改后，须在回复末尾说明本次改动涉及的重要知识点，尤其是后端知识和常见面试问题。

package/template-vp-monorepo-react-nestjs/apps/server/drizzle/0000_military_colonel_america.sql

@@ -0,0 +1,11 @@
+CREATE TYPE "public"."user_status" AS ENUM('active', 'locked', 'disabled');--> statement-breakpoint
+CREATE TABLE "users" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" varchar(100) NOT NULL,
+	"account" varchar(32) NOT NULL,
+	"password_hash" varchar(255) NOT NULL,
+	"status" "user_status" DEFAULT 'active' NOT NULL,
+	"create_at" timestamp DEFAULT now() NOT NULL,
+	"update_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "users_account_unique" UNIQUE("account")
+);

package/template-vp-monorepo-react-nestjs/apps/server/drizzle/0001_loud_siren.sql

@@ -0,0 +1,27 @@
+CREATE TYPE "public"."upload_status" AS ENUM('uploading', 'completing', 'completed', 'aborting', 'aborted', 'expired');--> statement-breakpoint
+CREATE TABLE "upload_sessions" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"owner_id" uuid NOT NULL,
+	"client_upload_id" uuid NOT NULL,
+	"bucket" varchar(63) NOT NULL,
+	"object_key" varchar(1024) NOT NULL,
+	"storage_upload_id" text NOT NULL,
+	"original_name" varchar(255) NOT NULL,
+	"content_type" varchar(255) NOT NULL,
+	"file_size" bigint NOT NULL,
+	"part_size" integer NOT NULL,
+	"total_parts" integer NOT NULL,
+	"status" "upload_status" DEFAULT 'uploading' NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"object_etag" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"completed_at" timestamp with time zone
+);
+--> statement-breakpoint
+ALTER TABLE "upload_sessions" ADD CONSTRAINT "upload_sessions_owner_id_users_id_fk" FOREIGN KEY ("owner_id") REFERENCES "public"."users"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "upload_sessions_owner_client_uq" ON "upload_sessions" USING btree ("owner_id","client_upload_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "upload_sessions_bucket_key_uq" ON "upload_sessions" USING btree ("bucket","object_key");--> statement-breakpoint
+CREATE INDEX "upload_sessions_owner_status_expires_idx" ON "upload_sessions" USING btree ("owner_id","status","expires_at");--> statement-breakpoint
+CREATE INDEX "upload_sessions_status_expires_idx" ON "upload_sessions" USING btree ("status","expires_at");--> statement-breakpoint
+CREATE INDEX "upload_sessions_status_updated_idx" ON "upload_sessions" USING btree ("status","updated_at");

package/template-vp-monorepo-react-nestjs/apps/server/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,97 @@
+{
+  "id": "4efaf73b-a515-4481-80da-b95ba325bf9f",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.users": {
+      "name": "users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "name": {
+          "name": "name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "account": {
+          "name": "account",
+          "type": "varchar(32)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "user_status",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'active'"
+        },
+        "create_at": {
+          "name": "create_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "update_at": {
+          "name": "update_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "users_account_unique": {
+          "name": "users_account_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "account"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {
+    "public.user_status": {
+      "name": "user_status",
+      "schema": "public",
+      "values": [
+        "active",
+        "locked",
+        "disabled"
+      ]
+    }
+  },
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}