初始提交：飞球 ETL 系统全量代码

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/goods_stock_summary.md
+++ b/docs/api-reference/goods_stock_summary.md
@@ -0,0 +1,176 @@
+# 库存汇总报表 — GetGoodsStockReport
+
+> 模块：`TenantGoods` · ODS 表：`goods_stock_summary` · 汇总事实表（按时间范围聚合）
+
+---
+
+## 一、接口概述
+
+查询门店商品在指定时间范围内的库存汇总数据，每条记录对应一个门店商品在查询区间内的期初/期末库存、出入库数量、盘点调整、销售数量与金额的汇总。所有记录严格满足库存平衡公式：`rangeStartStock + rangeIn + rangeInventory + rangeOut = rangeEndStock`。是库存变动明细（`goods_stock_movements`）按商品维度 + 时间范围聚合后的结果。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /TenantGoods/GetGoodsStockReport` |
+| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
+| 鉴权 | `Authorization: Bearer <token>` |
+| 分页 | `page` + `limit`（最大 100） |
+| 时间范围 | 需要（`startTime` / `endTime`） |
+
+---
+
+## 二、请求
+
+### 请求体（JSON）
+
+```json
+{
+  "siteId": 2790685415443269,
+  "startTime": "2026-02-01 08:00:00",
+  "endTime": "2026-02-13 08:00:00",
+  "page": 1,
+  "limit": 100
+}
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `siteId` | int | 是 | 门店 ID |
+| `startTime` | string | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
+| `endTime` | string | 是 | 查询结束时间，格式 `YYYY-MM-DD HH:MM:SS` |
+| `page` | int | 是 | 页码，从 1 开始 |
+| `limit` | int | 是 | 每页条数，最大 100 |
+
+---
+
+## 三、响应结构
+
+```
+{
+  "code": 200,
+  "data": {
+    "list": [ { ... }, { ... } ],
+    "total": 161
+  }
+}
+```
+
+`data.list` 中每个对象即为一条商品库存汇总记录，共 14 个字段，按逻辑分组说明如下。
+
+---
+
+## 四、响应字段详解（14 个字段）
+
+### 4.1 商品主键与基本信息
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `siteGoodsId` | int | `3089190204491141` | 门店商品 ID，本表主键（每个 `siteGoodsId` 仅一条记录）。对应门店商品档案（`store_goods_master`）的 `id`，也对应库存变动的 `siteGoodsId` |
+| `goodsName` | string | `"小合味道"` | 商品名称，冗余于门店商品档案的 `goods_name`，方便直接阅读汇总报表 |
+| `goodsUnit` | string | `"桶"` | 计量单位，与门店商品档案的 `unit` 一致。常见值：包（59）、瓶（46）、个（17）、份（13）、根（10）、盒、杯、桶、盘、支等 |
+
+### 4.2 分类维度
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `goodsCategoryId` | int | `2791941988405125` | 一级分类 ID，共 9 个不同值，与 `categoryName` 一一对应。对应分类树主键 |
+| `goodsCategorySecondId` | int | `2793236829620037` | 二级分类 ID，共 14 个不同值。对应分类树子节点，名称需到分类表或门店商品档案中查询 |
+| `categoryName` | string | `"零食"` | 一级分类名称（冗余展示字段）。枚举值共 9 个：零食、酒水、香烟、其他、雪糕、器材、小吃、槟榔、果盘 |
+
+### 4.3 库存数量（查询区间）
+
+> 库存平衡公式：`rangeStartStock + rangeIn + rangeInventory + rangeOut = rangeEndStock`
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `rangeStartStock` | int | `0` | 查询区间起始时刻的库存数量（期初库存） |
+| `rangeEndStock` | int | `22` | 查询区间结束时刻的库存数量（期末库存） |
+| `rangeIn` | int | `24` | 区间内入库数量汇总（正值），包括采购入库、调拨入库等 |
+| `rangeOut` | int | `-2` | 区间内出库数量汇总，以**负数**表示（出库/销售扣减）。注意：直接做代数求和，无需取绝对值 |
+| `rangeInventory` | int | `0` | 区间内盘点调整净变动量（盘盈 − 盘亏）。当前样本全部为 0（无盘点或盘点无净影响） |
+
+### 4.4 实时库存快照
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `currentStock` | int | `22` | 导出时刻的实时库存数量。与 `rangeEndStock` 不一定相等——后者是查询区间结束瞬间的库存，前者是当前瞬间的库存。部分记录存在 1–4 的差值（区间后又发生了出入库） |
+
+### 4.5 销量与销售金额
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `rangeSale` | int | `2` | 区间内销售数量汇总（售出多少"包/瓶/份"等）。与 `rangeOut` 绝对值大致一致（也可能有非销售出库如报损/调拨） |
+| `rangeSaleMoney` | float | `16.0` | 区间内销售金额小计（按商品维度汇总），单位：元（人民币）。有销量时 `rangeSaleMoney / rangeSale ≈ sale_price`（门店商品档案中的销售单价） |
+
+---
+
+## 五、响应样例（单条记录）
+
+```json
+{
+  "siteGoodsId": 3089190204491141,
+  "goodsName": "小合味道",
+  "goodsUnit": "桶",
+  "goodsCategoryId": 2791941988405125,
+  "goodsCategorySecondId": 2793236829620037,
+  "rangeStartStock": 0,
+  "rangeEndStock": 22,
+  "rangeIn": 24,
+  "rangeOut": -2,
+  "rangeInventory": 0,
+  "rangeSale": 2,
+  "rangeSaleMoney": 16.0,
+  "currentStock": 22,
+  "categoryName": "零食"
+}
+```
+
+---
+
+## 六、跨表关联
+
+### 与门店商品档案（`store_goods_master`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `siteGoodsId` | `id` | 门店商品 ID，关联商品基础信息（售价、成本、状态等） |
+| `goodsName` | `goods_name` | 商品名称一致 |
+| `goodsUnit` | `unit` | 计量单位一致 |
+| `goodsCategoryId` | `goods_category_id` | 一级分类 ID |
+| `goodsCategorySecondId` | `goods_second_category_id` | 二级分类 ID |
+
+> 门店商品档案是静态维表，库存汇总是按时间范围聚合的衍生事实表。
+
+### 与库存变动明细（`goods_stock_movements`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `siteGoodsId` | `siteGoodsId` | 门店商品 ID |
+
+> 结构关系：库存变动明细（明细表）→ 按 `siteGoodsId` + 时间范围聚合 → 库存汇总（本表）。`rangeIn`、`rangeOut`、`rangeInventory` 分别对应明细中不同 `stockType` 的 `changeNum` 汇总。
+
+### 与门店销售记录（`store_goods_sales_records`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `siteGoodsId` | `site_goods_id` | 门店商品 ID |
+
+> 销售记录是每一条销售明细，库存汇总是按商品维度在时间段内的汇总。`rangeSale` 对应销售记录按商品聚合的 `ledger_count` 之和，`rangeSaleMoney` 对应 `ledger_amount` 之和。
+
+### 与商品分类树（`stock_goods_category_tree`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `goodsCategoryId` | `id`（一级节点） | 一级分类主键 |
+| `goodsCategorySecondId` | `id`（二级节点） | 二级分类主键 |
+| `categoryName` | `category_name`（一级节点） | 一级分类名称 |
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/goods_stock_summary.md，按逻辑分组详解所有 14 个字段，含库存平衡公式说明和跨表关联
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
+-->