前后端与数据库命名规范

这份文档是 Taria Pay 当前唯一有效的命名规范，覆盖：

Dashboard 展示文案
前端页面、路由、TypeScript 类型
后端领域对象、接口字段
数据库表名与列名
历史旧名到新名的改名对照

目的只有一个：同一个概念在前端、后端、数据库里尽量只保留一套 canonical 名称，减少排查、联表、沟通和文档维护时的歧义。

1. 总原则

1.1 展示文案

面向商户、运营、客服的展示文案，统一使用清晰的业务名：

Payment ID
商户订单号
金额
稳定币币种
来源
交易哈希
支付状态
创建时间
支付时间
更新时间

1.2 前端 / 后端代码字段

前后端代码中的字段统一使用 camelCase：

paymentId
orderId
sourceType
txHash
paymentRecordId

1.3 数据库列名

数据库列统一使用 snake_case：

payment_id
order_id
source_type
tx_hash
payment_record_id

1.4 文档中的 `table.column`

像 payment_intents.source_type 这种写法，只表示“表名 + 列名”的完整引用。

它的意思是：

表：payment_intents
列：source_type

不是说列名要叫 payment_intents_source_type。

2. 业务对象命名

中文对象名	英文概念	前端页面模块	后端领域类型	数据库表	主键
支付订单	Payment Intent	`IntentsPage`	`MerchantPaymentIntent`	`payment_intents`	`payment_id`
支付记录	Payment Record	`/transactions`、`/overview` 交易聚合	`PaymentRecord`	`payments`	`payment_record_id`
收款链接	Paylink	`PaylinksPage`	`MerchantPaymentLink`	`payment_links`	`id`
订阅计划	Subscription Plan	`SubscriptionsPage`	`MerchantSubscriptionPlan`	`merchant_subscription_plans`	`id`
发票	Invoice	`InvoicesPage`	预留	暂未落库	暂无

说明：

“支付订单”是业务主对象，唯一标识是 payment_id
“支付记录”是链上支付落库对象，唯一标识是 payment_record_id
payments.payment_id 只是指向支付订单的关联字段，不是支付记录自己的主键

3. 页面、模块与路由命名

3.1 Dashboard 页面模块

场景	规范命名	文件
支付订单页	`IntentsPage`	`frontend/dash/src/pages/payments/IntentsPage.tsx`
收款链接页	`PaylinksPage`	`frontend/dash/src/pages/payments/PaylinksPage.tsx`
订阅计划页	`SubscriptionsPage`	`frontend/dash/src/pages/payments/SubscriptionsPage.tsx`
发票页	`InvoicesPage`	`frontend/dash/src/pages/payments/InvoicesPage.tsx`

3.2 Checkout 页面模块

场景	规范命名	文件
支付订单 checkout	`IntentsPage`	`frontend/dash/src/pages/checkout/IntentsPage.tsx`
Paylink checkout	`PaylinksPage`	`frontend/dash/src/pages/checkout/PaylinksPage.tsx`
订阅 checkout	`SubscriptionsPage`	`frontend/dash/src/pages/checkout/SubscriptionsPage.tsx`
发票 checkout	`InvoicesPage`	`frontend/dash/src/pages/checkout/InvoicesPage.tsx`

说明：

payments/* 和 checkout/* 允许出现同名 page module
在 App.tsx 中用 alias 区分 import
页面模块名统一用复数形式：IntentsPage、PaylinksPage、SubscriptionsPage、InvoicesPage

3.3 路由命名

业务对象	路由
支付订单列表	`/payment-intents`
收款链接列表	`/paylinks`
订阅计划列表	`/subscriptions`
发票列表	`/invoices`
支付订单 checkout	`/checkout/payment-intents/:paymentId`
Paylink checkout	`/paylink/:slug`
订阅 checkout	`/subscribe/:slug`
发票 checkout	`/invoice/:invoiceId`

4. 核心字段规范

4.1 通用字段

业务含义	Dashboard 文案	前端 / API 字段	后端领域字段	数据库列	备注
支付订单唯一标识	`Payment ID`	`paymentId`	`paymentId`	`payment_id`	支付订单主键
商户订单号	`商户订单号`	`orderId`	`orderId`	`order_id`	商户业务订单号
金额	`金额`	`amount`	`amount`	`amount`	面向商户的业务金额
原子单位金额	不默认展示	`amountMinor`	`amountMinor`	`amount_minor`	链上最小单位金额
稳定币币种	`稳定币币种`	`currency`	`currency`	`currency`	`USDC / USDT / EURC`
来源分类	`来源`	`sourceType`	`sourceType`	`source_type`	统一按来源分类
交易哈希	`交易哈希`	`txHash`	`txHash`	`tx_hash`	已上链后应唯一
支付状态	`支付状态`	`status`	`status`	`status`	订单和支付记录各自有状态机
创建时间	`创建时间`	`createdAt`	`createdAt`	`created_at`	交易聚合会做回退映射
支付时间	`支付时间`	`paidAt`	`paidAt`	`paid_at`	订单维度字段
更新时间	`更新时间`	`updatedAt`	`updatedAt`	`updated_at`	交易聚合会做回退映射
买家邮箱	`买家邮箱`	`customerEmail`	`customerEmail`	`customer_email`	可为空
买家姓名	`买家姓名`	`customerName`	`customerName`	`customer_name`	可为空
商户归属地址	不默认展示	`merchantRefAddress`	`merchantRefAddress`	`merchant_ref_address`	内部归属与匹配用
链上匹配哈希	不默认展示	`orderIdHash`	`orderIdHash`	`order_id_hash`	内部匹配用
链上支付记录 ID	不默认展示	`paymentRecordId`	`paymentRecordId`	`payment_record_id`	支付记录主键

4.2 交易聚合字段

/overview 与 /transactions 看到的是“交易聚合视图”，不是原始数据库单表。

这层当前有几个保留字段：

展示 / 聚合字段	前端字段	后端聚合字段	数据库来源	说明
客户	`customer`	`customer`	派生自 `customer_name / customer_email / payer_address`	这是展示字段，不是数据库原始列
网络	`network`	`network`	派生	当前由链配置推导，不直接落库
付款地址	`paymentAddress`	`paymentAddress`	`payments.payer_address`	交易详情字段
链上状态	`chainStatus`	`chainStatus`	`payments.chain_status`	交易详情字段
参考类型	`referenceType`	`referenceType`	聚合派生	当前用于兼容 invoice/subscription 视角
参考值	`reference`	`reference`	聚合派生	当前通常等于 `orderId`

说明：

这几个字段属于交易聚合层，不建议当作数据库 canonical 列名去理解
真正的数据库 canonical 名称仍以 payment_intents / payments 表为准

5. 状态命名

5.1 支付订单状态

对象：payment_intents.status

允许值：

requires_payment
processing
confirmed
failed
refunded
expired

5.2 支付记录状态

对象：payments.status

允许值：

pending
confirmed
reorged
failed
refunded

5.3 展示层统一 badge

Dashboard badge 文案可以统一，但数据库状态名不能混成一套。

统一显示规则：

requires_payment -> 待支付
processing / pending -> 确认中
confirmed -> 已确认
failed -> 失败
refunded -> 已退款
expired -> 已过期
reorged -> 链重组

6. 来源分类命名

支付类型分类统一只看 source_type。

允许值：

intent
paylink
subscription
invoice

对应含义：

intent：通过 API 创建的支付订单
paylink：收款链接支付
subscription：订阅支付
invoice：发票支付

以下名字不再是新的 canonical 值：

hosted
direct
payment_link

这些旧值只允许存在于兼容归一逻辑里。

7. 数据库表级规范

7.1 `public.payment_intents`

这是支付订单主表。

关键列：

payment_id
merchant_id
merchant_ref_address
order_id
order_id_hash
source_type
source_id
amount
amount_minor
currency
token_address
status
customer_email
customer_name
success_url
cancel_url
metadata
tx_hash
chain_status
paid_at
payment_record_id
expires_at
created_at
updated_at

语义：

payment_id 是支付订单主键
payment_record_id 是链上支付记录关联键
source_type 是支付来源分类

7.2 `public.payments`

这是链上支付记录表。

关键列：

payment_record_id
payment_id
payment_event_id
merchant_id
merchant_ref_address
order_id_hash
order_key
tx_hash
block_number
log_index
payer_address
token_address
amount_minor
confirmations
status
chain_status
detected_at
confirmed_at
updated_at

语义：

payment_record_id 是支付记录主键
payment_id 是关联到 payment_intents.payment_id
tx_hash 是链上交易哈希
order_key 是内部匹配键，不是对外订单号
detected_at 是支付记录首次被 listener 识别的时间

7.3 `public.payment_links`

这是收款链接主表。

关键列：

id
merchant_id
slug
merchant_ref_address
name
description
currencies
mode
amount
amount_minor
currency
lifecycle_status
success_url
cancel_url
collect_email
collect_name
checkout_title
button_label
expires_at
consumed_payment_id
created_at
updated_at

7.4 `public.merchant_subscription_plans`

这是订阅计划主表。

关键列遵循相同规则：

id
merchant_ref_address
amount
amount_minor
currency
status
success_url
cancel_url
created_at
updated_at

7.5 发票

发票目前前端页面已预留，但数据库主表还未作为正式 schema 定稿。

因此：

invoice 作为 source_type 已预留
发票页面模块已预留
数据库层不要擅自引入未审过的 invoice 主表命名

8. 已完成改名对照表

这张表记录已经完成、并且现在应该继续沿用的新命名。

旧命名	新命名	层级	说明
`HostedOrdersPage`	`IntentsPage`	前端页面模块	支付订单列表页
`PaymentIntentsPage`	`IntentsPage`	前端页面模块	payments 目录统一命名
`PayLinksPage`	`PaylinksPage`	前端页面模块	统一小写 `links` 语义
`StoredPayment`	`PaymentRecord`	后端领域类型	链上支付记录对象统一命名
`Transaction`	`PaymentRecordSummary`	前端聚合类型	交易页展示对象统一命名
`TransactionStatus`	`PaymentRecordStatus`	前端聚合类型	支付记录状态类型统一命名
`OverviewTransaction`	`PaymentRecordSummary`	后端聚合类型	overview / transactions 聚合对象统一命名
`DashboardTransactionRecord`	`DashboardPaymentRecordSummary`	前端 API 类型	dashboard 交易聚合对象统一命名
`IntentCheckoutPage`	`IntentsPage`	前端页面模块	checkout 目录统一命名
`PaylinkPage`	`PaylinksPage`	前端页面模块	checkout 目录统一命名
`SubscriptionPage`	`SubscriptionsPage`	前端页面模块	checkout 目录统一命名
`InvoicePage`	`InvoicesPage`	前端页面模块	checkout 目录统一命名
`订单支付`	`支付订单`	Dashboard 文案	避免动作感和资源名混淆
`Hosted Checkout`	`支付订单 checkout` / `payment intent checkout`	文案 / 文档	不再用 hosted 描述支付订单产品形态
`hosted-orders`	`/payment-intents`	路由 / 业务命名	不再用 hosted 作为业务对象名
`hosted`	`intent`	`sourceType` / `source_type`	旧来源值归一
`direct`	`intent`	`sourceType` / `source_type`	旧来源值归一
`payment_link`	`paylink`	`sourceType` / `source_type`	旧来源值归一
`hostedType`	`sourceType`	API / TS / metadata	来源分类统一用 `sourceType`
`coin`	`currency`	API / TS	稳定币币种字段统一命名
`externalOrderId`	`orderId`	API / TS	商户订单号统一命名
`external_order_id`	`order_id`	数据库	商户订单号统一命名
`merchantAddress`	`merchantRefAddress`	API / TS	商户归属地址统一命名
`merchant_address`	`merchant_ref_address`	数据库	商户归属地址统一命名
`chainPaymentId`	`paymentRecordId`	API / TS	链上支付记录 ID
`chain_payment_id`	`payment_record_id`	数据库	链上支付记录 ID
`paymentIntent.id`	`paymentIntent.paymentId`	SDK / 文档	Payment Intent 主键字段统一显式命名
`paymentIntentId`	`paymentId`	SDK / API 参数	路径参数与变量统一命名
`payment_intents.id`	`payment_intents.payment_id`	数据库	支付订单主键统一显式命名
`payments.id`	`payments.payment_record_id`	数据库	支付记录主键统一显式命名
`payments.payment_intent_id`	`payments.payment_id`	数据库	指向支付订单 ID 的关联列
`webhook_deliveries.payment_intent_id`	`webhook_deliveries.payment_id`	数据库	webhook 关联字段统一
`payment_links.consumed_intent_id`	`payment_links.consumed_payment_id`	数据库	Paylink 消费关联字段统一

9. 当前保留的内部字段

下面这些字段可以保留，但默认不作为对商户的主展示字段：

merchantRefAddress
orderIdHash
orderKey
paymentRecordId
paymentAddress
referenceType
reference

使用规则：

可以用于内部排障、联表、链上匹配
不要把它们拿来替代 orderId、paymentId、txHash
新页面默认不要优先展示这些字段

10. 未来新增字段的命名规则

后续新增字段时，必须遵守下面几条：

同一个概念先确定中文业务名，再确定 API 名，再确定数据库列名。
API / TS 一律用 camelCase。
数据库列一律用 snake_case。
如果只是来源分类，统一用 sourceType / source_type，不要再发明 kind、channel、hostedType 之类并行概念。
如果是订单主键，只能用 paymentId / payment_id。
如果是支付记录主键，只能用 paymentRecordId / payment_record_id。
如果是商户订单号，只能用 orderId / order_id。
如果只是文档里说明字段属于哪张表，可以写 table.column，但不要把表名前缀塞进列名本身。

11. 一句话总结

统一后的核心命名是：

支付订单主键：paymentId / payment_id
商户订单号：orderId / order_id
交易哈希：txHash / tx_hash
支付来源：sourceType / source_type
链上支付记录主键：paymentRecordId / payment_record_id

其余命名都应围绕这套基准扩展，不再引入第二套别名。

前后端与数据库命名规范 ​

1. 总原则 ​

1.1 展示文案 ​

1.2 前端 / 后端代码字段 ​

1.3 数据库列名 ​

1.4 文档中的 table.column ​

2. 业务对象命名 ​

3. 页面、模块与路由命名 ​

3.1 Dashboard 页面模块 ​

3.2 Checkout 页面模块 ​

3.3 路由命名 ​

4. 核心字段规范 ​

4.1 通用字段 ​

4.2 交易聚合字段 ​

5. 状态命名 ​

5.1 支付订单状态 ​

5.2 支付记录状态 ​

5.3 展示层统一 badge ​

6. 来源分类命名 ​

7. 数据库表级规范 ​

7.1 public.payment_intents ​

7.2 public.payments ​

7.3 public.payment_links ​

7.4 public.merchant_subscription_plans ​

7.5 发票 ​

8. 已完成改名对照表 ​

9. 当前保留的内部字段 ​

10. 未来新增字段的命名规则 ​

11. 一句话总结 ​

前后端与数据库命名规范

1. 总原则

1.1 展示文案

1.2 前端 / 后端代码字段

1.3 数据库列名

1.4 文档中的 `table.column`

2. 业务对象命名

3. 页面、模块与路由命名

3.1 Dashboard 页面模块

3.2 Checkout 页面模块

3.3 路由命名

4. 核心字段规范

4.1 通用字段

4.2 交易聚合字段

5. 状态命名

5.1 支付订单状态

5.2 支付记录状态

5.3 展示层统一 badge

6. 来源分类命名

7. 数据库表级规范

7.1 `public.payment_intents`

7.2 `public.payments`

7.3 `public.payment_links`

7.4 `public.merchant_subscription_plans`

7.5 发票

8. 已完成改名对照表

9. 当前保留的内部字段

10. 未来新增字段的命名规则

11. 一句话总结