joey5628/doodle-store
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
R524809
2026-10-19 13:17:51 +08:00
parent 8827110f2f
commit d30cf25890
148 changed files with 13287 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/server/.agents/skills/prisma-postgres-setup/SKILL.md
+47
View File
@@ -0,0 +1,47 @@
---
name: prisma-postgres-setup
description: Obtain or reuse a Prisma Postgres database and connect an application. Use when the user needs a database and has none configured ("I need a database", "add a Postgres database", "set up a database for this app"), runs or mentions `create-db` or `npx create-db`, or asks to set up or connect Prisma Postgres, including in v0 and the Vercel Marketplace. Hands Prisma ORM configuration to prisma-orm-setup; reuses an existing connection first and honors an explicit provider, driver, alternative ORM, or database-only choice.
license: MIT
metadata:
author: prisma
version: "2.2.0"
---
# Prisma Postgres setup
Connect the intended database, then verify it from the application. Keep provisioning separate from ORM configuration so an existing database is reused.
## 1. Inspect the project
Check the user's requested ORM or driver, installed packages, database connection, and environment-loading files. Check secret presence without printing values.
- Honor explicit choices such as Drizzle, `pg`, or database-only setup.
- For query or schema work in an already configured app, use its version-matched ORM guidance; do not restart setup.
## 2. Reuse or obtain a database
| Situation | Action |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Existing connection or connected integration | Verify its project, database, and environment; reuse it. |
| v0, Vercel Marketplace, or a Vercel project | Read [Marketplace setup](references/vercel-marketplace.md) and use the native integration flow. |
| No database yet and no provider named | Offer `npx create-db@latest` for a working database now with no account (it is deleted after 24 hours unless claimed, and claiming needs a free Prisma account; read the create-db section in [provisioning](references/provisioning.md)), or a persistent database through [provisioning](references/provisioning.md). Ask which one when the request does not say. |
| Standalone persistent database | Read [provisioning](references/provisioning.md); use an authenticated CLI, MCP tool, Console, or Management API. |
| Temporary development database requested | Read the `create-db` section in [provisioning](references/provisioning.md), including expiry and claiming. |
Resolve the workspace, project, and region before creation. If several resources fit, ask which one to use. If provisioning is blocked by permissions or quota, report the blocker; do not delete another resource or switch workspaces to get around it.
## 3. Connect the application
Use the connection appropriate to the chosen driver and runtime. Store it in the project's secret environment configuration, never source code or chat. Preserve unrelated entries, update the intended variable once, and ensure local secret files are ignored by Git.
Application processes and CLI commands may load different environment files. For example, a framework may load `.env.development.local` while a shell command does not. A variable missing from the shell does not mean the database is missing: load the intended file for that command without displaying credentials, and do not provision another database.
## 4. Configure the ORM and verify
For Prisma ORM setup, read [prisma-orm-setup/SKILL.md](https://github.com/prisma/skills/blob/main/prisma-orm-setup/SKILL.md) directly, or load the installed `prisma-orm-setup` skill when the host resolves sibling skills by name. It owns ORM version selection and configuration. If that handoff is unavailable, report it.
For an explicitly selected alternative, keep that ORM or driver and use its documented setup. For database-only setup, stop after verifying connectivity.
Run a read-only query against the intended database through the application's chosen ORM or driver. Report what was connected, the selected ORM/version, and the query result without secrets. If any step is blocked or untested, say so instead of claiming setup is complete.
For Studio, SDK integrations, or database operations beyond initial setup, read [operations](references/operations.md).
apps/server/.agents/skills/prisma-postgres-setup/references/operations.md
+20
View File
@@ -0,0 +1,20 @@
# Console and programmatic operations
Read this only for work beyond connecting one application.
## Console and database operations
Use [Prisma Console](https://console.prisma.io) to inspect the selected project and open its database in Studio. Use links returned by the API or UI rather than constructing Console URLs from guessed ID formats.
For usage, backups, connections, or restoration, inspect current Platform CLI help or the [Management API schema](https://api.prisma.io/v1/doc). Resolve resource IDs before acting. Database deletion, restoration, and credential revocation are separate actions requiring the user's authorization; they are not routine setup steps.
## Management API SDK
Use `@prisma/management-api-sdk` for a typed API integration. Its installed types define current routes and request/response shapes independently of ORM versions.
- `createManagementApiClient({ token })` uses an existing token. Check HTTP errors before reading response data and follow pagination on collection routes.
- `createManagementApiSdk(...)` supports OAuth and token refresh. Implement persistent, protected token storage; do not copy a no-op storage example into an application.
- In the OAuth flow, persist and validate state and the verifier, handle the callback, and store refreshed tokens securely.
- Service-token and connection creation can return credentials once. Save them to the intended secret store without logging the response. Listing token metadata does not recover the original value.
For exact interfaces and a complete integration, use the [SDK documentation](https://www.prisma.io/docs/postgres/introduction/management-api-sdk) and installed package types. Keep ORM schema and migration work in the version-matched ORM skill.
apps/server/.agents/skills/prisma-postgres-setup/references/provisioning.md
+43
View File
@@ -0,0 +1,43 @@
# Standalone provisioning
First reuse an existing connection or resource. For v0 or Vercel Marketplace, use the [native integration flow](vercel-marketplace.md) instead.
## Persistent databases
Choose an available authenticated surface: Prisma Console, the Prisma Platform CLI, a connected Prisma MCP server, or the Management API. Reuse existing authentication; do not ask the user to paste tokens into chat.
- **Console:** select the intended workspace and project at [Prisma Console](https://console.prisma.io), then obtain the database's connection details.
- **Platform CLI:** inspect the current command help before mutation. The Platform commands ship in the Prisma 8 CLI (`prisma` 8, also published as `@prisma/cli`); the `postgres` group of a Prisma 7 `prisma` binary only links an existing database. Start with `npx -y @prisma/cli@latest postgres --help`; discover list, create, and connection commands from that version.
- **MCP:** discover available tools and their input schemas. Confirm the workspace and resource context before invoking a provisioning tool. Missing tools or authentication are blockers, not permission to switch accounts.
- **Management API:** use the [current schema](https://api.prisma.io/v1/doc) at `https://api.prisma.io/v1`, or installed SDK types, for exact endpoints and payloads. Do not copy an older project/database response shape blindly.
List available regions and select one consistent with the user's location requirements and application. Resolve the intended workspace, project, and, where required, branch before creating a database. Follow pagination when listing resources. If creation is asynchronous, poll the returned resource until ready with a bounded wait; report a timeout without creating a replacement. Before retrying an ambiguous creation request, check whether it succeeded to avoid duplicates.
Store returned connection credentials immediately in the intended secret environment. Some credentials are shown only once. Select the direct or pooled endpoint appropriate to the chosen driver and runtime; inspect the returned connection details instead of assuming every endpoint is interchangeable.
## Authentication and errors
For server-to-server API access, use a workspace service token from the user's secret environment. If one is needed, direct the user to Workspace Settings → Service Tokens in Console and have them store it locally or in their secret manager. Use the bearer token without logging it. For an integration acting on behalf of users, use OAuth instead; see [operations](operations.md).
| Failure | Response |
| ------------------------------------ | ---------------------------------------------------------------------------------------- |
| Authentication or permission denied | Explain which authentication or access is missing. |
| Resource not found | Verify the resource ID and workspace; do not create a replacement automatically. |
| Invalid request | Check the current schema and selected region. |
| Rate limit or transient read failure | Retry with bounded backoff, honoring retry guidance. |
| Quota exhausted | Report the limit and available options. |
## Temporary databases with create-db
Use `create-db` when the user needs a working database now and has no connection or Prisma account. By default, the database is available for **24 hours** and is automatically deleted if unclaimed. Claim it through the returned claim URL **before its expiry** to keep it; claiming requires a Prisma account. Use the returned expiry as the deadline if a different lifetime was selected. See the [documented lifecycle](https://www.prisma.io/docs/postgres/npx-create-db#claiming-your-database).
Inspect the current commands when selecting a region or a non-default lifetime:
```bash
npx create-db@latest create --help
npx create-db@latest regions --help
```
Choose a supported region and lifetime. Store the connection string and claim URL privately, then tell the user when the database expires and how to claim it using the returned lifecycle information. Do not promise persistence until claiming is complete. Avoid flags that print credentials into shared output.
For programmatic provisioning, the `create-db` package exposes `create()` and `regions()`. Check the installed types, handle success and error results, and store returned connection/claim information without logging it. See the [create-db documentation](https://www.prisma.io/docs/postgres/npx-create-db).
apps/server/.agents/skills/prisma-postgres-setup/references/vercel-marketplace.md
+84
View File
@@ -0,0 +1,84 @@
# v0, Vercel CLI and Vercel Marketplace
Use the Prisma Postgres native integration so the database belongs to the user's Vercel team, is billed through Vercel, and is connected to the Vercel project. Unless the user asks for a database outside Vercel, do not substitute Prisma Console, the Prisma CLI, `create-db` or a Prisma MCP server: they create a database that Vercel does not bill, connect or rotate.
The integration slug is `prisma` and the product is `prisma/prisma-postgres`.
## 1. Reuse an existing resource
1. In the linked project, run `vercel integration list`. If a Prisma Postgres resource is connected, reuse it and go to step 3.
2. Run `vercel integration list --all` to see the team's resources that are not connected to this project. Connect one with `vercel integration resource connect <resource-name>`.
3. If several resources fit, ask the user which one to use.
## 2. Install and provision with the Vercel CLI
The project must be linked (`vercel link`). Read the current options before provisioning; do not guess metadata or plan IDs:
```bash
vercel integration add prisma --help
vercel integration add prisma/prisma-postgres --name <resource-name>
```
- In a non-interactive shell, pass the `region` metadata (`-m region=<value>`, values from `--help`) and `--plan`. The plan IDs are `free`, `starter`, `pro` and `business`. Use `free` unless the user chose a paid plan: a paid plan bills the user's Vercel account, so ask first.
- If Prisma is not yet installed on the team, the CLI asks the user to accept the integration's terms in the browser and waits. An agent cannot complete this step. Ask the user to accept, then let the command continue.
- By default the command connects the resource to the linked project's `production`, `preview` and `development` environments, then runs `vercel env pull`, which writes `.env.local`.
- One resource on all three environments means local development, previews and production share one database. Tell the user. If they want separate data, provision one resource per environment with `-e <environment>`, and connect only one Prisma resource to each environment.
In v0, use the host's native integration flow instead. It may appear as an integration request tool; discover what the host exposes instead of assuming a fixed tool name, then wait for the connection and its environment variables.
## 3. Environment variables
Connecting a resource sets these variables on each connected environment:
| Variable | Value | Use |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| `DATABASE_URL` | `postgres://<user>:<key>@db.prisma.io:5432/postgres?sslmode=require` | The application and Prisma CLI commands |
| `POSTGRES_URL` | The same value as `DATABASE_URL` | Libraries that read `POSTGRES_URL` |
| `PRISMA_DATABASE_URL` | The same value on resources created now. On older resources it can be a `prisma+postgres://accelerate.prisma-data.net/...` URL | Do not use in new code; use `DATABASE_URL` |
- With `--prefix`, each name gets the prefix as-is (`--prefix DB2_` gives `DB2_DATABASE_URL`). Read the prefixed name.
- Never print the values. `vercel env ls <environment>` lists names without values.
- `db.prisma.io` is the direct endpoint. It works for the application, migrations and Prisma Studio, so setup needs nothing else. Direct connections are capped low: 10 on Free and Starter, 5 of them reserved for the platform. Before production load from Vercel Functions, tell the user that application traffic should use the pooled endpoint (`pooled.db.prisma.io`), whose connection string Prisma Console shows for the database; `vercel integration open prisma` signs the user in. Do not overwrite the integration's variables: add the pooled string under a new name with `vercel env add`, keep `DATABASE_URL` for migrations, and switch the runtime client only if the user agrees.
## 4. First successful request
1. Make the variables available locally: `vercel env pull`, or run each command with `vercel env run -- <command>` to keep secrets off disk.
2. Return to `prisma-postgres-setup` step 4 to configure the chosen ORM or driver. Prisma ORM configuration belongs to `prisma-orm-setup`.
3. Run one read-only query (for example `SELECT 1`) through the application's ORM or driver against the connected database.
4. Deploy. Environment variable changes apply only to new deployments, so redeploy after connecting a resource, then call a route that queries the database.
## 5. Validate and report
- `vercel integration list` shows the resource, its status and the connected project.
- `vercel env ls production` lists `DATABASE_URL`.
- The local query and the deployed query both succeed.
Report the resource name, the environments it is connected to, the variable the application reads, and the query result, without secrets. If a step was blocked or not tested, say so.
## Plans, billing and backups
- Usage and invoices are on the user's Vercel bill. Changing the plan is the user's decision; do not do it on your own.
- The user can change plans in Prisma Console (`vercel integration open prisma`) or in the Vercel dashboard: **Integrations → Prisma → Manage → Settings → Change Plan**.
- Restorable daily backups come with paid plans. On Free, treat the connected database as having no backup.
## Common errors
| What you see | Cause | Fix |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The CLI asks the user to review and accept terms in the browser | Prisma is not installed on the team yet | Ask the user to accept. The agent cannot do it. |
| Connecting fails with an error that names an existing variable, project and environments | The project already has a variable such as `DATABASE_URL` | Ask the user. Remove the stale variable with `vercel env rm <name> <environment>`, or connect with `--prefix` and read the prefixed name. |
| A Prisma CLI command reports `DATABASE_URL` missing, but the app runs | The command does not load `.env.local` | Run it as `vercel env run -- <command>`, or load the intended file for that command. Do not provision another database. |
| `PRISMA_DATABASE_URL` starts with `prisma+postgres://accelerate.prisma-data.net` | An older resource still carries an Accelerate URL in that variable | Read `DATABASE_URL`, which holds a standard `postgres://` string. |
| Works locally; the deployment has no `DATABASE_URL` or old credentials | The deployment predates the connection or a secret rotation | Check `vercel env ls <environment>` and that the resource is connected to that environment, then redeploy. |
| "Too many connections" or connection-limit errors under load | Application traffic on the direct endpoint, or a client created per request | Create the database client once, outside the request handler. Move application traffic to the pooled endpoint (section 3). |
| Data is gone after a schema diff or reset | A shadow database or reset command ran against the connected database | Never point a shadow database URL or a reset command at the connected database; use a separate throwaway database. Restoring needs a paid plan's backup. |
## Where MCP fits
When native Marketplace MCP tools are available, inspect their descriptions, permissions, and resource scope before use. Use them for supported operations on the selected resource. Keep schema changes consistent with the application's migration workflow.
A general Prisma MCP provisioning tool creates a Prisma resource; that alone does not establish Marketplace registration, billing, project connection, or environment injection. Do not substitute it for a blocked native installation. Report the missing connection or permission.
The agent calls MCP tools while building the app. The generated app connects through its ORM or database driver; it does not need to call MCP for normal database queries.
Sources: [vercel integration](https://vercel.com/docs/cli/integration), [vercel env](https://vercel.com/docs/cli/env), [coding agents and Marketplace integrations](https://vercel.com/kb/guide/using-coding-agents-to-procure-vercel-marketplace-integrations), [Prisma Postgres on Vercel](https://www.prisma.io/docs/guides/postgres/vercel), [connection pooling](https://www.prisma.io/docs/postgres/database/connection-pooling), [v0 databases](https://v0.app/docs/databases), [v0 MCP](https://v0.app/docs/MCP), [Vercel native integrations](https://vercel.com/docs/integrations/create-integration/native-integration).