study_work/docs/database.md

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 创建本地配置。