开发文档

一、技术架构

• 形态：Go 语言开发的单体全栈数字商品销售系统，编译为单个二进制运行；数据库默认 SQLite（db/dujiao.db，零依赖），可配 Redis 做缓存/队列；
• 前后台分离：前台（商品、下单、查单）与后台 SPA 建议分域名部署（如 dujiao-net.域名 前台 / dujiao-admin.域名 后台），后台入口是独立的 SPA 页面；
• 配置：所有配置集中在 config.yml（段：app / server / log / database / jwt / user_jwt / bootstrap / redis / queue / upload / security / web）。

二、目录与运行

部署目录/
├── dujiao-next        # 编译好的二进制（systemd 直接跑）
├── config.yml         # 主配置（库、端口、JWT、Redis、上传、安全）
├── db/dujiao.db       # SQLite 数据库（备份就是拷这个文件）
├── uploads/           # 上传目录
└── logs/              # 运行日志

启动：./dujiao-next（默认监听 127.0.0.1:8090，端口在 config.yml 的 server 段）；用 systemd 托管 + Nginx 反代，HTTPS 用面板/证书自动签发。

三、数据库（SQLite，62 张表）

• 管理员与权限：admins / admin_login_logs / casbin_rule（RBAC 策略）；
• 商品与交付：products / product_skus / categories / cart_items / orders / order_items / fulfillments（交付记录）/ card_secrets / card_secret_batches（卡密池与批次）/ gift_cards / gift_card_batches；
• 支付：payment_channels（渠道配置）/ payments / order_refund_records / order_risk_lock_keys；
• 用户与钱包：users / wallet_accounts / wallet_transactions / wallet_recharge_orders / member_levels / member_level_prices / user_login_logs / user_oauth_identities / email_verify_codes；
• 分销与代理：reseller_profiles / reseller_balance_accounts / reseller_domains / reseller_ledger_entries / reseller_order_snapshots / reseller_product_settings / reseller_site_configs / reseller_withdraw_requests / reseller_related_accounts；affiliate_profiles / affiliate_clicks / affiliate_commissions / affiliate_withdraw_requests；
• 进货与对账：procurement_orders / reconciliation_jobs / reconciliation_items / downstream_order_refs / site_connections / api_credentials / sku_mappings / product_mappings；
• 内容与营销：posts / post_categories / post_products（文章挂商品）/ banners / promotions / coupons / coupon_usages；
• 系统：settings / media / notification_logs / telegram_broadcasts / channel_clients / channel_clients 等。

四、二次开发

• 改配置：优先在 config.yml 与后台里改（支付渠道、JWT、上传、日志级别），改动后重启服务；
• 改数据/加字段：直接操作 SQLite（sqlite3 db/dujiao.db），加字段用 ALTER TABLE；注意程序升级时官方迁移脚本可能也要跑；
• 接外部系统：二进制无法直接改源码时，推荐旁挂一个轻量接口（如 Node/PHP 小脚本直连 SQLite 读写），再用 Nginx 的 location = /路径 反代出去 —— 演示站的自动开号接口就是这么做的；
• 邮件/短信：走 settings 表里的 SMTP 配置；
• 备份：拷 db/dujiao.db + config.yml + uploads/ 即可（建议每天定时打包）。

五、常见运维

• 重启：systemctl restart dujiao-next；看日志：journalctl -u dujiao-next -f 或 logs/；
• 后台打不开：确认后台域名指向 SPA 入口、config.yml 的 web 段与 Nginx 一致；
• 支付回调不通：payment_channels 中渠道的 notify_url / return_url 必填且必须是外网可访问的地址。