feat: 完成现有小程序接口的全部迁移至新后端

2026-10-19 13:17:51 +08:00
parent 8827110f2f
commit d30cf25890
148 changed files with 13287 additions and 34 deletions
@@ -0,0 +1,86 @@
+# decision-stay-or-migrate
+
+How to decide between migrating a MongoDB project to Prisma 8 and staying on Prisma v6.
+
+## Priority
+
+CRITICAL
+
+## Why It Matters
+
+MongoDB projects cannot follow the general "upgrade Prisma" advice: Prisma 7 has no MongoDB
+connector, so the forward path is Prisma 8. Advising an impossible v7 upgrade, or
+silently rewriting the app onto SQL, are both serious failure modes. The encouraged path is
+migrating to Prisma 8 — its MongoDB support is Early Access and the Prisma team wants
+early adopters' feedback — with a deliberate stay on v6 where a hard blocker applies.
+
+## The facts the decision rests on
+
+Prisma 8 side ([supported databases](https://www.prisma.io/docs/orm/supported-databases),
+[6 to 8 MongoDB guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb)):
+
+- **MongoDB support is Early Access** in `@prisma/orm-mongo`; PostgreSQL is a release
+  candidate.
+- The implementation is not a stub: an ORM client, a typed aggregation-pipeline builder, a
+  raw lane, and first-class contract-driven migrations.
+- **Prisma 8 has no MongoDB transaction method yet** — there is no `db.transaction(...)` on
+  the MongoDB client. Multi-document atomicity uses the `mongodb` driver's session API on a
+  replica set. This skill will be updated when a transaction method ships.
+- Early Access means MongoDB behavior can change between release candidates. Floor:
+  Node.js 22.18+, TypeScript 5.9+, MongoDB 8.0+, and `mongodb@7`.
+
+Prisma v6 side:
+
+- v6 fully supports MongoDB, including transactions on replica sets — "MongoDB only allows
+  you to start a transaction on a replica set. Prisma ORM uses transactions internally"
+  ([replica set configuration](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration)).
+- v6 MongoDB has no Prisma Migrate; the workflow is `db push`
+  ([no support for Prisma Migrate](https://www.prisma.io/docs/orm/overview/databases/mongodb#no-support-for-prisma-migrate)).
+
+## Blocker checks before migrating
+
+Run these checks yourself — from the codebase, not by asking the user:
+
+- **Search the codebase for `$transaction` usage** (grep for `$transaction`). If present,
+  plan the raw-driver session equivalents before migrating (see `client-api-mapping.md`) —
+  or stay on v6 until Prisma 8 adds a MongoDB transaction method.
+- **Check the MongoDB server version** (must be 8.0+ for Prisma 8; v6 tolerated older).
+- **Confirm the team can absorb changes between release candidates.** Someone has to
+  follow the release notes and update the code. For a production app, confirm the user accepts
+  Early Access status before migrating.
+
+## Bad
+
+```text
+User: "We're on Prisma 6 with MongoDB. Should we upgrade to Prisma 7?"
+Agent: "Yes — here's the v7 upgrade guide. Step 1: install a driver adapter..."
+```
+
+Prisma 7 has no MongoDB connector; this migration is impossible and the SQL driver-adapter
+steps corrupt a working v6 setup.
+
+## Good
+
+```text
+User: "We're on Prisma 6 with MongoDB. Should we upgrade to Prisma 7?"
+Agent: "Prisma 7 does not support MongoDB — v6 is the last classic-ORM
+major for MongoDB. The path forward is Prisma 8, the successor: its MongoDB support is
+Early Access and migrating is encouraged. Let me check the codebase for blockers first —
+searching for $transaction usage and checking the MongoDB server version..."
+```
+
+## Stay-on-v6 hygiene
+
+Staying is a decision, not a default-by-neglect:
+
+- Pin `prisma` and `@prisma/client` to the latest 6.x and keep taking 6.x patches.
+- Watch Prisma release notes and security advisories for the 6.x maintenance line.
+- Keep the classic setup (`url = env("DATABASE_URL")` in the schema; `db push`; no SQL
+  driver adapters).
+- Re-evaluate when Prisma 8's MongoDB support leaves Early Access, or when the blockers are resolved.
+
+## References
+
+- [Prisma ORM 6 to 8 (MongoDB) guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb)
+- [Prisma 8 supported databases](https://www.prisma.io/docs/orm/supported-databases)
+- [Prisma v6 MongoDB documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb)