Web_BAI_Manage_ApiServer/docs/pb_tbl_cart.md

# pb_tbl_cart

> 来源：购物车表需求草图、`script/pocketbase.cart-order.js`
> 类型：`base`
> 读写规则：微信端原生访问建议仅允许记录所有者访问；当前脚本已按 `cart_owner = 当前 token 对应 openid` 配置原生 collection 规则，管理后台建议通过 hooks / API 聚合查询

## 表用途

用于存储购物车商品项明细。

当前结构按“一个购物车商品项一条记录”设计：

- `cart_id` 是单条购物车项业务 ID
- `cart_number` 是购物车名称 / 分组号，同一购物车下的多条商品项可共用同一个 `cart_number`
- `cart_owner` 用于标识购物车所属用户

## 字段清单

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `id` | `text` | 是 | PocketBase 记录主键 |
| `cart_id` | `text` | 是 | 购物车项业务 ID，唯一标识 |
| `cart_number` | `text` | 否 | 购物车名称 / 分组号，可为空；如需展示编号建议在 hooks / 业务侧补齐 |
| `cart_create` | `autodate` | 否 | 购物车项创建时间，由数据库自动生成 |
| `cart_owner` | `text` | 是 | 生成者 openid，约定保存 `tbl_auth_users.openid` |
| `cart_product_id` | `relation` | 是 | 原生关联 `tbl_product_list`，单选，保存的是目标产品记录的 PocketBase `recordId` |
| `cart_product_quantity` | `number` | 否 | 产品数量，可为空；如传值，建议业务侧约束为正整数 |
| `cart_status` | `text` | 否 | 购物车状态，可为空；如传值，建议值：`有效` / `无效` |
| `cart_at_price` | `number` | 否 | 加入购物车时的价格，可为空；如传值用于后续降价提醒或对比 |
| `cart_remark` | `text` | 否 | 备注 |
| `is_delete` | `number` | 否 | 软删除标记，`0` 表示未删除，`1` 表示已删除，默认 `0` |

## 索引

| 索引名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `idx_tbl_cart_cart_id` | `UNIQUE INDEX` | 保证 `cart_id` 唯一 |
| `idx_tbl_cart_cart_number` | `INDEX` | 加速按购物车名称 / 分组号查询 |
| `idx_tbl_cart_cart_owner` | `INDEX` | 加速按所属用户查询 |
| `idx_tbl_cart_cart_product_id` | `INDEX` | 加速按产品查询 |
| `idx_tbl_cart_cart_status` | `INDEX` | 加速按购物车状态过滤 |
| `idx_tbl_cart_cart_create` | `INDEX` | 加速按购物车项创建时间倒序查询 |
| `idx_tbl_cart_owner_number` | `INDEX` | 加速同一用户下按购物车分组查询 |
| `idx_tbl_cart_owner_status` | `INDEX` | 加速查询某用户的有效购物车项 |

## 补充约定

- `cart_owner` 当前按文本字段保存业务 ID。
- `cart_product_id` 已改为 PocketBase 原生 `relation` 字段，关联目标集合为 `tbl_product_list`，且 `maxSelect = 1`。
- 调用原生 records create / update 接口时，`cart_product_id` 必须传 **`tbl_product_list` 的 PocketBase 记录主键 `id`**，不能再传业务 ID `prod_list_id`。
- 如前端当前拿到的是业务 ID `prod_list_id`，需先调用 `GET /pb/api/collections/tbl_product_list/records?filter=prod_list_id="..."&perPage=1&page=1` 查出对应 `recordId`，再把该 `recordId` 作为 `cart_product_id` 提交。
- 当前原生 collection 层面，创建时仅要求客户端显式提交非空 `cart_owner`；不再强制要求与当前 token 对应 `openid` 相等。
- 当前表结构层面，除 `cart_id`、`cart_owner`、`cart_product_id` 外，其余业务字段均允许为空。
- `cart_owner` 统一保存 `tbl_auth_users.openid`，便于直接使用微信登录返回 token 做原生访问控制。
- `is_delete` 用于软删除控制，购物车项删除时建议优先标记为 `1`。
- 集合默认查询规则已内置 `is_delete = 0`，常规列表/详情不会返回已软删除数据。
- `cart_product_quantity`、`cart_at_price` 使用 `number`，数量正整数与价格精度建议在 hooks / API 层统一校验。
- 当购物车被清空时，建议业务侧将历史记录 `cart_status` 置为 `无效`，而不是直接覆盖有效记录。
- `cart_create` 由数据库自动写入，接口层不需要也不应允许客户端自行填值。
- PocketBase 系统字段 `created`、`updated` 仍然存在，只是不在 collection 字段清单里单独声明。