逻辑架构
实体全景 × 服务目录 — 我们设计了什么，能对外提供什么
设计原则
这张图不是技术部署图（那些在架构总览、模块架构），而是逻辑实体与服务能力矩阵：
- 左边：领域实体（模块/表/状态机）—— 回答「我们实际设计了多少东西」
- 右边：对外服务（可暴露的 API）—— 回答「外部系统能接什么」
一、内部实体全景
1.1 模块清单（10 个业务模块 + 1 个共享模块）
| # | 模块 | 目录 | 数据 Owner | 实体表数 |
|---|---|---|---|---|
| 1 | auth | internal/auth/ | 登录凭证、后台账号、角色权限 | 4 |
| 2 | user | internal/user/ | 用户、地址、积分 | 3 |
| 3 | catalog | internal/catalog/ | 商品、分类、溯源记录 | 3 |
| 4 | inventory | internal/inventory/ | 批次、库存、锁定、流水 | 4 |
| 5 | order | internal/order/ | 订单、订单项、售后 | 3 |
| 6 | payment | internal/payment/ | 支付、回调通知、退款 | 3 |
| 7 | coupon | internal/coupon/ | 券模板、用户券 | 2 |
| 8 | delivery | internal/delivery/ | 配送任务 | 1 |
| 9 | asset | internal/asset/ | 文件元数据 | 1 |
| 10 | shared | internal/shared/ | Outbox、幂等、审计 | 4 |
合计：10 个业务模块，21 张业务表 + 4 张基础设施表 = 25 张表
1.2 状态机清单（6 个）
| # | 状态机 | 状态数 | 终态 | 核心作用 |
|---|---|---|---|---|
| 1 | 订单 | 10 个状态 | completed / cancelled / refunded | 交易主干流转 |
| 2 | 支付 | 6 个状态 | paid / closed / failed / refunded | 资金安全闭环 |
| 3 | 库存锁定 | 3 个状态 | confirmed / released | 并发扣减保证 |
| 4 | 优惠券 | 3 个状态 | used / expired | 营销资损防控 |
| 5 | 配送 | 4 个状态 | delivered / cancelled | 履约追踪 |
| 6 | 售后 | 3 个状态 | completed / rejected | 退款/补发 |
1.3 API 端点清单（共 58 个）
| 端 | 端点数 | 范围 |
|---|---|---|
| 用户小程序 | 26 | 登录·商品·地址·订单·支付·券·售后 |
| 配送端 | 8 | 登录·任务·认领·取货·送达 |
| 运营后台 | 24 | 商品·库存·订单·支付·配送·券·审计 |
二、对外服务目录
以下按「外部系统想接什么」组织，标注已设计/可暴露/需鉴权。
2.1 🛒 商品查询服务
外部场景：合作渠道、内容平台、比价网站需要获取商品信息。
| 端点 | 方式 | 说明 | 鉴权 |
|---|---|---|---|
GET /api/products | 列表 | 分页、按分类筛选、状态过滤 | JWT（用户）或开放 |
GET /api/products/:id | 详情 | 商品名、图片、价格、描述 | JWT 或开放 |
GET /api/products/:id/trace | 溯源 | 养殖场、屠宰日期、检疫证明 | JWT 或开放 |
GET /api/products/search | 搜索 | 全文搜索 | JWT 或开放 |
可直接暴露：商品查询是天然适合对外开放的服务。加 API Key + 限流即可。
2.2 📋 交易接入服务
外部场景：企业团购系统、福利平台、异业合作需要下单。
| 端点 | 方式 | 说明 | 鉴权 |
|---|---|---|---|
POST /api/orders/preview | 预计算 | 输入商品+地址，返回价格快照 | JWT（强） |
POST /api/orders | 下单 | 正式创建订单，触发库存锁定 | JWT + 幂等（强） |
GET /api/orders | 列表 | 用户历史订单 | JWT（强） |
GET /api/orders/:order_no | 详情 | 订单状态、物流 | JWT（强） |
POST /api/orders/:order_no/cancel | 取消 | 未支付订单取消 | JWT（强） |
需要适配：下单涉及用户、地址、支付，通常需要走标准 OAuth 授权流程，不适合裸 API Key 暴露。
2.3 📊 库存协同服务
外部场景：供应商系统、供应链平台需要查询/同步库存。
| 端点 | 方式 | 说明 | 鉴权 |
|---|---|---|---|
GET /admin/inventory | 列表 | 当前库存 | 后台 RBAC |
POST /admin/inventory/inbound | 入库 | 供应商入库 | 后台 RBAC |
POST /admin/inventory/adjust | 调整 | 盘点调整 | 后台 RBAC |
GET /admin/inventory/movements | 流水 | 库存变动记录 | 后台 RBAC |
适合 B2B：如果对接供应商系统，可以开专门的 supplier-api 端点，按供应商账号隔离权限。
2.4 💳 支付回调服务
外部场景：微信支付服务器回调（必须暴露）。
| 端点 | 方式 | 说明 | 鉴权 |
|---|---|---|---|
POST /api/payments/wechat/notify | 回调 | 微信支付结果通知 | 微信证书验签 |
GET /api/payments/:order_no | 查询 | 支付状态 | JWT（强） |
POST /api/payments/refund | 退款 | 发起退款 | 后台 RBAC |
支付回调已设计为对外入口，微信标准验签机制，不依赖内部鉴权。
2.5 🚚 配送调度服务
外部场景：第三方配送平台、骑手 App 需要获取配送任务。
| 端点 | 方式 | 说明 | 鉴权 |
|---|---|---|---|
POST /api/driver/login | 登录 | 骑手登录 | 账号密码 |
GET /api/delivery/tasks | 任务列表 | 待配送任务 | JWT（骑手） |
GET /api/delivery/tasks/:id | 任务详情 | 脱敏地址+坐标 | JWT（骑手） |
POST /api/delivery/tasks/:id/claim | 认领 | 骑手接单 | JWT（骑手） |
POST /api/delivery/tasks/:id/pickup | 取货 | 确认取货 | JWT（骑手） |
POST /api/delivery/tasks/:id/deliver | 送达 | 确认送达 | JWT（骑手） |
POST /api/delivery/tasks/:id/release | 释放 | 放弃任务 | JWT（骑手） |
GET /api/delivery/tasks/locations | 坐标 | 任务位置集合 | JWT（骑手） |
可与达达/闪送/美团配送对接，按第三方配送平台的 API 规范做适配层。
2.6 🎫 营销发券服务
外部场景：合作渠道发券、异业联合营销。
| 端点 | 方式 | 说明 | 鉴权 |
|---|---|---|---|
GET /api/coupons | 我的券 | 用户券列表 | JWT（强） |
GET /api/coupons/available | 可领券 | 公开可领券模板 | JWT 或开放 |
POST /admin/coupons/templates | 创建模板 | 运营创建券模板 | 后台 RBAC |
POST /admin/coupons/issue | 发券 | 定向发券 | 后台 RBAC |
渠道发券场景：可为合作方开专用 partner-api，按渠道限制发券总量。
2.7 📝 合规审计服务
外部场景：财务对账、监管审查、第三方审计。
| 端点 | 方式 | 说明 | 鉴权 |
|---|---|---|---|
GET /admin/audit-logs | 审计日志 | 敏感操作记录 | 后台 RBAC（强） |
GET /admin/payments | 支付列表 | 对账查询 | 后台 RBAC |
GET /admin/refunds | 退款列表 | 退款流水 | 后台 RBAC |
GET /admin/orders | 订单列表 | 全部订单 | 后台 RBAC |
敏感数据，不建议对外暴露裸 API。建议导出为加密数据包交付。
三、对外暴露策略矩阵
| 服务 | 数据敏感度 | 建议暴露方式 | 鉴权方案 | MVP 就绪 |
|---|---|---|---|---|
| 🛒 商品查询 | 低 | 开放 API + API Key | API Key + 限流 | ✅ |
| 📋 交易接入 | 高 | OAuth 2.0 授权 | 用户授权码 | ⚠️ 需 OAuth 层 |
| 📊 库存协同 | 中 | 供应商专用 API | 供应商账号 + RBAC | ⚠️ 需供应商账号体系 |
| 💳 支付回调 | 高 | 微信标准入口 | 微信证书验签 | ✅ |
| 🚚 配送调度 | 中 | 骑手 App / 第三方 API | JWT + 角色 | ✅ |
| 🎫 营销发券 | 中 | 渠道 API + API Key | API Key + 限流 | ⚠️ 需渠道管理 |
| 📝 合规审计 | 极高 | 加密数据包导出 | 不暴露 HTTP | ❌ 不对外 |
四、实体-服务映射
五、一句话总结
| 维度 | 数量 |
|---|---|
| 业务模块 | 10 个 |
| 数据库表 | 25 张（21 业务 + 4 基础设施） |
| 状态机 | 6 个（29 个状态节点） |
| API 端点 | 58 个（用户 26 + 配送 8 + 后台 24） |
| 对外可暴露服务 | 7 类（商品·交易·库存·支付·配送·发券·审计） |
| MVP 立即可暴露 | 3 类（商品查询 · 支付回调 · 配送调度） |