客户

在 Dashboard > Commerce > Customers 标签页中或通过 SDK 管理应用的计费用户。

客户是应用中被收费的实体——通常是某个用户、组织或项目。当对应实体在你的数据库中创建时，应立即在 Proyecta 中创建一个客户，并保存返回的 id 以便后续引用。

Customers 标签页

打开 Dashboard > Commerce，切换到 Customers 标签页，即可查看当前应用的所有计费客户。每一行显示：

邮箱
全名
创建时间

可通过 SDK 使用搜索框并按邮箱或创建日期筛选；面板中更丰富的控制功能即将推出。

SDK

import Proyecta from '@proyecta-ai/sdk';
const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

创建

const customer = await proyecta.commerce.customers.create({
    email: 'alice@example.com',
    name: 'Alice Liddell',
    phone: '+14155551234', // E.164 format
    address: {
        line1: '123 Wonderland Ave',
        city: 'San Francisco',
        state: 'CA',
        postal_code: '94110',
        country: 'US',
    },
});

读取

// Single customer
const customer = await proyecta.commerce.customers.get({ customerId: 'cus_123' });

// Paginate
const result = await proyecta.commerce.customers.list({ limit: '20' });
for (const customer of result.data) {
    console.log(customer.name, customer.email);
}

更新

await proyecta.commerce.customers.update({ customerId: 'cus_123', email: 'new@example.com', address: { ... } });

常见用法

用户注册时创建 Proyecta 客户

When a new user finishes signup, call proyecta.commerce.customers.create
with their email and name. Store the returned id on the user record as
proyecta_customer_id.

构建管理员客户浏览页

Build an admin page at /admin/customers that lists every Proyecta customer
with their email, name, created date, and a link to view their detail page.
Use proyecta.commerce.customers.list to paginate through all customers.

常见问题

我应该为每个用户创建 Proyecta 客户，还是只为付费用户创建？

为每个用户都创建。这是免费的，且具有幂等性（使用相同邮箱调用会返回同一个客户），这样当用户升级时你已随时准备好——无需事后补录数据。

一个客户可以拥有多个订阅吗？

可以。订阅归属于客户，而非相反。使用 commerce.checkout() 创建新的订阅结账会话。

如何查看客户订阅了哪些内容？

目前：通过嵌入的 Stripe 控制台，或针对你关心的每个功能调用 commerce.check()。面板中的订阅历史视图已在路线图中。