# Database Draft

第一阶段使用 TypeORM 描述 MySQL 数据模型。当前只保留管理后台的最小底座，并把第三方接口账号改为环境变量配置。

后续数据库设计必须按商城模型扩展：第三方分类/商品和自营分类/商品使用统一业务主干，通过 `source_type`、`provider`、`external_id` 等字段区分来源。支付功能先按订单、支付单、支付事件和退款单预留结构，详细说明见 `docs/payment-integration.md`。

## Initial Entities

- `users`: 管理后台用户。
- `roles`: 角色与权限集合。
- `user_roles`: 用户角色关联表。
- `api_call_logs`: 所有第三方接口调用日志。
- `categories`: 商品分类。当前迁移草案偏第三方项目分类缓存，后续需要支持 `third_party` 和 `self_owned`。
- `courses`: 第三方商品/课程缓存。后续可改造为统一 `products`，或保留表名但补齐商品来源、价格、库存、上下架和履约类型等字段。

## Unified Commerce Model

建议后续补齐或新建以下核心表：

- `products`: 商品主表，统一承载第三方课程商品和自营商品。
- `product_skus`: 商品规格/套餐表，后续存在周期、套餐、规格时使用。
- `orders`: 订单主表，保存订单号、用户、金额、支付状态、履约状态。
- `order_items`: 订单明细表，保存商品快照和下单扩展信息。
- `order_fulfillments`: 履约记录表，区分第三方 API 提交、本地自动交付和人工处理。
- `payments`: 支付单表，记录支付渠道、金额、渠道流水号和支付状态。
- `payment_events`: 支付回调、主动查询、退款回调等事件日志。
- `refunds`: 退款单表。
- `audit_logs`: 后台操作审计日志。

关键来源字段：

- `source_type`: `third_party` 或 `self_owned`。
- `provider`: 第三方供应商标识，当前第三方默认可用 `biedawo`，自营可为空。
- `external_id`: 第三方分类、商品或订单 ID，自营数据为空。
- `fulfillment_type`: `third_party_api`、`local_only`、`manual`。

## Third-Party API Config

当前不再维护渠道管理或多套接口账号配置。服务端统一读取：

- `WK_BASE_URL`
- `WK_APP_UID`
- `WK_APP_KEY`

`WK_APP_KEY` 原样作为第三方 `key` 使用，前端和日志展示时只允许脱敏显示。

## Migration Policy

- 不在运行时开启 `synchronize`。
- 本地开发可以通过 TypeORM migration 生成 SQL。
- 生产环境必须使用 migration 执行结构变更。
- `.env` 不提交到仓库，参考 `.env.example` 创建本地配置。