# KuiGuOS 工业品 B2B 平台（多租户商业操作系统）

> AI Agent 可据此自主完成：发现商品 → 参数选型 → 比阶梯价 → 询价 → 按合约价下单 → 查订单。
> 所有 /api/* 请求必须携带 HTTP 头：X-Tenant-Slug: kuigu（租户隔离）。

## 商品发现（无需登录）
- GET /api/catalog/storefronts/kuigu-cn/products?page=1&pageSize=50   商品列表（SINGLE/MARKETPLACE 模式过滤）
- GET /api/catalog/storefronts/kuigu-cn/selector?dims={"宽度":["45"]}  参数化选型器（dims 为 JSON，返回 facets 可继续下钻）
- GET /api/catalog/feed.json?page=1&pageSize=100                       结构化 Catalog Feed（含阶梯价/参数/认证/图片，kuigu.catalog.v1）

## 交易（买家身份，需 JWT）
- POST /api/auth/login { email, password }                             登录（返回 Bearer token）
- POST /api/orders { storefrontId, orgId, accountId, items:[{sku,title,qty,unitPrice,ownership}] }   现货下单（自动按供应商拆单+佣金）
- POST /api/b2b/rfqs { orgId, accountId, lines:[{productName,spec,qty,targetPrice}] }                提交询价单
- GET  /api/b2b/rfqs/:id/quotes                                        查看收到的报价
- POST /api/b2b/quotes/:id/approvals { approverAccountId, level }      审批报价
- POST /api/b2b/quotes/:id/place-order                                 按合约价下单
- GET  /api/orders?page=1                                              我的订单（含拆单明细）
- POST /api/orders/:id/confirm-receipt                                 确认收货（履约完成）

## 账期结算
- GET  /api/b2b/statements?orgId=xxx                                   我的对账单
- POST /api/b2b/statements/:id/confirm                                 确认对账单
- POST /api/b2b/statements/:id/pay { voucherUrl? }                     支付（可附打款凭证）

## 运营与治理
- GET  /api/ops/dashboard                                              运营仪表盘（owner/admin）
- GET  /api/ops/audit-logs?tool=                                       审计日志（owner/admin）
- GET  /health                                                         健康检查
- MCP  /mcp/call                                                       10 个 MCP 工具（需凭证：X-API-Key kuigu_* 或
                                                                       owner/admin JWT；平台级工具需 X-Platform-Key）
- GET  /mcp/tools                                                       工具清单（公开元数据）

## SaaS 平台（场景 B：自助开店）
- GET  /api/saas/plans                                                  公开套餐目录（月付/年付）
- POST /api/saas/signup {company,slug,email,password,planCode?}         开户一条龙（租户+owner 账号+14 天试用）
- POST /api/saas/checkout {planCode,billingCycle}                      创建支付会话（租户上下文）
- POST /api/saas/checkout/:id/mock-pay                                 支付确认（mock 渠道演示）
- GET  /api/saas/subscription                                          当前订阅状态
- POST /api/site-builder/create|apply-template                         AI 建站（siteBuilder 授权 + quota.sites 配额）
- POST /api/site-builder/custom-domain/:id                             绑定客户自有域名（CNAME）
- GET  /api/resolve-domain?host=                                       域名 → 租户/店面解析（多租户路由底座）
- GET  /api/vendors?status=approved / GET /api/vendors/:slug           供应商黄页目录/门户详情

## 约束与合规
- 多租户隔离：MCP 租户上下文只来自凭证（API Key/JWT），X-Tenant-Slug 声明不一致将被拒绝
- 敏感写操作（审核/打款/审批/支付/模式切换）全部落审计日志
- 退款/打款类操作需人类二次确认（PRD 铁律）
- 套餐治理：features 门禁（403 FEATURE_NOT_ENABLED）+ 硬配额（402 QUOTA_EXCEEDED）+ 到期自动封停（423）