root/ZQYY.FQ-ETL
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Neo
2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
.gitignore vendored Normal file
View File

@@ -0,0 +1,59 @@
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
# 虚拟环境
venv/
ENV/
env/
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
.specstory/
.cursorindexingignore
# 日志和导出
*.log
*.jsonl
export/
logs/
scripts/logs/
reports/
# 环境变量
.env
# 测试
.pytest_cache/
.hypothesis/
pytest-cache-files-*/
.coverage
htmlcov/
# 临时文件
tmp/
*.lnk
# 清理归档
.Deleted/

15
.kiro/hooks/change-impact-review.kiro.hook Normal file
View File

@@ -0,0 +1,15 @@
{
"enabled": true,
"name": "change-impact-review（Steering + README）",
"description": "每次 agent 执行结束后，评估本轮代码变更是否需要同步更新 product/tech/structure steering 文档及 README，必要时自动更新并输出审计摘要。",
"version": "1",
"when": {
"type": "agentStop"
},
"then": {
"type": "askAgent",
"prompt": "你必须对本轮执行进行「变更影响审查」。\n\n第一步）判断本轮是否引入了「逻辑改动」（业务规则、数据处理/ETL 逻辑、API 行为、鉴权/权限、小程序交互逻辑）。如果没有逻辑改动（仅格式化/注释/拼写修正），输出「无逻辑改动」并结束。\n\n第二步）如果存在逻辑改动，逐一评估以下文档是否需要更新，需要则立即更新：\n- .kiro/steering/product.md（产品定位、业务规则/定义）\n- .kiro/steering/tech.md（技术栈/约束、部署/运行时假设）\n- .kiro/steering/structure.md（目录结构、关键模块边界）\n- README.md（运行方式、环境变量、接口、本地部署、集成说明）\n- gui/README.md\tGUI 的独立文档，需要说明各子目录用途和常用命令\n- docs/ 文档目录索引，帮助找到正确的子目录\n- scripts/ 脚本较多且分子目录，需要说明各子目录用途和常用命令\n- tasks/ 任务开发约定（如何新增任务、注册流程）\n- database/ Schema 约定、迁移规范\n- tests/ 测试运行方式、FakeDB/FakeAPI 用法\n\n第三步）输出审计友好的摘要：\n- 变更范围：涉及的模块/接口/数据库对象\n- 变更原因：为什么改\n- 风险评估：回归范围 + 建议运行的测试/验证\n- 文档同步：已更新的文档列表（或明确说明无需更新的理由）\n\n第4步) 变更标注与审计落盘（强制执行）：\n创建或更新审计记录文件：docs/ai_audit/changes/<YYYY-MM-DD>__<slug>.md，内容必须包含：\n- 日期/时间（Asia/Taipei）\n- 原始用户 Prompt（原文；或引用 Prompt-ID + 不超过 5 行的摘录）\n- 直接原因：AI 分析后“为何必须改” + “修改方案简介”\n- 修改文件清单（Files changed list）\n- 风险点、回滚要点、验证步骤（至少包含可执行的验证方式）\n对每一个被修改的文件，必须在文件内新增或更新 AI_CHANGELOG 记录项，至少包含：\n- 日期\n- Prompt（Prompt-ID + 摘录）\n- 直接原因（必要性 + 方案简介）\n- 变更摘要（改了什么：模块/函数/接口/字段等）\n- 风险与验证（回归范围 + 验证方法/测试点/SQL/联调步骤）\n对每一处“逻辑变更”的代码块，必须在变更附近添加内联 CHANGE 标记注释，至少说明：\n- 变更意图（intent）\n- 关键假设（assumptions）\n- 边界条件/资金口径/精度与舍入规则（若相关）\n- 关联 Prompt（Prompt-ID 或摘录）以及必要的验证提示\n\n硬性规则：如果涉及数据库 schema 或表结构变更，必须同步更新 C:\\ZQYY\\FQ-ETL\\docs\\bd_manual\\ 下对应的表结构文档。"
},
"workspaceFolderName": "FQ-ETL",
"shortName": "change-impact-review"
}

15
.kiro/hooks/db-docs-sync.kiro.hook Normal file
View File

@@ -0,0 +1,15 @@
{
"enabled": true,
"name": "Manual: DB 文档全量同步",
"description": "按需触发：对比 Postgres 实际 schema 与 docs/bd_manual/ 下的文档，自动补全或更新缺失/过时的表结构说明，并输出变更摘要。",
"version": "1",
"when": {
"type": "userTriggered"
},
"then": {
"type": "askAgent",
"prompt": "执行一次按需的数据库文档全量同步。\n\n步骤：\n1) 检查当前 Postgres schema（使用环境中可用的工具/命令，例如 pg_dump --schema-only 或查询 information_schema）。\n2) 与 docs/bd_manual 下现有文档进行对比。\n3) 更新缺失或过时的 schema/表结构文档。\n4) 输出对账摘要：哪些文档被修改了、修改原因。输出路径遵循.env路径定义。\n\n注意：如果需要执行 shell 命令，请通过 agent 的 shell 工具调用。"
},
"workspaceFolderName": "FQ-ETL",
"shortName": "db-docs-sync"
}

22
.kiro/hooks/db-schema-doc-enforcer.kiro.hook Normal file
View File

@@ -0,0 +1,22 @@
{
"enabled": true,
"name": "DB Schema 文档执行 (bd_manual)",
"description": "当数据库 schema/migration 相关文件被保存时，检查是否有表结构变更，并自动更新 docs/bd_manual/ 下对应的表结构文档。",
"version": "1",
"when": {
"type": "fileEdited",
"patterns": [
"**/migrations/**/*.*",
"**/*.sql",
"**/*ddl*.*",
"**/*schema*.*",
"**/*.prisma"
]
},
"then": {
"type": "askAgent",
"prompt": "一个数据库相关文件刚被保存。你必须检查是否发生了 schema/表结构变更。\n\n如果发生了表结构变更，你必须更新以下目录中的文档：\ndocs/bd_manual/\n\n最低输出要求（必须写入对应 schema 目录 + 表结构文档）：\n1) 变更内容：表/字段/类型/可空性/默认值/约束/索引/外键的具体变化\n2) 变更原因：业务背景与动机\n3) 影响范围：ETL 管线、后端 API 契约、小程序字段等\n4) 回滚策略：如何回退 + 数据回填注意事项\n5) 验证 SQL：至少 3 条查询语句用于验证变更正确性\n6) 溯源留痕日期（Asia/Taipei，YYYY-MM-DD）；Prompt（Prompt-ID + ≤5 行摘录或原文）；Direct cause（必要性 + 修改方案简介）\n\n如果没有发生表结构变更（例如仅修改注释），在变更日志文档中写一条简短说明：\"无结构性变更\"（同样要带日期 + Prompt-ID）。"
},
"workspaceFolderName": "FQ-ETL",
"shortName": "db-schema-doc-enforcer"
}

13
.kiro/hooks/prompt-audit-log.kiro.hook Normal file
View File

@@ -0,0 +1,13 @@
{
"enabled": true,
"name": "Prompt Audit Log",
"description": "每次提交 prompt 时，自动将原始用户 prompt 追加到 docs/ai_audit/prompt_log.md，包含日期时间和 Prompt-ID。",
"version": "1",
"when": {
"type": "promptSubmit"
},
"then": {
"type": "askAgent",
"prompt": "将本次用户 Prompt 追加写入 docs/ai_audit/prompt_log.md。\n\n要求：\n- 使用 Asia/Taipei 日期时间。\n- 生成 Prompt-ID：P<YYYYMMDD-HHMMSS>（例如 P20260213-101530）。\n- 记录 Prompt 原文（如包含敏感信息则用 [REDACTED] 脱敏，并说明已脱敏）。\n- 记录一行摘要（≤120 字），用于后续快速检索。\n\n最后一行必须输出：Prompt-ID: <id>"
}
}

41
.kiro/skills/bd-manual-db-docs/SKILL.md Normal file
View File

@@ -0,0 +1,41 @@
---
name: bd-manual-db-docs
description: 当 PostgreSQL schema/表结构发生变化时，用于将变更以审计友好的方式落盘到 docs/bd_manual/（含变更原因、影响、回滚与验证 SQL）。
---
# 目的
保证数据库结构变化可追溯、可审计、可回滚，并与 ETL/后端/小程序字段映射保持一致。
# 触发条件
- 迁移脚本/DDL 修改（新增/删除/改表、字段、类型、默认值、非空、约束、索引、外键）
- ORM/Schema 定义变更导致实际 DB 结构变化
- 手工执行 DDL（需用 manualTrigger hook 或本 Skill 补齐文档）
# 输出要求（必须全部满足）
所有输出必须落盘到：`docs/bd_manual/`
至少包含：
1) Schema Change Log（变更日志条目）
2) Table Structure Doc（涉及表的结构文档更新）
3) Rollback & Verification（回滚要点 + 至少 3 条验证 SQL）
4) 溯源：日期 + Prompt-ID/Prompt 摘录 + Direct cause（必要性 + 方案简介）
# 工作流
## 1) 识别结构性变化
- 列出新增/修改/删除的对象：schema/table/column/index/constraint/fk
- 明确变更前后差异（before/after）
## 2) 更新变更日志（Schema Change Log）
- 在对应 schema 目录下追加一条变更记录（模板见 assets/schema-changelog-template.md）
## 3) 更新表结构文档（Table Structure Doc）
- 每张受影响的表都要更新（模板见 assets/table-structure-template.md）
- 同步字段含义/口径说明，尤其是金额类字段：精度、币种、舍入
## 4) 回滚与验证
- 写清楚 DDL 回滚路径（必要时提供反向迁移）
- 写至少 3 条验证 SQL（含约束/索引/关键字段检查）
# 模板
- `assets/schema-changelog-template.md`
- `assets/table-structure-template.md`

27
.kiro/skills/bd-manual-db-docs/assets/schema-changelog-template.md Normal file
View File

@@ -0,0 +1,27 @@
# Schema 变更日志（Schema Change Log）
- 日期（Asia/Taipei，YYYY-MM-DD）：
- Prompt-ID：
- 原始原因（Prompt 摘录/原文）：
- 直接原因（必要性 + 方案简介）：
- 影响的 Schema：
- 变更摘要（一句话）：
## 变更明细
- 新增：
- 修改：
- 删除：
## 影响范围
- ETL：
- 后端 API：
- 小程序：
## 回滚要点
- DDL 回滚：
- 数据回填/迁移注意事项：
## 验证 SQL（至少 3 条）
1)
2)
3)

22
.kiro/skills/bd-manual-db-docs/assets/table-structure-template.md Normal file
View File

@@ -0,0 +1,22 @@
# <schema>.<table>
## 表用途（Purpose）
- 该表代表什么业务对象/过程
## 字段（Columns）
| 字段名 | 类型 | 可空 | 默认值 | 约束/键 | 说明（含口径） |
|---|---|---:|---|---|---|
> 金额类字段必须注明：币种、精度、舍入/截断规则、是否允许负数。
## 索引（Indexes）
- 索引名 / 字段 / 是否唯一 / 备注
## 约束与外键（Constraints & FKs）
- 约束名 / 定义 / 备注
## 数据不变量（Invariants）
- 例如：状态机枚举范围、唯一性、跨字段一致性约束（如有）
## 变更历史（Change History）
- YYYY-MM-DD | Prompt-ID | 直接原因 | 变更摘要

37
.kiro/skills/change-annotation-audit/SKILL.md Normal file
View File

@@ -0,0 +1,37 @@
---
name: change-annotation-audit
description: 对每次修改强制生成审计记录（docs/ai_audit/changes/...），并在每个被改文件写 AI_CHANGELOG、在逻辑变更处写 CHANGE 标记注释（包含日期、Prompt 与直接原因）。
---
# 目的
把“为什么改、怎么改、怎么验”固化到可审计产物中，满足资金相关项目的严谨性要求。
# 触发条件
- 任何对代码或文档的实质修改（非纯格式化）
- 特别是：逻辑改动、资金口径改动、接口契约改动、DB 结构改动
# 必须产物（缺一不可）
1) `docs/ai_audit/changes/<YYYY-MM-DD>__<slug>.md`
2) 每个被修改文件内的 `AI_CHANGELOG` 条目
3) 每个逻辑变更附近的 `CHANGE` 标记注释
# 工作流
## 1) Prompt 溯源
- 确认本次修改有 Prompt-ID（来自 prompt_log.md）
- 若没有，先补写 Prompt-ID，再继续
## 2) 写审计记录（Per-change）
使用模板：`assets/audit-record-template.md`
- 必须写：原始原因（Prompt）、直接原因、改动方案简介、文件清单、风险/回滚/验证
## 3) 写文件内 AI_CHANGELOG（Per-file）
- 对每个修改的文件追加一条 AI_CHANGELOG
- 选择适合语言/文件类型的注释风格（模板见 assets/file-changelog-templates.md）
## 4) 写 CHANGE 标记（Block-level）
- 对每处逻辑变更，必须在附近写 CHANGE 标记
- 必须包含：intent、assumptions、边界条件（金额/舍入/精度）、验证提示
# 模板
- `assets/audit-record-template.md`
- `assets/file-changelog-templates.md`

19
.kiro/skills/change-annotation-audit/assets/audit-record-template.md Normal file
View File

@@ -0,0 +1,19 @@
# 变更审计记录（Change Audit Record）
- 日期/时间（Asia/Taipei）：
- Prompt-ID：
- 原始原因（Prompt 原文或 ≤5 行摘录）：
- 直接原因（必要性 + 修改方案简介）：
## 变更范围（Changed）
- 模块/接口/表/关键文件：
## 风险与回滚（Risk & Rollback）
- 风险点：
- 回滚要点：
## 验证（Verification）
- 至少 1 条可执行验证方式（测试/SQL/联调）：
## 文件清单（Files changed）
- ...

48
.kiro/skills/change-annotation-audit/assets/file-changelog-templates.md Normal file
View File

@@ -0,0 +1,48 @@
# 文件内 AI_CHANGELOG 与 CHANGE 标记模板
## 通用 AI_CHANGELOG（建议放在文件头部或“变更记录”小节）
- 2026-02-13 | Prompt: P20260213-101530（摘录：...）| Direct cause：... | Summary：... | Verify：...
---
## Markdown / 文档（放在文档末尾或“变更记录”小节）
### AI_CHANGELOG
- YYYY-MM-DD | Prompt: P...（摘录：...）| Direct cause：... | Summary：... | Verify：...
---
## JS/TS（块注释）
/*
AI_CHANGELOG
- YYYY-MM-DD | Prompt: P...（摘录：...）| Direct cause：... | Summary：... | Verify：...
*/
// [CHANGE P...] intent: ...
// assumptions: ...
// edge cases / money semantics: ...
// verify: ...
---
## Python（docstring/块注释）
"""
AI_CHANGELOG
- YYYY-MM-DD | Prompt: P...（摘录：...）| Direct cause：... | Summary：... | Verify：...
"""
# [CHANGE P...] intent: ...
# assumptions: ...
# edge cases / money semantics: ...
# verify: ...
---
## SQL（块注释 + 行注释）
/*
AI_CHANGELOG
- YYYY-MM-DD | Prompt: P...（摘录：...）| Direct cause：... | Summary：... | Verify：...
*/
-- [CHANGE P...] intent: ...
-- assumptions: ...
-- money semantics: precision/rounding/currency ...
-- verify: ...

38
.kiro/skills/steering-readme-maintainer/SKILL.md Normal file
View File

@@ -0,0 +1,38 @@
---
name: steering-readme-maintainer
description: 当发生业务/ETL/API/鉴权/小程序交互等逻辑改动时，用于执行变更影响审查并同步更新 product/tech/structure/README 与审计记录。
---
# 目的
将“逻辑改动→文档同步→审计留痕”流程标准化，减少漏更与口径漂移风险（资金相关场景优先保证可追溯与可复算）。
# 触发条件（何时调用本 Skill）
- 修改了业务规则/计算口径/资金处理（精度、舍入、阈值等）
- 修改了 ETL/SQL 清洗聚合映射逻辑
- 修改了 API 行为（返回结构、错误码、鉴权/权限）
- 修改了小程序关键交互流程（校验、状态机、关键字段）
# 工作流（必须按顺序执行）
## 1) 分类：是否属于“逻辑改动”
- 若不是逻辑改动：写明“无逻辑改动”，并说明为何（例如仅格式化/拼写修正/注释调整）。
- 若是逻辑改动：进入下一步。
## 2) Steering 与 README 同步（逐项评估）
- `.kiro/steering/product.md`：业务定义/口径/资金规则是否变化？
- `.kiro/steering/tech.md`：技术栈/运行方式/依赖/部署假设是否变化？
- `.kiro/steering/structure.md`：目录/模块边界/职责是否变化？
- `README.md`：运行方式、配置、环境变量、接口契约、联调步骤是否变化？
> 规则：如果“对读者理解系统行为”有帮助，就应更新；不要为了追求“少改文档”而拒绝同步。
## 3) 输出审计友好摘要（对话回复/审计记录都需要）
- Changed：改了哪些模块/接口/表/关键文件
- Why：原始原因（Prompt-ID + 摘录）与直接原因（必要性 + 方案简介）
- Risk：风险点与回归范围
- Verify：建议的验证步骤（测试/SQL/联调）
## 4) 联动硬规则检查
- 如果涉及 DB schema/表结构变化：必须同步更新 `docs/bd_manual/`（见 skill `bd-manual-db-docs`）。
# 资产（可复制模板/清单）
见：`assets/steering-update-checklist.md`

23
.kiro/skills/steering-readme-maintainer/assets/steering-update-checklist.md Normal file
View File

@@ -0,0 +1,23 @@
# Steering & README 同步清单（逻辑改动必查）
## product.md（产品/口径）
- 业务定义/指标口径/字段含义是否改变？
- 涉及金额的精度/舍入/阈值规则是否改变？
- 角色/权限模型是否改变？
## tech.md（技术/运行）
- 新增/变更依赖（框架、库、驱动）？
- 配置项/环境变量/端口/服务启动方式是否改变？
- 数据访问边界（ETL 库 vs 业务库）是否改变？
- 性能/一致性/幂等/重试策略是否改变？
## structure.md（结构/职责）
- 新增目录/模块？
- 模块职责或边界是否重新划分？
- 新增集成点（队列、定时任务、外部系统）？
## README.md（使用/联调）
- 本地启动步骤是否改变？
- 新增/变更配置项（.env 等）？
- API 契约是否变化（路径、参数、返回、错误码）？
- 小程序联调步骤是否变化？

1
.kiro/specs/repo-audit/.config.kiro Normal file
View File

@@ -0,0 +1 @@
{"generationMode": "requirements-first"}

424
.kiro/specs/repo-audit/design.md Normal file
View File

@@ -0,0 +1,424 @@
# 设计文档：仓库治理只读审计
## 概述
本设计描述三个 Python 审计脚本的实现方案，用于对 etl-billiards 仓库进行只读分析并生成三份 Markdown 报告。脚本仅读取文件系统和源代码，不连接数据库、不修改任何现有文件，仅在 `docs/audit/` 目录下输出报告。
审计脚本采用模块化设计：一个共享的仓库扫描器负责遍历文件系统，三个独立的分析器分别生成文件清单、流程树和文档对齐报告。
## 架构
```mermaid
graph TD
A[scripts/audit/run_audit.py<br/>审计主入口] --> B[scripts/audit/scanner.py<br/>仓库扫描器]
A --> C[scripts/audit/inventory_analyzer.py<br/>文件清单分析器]
A --> D[scripts/audit/flow_analyzer.py<br/>流程树分析器]
A --> E[scripts/audit/doc_alignment_analyzer.py<br/>文档对齐分析器]
B --> F[文件系统<br/>只读遍历]
C --> G[docs/audit/file_inventory.md]
D --> H[docs/audit/flow_tree.md]
E --> I[docs/audit/doc_alignment.md]
C --> B
D --> B
E --> B
```
### 执行流程
1. `run_audit.py` 作为主入口，初始化扫描器并依次调用三个分析器
2. `scanner.py` 递归遍历仓库，构建文件元信息列表（路径、大小、类型）
3. 各分析器接收扫描结果，执行各自的分析逻辑，输出 Markdown 报告
4. 所有报告写入 `docs/audit/` 目录
## 组件与接口
### 1. 仓库扫描器 (`scripts/audit/scanner.py`)
负责递归遍历仓库文件系统，返回结构化的文件元信息。
```python
@dataclass
class FileEntry:
"""单个文件/目录的元信息"""
rel_path: str # 相对于仓库根目录的路径
is_dir: bool # 是否为目录
size_bytes: int # 文件大小（目录为 0）
extension: str # 文件扩展名（小写，含点号）
is_empty_dir: bool # 是否为空目录
EXCLUDED_PATTERNS: list[str] = [
".git", "__pycache__", ".pytest_cache",
"*.pyc", ".kiro",
]
def scan_repo(root: Path, exclude: list[str] = EXCLUDED_PATTERNS) -> list[FileEntry]:
"""递归扫描仓库，返回所有文件和目录的元信息列表"""
...
```
### 2. 文件清单分析器 (`scripts/audit/inventory_analyzer.py`)
对扫描结果进行用途分类和处置标签分配。
```python
# 用途分类枚举
class Category(str, Enum):
CORE_CODE = "核心代码"
CONFIG = "配置"
DATABASE_DEF = "数据库定义"
TEST = "测试"
DOCS = "文档"
SCRIPTS = "脚本工具"
GUI = "GUI"
BUILD_DEPLOY = "构建与部署"
LOG_OUTPUT = "日志与输出"
TEMP_DEBUG = "临时与调试"
OTHER = "其他"
# 处置标签枚举
class Disposition(str, Enum):
KEEP = "保留"
CANDIDATE_DELETE = "候选删除"
CANDIDATE_ARCHIVE = "候选归档"
NEEDS_REVIEW = "待确认"
@dataclass
class InventoryItem:
"""清单条目"""
rel_path: str
category: Category
disposition: Disposition
description: str
def classify(entry: FileEntry) -> InventoryItem:
"""根据路径、扩展名等规则对单个文件/目录进行分类和标签分配"""
...
def build_inventory(entries: list[FileEntry]) -> list[InventoryItem]:
"""批量分类所有文件条目"""
...
def render_inventory_report(items: list[InventoryItem], repo_root: str) -> str:
"""生成 Markdown 格式的文件清单报告"""
...
```
**分类规则（按优先级从高到低）**：
| 路径模式 | 用途分类 | 默认处置 |
|---------|---------|---------|
| `tmp/` 下所有文件 | 临时与调试 | 候选删除/候选归档 |
| `logs/`、`export/` 下的运行时产出 | 日志与输出 | 候选归档 |
| `*.lnk`、`*.rar` 文件 | 其他 | 候选删除 |
| 空目录（如 `Deleded & backup/`） | 其他 | 候选删除 |
| `tasks/`、`loaders/`、`scd/`、`orchestration/`、`quality/`、`models/`、`utils/`、`api/` | 核心代码 | 保留 |
| `config/` | 配置 | 保留 |
| `database/*.sql`、`database/migrations/` | 数据库定义 | 保留 |
| `database/*.py` | 核心代码 | 保留 |
| `tests/` | 测试 | 保留 |
| `docs/` | 文档 | 保留 |
| `scripts/` 下的 `.py` 文件 | 脚本工具 | 保留/待确认 |
| `gui/` | GUI | 保留 |
| `setup.py`、`build_exe.py`、`*.bat`、`*.sh`、`*.ps1` | 构建与部署 | 保留 |
| 根目录散落文件（`Prompt用.md`、`Untitled`、`fix_symbols.py` 等） | 其他 | 待确认 |
### 3. 流程树分析器 (`scripts/audit/flow_analyzer.py`)
通过静态分析 Python 源码的 `import` 语句和类继承关系，构建从入口到末端模块的调用树。
```python
@dataclass
class FlowNode:
"""流程树节点"""
name: str # 节点名称（模块名/类名/函数名）
source_file: str # 所在源文件路径
node_type: str # 类型：entry/module/class/function
children: list["FlowNode"]
def parse_imports(filepath: Path) -> list[str]:
"""使用 ast 模块解析 Python 文件的 import 语句，返回被导入的本地模块列表"""
...
def build_flow_tree(repo_root: Path, entry_file: str) -> FlowNode:
"""从指定入口文件出发，递归追踪 import 链，构建流程树"""
...
def find_orphan_modules(repo_root: Path, all_entries: list[FileEntry], reachable: set[str]) -> list[str]:
"""找出未被任何入口直接或间接引用的 Python 模块"""
...
def render_flow_report(trees: list[FlowNode], orphans: list[str], repo_root: str) -> str:
"""生成 Markdown 格式的流程树报告（含 Mermaid 图和缩进文本）"""
...
```
**入口点识别**：
- CLI 入口：`cli/main.py` → `main()` 函数
- GUI 入口：`gui/main.py` → `main()` 函数
- 批处理入口：`run_etl.bat`、`run_gui.bat`、`run_ods.bat` → 解析其中的 `python` 命令
- 运维脚本：`scripts/*.py` → 各自的 `if __name__ == "__main__"` 块
**静态分析策略**：
- 使用 Python `ast` 模块解析源文件，提取 `import` 和 `from ... import` 语句
- 仅追踪项目内部模块（排除标准库和第三方包）
- 通过 `orchestration/task_registry.py` 的注册语句识别所有任务类及其源文件
- 通过类继承关系（`BaseTask`、`BaseLoader`、`BaseDwsTask` 等）识别任务和加载器层级
### 4. 文档对齐分析器 (`scripts/audit/doc_alignment_analyzer.py`)
检查文档与代码之间的映射关系、过期点、冲突点和缺失点。
```python
@dataclass
class DocMapping:
"""文档与代码的映射关系"""
doc_path: str # 文档文件路径
doc_topic: str # 文档主题
related_code: list[str] # 关联的代码文件/模块
status: str # 状态：aligned/stale/conflict/orphan
@dataclass
class AlignmentIssue:
"""对齐问题"""
doc_path: str
issue_type: str # stale/conflict/missing
description: str
related_code: str
def scan_docs(repo_root: Path) -> list[str]:
"""扫描所有文档文件路径"""
...
def extract_code_references(doc_path: Path) -> list[str]:
"""从文档中提取代码引用（文件路径、类名、函数名、表名等）"""
...
def check_reference_validity(ref: str, repo_root: Path) -> bool:
"""检查文档中的代码引用是否仍然有效"""
...
def find_undocumented_modules(repo_root: Path, documented: set[str]) -> list[str]:
"""找出缺少文档的核心代码模块"""
...
def check_ddl_vs_dictionary(repo_root: Path) -> list[AlignmentIssue]:
"""比对 DDL 文件与数据字典文档的覆盖度"""
...
def check_api_samples_vs_parsers(repo_root: Path) -> list[AlignmentIssue]:
"""比对 API 响应样本与 ODS 表结构/解析器的一致性"""
...
def render_alignment_report(mappings: list[DocMapping], issues: list[AlignmentIssue], repo_root: str) -> str:
"""生成 Markdown 格式的文档对齐报告"""
...
```
**文档来源识别**：
- `docs/` 目录下的 `.md`、`.txt`、`.csv` 文件
- 根目录的 `README.md`
- `开发笔记/` 目录
- 各模块内的 `README.md`（`gui/README.md`、`fetch-test/README.md`）
- `.kiro/steering/` 下的引导文件
- `docs/test-json-doc/` 下的 API 响应样本及分析文档
**对齐检查策略**：
- 过期点检测：文档中引用的文件路径、类名、函数名在代码中已不存在
- 冲突点检测：DDL 中的表/字段定义与数据字典文档不一致；API 样本字段与解析器不匹配
- 缺失点检测：核心代码模块（`tasks/`、`loaders/`、`orchestration/` 等）缺少对应文档
### 5. 审计主入口 (`scripts/audit/run_audit.py`)
```python
def run_audit(repo_root: Path | None = None) -> None:
"""执行完整审计流程，生成三份报告到 docs/audit/"""
...
if __name__ == "__main__":
run_audit()
```
## 数据模型
### FileEntry（文件元信息）
| 字段 | 类型 | 说明 |
|------|------|------|
| `rel_path` | `str` | 相对路径 |
| `is_dir` | `bool` | 是否为目录 |
| `size_bytes` | `int` | 文件大小 |
| `extension` | `str` | 扩展名 |
| `is_empty_dir` | `bool` | 是否为空目录 |
### InventoryItem（清单条目）
| 字段 | 类型 | 说明 |
|------|------|------|
| `rel_path` | `str` | 相对路径 |
| `category` | `Category` | 用途分类 |
| `disposition` | `Disposition` | 处置标签 |
| `description` | `str` | 简要说明 |
### FlowNode（流程树节点）
| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | `str` | 节点名称 |
| `source_file` | `str` | 源文件路径 |
| `node_type` | `str` | 节点类型 |
| `children` | `list[FlowNode]` | 子节点列表 |
### DocMapping / AlignmentIssue（文档对齐）
| 字段 | 类型 | 说明 |
|------|------|------|
| `doc_path` | `str` | 文档路径 |
| `doc_topic` / `issue_type` | `str` | 主题/问题类型 |
| `related_code` | `list[str]` / `str` | 关联代码 |
| `status` / `description` | `str` | 状态/描述 |
## 正确性属性
*属性（Property）是指在系统所有合法执行路径上都应成立的特征或行为——本质上是对"系统应该做什么"的形式化陈述。属性是连接人类可读规格说明与机器可验证正确性保证之间的桥梁。*
### Property 1: classify 完整性
*对于任意* `FileEntry`，`classify` 函数返回的 `InventoryItem` 的 `category` 字段应属于 `Category` 枚举，`disposition` 字段应属于 `Disposition` 枚举，且 `description` 字段为非空字符串。
**Validates: Requirements 1.2, 1.3**
### Property 2: 清单渲染完整性
*对于任意* `InventoryItem` 列表，`render_inventory_report` 生成的 Markdown 文本中，每个条目对应的行应包含该条目的 `rel_path`、`category.value`、`disposition.value` 和 `description` 四个字段。
**Validates: Requirements 1.4**
### Property 3: 空目录标记为候选删除
*对于任意* `is_empty_dir=True` 的 `FileEntry`，`classify` 返回的 `disposition` 应为 `Disposition.CANDIDATE_DELETE`。
**Validates: Requirements 1.5**
### Property 4: .lnk/.rar 文件标记为候选删除
*对于任意* 扩展名为 `.lnk` 或 `.rar` 的 `FileEntry`，`classify` 返回的 `disposition` 应为 `Disposition.CANDIDATE_DELETE`。
**Validates: Requirements 1.6**
### Property 5: tmp/ 下文件处置范围
*对于任意* `rel_path` 以 `tmp/` 开头的 `FileEntry`，`classify` 返回的 `disposition` 应为 `Disposition.CANDIDATE_DELETE` 或 `Disposition.CANDIDATE_ARCHIVE` 之一。
**Validates: Requirements 1.7**
### Property 6: 运行时产出目录标记为候选归档
*对于任意* `rel_path` 以 `logs/` 或 `export/` 开头且非 `__init__.py` 的 `FileEntry`，`classify` 返回的 `disposition` 应为 `Disposition.CANDIDATE_ARCHIVE`。
**Validates: Requirements 1.8**
### Property 7: 扫描器排除规则
*对于任意* 文件树，`scan_repo` 返回的 `FileEntry` 列表中不应包含 `rel_path` 匹配排除模式（`.git`、`__pycache__`、`.pytest_cache`）的条目。
**Validates: Requirements 1.1**
### Property 8: 清单按分类分组
*对于任意* `InventoryItem` 列表，`render_inventory_report` 生成的 Markdown 中，同一 `Category` 的条目应连续出现（即按分类分组排列）。
**Validates: Requirements 1.10**
### Property 9: 流程树节点 source_file 有效性
*对于任意* `FlowNode` 树中的节点，`source_file` 字段应为非空字符串，且对应的文件在仓库中实际存在。
**Validates: Requirements 2.7**
### Property 10: 孤立模块检测正确性
*对于任意* 文件集合和可达模块集合，`find_orphan_modules` 返回的孤立模块列表中的每个模块都不应出现在可达集合中，且可达集合中的每个模块都不应出现在孤立列表中。
**Validates: Requirements 2.8**
### Property 11: 过期引用检测
*对于任意* 文档中提取的代码引用，若该引用指向的文件路径在仓库中不存在，则 `check_reference_validity` 应返回 `False`。
**Validates: Requirements 3.3**
### Property 12: 缺失文档检测
*对于任意* 核心代码模块集合和已文档化模块集合，`find_undocumented_modules` 返回的缺失列表应恰好等于核心模块集合与已文档化集合的差集。
**Validates: Requirements 3.5**
### Property 13: 统计摘要一致性
*对于任意* 报告的统计摘要，各分类/标签的计数之和应等于对应条目列表的总长度。
**Validates: Requirements 4.5, 4.6, 4.7**
### Property 14: 报告头部元信息
*对于任意* 报告输出，头部应包含一个符合 ISO 格式的时间戳字符串和仓库根目录路径字符串。
**Validates: Requirements 4.2**
### Property 15: 写操作仅限 docs/audit/
*对于任意* 审计执行过程，所有文件写操作的目标路径应以 `docs/audit/` 为前缀。
**Validates: Requirements 5.2**
### Property 16: 文档对齐报告分区完整性
*对于任意* `render_alignment_report` 的输出，Markdown 文本应包含"映射关系"、"过期点"、"冲突点"、"缺失点"四个分区标题。
**Validates: Requirements 3.8**
## 错误处理
| 场景 | 处理方式 |
|------|---------|
| 文件读取权限不足 | 记录警告到报告的"错误"分区，跳过该文件，继续处理 |
| Python 源文件语法错误（`ast.parse` 失败） | 记录警告，将该文件标记为"待确认"，不中断流程树构建 |
| 文档中的代码引用格式无法解析 | 跳过该引用，不产生误报 |
| DDL 文件 SQL 语法不规范 | 使用正则提取 `CREATE TABLE` 和列定义，容忍非标准语法 |
| `docs/audit/` 目录创建失败 | 抛出异常并终止，因为无法输出报告 |
| 编码问题（非 UTF-8 文件） | 尝试 `utf-8` → `gbk` → `latin-1` 回退读取，记录编码警告 |
## 测试策略
### 测试框架
- 单元测试与属性测试均使用 `pytest`
- 属性测试库：`hypothesis`（Python 生态最成熟的属性测试框架）
- 测试文件位于 `tests/unit/test_audit_*.py`
### 单元测试
针对具体示例和边界情况：
- 扫描器对实际仓库子集的遍历结果
- classify 对已知文件路径的分类正确性（如 `tmp/hebing.py` → 临时与调试/候选删除）
- 入口点识别对实际仓库的结果
- DDL 与数据字典的比对结果
- 文件读取失败时的容错行为
- `docs/audit/` 目录不存在时的自动创建
### 属性测试
每个正确性属性对应一个属性测试，使用 `hypothesis` 生成随机输入：
- 每个属性测试至少运行 100 次迭代
- 每个测试用注释标注对应的设计属性编号
- 标注格式：**Feature: repo-audit, Property {N}: {属性标题}**
**生成器策略**：
- `FileEntry` 生成器：随机路径（含各种扩展名、目录层级）、随机大小、随机 is_dir/is_empty_dir
- `InventoryItem` 生成器：随机 Category/Disposition 组合、随机描述文本
- `FlowNode` 生成器：随机树结构（限制深度和宽度）
- 文件树生成器：构造临时目录结构用于扫描器测试

90
.kiro/specs/repo-audit/requirements.md Normal file
View File

@@ -0,0 +1,90 @@
# 需求文档：仓库治理只读审计
## 简介
对飞球 ETL 系统 (etl-billiards) 仓库进行全面的只读审计分析，产出三份结构化报告：文件/目录清单（含处置建议）、项目流程树（从入口到末端逻辑）、文档对齐报告（文档与代码的映射关系）。本阶段不修改任何文件，所有处置决策留待用户逐一确认后再执行。
## 术语表
- **审计脚本 (Audit_Script)**：执行只读分析并生成报告的 Python 脚本集合
- **文件清单 (File_Inventory)**：按用途归类的仓库文件与目录列表，每项附带处置标签
- **处置标签 (Disposition_Tag)**：对文件/目录的处置建议，取值为：保留、候选删除、候选归档、待确认
- **流程树 (Flow_Tree)**：从程序入口出发，沿调用链展开到各子模块/子逻辑的树状结构
- **文档对齐报告 (Doc_Alignment_Report)**：文档与代码之间映射关系的分析报告，包含过期点、冲突点、缺失点
- **入口 (Entry_Point)**：程序的顶层启动点，如 `cli/main.py`、`gui/main.py`、`scripts/*.py`
- **ODS/DWD/DWS**：数据仓库三层架构——操作数据存储层/明细数据层/数据服务层
- **SCD2**：缓慢变化维度类型 2，维度表的历史版本管理策略
## 需求
### 需求 1：文件与目录清单生成
**用户故事：** 作为项目维护者，我希望获得一份按用途归类的仓库文件与目录清单，以便了解每个文件的角色并决定其去留。
#### 验收标准
1. WHEN 审计脚本扫描仓库根目录时，THE Audit_Script SHALL 递归遍历所有文件和目录（排除 `.git/`、`__pycache__/`、`.pytest_cache/` 等运行时缓存目录）
2. WHEN 审计脚本处理每个文件或目录时，THE Audit_Script SHALL 将其归入以下用途分类之一：核心代码、配置、数据库定义、测试、文档、脚本工具、GUI、构建与部署、日志与输出、临时与调试、其他
3. WHEN 审计脚本完成归类后，THE Audit_Script SHALL 为每个条目分配一个处置标签（保留/候选删除/候选归档/待确认）
4. WHEN 审计脚本生成清单时，THE File_Inventory SHALL 包含以下字段：相对路径、用途分类、处置标签、简要说明
5. WHEN 审计脚本遇到空目录（如 `database/Deleded & backup/`、`scripts/Deleded & backup/`）时，THE Audit_Script SHALL 将其标记为"候选删除"
6. WHEN 审计脚本遇到 `.lnk` 快捷方式文件或 `.rar` 压缩包时，THE Audit_Script SHALL 将其标记为"候选删除"
7. WHEN 审计脚本遇到 `tmp/` 目录下的文件时，THE Audit_Script SHALL 逐一评估并标记为"候选删除"或"候选归档"
8. WHEN 审计脚本遇到 `logs/`、`export/` 目录下的运行时产出文件时，THE Audit_Script SHALL 将其标记为"候选归档"
9. IF 审计脚本无法确定某文件的用途分类，THEN THE Audit_Script SHALL 将其标记为"待确认"并在说明中注明原因
10. WHEN 审计脚本完成清单生成后，THE File_Inventory SHALL 以 Markdown 表格格式输出，按用途分类分组排列
### 需求 2：项目流程树生成
**用户故事：** 作为项目维护者，我希望获得一份从入口到各子模块的调用流程树，以便理解系统的执行路径和模块依赖关系。
#### 验收标准
1. WHEN 审计脚本分析项目入口时，THE Audit_Script SHALL 识别以下入口点：`cli/main.py`（CLI 主入口）、`gui/main.py`（GUI 主入口）、`scripts/*.py`（运维脚本）、批处理文件（`run_etl.bat`、`run_gui.bat`、`run_ods.bat` 等）
2. WHEN 审计脚本从 CLI 入口展开时，THE Flow_Tree SHALL 追踪以下调用链：CLI 参数解析 → 配置加载 → 调度器初始化 → 任务注册表查询 → 任务执行（Extract → Transform → Load）→ 加载器调用 → 数据库操作
3. WHEN 审计脚本从 GUI 入口展开时，THE Flow_Tree SHALL 追踪以下调用链：GUI 主窗口初始化 → 各面板/组件加载 → 后台工作线程 → CLI 命令构建 → 任务执行
4. WHEN 审计脚本分析任务模块时，THE Flow_Tree SHALL 区分以下任务类型：ODS 抓取任务、DWD 加载任务、DWS 汇总任务、校验任务、Schema 初始化任务
5. WHEN 审计脚本分析加载器模块时，THE Flow_Tree SHALL 区分以下加载器类型：ODS 通用加载器、维度加载器（SCD2）、事实表加载器
6. WHEN 审计脚本生成流程树时，THE Flow_Tree SHALL 以缩进文本或 Mermaid 图的形式输出，层级深度至少达到函数/方法级别
7. WHEN 审计脚本分析模块依赖时，THE Flow_Tree SHALL 标注每个节点所在的源文件路径
8. IF 审计脚本发现存在孤立模块（未被任何入口直接或间接引用的代码文件），THEN THE Flow_Tree SHALL 在报告末尾单独列出这些孤立模块
### 需求 3：文档对齐报告生成
**用户故事：** 作为项目维护者，我希望了解现有文档与代码之间的对齐状况，以便识别过期、冲突和缺失的文档。
#### 验收标准
1. WHEN 审计脚本扫描文档目录时，THE Audit_Script SHALL 识别以下文档来源：`docs/` 目录、`README.md`、`开发笔记/`、各模块内的 `README.md`（如 `gui/README.md`、`fetch-test/README.md`）、`.kiro/steering/` 下的引导文件
2. WHEN 审计脚本分析每份文档时，THE Doc_Alignment_Report SHALL 建立文档与代码模块之间的映射关系
3. WHEN 审计脚本检测到文档引用了已不存在的代码实体（函数、类、文件路径）时，THE Doc_Alignment_Report SHALL 将该引用标记为"过期点"
4. WHEN 审计脚本检测到文档描述与代码实际行为不一致时，THE Doc_Alignment_Report SHALL 将该处标记为"冲突点"
5. WHEN 审计脚本检测到核心代码模块缺少对应文档时，THE Doc_Alignment_Report SHALL 将该模块标记为"缺失点"
6. WHEN 审计脚本分析 DDL 文件（`database/schema_*.sql`）时，THE Doc_Alignment_Report SHALL 检查数据字典文档（`docs/dwd_main_tables_dictionary.md`、`docs/dws_tables_dictionary.md`）是否覆盖了所有表和字段
7. WHEN 审计脚本分析 `docs/test-json-doc/` 下的 API 响应样本时，THE Doc_Alignment_Report SHALL 检查样本字段是否与 ODS 表结构和解析器（`models/parsers.py`）一致
8. WHEN 审计脚本完成分析后，THE Doc_Alignment_Report SHALL 以 Markdown 格式输出，包含以下分区：映射关系表、过期点列表、冲突点列表、缺失点列表
### 需求 4：报告输出与格式规范
**用户故事：** 作为项目维护者，我希望审计报告以统一、可读的格式输出，以便后续逐项决策和执行。
#### 验收标准
1. THE Audit_Script SHALL 将三份报告输出到 `docs/audit/` 目录下，文件名分别为 `file_inventory.md`、`flow_tree.md`、`doc_alignment.md`
2. THE Audit_Script SHALL 在每份报告的头部包含生成时间戳和仓库根目录路径
3. WHEN 报告引用代码标识符（类名、函数名、变量名、文件路径）时，THE Audit_Script SHALL 保留英文原文，使用行内代码格式（反引号）
4. WHEN 报告包含说明性文字时，THE Audit_Script SHALL 使用简体中文
5. THE Audit_Script SHALL 在文件清单报告末尾附加统计摘要：各用途分类的文件数量、各处置标签的文件数量
6. THE Audit_Script SHALL 在流程树报告末尾附加统计摘要：入口点数量、任务数量、加载器数量、孤立模块数量
7. THE Audit_Script SHALL 在文档对齐报告末尾附加统计摘要：过期点数量、冲突点数量、缺失点数量
### 需求 5：只读安全保障
**用户故事：** 作为项目维护者，我希望审计过程不会修改仓库中的任何文件，以确保分析阶段的安全性。
#### 验收标准
1. THE Audit_Script SHALL 仅执行文件系统的读取操作（读取文件内容、列出目录、获取文件元信息）
2. THE Audit_Script SHALL 仅在 `docs/audit/` 目录下创建新文件，该目录为报告专用输出目录
3. IF 审计脚本在执行过程中遇到权限错误或文件读取失败，THEN THE Audit_Script SHALL 在报告中记录该错误并继续处理其余文件
4. THE Audit_Script SHALL 在运行前检查 `docs/audit/` 目录是否存在，若不存在则创建该目录

118
.kiro/specs/repo-audit/tasks.md Normal file
View File

@@ -0,0 +1,118 @@
# 实施计划：仓库治理只读审计
## 概述
将设计文档中的审计脚本拆分为增量式编码任务。每个任务构建在前一个任务之上，最终产出可运行的审计工具集。所有脚本位于 `scripts/audit/` 目录，报告输出到 `docs/audit/`。
## 任务
- [x] 1. 搭建审计脚本骨架和数据模型
- [x] 1.1 创建 `scripts/audit/__init__.py` 和数据模型定义
- 定义 `FileEntry` dataclass（`rel_path`, `is_dir`, `size_bytes`, `extension`, `is_empty_dir`）
- 定义 `Category` 和 `Disposition` 枚举
- 定义 `InventoryItem` dataclass
- 定义 `FlowNode` dataclass
- 定义 `DocMapping` 和 `AlignmentIssue` dataclass
- _Requirements: 1.2, 1.3, 1.4, 2.7, 3.2, 3.3_
- [x] 1.2 编写 classify 完整性属性测试
- **Property 1: classify 完整性**
- **Validates: Requirements 1.2, 1.3**
- [x] 2. 实现仓库扫描器
- [x] 2.1 创建 `scripts/audit/scanner.py`
- 实现 `EXCLUDED_PATTERNS` 常量和排除匹配逻辑
- 实现 `scan_repo(root, exclude)` 函数：递归遍历文件系统，返回 `list[FileEntry]`
- 处理空目录检测（`is_empty_dir`）
- 处理文件读取权限错误（跳过并记录）
- _Requirements: 1.1, 5.1, 5.3_
- [x] 2.2 编写扫描器排除规则属性测试
- **Property 7: 扫描器排除规则**
- **Validates: Requirements 1.1**
- [x] 3. 实现文件清单分析器
- [x] 3.1 创建 `scripts/audit/inventory_analyzer.py`
- 实现 `classify(entry: FileEntry) -> InventoryItem` 函数，包含完整分类规则表
- 实现 `build_inventory(entries) -> list[InventoryItem]` 批量分类函数
- 实现 `render_inventory_report(items, repo_root) -> str` Markdown 渲染函数
- 包含统计摘要生成（各分类/标签计数）
- 注意：需求 1.8 仅覆盖 `logs/` 和 `export/` 目录（不含 `reports/`）
- _Requirements: 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 4.2, 4.5_
- [x] 3.2 编写 classify 分类规则属性测试
- **Property 3: 空目录标记为候选删除**
- **Property 4: .lnk/.rar 文件标记为候选删除**
- **Property 5: tmp/ 下文件处置范围**
- **Property 6: 运行时产出目录标记为候选归档**（仅 `logs/`、`export/`）
- **Validates: Requirements 1.5, 1.6, 1.7, 1.8**
- [x] 3.3 编写清单渲染属性测试
- **Property 2: 清单渲染完整性**
- **Property 8: 清单按分类分组**
- **Validates: Requirements 1.4, 1.10**
- [x] 4. 检查点 - 确保文件清单模块测试通过
- 确保所有测试通过，如有疑问请向用户确认。
- [x] 5. 实现流程树分析器
- [x] 5.1 创建 `scripts/audit/flow_analyzer.py`
- 实现 `parse_imports(filepath)` 函数：使用 `ast` 模块解析 Python 文件的 import 语句
- 实现 `build_flow_tree(repo_root, entry_file)` 函数：从入口递归追踪 import 链
- 实现 `find_orphan_modules(repo_root, all_entries, reachable)` 函数
- 实现 `render_flow_report(trees, orphans, repo_root)` 函数：生成 Mermaid 图和缩进文本
- 包含入口点识别逻辑（CLI、GUI、批处理、运维脚本）
- 包含任务类型和加载器类型区分逻辑
- 包含统计摘要生成
- _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 4.6_
- [x] 5.2 编写流程树属性测试
- **Property 9: 流程树节点 source_file 有效性**
- **Property 10: 孤立模块检测正确性**
- **Validates: Requirements 2.7, 2.8**
- [x] 6. 实现文档对齐分析器
- [x] 6.1 创建 `scripts/audit/doc_alignment_analyzer.py`
- 实现 `scan_docs(repo_root)` 函数：扫描所有文档来源
- 实现 `extract_code_references(doc_path)` 函数：从文档提取代码引用
- 实现 `check_reference_validity(ref, repo_root)` 函数
- 实现 `find_undocumented_modules(repo_root, documented)` 函数
- 实现 `check_ddl_vs_dictionary(repo_root)` 函数：DDL 与数据字典比对
- 实现 `check_api_samples_vs_parsers(repo_root)` 函数：API 样本与解析器比对
- 实现 `render_alignment_report(mappings, issues, repo_root)` 函数
- 包含统计摘要生成
- _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 4.7_
- [x] 6.2 编写文档对齐属性测试
- **Property 11: 过期引用检测**
- **Property 12: 缺失文档检测**
- **Property 16: 文档对齐报告分区完整性**
- **Validates: Requirements 3.3, 3.5, 3.8**
- [x] 7. 检查点 - 确保流程树和文档对齐模块测试通过
- 确保所有测试通过，如有疑问请向用户确认。
- [x] 8. 实现审计主入口和报告输出
- [x] 8.1 创建 `scripts/audit/run_audit.py`
- 实现 `run_audit(repo_root)` 主函数：依次调用扫描器和三个分析器
- 实现 `docs/audit/` 目录检查与创建逻辑
- 实现报告头部元信息（时间戳、仓库路径）注入
- 实现三份报告的文件写入
- 添加 `if __name__ == "__main__"` 入口
- _Requirements: 4.1, 4.2, 4.3, 4.4, 5.2, 5.4_
- [x] 8.2 编写报告输出属性测试
- **Property 13: 统计摘要一致性**
- **Property 14: 报告头部元信息**
- **Property 15: 写操作仅限 docs/audit/**
- **Validates: Requirements 4.2, 4.5, 4.6, 4.7, 5.2**
- [x] 9. 最终检查点 - 确保所有测试通过
- 确保所有测试通过，如有疑问请向用户确认。
## 备注
- 标记 `*` 的子任务为可选，可跳过以加速 MVP 交付
- 每个任务引用了具体的需求编号，便于追溯
- 属性测试使用 `hypothesis` 库，每个测试至少 100 次迭代
- 单元测试验证具体示例和边界情况，属性测试验证通用正确性

1
.kiro/specs/scheduler-refactor/.config.kiro Normal file
View File

@@ -0,0 +1 @@
{"generationMode": "requirements-first"}

462
.kiro/specs/scheduler-refactor/design.md Normal file
View File

@@ -0,0 +1,462 @@
# 设计文档：ETL 调度器重构
## 概述
本次重构将 `ETLScheduler`（约 900 行，职责混乱的"上帝类"）拆分为三层清晰的架构：
1. **CLI 层**（`cli/main.py`）：参数解析、配置加载、资源创建与释放
2. **PipelineRunner**（`orchestration/pipeline_runner.py`）：管道定义、层→任务映射、校验编排
3. **TaskExecutor**（`orchestration/task_executor.py`）：单任务执行、游标管理、运行记录
核心设计原则：**单个任务是最小执行单元，管道模式只是"调度拼接"**。每层通过依赖注入接收协作对象，不自行创建资源，便于独立测试。
## 架构
### 分层架构图
```mermaid
graph TD
CLI["CLI 层<br/>cli/main.py<br/>参数解析 · 配置加载 · 资源管理"]
PR["PipelineRunner<br/>orchestration/pipeline_runner.py<br/>管道定义 · 层→任务映射 · 校验编排"]
TE["TaskExecutor<br/>orchestration/task_executor.py<br/>单任务执行 · 游标管理 · 运行记录"]
TR["TaskRegistry<br/>orchestration/task_registry.py<br/>任务注册 · 元数据查询"]
CM["CursorManager"]
RT["RunTracker"]
DB["DatabaseConnection"]
API["APIClient"]
CLI -->|"创建并注入"| PR
CLI -->|"创建并注入"| TE
CLI -->|"管理生命周期"| DB
CLI -->|"管理生命周期"| API
PR -->|"委托执行"| TE
PR -->|"查询任务"| TR
TE -->|"查询元数据"| TR
TE -->|"管理游标"| CM
TE -->|"记录运行"| RT
TE -->|"使用"| DB
TE -->|"使用"| API
```
### 调用流程
**传统模式**（`--tasks`）：
```
CLI → TaskExecutor.run_tasks([task_codes]) → TaskExecutor._run_single_task() × N
```
**管道模式**（`--pipeline`）：
```
CLI → PipelineRunner.run(pipeline, processing_mode, ...)
→ PipelineRunner._resolve_tasks(layers)
→ TaskExecutor.run_tasks([resolved_tasks])
→ [可选] PipelineRunner._run_verification(layers, ...)
```
## 组件与接口
### TaskExecutor
负责单任务执行的完整生命周期。从原 `ETLScheduler` 中提取 `_run_single_task`、`_execute_fetch`、`_execute_ingest`、`_execute_ods_record_and_load`、`_run_utility_task` 等方法。
```python
class TaskExecutor:
def __init__(
self,
config: AppConfig,
db_ops: DatabaseOperations,
api_client: APIClient,
cursor_mgr: CursorManager,
run_tracker: RunTracker,
task_registry: TaskRegistry,
logger: logging.Logger,
):
...
def run_tasks(
self,
task_codes: list[str],
data_source: str = "hybrid", # online / offline / hybrid
) -> list[dict[str, Any]]:
"""批量执行任务列表，返回每个任务的结果。"""
...
def run_single_task(
self,
task_code: str,
run_uuid: str,
store_id: int,
data_source: str = "hybrid",
) -> dict[str, Any]:
"""执行单个任务的完整生命周期。"""
...
```
关键变化：
- `data_source` 作为显式参数传入，不再读取 `self.pipeline_flow` 全局状态
- 工具类任务判断通过 `TaskRegistry.get_metadata(task_code)` 查询，不再硬编码
- 不自行创建 `DatabaseConnection` 或 `APIClient`
### PipelineRunner
负责管道编排。从原 `ETLScheduler` 中提取 `run_pipeline_with_verification`、`_run_layer_verification`、`_get_tasks_for_layers` 等方法。
```python
class PipelineRunner:
# 管道定义（从 scheduler.py 模块级常量迁移至此）
PIPELINE_LAYERS: dict[str, list[str]] = {
"api_ods": ["ODS"],
"api_ods_dwd": ["ODS", "DWD"],
"api_full": ["ODS", "DWD", "DWS", "INDEX"],
"ods_dwd": ["DWD"],
"dwd_dws": ["DWS"],
"dwd_dws_index": ["DWS", "INDEX"],
"dwd_index": ["INDEX"],
}
def __init__(
self,
config: AppConfig,
task_executor: TaskExecutor,
task_registry: TaskRegistry,
db_conn: DatabaseConnection,
api_client: APIClient,
logger: logging.Logger,
):
...
def run(
self,
pipeline: str,
processing_mode: str = "increment_only",
data_source: str = "hybrid",
window_start: datetime | None = None,
window_end: datetime | None = None,
window_split: str | None = None,
task_codes: list[str] | None = None,
fetch_before_verify: bool = False,
verify_tables: list[str] | None = None,
) -> dict[str, Any]:
"""执行管道，返回汇总结果。"""
...
def _resolve_tasks(self, layers: list[str]) -> list[str]:
"""根据层列表解析任务代码，优先查询 TaskRegistry 元数据。"""
...
def _run_verification(self, layers, window_start, window_end, ...):
"""执行后置校验（从原 _run_layer_verification 迁移）。"""
...
```
### TaskRegistry（增强）
在现有注册功能基础上增加元数据支持。
```python
@dataclass
class TaskMeta:
"""任务元数据"""
task_class: type
requires_db_config: bool = True
layer: str | None = None # "ODS" / "DWD" / "DWS" / "INDEX" / None
task_type: str = "etl" # "etl" / "utility" / "verification"
class TaskRegistry:
def __init__(self):
self._tasks: dict[str, TaskMeta] = {}
def register(
self,
task_code: str,
task_class: type,
requires_db_config: bool = True,
layer: str | None = None,
task_type: str = "etl",
):
"""注册任务类及其元数据。"""
self._tasks[task_code.upper()] = TaskMeta(
task_class=task_class,
requires_db_config=requires_db_config,
layer=layer,
task_type=task_type,
)
def create_task(self, task_code, config, db_connection, api_client, logger):
"""创建任务实例（保持原有接口不变）。"""
...
def get_metadata(self, task_code: str) -> TaskMeta | None:
"""查询任务元数据。"""
...
def get_tasks_by_layer(self, layer: str) -> list[str]:
"""获取指定层的所有任务代码。"""
...
def is_utility_task(self, task_code: str) -> bool:
"""判断是否为工具类任务（不需要游标/运行记录）。"""
meta = self.get_metadata(task_code)
return meta is not None and not meta.requires_db_config
def get_all_task_codes(self) -> list[str]:
"""获取所有已注册的任务代码（保持原有接口）。"""
...
```
### CLI 层重构
```python
# cli/main.py 核心流程伪代码
def main():
args = parse_args()
config = AppConfig.load(build_cli_overrides(args))
# 资源创建
db_conn = DatabaseConnection(...)
api_client = APIClient(...)
try:
# 组装依赖
db_ops = DatabaseOperations(db_conn)
cursor_mgr = CursorManager(db_conn)
run_tracker = RunTracker(db_conn)
registry = default_registry
executor = TaskExecutor(config, db_ops, api_client, cursor_mgr, run_tracker, registry, logger)
if args.pipeline:
runner = PipelineRunner(config, executor, registry, db_conn, api_client, logger)
runner.run(
pipeline=args.pipeline,
processing_mode=args.processing_mode,
data_source=resolve_data_source(args),
...
)
else:
task_codes = config.get("run.tasks")
data_source = resolve_data_source(args)
executor.run_tasks(task_codes, data_source=data_source)
finally:
db_conn.close()
```
### 参数映射
| 旧参数 | 旧值 | 新参数 | 新值 | 说明 |
|--------|------|--------|------|------|
| `--pipeline-flow` | `FULL` | `--data-source` | `hybrid` | 在线抓取 + 本地入库 |
| `--pipeline-flow` | `FETCH_ONLY` | `--data-source` | `online` | 仅在线抓取落盘 |
| `--pipeline-flow` | `INGEST_ONLY` | `--data-source` | `offline` | 仅本地清洗入库 |
### 静态方法归位
| 方法 | 原位置 | 新位置 | 理由 |
|------|--------|--------|------|
| `_map_run_status` | `ETLScheduler` | `RunTracker` | 状态映射是运行记录的职责 |
| `_filter_verify_tables` | `ETLScheduler` | `tasks/verification/` 模块 | 校验表过滤是校验模块的职责 |
## 数据模型
### TaskMeta（新增）
```python
@dataclass
class TaskMeta:
task_class: type # 任务类引用
requires_db_config: bool = True # 是否需要数据库任务配置（游标/运行记录）
layer: str | None = None # 所属层："ODS"/"DWD"/"DWS"/"INDEX"/None
task_type: str = "etl" # 任务类型："etl"/"utility"/"verification"
```
### DataSource 枚举
```python
class DataSource(str, Enum):
ONLINE = "online" # 仅在线抓取（原 FETCH_ONLY）
OFFLINE = "offline" # 仅本地入库（原 INGEST_ONLY）
HYBRID = "hybrid" # 抓取 + 入库（原 FULL）
```
### 配置键映射
| 旧键 | 新键 | 默认值 |
|------|------|--------|
| `app.timezone` | `app.timezone` | `Asia/Shanghai`（原 `Asia/Taipei`） |
| `pipeline.flow` | `run.data_source` | `hybrid` |
| `pipeline.fetch_root` | `io.fetch_root` | `export/JSON` |
| `pipeline.ingest_source_dir` | `io.ingest_source_dir` | `""` |
### 任务执行结果（不变）
```python
# 单任务结果
{
"task_code": str,
"status": str, # "SUCCESS" / "FAIL" / "SKIP"
"counts": {
"fetched": int,
"inserted": int,
"updated": int,
"skipped": int,
"errors": int,
},
"window": {"start": datetime, "end": datetime, "minutes": int} | None,
"dump_dir": str | None,
}
# 管道结果
{
"status": str,
"pipeline": str,
"layers": list[str],
"results": list[dict], # 各任务结果
"verification_summary": dict | None, # 校验汇总
}
```
## 正确性属性
*正确性属性是一种在系统所有有效执行中都应成立的特征或行为——本质上是对系统应做什么的形式化陈述。属性是人类可读规格与机器可验证正确性保证之间的桥梁。*
### Property 1：data_source 参数决定执行路径
*对于任意* 任务代码和任意 `data_source` 值（online/offline/hybrid），TaskExecutor 执行该任务时，抓取阶段执行当且仅当 `data_source` 为 `online` 或 `hybrid`，入库阶段执行当且仅当 `data_source` 为 `offline` 或 `hybrid`。
**验证：需求 1.2**
### Property 2：成功任务推进游标
*对于任意* 非工具类任务，当任务执行成功且返回包含有效 `window`（含 `start` 和 `end`）的结果时，CursorManager.advance 应被调用且参数与返回的窗口一致。
**验证：需求 1.3**
### Property 3：失败任务标记 FAIL 并重新抛出
*对于任意* 非工具类任务，当任务执行过程中抛出异常时，RunTracker 应被更新为 FAIL 状态，且该异常应被重新抛出给调用方。
**验证：需求 1.4**
### Property 4：工具类任务由元数据决定
*对于任意* 任务代码，TaskExecutor 是否跳过游标管理和运行记录，取决于 TaskRegistry 中该任务的 `requires_db_config` 元数据。当 `requires_db_config=False` 时跳过，否则执行完整生命周期。
**验证：需求 1.6, 4.2**
### Property 5：管道名称→层列表映射
*对于任意* 有效的管道名称，PipelineRunner 解析出的层列表应与 `PIPELINE_LAYERS` 字典中的定义完全一致。
**验证：需求 2.1**
### Property 6：processing_mode 控制执行流程
*对于任意* processing_mode 值，增量 ETL 执行当且仅当模式包含 `increment`（即 `increment_only` 或 `increment_verify`），校验流程执行当且仅当模式包含 `verify`（即 `verify_only` 或 `increment_verify`）。
**验证：需求 2.3, 2.4**
### Property 7：管道结果汇总完整性
*对于任意* 一组任务执行结果，PipelineRunner 返回的汇总字典应包含 `status`、`pipeline`、`layers`、`results` 字段，且 `results` 列表长度等于实际执行的任务数。
**验证：需求 2.6**
### Property 8：TaskRegistry 元数据 round-trip
*对于任意* 任务代码、任务类和元数据组合（requires_db_config、layer、task_type），注册后通过 `get_metadata` 查询应返回相同的元数据值。
**验证：需求 4.1**
### Property 9：TaskRegistry 向后兼容默认值
*对于任意* 使用旧接口（仅 task_code 和 task_class）注册的任务，查询元数据应返回 `requires_db_config=True`、`layer=None`、`task_type="etl"`。
**验证：需求 4.4**
### Property 10：按层查询任务
*对于任意* 注册了 `layer` 元数据的任务集合，`get_tasks_by_layer(layer)` 返回的任务代码集合应等于所有 `layer` 匹配的已注册任务代码集合。
**验证：需求 4.3**
### Property 11：pipeline_flow → data_source 映射一致性
*对于任意* 旧 `pipeline_flow` 值（FULL/FETCH_ONLY/INGEST_ONLY），映射到 `data_source` 的结果应与预定义映射表一致：FULL→hybrid、FETCH_ONLY→online、INGEST_ONLY→offline。同样，配置键 `pipeline.flow` 应自动映射到 `run.data_source`。
**验证：需求 8.1, 8.2, 8.3, 5.2, 8.4**
## 错误处理
### TaskExecutor 错误处理
- 任务执行异常：更新 RunTracker 状态为 FAIL（含 error_message），然后重新抛出异常
- 游标推进失败：记录错误日志，不影响任务结果（任务本身已成功）
- 任务配置不存在：返回 `{"status": "SKIP"}` 结果，不抛异常
### PipelineRunner 错误处理
- 单个任务失败：记录错误，继续执行后续任务（与当前行为一致）
- 校验框架未安装：返回 `{"status": "SKIPPED"}` 并记录警告
- 无效管道名称：抛出 `ValueError`
### CLI 错误处理
- 配置加载失败：`SystemExit` 并输出错误信息
- 资源创建失败：`SystemExit` 并输出错误信息
- 执行过程异常：记录错误日志，`finally` 块确保资源释放，返回非零退出码
### 弃用警告
- 使用 Python `warnings.warn(DeprecationWarning)` 发出弃用警告
- 同时在日志中记录映射详情，便于运维排查
## 测试策略
### 单元测试
使用 `pytest` + 现有的 `FakeDB`/`FakeAPI` 测试工具（`tests/unit/task_test_utils.py`）。
**TaskExecutor 测试**：
- 注入 mock 依赖（FakeDB、FakeAPI、mock CursorManager、mock RunTracker）
- 验证成功/失败/跳过三种路径
- 验证工具类任务不触发游标/运行记录
- 验证 data_source 参数正确控制抓取/入库阶段
**PipelineRunner 测试**：
- 注入 mock TaskExecutor
- 验证不同 processing_mode 下的执行流程
- 验证管道→层→任务的解析链
**TaskRegistry 测试**：
- 验证元数据注册和查询
- 验证向后兼容（无元数据注册）
- 验证按层查询
**配置兼容性测试**：
- 验证旧键→新键映射
- 验证优先级规则
- 验证默认值变更
### 属性测试
使用 `hypothesis` 库进行属性测试，每个属性至少运行 100 次迭代。
每个属性测试必须用注释标注对应的设计属性编号：
```python
# Feature: scheduler-refactor, Property 8: TaskRegistry 元数据 round-trip
```
**属性测试覆盖**：
- Property 1: data_source 参数决定执行路径
- Property 2: 成功任务推进游标
- Property 3: 失败任务标记 FAIL 并重新抛出
- Property 4: 工具类任务由元数据决定
- Property 5: 管道名称→层列表映射
- Property 6: processing_mode 控制执行流程
- Property 7: 管道结果汇总完整性
- Property 8: TaskRegistry 元数据 round-trip
- Property 9: TaskRegistry 向后兼容默认值
- Property 10: 按层查询任务
- Property 11: pipeline_flow → data_source 映射一致性

123
.kiro/specs/scheduler-refactor/requirements.md Normal file
View File

@@ -0,0 +1,123 @@
# 需求文档：ETL 调度器重构
## 简介
当前 `orchestration/scheduler.py`（约 900 行）中的 `ETLScheduler` 类承担了过多职责：单任务执行、管道编排、资源管理。CLI 参数命名混乱（`--pipeline` vs `--pipeline-flow` vs `--processing-mode`），全局状态耦合严重，配置键语义重叠。本次重构将调度器拆分为三层架构（CLI → PipelineRunner → TaskExecutor），重新设计参数命名，消除全局状态依赖，使每层可独立测试。
## 术语表
- **TaskExecutor**：任务执行器，负责单个 ETL 任务的执行、游标管理和运行记录
- **PipelineRunner**：管道运行器，负责管道定义、层→任务映射、校验编排
- **TaskRegistry**：任务注册表，管理所有已注册的任务类及其元数据
- **DataSource**：数据源模式，取代原 `pipeline.flow`，表示数据来自在线 API（`online`）、本地 JSON（`offline`）或混合模式（`hybrid`）
- **ProcessingMode**：处理模式，控制 ETL 执行策略（仅增量 / 仅校验 / 增量+校验）
- **Pipeline**：管道，定义一组按层顺序执行的 ETL 任务集合（如 `api_full` = ODS → DWD → DWS → INDEX）
- **CursorManager**：游标管理器，管理任务的时间水位（上次处理到哪里）
- **RunTracker**：运行记录器，在 `etl_admin` Schema 中记录每次任务执行的状态和统计
## 需求
### 需求 1：架构分层 — TaskExecutor（执行层）
**用户故事：** 作为开发者，我希望单任务执行逻辑独立封装在 TaskExecutor 中，以便可以脱离管道上下文独立测试和复用。
#### 验收标准
1. THE TaskExecutor SHALL 封装单个任务的完整执行生命周期：创建运行记录、执行任务、更新游标、记录结果
2. WHEN TaskExecutor 执行一个任务时，THE TaskExecutor SHALL 接收显式的 `data_source` 参数，而非读取全局状态
3. WHEN 任务执行成功且返回有效时间窗口时，THE TaskExecutor SHALL 推进该任务的游标水位
4. WHEN 任务执行过程中发生异常时，THE TaskExecutor SHALL 将运行记录状态更新为 FAIL 并重新抛出异常
5. THE TaskExecutor SHALL 通过构造函数接收 `db_ops`、`api_client`、`cursor_manager`、`run_tracker`、`task_registry` 等依赖，而非自行创建
6. WHEN 执行工具类任务（如 INIT_ODS_SCHEMA）时，THE TaskExecutor SHALL 跳过游标管理和运行记录，直接执行任务
### 需求 2：架构分层 — PipelineRunner（编排层）
**用户故事：** 作为开发者，我希望管道编排逻辑独立封装在 PipelineRunner 中，以便管道定义和校验流程可以独立演进。
#### 验收标准
1. THE PipelineRunner SHALL 根据管道名称解析出需要执行的层列表（如 `api_full` → `["ODS", "DWD", "DWS", "INDEX"]`）
2. WHEN PipelineRunner 执行管道时，THE PipelineRunner SHALL 委托 TaskExecutor 逐个执行任务，而非直接操作数据库或 API
3. WHEN 处理模式为 `verify_only` 时，THE PipelineRunner SHALL 跳过增量 ETL，仅执行校验流程
4. WHEN 处理模式为 `increment_verify` 时，THE PipelineRunner SHALL 先执行增量 ETL，再执行校验流程
5. THE PipelineRunner SHALL 根据层列表自动选择对应的任务代码，支持配置覆盖
6. WHEN 管道执行完成时，THE PipelineRunner SHALL 汇总所有任务的执行结果并返回统一的结果字典
### 需求 3：架构分层 — CLI 层重构
**用户故事：** 作为运维人员，我希望 CLI 参数命名清晰、语义无歧义，以便快速理解和正确使用各种执行模式。
#### 验收标准
1. THE CLI SHALL 将 `--pipeline-flow`（FULL/FETCH_ONLY/INGEST_ONLY）重命名为 `--data-source`（online/offline/hybrid），并保留旧名称作为别名
2. THE CLI SHALL 保留 `--pipeline` 参数用于管道模式，保留 `--tasks` 参数用于传统模式
3. WHEN 用户同时指定 `--pipeline` 和 `--tasks` 时，THE CLI SHALL 将 `--tasks` 作为管道内的任务过滤器
4. THE CLI SHALL 保留 `--processing-mode`（increment_only/verify_only/increment_verify）参数不变
5. WHEN 用户使用旧参数名 `--pipeline-flow` 时，THE CLI SHALL 发出弃用警告并将值映射到新的 `--data-source` 参数
6. THE CLI SHALL 仅负责参数解析和配置加载，将执行逻辑委托给 PipelineRunner 或 TaskExecutor
### 需求 4：任务分类元数据化
**用户故事：** 作为开发者，我希望任务的分类信息（是否需要数据库配置、所属层等）由任务注册表管理，而非硬编码在调度器中。
#### 验收标准
1. THE TaskRegistry SHALL 支持在注册任务时附带元数据（`requires_db_config`、`layer`、`task_type`）
2. WHEN TaskExecutor 需要判断任务是否为工具类任务时，THE TaskExecutor SHALL 查询 TaskRegistry 的元数据，而非检查硬编码集合
3. WHEN PipelineRunner 需要根据层获取任务列表时，THE PipelineRunner SHALL 查询 TaskRegistry 的 `layer` 元数据
4. THE TaskRegistry SHALL 保持向后兼容，无元数据的任务默认为 `requires_db_config=True`、`layer=None`
### 需求 5：配置键重构
**用户故事：** 作为运维人员，我希望配置键命名合理、语义清晰，以便正确配置 ETL 系统的运行参数。
#### 验收标准
1. THE AppConfig SHALL 将 `app.timezone` 默认值从 `Asia/Taipei` 改为 `Asia/Shanghai`
2. THE AppConfig SHALL 将 `pipeline.flow` 配置键重命名为 `run.data_source`，并保留旧键作为兼容别名
3. WHEN 配置中同时存在旧键 `pipeline.flow` 和新键 `run.data_source` 时，THE AppConfig SHALL 优先使用新键的值
4. THE AppConfig SHALL 将 `pipeline.fetch_root` 和 `pipeline.ingest_source_dir` 移至 `io` 命名空间下（`io.fetch_root`、`io.ingest_source_dir`）
### 需求 6：资源管理与生命周期
**用户故事：** 作为开发者，我希望数据库连接和 API 客户端的创建与关闭由 CLI 层统一管理，以便确保资源正确释放。
#### 验收标准
1. THE CLI SHALL 在 `finally` 块中关闭数据库连接和 API 客户端，确保异常情况下资源也能释放
2. THE TaskExecutor SHALL 通过依赖注入接收已创建的数据库连接和 API 客户端，而非自行创建
3. THE PipelineRunner SHALL 通过依赖注入接收已创建的数据库连接和 API 客户端，而非自行创建
4. WHEN CLI 创建资源时，THE CLI SHALL 使用 Python 上下文管理器（`with` 语句）或 `try/finally` 模式管理生命周期
### 需求 7：静态方法归位
**用户故事：** 作为开发者，我希望与调度器无关的静态工具方法移至合适的模块，以便保持类的职责单一。
#### 验收标准
1. THE `_map_run_status` 方法 SHALL 从 ETLScheduler 移至 RunTracker 或独立的工具模块
2. THE `_filter_verify_tables` 方法 SHALL 从 ETLScheduler 移至校验相关模块
3. WHEN 静态方法被移动后，THE 原调用方 SHALL 更新导入路径以引用新位置
### 需求 8：向后兼容与过渡
**用户故事：** 作为运维人员，我希望重构后的系统在过渡期内兼容旧的 CLI 参数和配置键，以便平滑迁移。
#### 验收标准
1. WHEN 用户使用旧参数 `--pipeline-flow FULL` 时，THE CLI SHALL 将其等价映射为 `--data-source hybrid` 并发出弃用警告
2. WHEN 用户使用旧参数 `--pipeline-flow FETCH_ONLY` 时，THE CLI SHALL 将其等价映射为 `--data-source online` 并发出弃用警告
3. WHEN 用户使用旧参数 `--pipeline-flow INGEST_ONLY` 时，THE CLI SHALL 将其等价映射为 `--data-source offline` 并发出弃用警告
4. WHEN 配置文件中使用旧键 `pipeline.flow` 时，THE AppConfig SHALL 自动映射到新键 `run.data_source`
5. THE 系统 SHALL 在日志中记录所有弃用映射，便于运维人员逐步迁移
### 需求 9：可测试性
**用户故事：** 作为开发者，我希望重构后的每一层都可以独立进行单元测试，以便快速验证逻辑正确性。
#### 验收标准
1. THE TaskExecutor SHALL 支持通过注入 mock 依赖（FakeDB、FakeAPI）进行单元测试，无需真实数据库
2. THE PipelineRunner SHALL 支持通过注入 mock TaskExecutor 进行单元测试，无需执行真实任务
3. THE TaskRegistry SHALL 支持在测试中创建独立实例，不依赖全局 `default_registry`
4. WHEN 运行单元测试时，THE 测试 SHALL 验证各层之间的交互契约（调用参数、返回值格式）

147
.kiro/specs/scheduler-refactor/tasks.md Normal file
View File

@@ -0,0 +1,147 @@
# 实现计划：ETL 调度器重构
## 概述
将 `ETLScheduler`（~900 行）拆分为 TaskExecutor（执行层）、PipelineRunner（编排层）、增强版 TaskRegistry（元数据），重构 CLI 参数和配置键，保持向后兼容。采用自底向上的实现顺序：先基础组件，再上层编排，最后 CLI 集成。
## 任务
- [x] 1. 增强 TaskRegistry，支持元数据注册与查询
- [x] 1.1 扩展 TaskRegistry 类，添加 TaskMeta 数据类和元数据相关方法
- 在 `orchestration/task_registry.py` 中添加 `TaskMeta` dataclass（`task_class`、`requires_db_config`、`layer`、`task_type`）
- 修改 `register()` 方法签名，增加可选的 `requires_db_config`、`layer`、`task_type` 参数
- 添加 `get_metadata()`、`get_tasks_by_layer()`、`is_utility_task()` 方法
- 保持 `create_task()` 和 `get_all_task_codes()` 接口不变
- _需求: 4.1, 4.4_
- [x] 1.2 更新所有任务注册调用，添加元数据
- 将原 `NO_DB_CONFIG_TASKS` 硬编码集合中的任务标记为 `requires_db_config=False`
- 为 ODS 任务添加 `layer="ODS"`，DWD 任务添加 `layer="DWD"`，DWS 任务添加 `layer="DWS"`，INDEX 任务添加 `layer="INDEX"`
- 工具类任务标记 `task_type="utility"`，校验类任务标记 `task_type="verification"`
- _需求: 4.1, 4.2, 4.3_
- [x] 1.3 编写 TaskRegistry 属性测试
- **Property 8: TaskRegistry 元数据 round-trip**
- **验证: 需求 4.1**
- [x] 1.4 编写 TaskRegistry 向后兼容和按层查询属性测试
- **Property 9: TaskRegistry 向后兼容默认值**
- **Property 10: 按层查询任务**
- **验证: 需求 4.4, 4.3**
- [x] 2. 配置键重构与向后兼容
- [x] 2.1 修改 `config/defaults.py` 默认值
- 将 `app.timezone` 默认值从 `Asia/Taipei` 改为 `Asia/Shanghai`
- 将 `db.session.timezone` 默认值从 `Asia/Taipei` 改为 `Asia/Shanghai`
- 添加 `run.data_source` 键（默认 `hybrid`）
- 将 `pipeline.fetch_root` 和 `pipeline.ingest_source_dir` 复制到 `io.fetch_root` 和 `io.ingest_source_dir`（保留旧键兼容）
- _需求: 5.1, 5.2, 5.4_
- [x] 2.2 在 `config/settings.py` 的 `_normalize()` 中添加兼容映射逻辑
- 旧键 `pipeline.flow` → 新键 `run.data_source`（值映射：FULL→hybrid, FETCH_ONLY→online, INGEST_ONLY→offline）
- 旧键 `pipeline.fetch_root` → `io.fetch_root`，`pipeline.ingest_source_dir` → `io.ingest_source_dir`
- 新键优先：当新旧键同时存在时，使用新键的值
- 记录弃用警告日志
- _需求: 5.2, 5.3, 5.4, 8.4, 8.5_
- [x] 2.3 编写配置映射属性测试
- **Property 11: pipeline_flow → data_source 映射一致性**
- **验证: 需求 8.1, 8.2, 8.3, 5.2, 8.4**
- [x] 3. 静态方法归位
- [x] 3.1 将 `_map_run_status` 移至 RunTracker
- 在 `orchestration/run_tracker.py` 中添加 `map_run_status()` 静态方法（从 `ETLScheduler._map_run_status` 复制）
- _需求: 7.1_
- [x] 3.2 将 `_filter_verify_tables` 移至校验模块
- 在 `tasks/verification/` 下合适的模块中添加 `filter_verify_tables()` 函数
- _需求: 7.2_
- [x] 4. 检查点 — 确保所有测试通过
- 运行 `pytest tests/unit`，确保所有测试通过，如有问题请询问用户。
- [x] 5. 实现 TaskExecutor（执行层）
- [x] 5.1 创建 `orchestration/task_executor.py`
- 实现 `TaskExecutor` 类，构造函数接收 `config`、`db_ops`、`api_client`、`cursor_mgr`、`run_tracker`、`task_registry`、`logger`
- 从 `ETLScheduler` 迁移以下方法：`run_tasks`、`_run_single_task`、`_execute_fetch`、`_execute_ingest`、`_execute_ods_record_and_load`、`_run_utility_task`、`_build_fetch_dir`、`_resolve_ingest_source`、`_counts_from_fetch`、`_load_task_config`、`_maybe_run_integrity_check`、`_attach_run_file_logger`
- 将 `data_source` 改为方法参数（替代原 `self.pipeline_flow` 全局状态）
- 使用 `self.task_registry.is_utility_task()` 替代硬编码的 `NO_DB_CONFIG_TASKS`
- 使用 `RunTracker.map_run_status()` 替代 `self._map_run_status()`
- 添加 `DataSource` 枚举类（`online`/`offline`/`hybrid`）
- _需求: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6_
- [x] 5.2 编写 TaskExecutor 属性测试
- **Property 1: data_source 参数决定执行路径**
- **Property 2: 成功任务推进游标**
- **Property 3: 失败任务标记 FAIL 并重新抛出**
- **Property 4: 工具类任务由元数据决定**
- **验证: 需求 1.2, 1.3, 1.4, 1.6, 4.2**
- [x] 6. 实现 PipelineRunner（编排层）
- [x] 6.1 创建 `orchestration/pipeline_runner.py`
- 实现 `PipelineRunner` 类，构造函数接收 `config`、`task_executor`、`task_registry`、`db_conn`、`api_client`、`logger`
- 将 `PIPELINE_LAYERS` 常量从 `scheduler.py` 迁移至此
- 从 `ETLScheduler` 迁移以下方法：`run_pipeline_with_verification`（重命名为 `run`）、`_run_layer_verification`（重命名为 `_run_verification`）、`_get_tasks_for_layers`（重命名为 `_resolve_tasks`）
- 使用 `filter_verify_tables()`（已移至校验模块）替代原内联静态方法
- 使用 `task_registry.get_tasks_by_layer()` 作为默认任务解析，配置覆盖优先
- _需求: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6_
- [x] 6.2 编写 PipelineRunner 属性测试
- **Property 5: 管道名称→层列表映射**
- **Property 6: processing_mode 控制执行流程**
- **Property 7: 管道结果汇总完整性**
- **验证: 需求 2.1, 2.3, 2.4, 2.6**
- [x] 7. 检查点 — 确保所有测试通过
- 运行 `pytest tests/unit`，确保所有测试通过，如有问题请询问用户。
- [x] 8. 重构 CLI 层
- [x] 8.1 重构 `cli/main.py` 参数解析
- 添加 `--data-source` 参数（choices: online/offline/hybrid，默认 hybrid）
- 保留 `--pipeline-flow` 作为弃用别名，使用时发出 `DeprecationWarning` 并映射到 `--data-source`
- 更新 `build_cli_overrides()` 将 `--data-source` 写入 `run.data_source` 配置键
- _需求: 3.1, 3.5, 8.1, 8.2, 8.3_
- [x] 8.2 重构 `cli/main.py` 的 `main()` 函数
- 在 `try/finally` 块中管理 `DatabaseConnection` 和 `APIClient` 的生命周期
- 在 `try` 块内组装 `TaskExecutor` 和 `PipelineRunner`（依赖注入）
- 管道模式委托 `PipelineRunner.run()`，传统模式委托 `TaskExecutor.run_tasks()`
- 添加 `resolve_data_source(args)` 辅助函数处理新旧参数映射
- _需求: 3.2, 3.3, 3.4, 3.6, 6.1, 6.4_
- [x] 8.3 编写 CLI 参数解析单元测试
- 测试 `--data-source` 新参数正确解析
- 测试 `--pipeline-flow` 旧参数弃用映射
- 测试 `--pipeline` + `--tasks` 同时使用时的行为
- _需求: 3.1, 3.3, 3.5_
- [x] 9. 清理旧代码与集成
- [x] 9.1 重构 `orchestration/scheduler.py` 为薄包装层
- 将 `ETLScheduler` 改为薄包装，内部委托 `TaskExecutor` 和 `PipelineRunner`
- 保留 `ETLScheduler` 类名和 `run_tasks()`、`run_pipeline_with_verification()`、`close()` 公共接口，标记为弃用
- 确保 GUI 层（`gui/workers/`）等现有调用方无需立即修改
- _需求: 8.1, 8.4_
- [x] 9.2 更新 GUI 工作线程中的调度器引用
- 检查 `gui/workers/` 中对 `ETLScheduler` 的使用
- 如有直接引用内部方法，更新为使用新的公共接口
- _需求: 7.3_
- [x] 9.3 编写集成测试验证端到端流程
- 使用 FakeDB/FakeAPI 验证 CLI → PipelineRunner → TaskExecutor 完整调用链
- 验证传统模式和管道模式均正常工作
- _需求: 9.4_
- [x] 10. 最终检查点 — 确保所有测试通过
- 运行 `pytest tests/unit`，确保所有测试通过，如有问题请询问用户。
## 备注
- 标记 `*` 的子任务为可选测试任务，可跳过以加速 MVP
- 每个任务引用了具体的需求编号，确保可追溯性
- 检查点确保增量验证，避免问题累积
- 属性测试使用 `hypothesis` 库，验证通用正确性属性
- 单元测试验证具体示例和边界条件
- `ETLScheduler` 保留为薄包装层，确保 GUI 等现有调用方平滑过渡

22
.kiro/steering/db-docs.md Normal file
View File

@@ -0,0 +1,22 @@
---
inclusion: fileMatch
fileMatchPattern:
- "**/migrations/**/*.*"
- "**/*.sql"
- "**/*schema*.*"
- "**/*ddl*.*"
- "**/*.prisma"
---
# Database Schema Documentation Rules
当你修改任何可能影响 PostgreSQL schema/表结构的内容时（迁移脚本/DDL/表定义/ORM 模型）：
1) 必须同步更新 BD 手册目录：
docs/bd_manual
2) 文档最低要求：
- 变更说明：新增/修改/删除的表、字段、约束、索引
- 兼容性：对 ETL、后端 API、小程序字段映射的影响
- 回滚策略：如何撤销（DDL 回滚 / 数据回填）
- 验证步骤：最少包含 3 条校验 SQL

59
.kiro/steering/governance.md Normal file
View File

@@ -0,0 +1,59 @@
---
inclusion: always
---
# Governance / Engineering Rigour
## Hard Rules（必须遵守）
### 1) Logic Change → Change Impact Review + Doc Updates
任何**逻辑改动**必须做 Change Impact Review，并评估/必要时更新：
- .kiro/steering/product.md
- .kiro/steering/structure.md
- .kiro/steering/tech.md
- README.md
**逻辑改动**包括（不限于）：
- 业务规则/计算口径/资金处理（精度、舍入、阈值等）
- 数据处理与 ETL 逻辑（含 SQL 逻辑、清洗/聚合/映射）
- API 行为（返回结构、错误码、鉴权/权限）
- 小程序交互逻辑（校验、关键流程状态机）
**通常不视为逻辑改动**（仍需判断是否影响结构文档/运行方式）：
- 纯格式化、拼写/文案微调、仅注释调整、无行为变化的重命名
### 2) DB Schema / Table Structure Change → Must Update BD Manual
任何数据库 schema / 表结构变化（DDL/迁移/字段类型/默认值/非空/约束/索引/外键等），必须同步到：
- `docs/bd_manual` 下对应 schema 目录与表结构文档
文档必须包含：变更原因、影响范围、回滚策略、数据迁移注意事项、验证 SQL。
---
## Audit & Annotation Requirements（审计与标注）
### A) Per-change Audit Artifact（一次 Prompt 一份记录）
每次修改（以一次用户 Prompt 驱动为单位）必须创建/追加：
- `docs/ai_audit/changes/<YYYY-MM-DD>__<slug>.md`
内容至少包含：
- 日期（Asia/Taipei，YYYY-MM-DD）
- 原始原因：用户 Prompt（原文或 ≤5 行摘录，需可追溯完整 Prompt）
- 直接原因：为什么必须改 + 修改方案简介
- Changed：涉及模块/接口/表（或关键文件）
- Risk/Verify：风险点、回归范围、验证步骤
- 如涉及 DB 结构：回滚要点 + 验证 SQL
### B) Per-file AI_CHANGELOG（每个被修改文件必须可追溯）
每个被修改的代码/文档文件必须追加/更新 **AI_CHANGELOG** 条目，至少包含：
- 日期（Asia/Taipei，YYYY-MM-DD）
- Prompt（原文或引用 Prompt-ID + 摘录）
- 直接原因（必要性 + 方案简介）
- 变更摘要（改了什么）
- 风险与验证（至少 1 条验证方式）
### C) Inline CHANGE Markers（逻辑变更处必须可读）
对“逻辑变更”的代码块，在变更附近增加 **CHANGE 标记注释**，包含：
- intent（变更意图）
- assumptions（前置假设）
- edge cases / money semantics（边界条件与资金口径：精度/舍入等）

18
.kiro/steering/language-zh.md Normal file
View File

@@ -0,0 +1,18 @@
---
inclusion: always
---
# 语言与编码规范（强制）
## 输出语言
- 默认：所有“说明性文字”一律使用简体中文（对话回复、文档内容、代码注释、README/ADR/变更说明等）。
- 允许保留英文的部分：
- 代码标识符（类名/函数名/变量名/接口名/库名/命令名）不翻译
- 第三方工具的原始 CLI 输出/报错原文不篡改（可在原文后补充中文解释）
## 文档与注释
- 新增/修改的文档必须与代码变更同步更新
- 注释只写“为什么/边界/假设”，避免复述代码
## 编码与字符集
- 仓库内所有文本文件统一 UTF-8（建议无 BOM）
- 禁止出现 GBK/Big5 混用；若发现历史文件，先转码再重构

22
.kiro/steering/product.md Normal file
View File

@@ -0,0 +1,22 @@
# 产品概述
飞球 ETL 系统 (etl-billiards) — 面向台球门店业务的数据仓库 ETL 管线。
## 功能
- 从上游 SaaS API 抽取运营数据（订单、支付、会员、助教、库存等）
- 原始数据落地 **ODS**（操作数据存储层），保留源 payload 便于回溯
- 清洗装载至 **DWD**（明细数据层），维度走 SCD2，事实按时间增量
- 汇总至 **DWS**（数据服务层）：助教业绩、财务日报、会员分析、工资计算、自定义指数算法（WBI/NCI/RS/OS/MS/ML）
- 提供 **PySide6 桌面 GUI**，支持任务管理、调度配置
- 支持在线（API 抓取）和离线（JSON 回放）两种模式
## 业务上下文
- 单租户：一家台球门店（由 `STORE_ID` 标识）
- 核心实体：会员（客户）、助教（教练）、台桌、订单、支付、退款、团购套餐、库存
- 领域语言以中文为主；代码注释、文档、UI 文案均为中文
- 货币：人民币（CNY），金额以 numeric(2) 存储
## 主要入口
- CLI：`python -m cli.main`（主入口）
- GUI：`python -m gui.main`
- 批处理脚本：`run_etl.bat`、`run_gui.bat`（根目录）、`scripts/run_ods.bat`

17
.kiro/steering/steering-readme-maintainer.md Normal file
View File

@@ -0,0 +1,17 @@
---
inclusion: manual
---
# 变更影响审查与文档同步（手动参考）
说明：本文件用于“按需加载”的快速参考（可作为 /slash command），详细流程请优先使用 skill：
- steering-readme-maintainer
## 何时使用
- 发生业务/资金口径/ETL/接口/鉴权/小程序交互等“逻辑改动”时
## 快速清单
- 是否需要更新 product.md / tech.md / structure.md / README.md / (各子目录下README.md)
- 是否需要补齐审计记录 docs/ai_audit/changes/<date>__<slug>.md
- 是否需要在每个修改文件写入 AI_CHANGELOG
- 是否需要在逻辑变更处加 CHANGE 标记注释

105
.kiro/steering/structure.md Normal file
View File

@@ -0,0 +1,105 @@
# 项目结构
```
FQ-ETL/ # 工作区根目录（C:\ZQYY\FQ-ETL）
├── cli/ # CLI 入口（main.py）
├── config/ # 配置：默认值、环境变量解析、AppConfig、调度任务配置
│ └── scheduled_tasks.json
├── api/ # API 客户端（HTTP、本地 JSON 回放、录制）
│ └── endpoint_routing.py # 端点路由映射
├── database/ # 数据库连接、操作、DDL Schema、种子脚本、迁移
│ ├── migrations/ # 迁移脚本（纯 SQL，日期前缀命名）
│ ├── schema_*.sql # DDL 定义
│ └── seed_*.sql # 种子数据
├── tasks/ # ETL 任务实现（按数据层分目录）
│ ├── base_task.py # BaseTask 基类，提供 Extract/Transform/Load 模板
│ ├── ods/ # ODS 层抓取任务（16 个业务实体 + ods_tasks 工厂）
│ ├── dwd/ # DWD 层装载任务（base_dwd_task、维度/事实装载、质量检查）
│ ├── dws/ # DWS 汇总与指数任务
│ │ └── index/ # 指数计算任务（亲密度、新客转化、召回、关系、赢回）
│ ├── utility/ # 工具类任务（Schema 初始化、手动入库、完整性检查、DWS 构建等）
│ └── verification/ # ETL 后置校验任务（ODS/DWD/DWS/指数校验器）
├── loaders/ # 数据加载器（ODS、维度、事实）
│ ├── base_loader.py # BaseLoader 基类，定义 upsert 接口
│ ├── ods/ # 通用 ODS 加载器
│ ├── dimensions/ # SCD2 维度加载器（会员、助教、商品、台桌、套餐）
│ └── facts/ # 事实表加载器（订单、支付、退款、小票、充值等）
├── scd/ # SCD2（缓慢变化维度）处理器
├── orchestration/ # 调度器、任务注册表、游标管理、运行记录
│ ├── pipeline_runner.py # 管线运行器
│ ├── task_executor.py # 任务执行器
│ ├── task_registry.py # 任务注册表
│ ├── scheduler.py # ETL 调度器
│ ├── cursor_manager.py # 游标（水位）管理
│ └── run_tracker.py # 运行记录追踪
├── quality/ # 数据质量检查器（余额一致性、完整性）
│ └── integrity_service.py # 完整性检查服务
├── models/ # 解析器与验证器
├── utils/ # 工具函数：日志、JSON 存储、报告、窗口切分
├── gui/ # PySide6 桌面 GUI
│ ├── main_window.py
│ ├── widgets/ # UI 面板与组件
│ ├── workers/ # 后台工作线程
│ ├── models/ # GUI 数据模型（任务、调度）
│ ├── utils/ # GUI 专用工具（设置、CLI 构建器）
│ └── resources/ # 样式表
├── scripts/ # 运维/工具脚本
│ ├── run_update.py # 一键增量更新入口（ODS → DWD → DWS）
│ ├── run_ods.bat # ODS 批处理入口
│ ├── audit/ # 仓库审计脚本（扫描器、分析器、报告生成）
│ ├── check/ # 数据检查脚本（完整性、ODS 缺口、DWD 服务、内容哈希等）
│ ├── db_admin/ # 数据库管理脚本（Excel 导入）
│ ├── export/ # 数据导出脚本（指数、团购、亲密度、会员明细等）
│ ├── rebuild/ # 数据重建脚本（全量 ODS→DWD 重建）
│ └── repair/ # 数据修复脚本（回填、去重、hash 修复、维度修复、索引调优）
├── tests/ # 测试套件
│ ├── unit/ # 单元测试（FakeDB/FakeAPI，无需真实数据库）
│ └── integration/ # 集成测试（需要 TEST_DB_DSN 或真实数据库）
├── docs/ # 文档
│ ├── audit/ # 仓库审计报告（自动生成）
│ ├── bd_manual/ # 业务数据手册（DWD/DWS 表说明）
│ │ ├── DWD/ # DWD 层表手册（main + Ex 扩展）
│ │ └── dws/ # DWS 层表手册
│ ├── dictionary/ # 数据字典
│ ├── index/ # 指数算法文档
│ ├── requirements/ # 需求文档
│ ├── reports/ # 分析报告
│ ├── data_exports/ # 数据导出文档与 CSV
│ ├── templates/ # 模板文件（Excel 等）
│ ├── api-reference/ # API 参考文档（标准化，替代 test-json-doc）
│ │ ├── api_registry.json # API 注册表（25 个端点定义）
│ │ ├── endpoints/ # 每个 API 一个 .md 文档（25 个）
│ │ └── samples/ # 最新响应样本（JSON）
│ ├── test-json-doc/ # [已废弃] 旧版 API 测试 JSON 样本与分析
│ └── 开发笔记/ # 开发备忘
├── reports/ # 质检输出（JSON，已 gitignore）
├── export/ # JSON 落盘与日志（已 gitignore）
├── logs/ # 运行日志（已 gitignore）
└── .Deleted/ # 已归档/废弃文件（隐藏目录，已 gitignore）
```
## 架构模式
- **任务模式**：每个 ETL 任务继承 `BaseTask`（Extract → Transform → Load 模板方法），在 `orchestration/task_registry.py` 中注册。
- **加载器模式**：每张目标表对应一个加载器，继承 `BaseLoader` 并实现 `upsert()` 方法。维度加载器在 `loaders/dimensions/`，事实加载器在 `loaders/facts/`。
- **配置分层**：`DEFAULTS` 字典 → `.env` 覆盖 → CLI 参数覆盖。通过 `AppConfig.get("dotted.path")` 访问。
- **管线流程**：`FULL`（抓取 + 入库）、`FETCH_ONLY`（仅抓取）、`INGEST_ONLY`（仅入库）。由 `--pipeline-flow` CLI 参数或 `PIPELINE_FLOW` 环境变量控制。
- **调度器**：`ETLScheduler` 编排任务执行，管理游标（水位），在 `etl_admin` Schema 中记录运行状态。
- **API 抽象**：`APIClient`（HTTP）、`LocalJsonClient`（离线回放）、`RecordingAPIClient`（抓取 + 落盘）共享相同接口，任务代码无需关心数据来源。
## 编码约定
- 文件编码：UTF-8，文件头加 `# -*- coding: utf-8 -*-`
- 日志格式：通过 `utils/logging_utils.py` 统一
- 任务代码：大写蛇形命名（如 `DWD_LOAD_FROM_ODS`、`DWS_ASSISTANT_DAILY`）
- SQL 文件：纯 SQL，不使用 ORM；通过 `psycopg2` 执行
- 数据库操作：批量 upsert + 冲突处理，显式 commit/rollback
- 中文注释和文档字符串是正常且预期的
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-171500 — "继续"（Task 3 API 文档全面重构续接）
- 直接原因: 新增 docs/api-reference/ 目录替代旧 test-json-doc，需在项目结构文档中反映
- 变更摘要: docs/ 树中新增 api-reference/（含 api_registry.json、endpoints/、samples/）；test-json-doc 标记为 [已废弃]
- 风险与验证: 纯文档结构描述变更，无运行时影响；验证方式：对比实际目录 `ls docs/api-reference/` 确认一致
-->

60
.kiro/steering/tech.md Normal file
View File

@@ -0,0 +1,60 @@
# 技术栈与构建
## 语言与运行时
- Python 3.10+（测试缓存中观察到 3.13）
- 未提交虚拟环境；用户自行管理
## 核心依赖（requirements.txt）
- `psycopg2-binary>=2.9.0` — PostgreSQL 驱动
- `requests>=2.28.0` — 上游 API 的 HTTP 客户端
- `python-dateutil>=2.8.0` / `tzdata>=2023.0` — 日期解析与时区处理
- `python-dotenv` — `.env` 文件加载
- `openpyxl>=3.1.0` — Excel 导入导出（DWS 数据）
- `PySide6>=6.5.0` — Qt 桌面 GUI 框架
- `flask>=2.3` — 可选 Web API
- `pyinstaller>=6.0.0` — 可选，仅打包 EXE 时需要
## 数据库
- PostgreSQL（连接远程实例）
- Schema：`billiards`（OLTP/ODS）、`billiards_dwd`、`billiards_dws`、`etl_admin`
- DDL 文件位于 `database/schema_*.sql`，种子脚本位于 `database/seed_*.sql`
- 迁移脚本位于 `database/migrations/`（纯 SQL，日期前缀命名）
## 测试
- 框架：`pytest`（未固定在 requirements 中，需单独安装）
- 配置：`pytest.ini` 设置 `pythonpath = .`
- 结构：`tests/unit/`（基于 mock，无需数据库）、`tests/integration/`（需要 `TEST_DB_DSN`）
- 测试工具：`tests/unit/task_test_utils.py` 提供 FakeDB/FakeAPI 辅助类
## 常用命令
```bash
# 安装依赖
pip install -r requirements.txt
# 在线全流程 ETL（抓取 + 入库）
python -m cli.main --pg-dsn "$PG_DSN" --store-id "$STORE_ID" --api-token "$API_TOKEN"
# 运行指定任务
python -m cli.main --tasks INIT_ODS_SCHEMA,MANUAL_INGEST --pipeline-flow INGEST_ONLY
# 试运行（不写库）
python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
# 单元测试
pytest tests/unit
# 集成测试（需要数据库）
TEST_DB_DSN="postgresql://..." pytest tests/integration
# 启动 GUI
python -m gui.main
```
## 配置体系
- 分层叠加：`config/defaults.py` < `.env` / 环境变量 < CLI 参数
- 配置类：`config.settings.AppConfig`，支持点号路径访问（`config.get("db.dsn")`）
- 敏感值（DSN、API Token）放在 `.env` 中，禁止提交
## 打包
- 已移除 EXE 打包支持（`build_exe.py`、`setup.py` 已归档至 `.Deleted/`）
- 直接通过 `python -m cli.main` 或 `python -m gui.main` 运行

204
README.md Normal file
View File

@@ -0,0 +1,204 @@
# 飞球 ETL 系统（ODS → DWD → DWS）
面向台球门店业务的数据仓库 ETL 管线：从上游 SaaS API 或离线 JSON 采集订单、支付、会员、库存等数据，先落地 **ODS**，再清洗装载 **DWD**（含 SCD2 维度、事实增量），汇总至 **DWS**（助教业绩、财务日报、会员分析、工资计算、自定义指数算法），并输出质量校验报表。
## 快速开始
> 工作区根目录：`C:\ZQYY\FQ-ETL`，所有命令在此目录执行。
1) 环境：Python 3.10+、PostgreSQL。
2) 配置：编辑 `.env`（或设环境变量），至少包含：
```env
STORE_ID=123
PG_DSN=postgresql://<user>:<password>@<host>:<port>/<db>
```
3) 安装依赖：
```bash
pip install -r requirements.txt
```
4) 离线回放入库（ODS → DWD → 质检）：
```bash
python -m cli.main --pipeline-flow INGEST_ONLY --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA
python -m cli.main --pipeline-flow INGEST_ONLY --tasks MANUAL_INGEST --ingest-source "./export/test-json-doc"
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWD_LOAD_FROM_ODS
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWD_QUALITY_CHECK
```
> Windows 可用 `scripts/run_ods.bat` 一键执行 ODS 建表 + 灌入示例 JSON。
## 正式环境（在线抓取 → ODS → DWD）
**核心入口 CLI**：`python -m cli.main`
### 必备配置（`.env` 或环境变量）
- 数据库：`PG_DSN`、`STORE_ID`
- 在线抓取：`API_TOKEN`（可选 `API_BASE`、`API_TIMEOUT`、`API_PAGE_SIZE`）
- 输出目录（可选）：`EXPORT_ROOT`、`LOG_ROOT`、`FETCH_ROOT`
### 推荐定时方式
**方式 A（两段定时）**
1. 更新 ODS（在线抓取 + 入库）：
```bash
python -m cli.main --pipeline-flow FULL \
--tasks PRODUCTS,TABLES,MEMBERS,ASSISTANTS,PACKAGES_DEF,ORDERS,PAYMENTS,REFUNDS,COUPON_USAGE,INVENTORY_CHANGE,TOPUPS,TABLE_DISCOUNT,ASSISTANT_ABOLISH,LEDGER
```
2. ODS → DWD：
```bash
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWD_LOAD_FROM_ODS
```
**方式 B（一条命令）**
```bash
python -m cli.main --pipeline-flow FULL \
--tasks PRODUCTS,TABLES,MEMBERS,ASSISTANTS,PACKAGES_DEF,ORDERS,PAYMENTS,REFUNDS,COUPON_USAGE,INVENTORY_CHANGE,TOPUPS,TABLE_DISCOUNT,ASSISTANT_ABOLISH,LEDGER,DWD_LOAD_FROM_ODS
```
### `--data-source` 参数
- `online`：仅在线抓取（等价于旧 `FETCH_ONLY`）
- `offline`：仅离线入库（等价于旧 `INGEST_ONLY`）
- `hybrid`：在线抓取 + 离线入库（等价于旧 `FULL`，默认值）
### `--pipeline` 管道模式
通过 `--pipeline` 指定预定义管道，配合 `--processing-mode` 控制流程：
- `increment_only`：仅增量 ETL（默认）
- `verify_only`：仅校验
- `increment_verify`：增量 + 校验
## DWS 层（汇总/财务）
### 建表与初始化
- 建表：`INIT_DWS_SCHEMA`
- 配置：`SEED_DWS_CONFIG`
- 指数参数：`database/seed_index_parameters.sql`（WBI/NCI/RS/OS/MS/ML）
### 任务调度建议
- **每小时**：`DWS_ASSISTANT_DAILY`、`DWS_FINANCE_DAILY`、`DWS_FINANCE_INCOME_STRUCTURE`
- **每日**：`DWS_ASSISTANT_MONTHLY`、`DWS_ASSISTANT_CUSTOMER`、`DWS_MEMBER_CONSUMPTION`、`DWS_MEMBER_VISIT`、`DWS_FINANCE_DISCOUNT_DETAIL`、`DWS_FINANCE_RECHARGE`、`DWS_ASSISTANT_FINANCE`
- **每2小时**：`DWS_WINBACK_INDEX`、`DWS_NEWCONV_INDEX`
- **每4小时**：`DWS_RELATION_INDEX`（RS/OS/MS/ML）
- **按需**：`DWS_ML_MANUAL_IMPORT`（ML人工台账导入）
- **每月（月初）**：`DWS_ASSISTANT_SALARY`
- **维护（按需）**：`DWS_RETENTION_CLEANUP`
- **物化刷新（可选）**：`DWS_MV_REFRESH_FINANCE_DAILY`、`DWS_MV_REFRESH_ASSISTANT_DAILY`
调度配置保存在 `config/scheduled_tasks.json`，GUI 调度器会读取该文件。
### 指数算法参数（cfg_index_parameters）
- 参数表：`billiards_dws.cfg_index_parameters`
- 初始化脚本：`database/seed_index_parameters.sql`（WBI/NCI/RS/OS/MS/ML）
- 公共参数：`percentile_lower/upper`（分位截断锚点），`ewma_alpha`（平滑系数）
### ML人工台账导入
- 模板文件：`docs/templates/ml_manual_ledger_template.xlsx`
- GUI 路径：`任务配置 -> 数据建设 -> ML人工台账导入`
- 导入环境变量：`ML_MANUAL_LEDGER_FILE=<xlsx路径>`
### Excel 导入（支出/平台回款/充值提成）
脚本：`scripts/db_admin/import_dws_excel.py`
- 支出结构：`--type expense`，按月导入
- 平台回款：`--type platform`，按回款日期导入
- 充值提成：`--type commission`，按月份导入
### 时间口径
- 周起始日：周一
- 月/季度起始：第一天 0 点
- 环比：对比上一个等长区间
### DWS 口径要点
- 财务/消费类统计统一按 `pay_time`；来店开始时间保留 `create_time`
- 团购实付/优惠按结账日对齐（`order_settle_id` + `pay_time`）
- 来店时长按 `dwd_table_fee_log.real_table_use_seconds` 计算
- 有效业绩统一过滤 `is_delete = 1` 的作废记录
### 物化汇总层（可选）
- `l1`=近2天，`l2`=近1月，`l3`=近3月，`l4`=近6月（不含本月）
- 刷新任务：`DWS_MV_REFRESH_FINANCE_DAILY`、`DWS_MV_REFRESH_ASSISTANT_DAILY`
- 配置：`DWS_MV_ENABLED`、`DWS_MV_LAYERS`、`DWS_MV_TABLES` 等
## 目录结构
详见 `.kiro/steering/structure.md`，核心目录：
```
FQ-ETL/
├── cli/ # CLI 入口
├── config/ # 配置（默认值、环境变量解析、AppConfig）
├── api/ # API 客户端（HTTP、本地 JSON 回放、录制）
├── database/ # 数据库连接、DDL、种子脚本、迁移
├── tasks/ # ETL 任务（ods/ dwd/ dws/ utility/ verification/）
├── loaders/ # 数据加载器（ods/ dimensions/ facts/）
├── scd/ # SCD2 处理器
├── orchestration/ # 调度器、任务注册表、游标管理、运行记录
├── quality/ # 数据质量检查器
├── models/ # 解析器与验证器
├── utils/ # 工具函数
├── gui/ # PySide6 桌面 GUI
├── scripts/ # 运维脚本（audit/ check/ rebuild/ repair/ export/）
├── tests/ # 测试（unit/ integration/）
├── docs/ # 文档（audit/ bd_manual/ dictionary/ index/ templates/）
├── reports/ # 质检输出（gitignore）
├── export/ # JSON 落盘（gitignore）
└── logs/ # 运行日志（gitignore）
```
## 架构与流程
执行链路（三层架构）：
1. **CLI 层**（`cli/main.py`）：解析参数 → 生成 AppConfig → 依赖注入
2. **编排层**（`orchestration/pipeline_runner.py`）：管道名称→层→任务列表解析，`processing_mode` 控制增量/校验
3. **执行层**（`orchestration/task_executor.py`）：`DataSource` 枚举决定 fetch/ingest 路径，含游标管理、运行记录、失败标记
任务模板：Extract（API 分页/重试或离线 JSON）→ Transform（解析/校验）→ Load（批量 upsert/SCD2/增量写入）→（可选）质量检查 → 更新水位
## 窗口切分与补偿
配置项（默认值见 `config/defaults.py`）：
- `run.window_split.unit`：`day` / `week` / `month` / `none`（默认 `day`）
- `run.window_split.days`：默认 `10`
- `run.window_split.compensation_hours`：默认 `2`
## 测试
```bash
pip install pytest hypothesis
# 全部单元测试
pytest tests/unit
# 集成测试（需要数据库）
TEST_DB_DSN="postgresql://..." pytest tests/integration
```
## 开发与扩展
- 新任务：在 `tasks/` 继承 `BaseTask`，实现 `get_task_code/execute`，在 `orchestration/task_registry.py` 注册
- 新 Loader：参考 `loaders/`，复用批量 upsert 接口
- 新配置项：在 `config/defaults.py` 增加默认值，`config/env_parser.py` 增加环境变量映射
## ODS 表概览
| ODS 表名 | 接口 Path | 数据路径 |
|----------|-----------|----------|
| assistant_accounts_master | /PersonnelManagement/SearchAssistantInfo | data.assistantInfos |
| assistant_service_records | /AssistantPerformance/GetOrderAssistantDetails | data.orderAssistantDetails |
| assistant_cancellation_records | /AssistantPerformance/GetAbolitionAssistant | data.abolitionAssistants |
| goods_stock_movements | /GoodsStockManage/QueryGoodsOutboundReceipt | data.queryDeliveryRecordsList |
| goods_stock_summary | /TenantGoods/GetGoodsStockReport | data |
| group_buy_packages | /PackageCoupon/QueryPackageCouponList | data.packageCouponList |
| group_buy_redemption_records | /Site/GetSiteTableUseDetails | data.siteTableUseDetailsList |
| member_profiles | /MemberProfile/GetTenantMemberList | data.tenantMemberInfos |
| member_balance_changes | /MemberProfile/GetMemberCardBalanceChange | data.tenantMemberCardLogs |
| member_stored_value_cards | /MemberProfile/GetTenantMemberCardList | data.tenantMemberCards |
| payment_transactions | /PayLog/GetPayLogListPage | data |
| platform_coupon_redemption_records | /Promotion/GetOfflineCouponConsumePageList | data |
| recharge_settlements | /Site/GetRechargeSettleList | data.settleList |
| refund_transactions | /Order/GetRefundPayLogList | data |
| settlement_records | /Site/GetAllOrderSettleList | data.settleList |
| settlement_ticket_details | /Site/GetSiteTableUseDetails | data.siteTableUseDetailsList |
| site_tables_master | /Table/GetSiteTables | data.siteTables |
| store_goods_master | /TenantGoods/QuerySiteGoods | data.siteGoodsList |
| store_goods_sales_records | /TenantGoods/QuerySiteGoodsSaleRecord | data.siteGoodsSaleRecords |
| table_fee_discount_records | /Site/GetTaiFeeAdjustList | data.taiFeeAdjustInfos |
| table_fee_transactions | /Site/GetTaiFeeList | data.taiFeeList |
| tenant_goods_master | /TenantGoods/QueryTenantGoods | data.tenantGoodsList |
| stock_goods_category_tree | /TenantGoods/QueryGoodsCategoryTree | data.goodsCategoryTree |

0
api/__init__.py Normal file
View File

293
api/client.py Normal file
View File

@@ -0,0 +1,293 @@
# -*- coding: utf-8 -*-
"""API客户端：统一封装 POST/重试/分页与列表提取逻辑。"""
from __future__ import annotations
from typing import Iterable, Sequence, Tuple
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
from api.endpoint_routing import plan_calls
DEFAULT_BROWSER_HEADERS = {
"Accept": "application/json, text/plain, */*",
"Content-Type": "application/json",
"Origin": "https://pc.ficoo.vip",
"Referer": "https://pc.ficoo.vip/",
"User-Agent": (
"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
"(KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36"
),
"Accept-Language": "zh-CN,zh;q=0.9",
"sec-ch-ua": '"Google Chrome";v="141", "Not?A_Brand";v="8", "Chromium";v="141"',
"sec-ch-ua-platform": '"Windows"',
"sec-ch-ua-mobile": "?0",
"sec-fetch-site": "same-origin",
"sec-fetch-mode": "cors",
"sec-fetch-dest": "empty",
"priority": "u=1, i",
"X-Requested-With": "XMLHttpRequest",
"DNT": "1",
}
DEFAULT_LIST_KEYS: Tuple[str, ...] = (
"list",
"rows",
"records",
"items",
"dataList",
"data_list",
"tenantMemberInfos",
"tenantMemberCardLogs",
"tenantMemberCards",
"settleList",
"orderAssistantDetails",
"assistantInfos",
"siteTables",
"taiFeeAdjustInfos",
"siteTableUseDetailsList",
"tenantGoodsList",
"packageCouponList",
"queryDeliveryRecordsList",
"goodsCategoryList",
"orderGoodsList",
"orderGoodsLedgers",
)
class APIClient:
"""HTTP API 客户端（默认使用 POST + JSON 请求体）"""
def __init__(
self,
base_url: str,
token: str | None = None,
timeout: int = 20,
retry_max: int = 3,
headers_extra: dict | None = None,
):
self.base_url = (base_url or "").rstrip("/")
self.token = self._normalize_token(token)
self.timeout = timeout
self.retry_max = retry_max
self.headers_extra = headers_extra or {}
self._session: requests.Session | None = None
# ------------------------------------------------------------------ HTTP 基础
def _get_session(self) -> requests.Session:
"""获取或创建带重试的 Session。"""
if self._session is None:
self._session = requests.Session()
retries = max(0, int(self.retry_max) - 1)
retry = Retry(
total=None,
connect=retries,
read=retries,
status=retries,
allowed_methods=frozenset(["GET", "POST"]),
status_forcelist=(429, 500, 502, 503, 504),
backoff_factor=0.5,
respect_retry_after_header=True,
raise_on_status=False,
)
adapter = HTTPAdapter(max_retries=retry)
self._session.mount("http://", adapter)
self._session.mount("https://", adapter)
self._session.headers.update(self._build_headers())
return self._session
def get(self, endpoint: str, params: dict | None = None) -> dict:
"""
兼容旧名的请求入口（实际以 POST JSON 方式请求）。
"""
return self._post_json(endpoint, params)
def _post_json(self, endpoint: str, payload: dict | None = None) -> dict:
if not self.base_url:
raise ValueError("API base_url 未配置")
url = f"{self.base_url}/{endpoint.lstrip('/')}"
sess = self._get_session()
resp = sess.post(url, json=payload or {}, timeout=self.timeout)
resp.raise_for_status()
data = resp.json()
self._ensure_success(data)
return data
def _build_headers(self) -> dict:
headers = dict(DEFAULT_BROWSER_HEADERS)
headers.update(self.headers_extra)
if self.token:
headers["Authorization"] = self.token
return headers
@staticmethod
def _normalize_token(token: str | None) -> str | None:
if not token:
return None
t = str(token).strip()
if not t.lower().startswith("bearer "):
t = f"Bearer {t}"
return t
@staticmethod
def _ensure_success(payload: dict):
"""API 返回 code 非 0 时主动抛错，便于上层重试/记录。"""
if isinstance(payload, dict) and "code" in payload:
code = payload.get("code")
if code not in (0, "0", None):
msg = payload.get("msg") or payload.get("message") or ""
raise ValueError(f"API 返回错误 code={code} msg={msg}")
# ------------------------------------------------------------------ 分页
def _iter_paginated_single(
self,
endpoint: str,
params: dict | None,
page_size: int | None = 200,
page_field: str = "page",
size_field: str = "limit",
data_path: tuple = ("data",),
list_key: str | Sequence[str] | None = None,
page_start: int = 1,
page_end: int | None = None,
) -> Iterable[tuple[int, list, dict, dict]]:
"""
单一 endpoint 的分页迭代器（不包含 recent/former 路由逻辑）。
"""
base_params = dict(params or {})
page = page_start
while True:
page_params = dict(base_params)
if page_size is not None:
page_params[page_field] = page
page_params[size_field] = page_size
payload = self._post_json(endpoint, page_params)
records = self._extract_list(payload, data_path, list_key)
yield page, records, page_params, payload
if page_size is None:
break
if page_end is not None and page >= page_end:
break
if len(records) < (page_size or 0):
break
if len(records) == 0:
break
page += 1
def iter_paginated(
self,
endpoint: str,
params: dict | None,
page_size: int | None = 200,
page_field: str = "page",
size_field: str = "limit",
data_path: tuple = ("data",),
list_key: str | Sequence[str] | None = None,
page_start: int = 1,
page_end: int | None = None,
) -> Iterable[tuple[int, list, dict, dict]]:
"""
分页迭代器：逐页拉取数据并产出 (page_no, records, request_params, raw_response)。
page_size=None 时不附带分页参数，仅拉取一次。
"""
# recent/former 路由：当 params 带时间范围字段时，按“3个月自然月”边界决定走哪个 endpoint，
# 跨越边界则拆分为两段请求并顺序产出，确保调用方使用 page_no 命名文件时不会被覆盖。
call_plan = plan_calls(endpoint, params)
global_page = 1
for call in call_plan:
for _, records, request_params, payload in self._iter_paginated_single(
endpoint=call.endpoint,
params=call.params,
page_size=page_size,
page_field=page_field,
size_field=size_field,
data_path=data_path,
list_key=list_key,
page_start=page_start,
page_end=page_end,
):
yield global_page, records, request_params, payload
global_page += 1
def get_paginated(
self,
endpoint: str,
params: dict,
page_size: int | None = 200,
page_field: str = "page",
size_field: str = "limit",
data_path: tuple = ("data",),
list_key: str | Sequence[str] | None = None,
page_start: int = 1,
page_end: int | None = None,
) -> tuple[list, list]:
"""分页获取数据并将所有记录汇总在一个列表中。"""
records, pages_meta = [], []
for page_no, page_records, request_params, response in self.iter_paginated(
endpoint=endpoint,
params=params,
page_size=page_size,
page_field=page_field,
size_field=size_field,
data_path=data_path,
list_key=list_key,
page_start=page_start,
page_end=page_end,
):
records.extend(page_records)
pages_meta.append(
{"page": page_no, "request": request_params, "response": response}
)
return records, pages_meta
# ------------------------------------------------------------------ 响应解析
@classmethod
def _extract_list(
cls, payload: dict | list, data_path: tuple, list_key: str | Sequence[str] | None
) -> list:
"""根据 data_path/list_key 提取列表结构，兼容常见字段名。"""
cur: object = payload
if isinstance(cur, list):
return cur
for key in data_path:
if isinstance(cur, dict):
cur = cur.get(key)
else:
cur = None
if cur is None:
break
if isinstance(cur, list):
return cur
if isinstance(cur, dict):
if list_key:
keys = (list_key,) if isinstance(list_key, str) else tuple(list_key)
for k in keys:
if isinstance(cur.get(k), list):
return cur[k]
for k in DEFAULT_LIST_KEYS:
if isinstance(cur.get(k), list):
return cur[k]
for v in cur.values():
if isinstance(v, list):
return v
return []

166
api/endpoint_routing.py Normal file
View File

@@ -0,0 +1,166 @@
# -*- coding: utf-8 -*-
"""
“近期记录 / 历史记录(Former)”接口路由规则。
需求：
- 当请求参数包含可定义时间范围的字段时，根据当前时间（北京时间/上海时区）判断：
- 3个月（自然月）之前 -> 使用“历史记录”接口
- 3个月以内 -> 使用“近期记录”接口
- 若时间范围跨越边界 -> 拆分为两段分别请求并合并（由上层分页迭代器顺序产出）
"""
from __future__ import annotations
from dataclasses import dataclass
from datetime import datetime
from typing import Optional
from dateutil import parser as dtparser
from dateutil.relativedelta import relativedelta
from zoneinfo import ZoneInfo
ROUTING_TZ = ZoneInfo("Asia/Shanghai")
RECENT_MONTHS = 3
# 按 `fetch-test/recent_vs_former_report.md` 更新（“无”表示没有历史接口；相同 path 表示同一个接口可查历史）
RECENT_TO_FORMER_OVERRIDES: dict[str, str | None] = {
"/AssistantPerformance/GetAbolitionAssistant": None,
"/Site/GetSiteTableUseDetails": "/Site/GetSiteTableUseDetails",
"/GoodsStockManage/QueryGoodsOutboundReceipt": "/GoodsStockManage/QueryFormerGoodsOutboundReceipt",
"/Promotion/GetOfflineCouponConsumePageList": "/Promotion/GetOfflineCouponConsumePageList",
"/Order/GetRefundPayLogList": None,
# 已知特殊
"/Site/GetAllOrderSettleList": "/Site/GetFormerOrderSettleList",
"/PayLog/GetPayLogListPage": "/PayLog/GetFormerPayLogListPage",
}
TIME_WINDOW_KEYS: tuple[tuple[str, str], ...] = (
("startTime", "endTime"),
("rangeStartTime", "rangeEndTime"),
("StartPayTime", "EndPayTime"),
)
@dataclass(frozen=True)
class WindowSpec:
start_key: str
end_key: str
start: datetime
end: datetime
@dataclass(frozen=True)
class RoutedCall:
endpoint: str
params: dict
def is_former_endpoint(endpoint: str) -> bool:
return "Former" in str(endpoint or "")
def _parse_dt(value: object, tz: ZoneInfo) -> datetime | None:
if value is None:
return None
s = str(value).strip()
if not s:
return None
dt = dtparser.parse(s)
if dt.tzinfo is None:
return dt.replace(tzinfo=tz)
return dt.astimezone(tz)
def _fmt_dt(dt: datetime, tz: ZoneInfo) -> str:
return dt.astimezone(tz).strftime("%Y-%m-%d %H:%M:%S")
def extract_window_spec(params: dict | None, tz: ZoneInfo = ROUTING_TZ) -> WindowSpec | None:
if not isinstance(params, dict) or not params:
return None
for start_key, end_key in TIME_WINDOW_KEYS:
if start_key in params or end_key in params:
start = _parse_dt(params.get(start_key), tz)
end = _parse_dt(params.get(end_key), tz)
if start and end:
return WindowSpec(start_key=start_key, end_key=end_key, start=start, end=end)
return None
def derive_former_endpoint(recent_endpoint: str) -> str | None:
endpoint = str(recent_endpoint or "").strip()
if not endpoint:
return None
if endpoint in RECENT_TO_FORMER_OVERRIDES:
return RECENT_TO_FORMER_OVERRIDES[endpoint]
if is_former_endpoint(endpoint):
return endpoint
idx = endpoint.find("Get")
if idx == -1:
return endpoint
return f"{endpoint[:idx]}GetFormer{endpoint[idx + 3:]}"
def recent_boundary(now: datetime, months: int = RECENT_MONTHS) -> datetime:
"""
3个月（自然月）边界：取 (now - months) 所在月份的 1 号 00:00:00。
"""
if now.tzinfo is None:
raise ValueError("now 必须为时区时间")
base = now - relativedelta(months=months)
return base.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
def plan_calls(
endpoint: str,
params: dict | None,
*,
now: datetime | None = None,
tz: ZoneInfo = ROUTING_TZ,
months: int = RECENT_MONTHS,
) -> list[RoutedCall]:
"""
根据 endpoint + params 的时间窗口，返回要调用的 endpoint/params 列表（可能拆分为两段）。
"""
base_params = dict(params or {})
if not base_params:
return [RoutedCall(endpoint=endpoint, params=base_params)]
# 若调用方显式传了 Former 接口，则不二次路由。
if is_former_endpoint(endpoint):
return [RoutedCall(endpoint=endpoint, params=base_params)]
window = extract_window_spec(base_params, tz)
if not window:
return [RoutedCall(endpoint=endpoint, params=base_params)]
former_endpoint = derive_former_endpoint(endpoint)
if former_endpoint is None or former_endpoint == endpoint:
return [RoutedCall(endpoint=endpoint, params=base_params)]
now_dt = (now or datetime.now(tz)).astimezone(tz)
boundary = recent_boundary(now_dt, months=months)
start, end = window.start, window.end
if end <= boundary:
return [RoutedCall(endpoint=former_endpoint, params=base_params)]
if start >= boundary:
return [RoutedCall(endpoint=endpoint, params=base_params)]
# 跨越边界：拆分两段（老数据 -> former，新数据 -> recent）
p1 = dict(base_params)
p1[window.start_key] = _fmt_dt(start, tz)
p1[window.end_key] = _fmt_dt(boundary, tz)
p2 = dict(base_params)
p2[window.start_key] = _fmt_dt(boundary, tz)
p2[window.end_key] = _fmt_dt(end, tz)
return [RoutedCall(endpoint=former_endpoint, params=p1), RoutedCall(endpoint=endpoint, params=p2)]

78
api/local_json_client.py Normal file
View File

@@ -0,0 +1,78 @@
# -*- coding: utf-8 -*-
"""本地 JSON 客户端，模拟 APIClient 的分页接口，从落盘的 JSON 回放数据。"""
from __future__ import annotations
import json
from pathlib import Path
from typing import Iterable, Tuple
from api.client import APIClient
from utils.json_store import endpoint_to_filename
class LocalJsonClient:
"""
读取 RecordingAPIClient 生成的 JSON，提供 iter_paginated/get_paginated 接口。
"""
def __init__(self, base_dir: str | Path):
self.base_dir = Path(base_dir)
if not self.base_dir.exists():
raise FileNotFoundError(f"JSON 目录不存在: {self.base_dir}")
def get_source_hint(self, endpoint: str) -> str:
"""Return the JSON file path for this endpoint (for source_file lineage)."""
return str(self.base_dir / endpoint_to_filename(endpoint))
def iter_paginated(
self,
endpoint: str,
params: dict | None,
page_size: int = 200,
page_field: str = "page",
size_field: str = "limit",
data_path: tuple = ("data",),
list_key: str | None = None,
) -> Iterable[Tuple[int, list, dict, dict]]:
file_path = self.base_dir / endpoint_to_filename(endpoint)
if not file_path.exists():
raise FileNotFoundError(f"未找到匹配的 JSON 文件: {file_path}")
with file_path.open("r", encoding="utf-8") as fp:
payload = json.load(fp)
pages = payload.get("pages")
if not isinstance(pages, list) or not pages:
pages = [{"page": 1, "request": params or {}, "response": payload}]
for idx, page in enumerate(pages, start=1):
response = page.get("response", {})
request_params = page.get("request") or {}
page_no = page.get("page") or idx
records = APIClient._extract_list(response, data_path, list_key) # type: ignore[attr-defined]
yield page_no, records, request_params, response
def get_paginated(
self,
endpoint: str,
params: dict,
page_size: int = 200,
page_field: str = "page",
size_field: str = "limit",
data_path: tuple = ("data",),
list_key: str | None = None,
) -> tuple[list, list]:
records: list = []
pages_meta: list = []
for page_no, page_records, request_params, response in self.iter_paginated(
endpoint=endpoint,
params=params,
page_size=page_size,
page_field=page_field,
size_field=size_field,
data_path=data_path,
list_key=list_key,
):
records.extend(page_records)
pages_meta.append({"page": page_no, "request": request_params, "response": response})
return records, pages_meta

186
api/recording_client.py Normal file
View File

@@ -0,0 +1,186 @@
# -*- coding: utf-8 -*-
"""包装 APIClient，将分页响应落盘便于后续本地清洗。"""
from __future__ import annotations
from datetime import datetime
from pathlib import Path
import time
from typing import Any, Iterable, Tuple
from zoneinfo import ZoneInfo
from api.client import APIClient
from api.endpoint_routing import plan_calls
from utils.json_store import dump_json, endpoint_to_filename
class RecordingAPIClient:
"""
代理 APIClient，在调用 iter_paginated/get_paginated 时同时把响应写入 JSON 文件。
文件名根据 endpoint 生成，写入到指定 output_dir。
"""
def __init__(
self,
base_client: APIClient,
output_dir: Path | str,
task_code: str,
run_id: int,
write_pretty: bool = False,
):
self.base = base_client
self.output_dir = Path(output_dir)
self.output_dir.mkdir(parents=True, exist_ok=True)
self.task_code = task_code
self.run_id = run_id
self.write_pretty = write_pretty
self.last_dump: dict[str, Any] | None = None
# ------------------------------------------------------------------ 公共 API
def get_source_hint(self, endpoint: str) -> str:
"""Return the JSON dump path for this endpoint (for source_file lineage)."""
return str(self.output_dir / endpoint_to_filename(endpoint))
def iter_paginated(
self,
endpoint: str,
params: dict | None,
page_size: int = 200,
page_field: str = "page",
size_field: str = "limit",
data_path: tuple = ("data",),
list_key: str | None = None,
) -> Iterable[Tuple[int, list, dict, dict]]:
pages: list[dict[str, Any]] = []
total_records = 0
for page_no, records, request_params, response in self.base.iter_paginated(
endpoint=endpoint,
params=params,
page_size=page_size,
page_field=page_field,
size_field=size_field,
data_path=data_path,
list_key=list_key,
):
pages.append({"page": page_no, "request": request_params, "response": response})
total_records += len(records)
yield page_no, records, request_params, response
self._dump(endpoint, params, page_size, pages, total_records)
def get_paginated(
self,
endpoint: str,
params: dict,
page_size: int = 200,
page_field: str = "page",
size_field: str = "limit",
data_path: tuple = ("data",),
list_key: str | None = None,
) -> tuple[list, list]:
records: list = []
pages_meta: list = []
for page_no, page_records, request_params, response in self.iter_paginated(
endpoint=endpoint,
params=params,
page_size=page_size,
page_field=page_field,
size_field=size_field,
data_path=data_path,
list_key=list_key,
):
records.extend(page_records)
pages_meta.append({"page": page_no, "request": request_params, "response": response})
return records, pages_meta
# ------------------------------------------------------------------ 内部方法
def _dump(
self,
endpoint: str,
params: dict | None,
page_size: int,
pages: list[dict[str, Any]],
total_records: int,
):
filename = endpoint_to_filename(endpoint)
path = self.output_dir / filename
routing_calls = []
try:
for call in plan_calls(endpoint, params):
routing_calls.append({"endpoint": call.endpoint, "params": call.params})
except Exception:
routing_calls = []
payload = {
"task_code": self.task_code,
"run_id": self.run_id,
"endpoint": endpoint,
"params": params or {},
"endpoint_routing": {"calls": routing_calls} if routing_calls else None,
"page_size": page_size,
"pages": pages,
"total_records": total_records,
"dumped_at": datetime.utcnow().isoformat() + "Z",
}
dump_json(path, payload, pretty=self.write_pretty)
self.last_dump = {
"file": str(path),
"endpoint": endpoint,
"pages": len(pages),
"records": total_records,
}
def _cfg_get(cfg, key: str, default=None):
if isinstance(cfg, dict):
cur = cfg
for part in key.split("."):
if not isinstance(cur, dict) or part not in cur:
return default
cur = cur[part]
return cur
getter = getattr(cfg, "get", None)
if callable(getter):
return getter(key, default)
return default
def build_recording_client(
cfg,
*,
task_code: str,
output_dir: Path | str | None = None,
run_id: int | None = None,
write_pretty: bool | None = None,
):
"""Build RecordingAPIClient from AppConfig or dict config."""
base_client = APIClient(
base_url=_cfg_get(cfg, "api.base_url") or "",
token=_cfg_get(cfg, "api.token"),
timeout=int(_cfg_get(cfg, "api.timeout_sec", 20) or 20),
retry_max=int(_cfg_get(cfg, "api.retries.max_attempts", 3) or 3),
headers_extra=_cfg_get(cfg, "api.headers_extra") or {},
)
if write_pretty is None:
write_pretty = bool(_cfg_get(cfg, "io.write_pretty_json", False))
if run_id is None:
run_id = int(time.time())
if output_dir is None:
tz_name = _cfg_get(cfg, "app.timezone", "Asia/Taipei") or "Asia/Taipei"
tz = ZoneInfo(tz_name)
ts = datetime.now(tz).strftime("%Y%m%d-%H%M%S")
fetch_root = _cfg_get(cfg, "pipeline.fetch_root") or _cfg_get(cfg, "io.export_root") or "export/JSON"
task_upper = str(task_code).upper()
output_dir = Path(fetch_root) / task_upper / f"{task_upper}-{run_id}-{ts}"
return RecordingAPIClient(
base_client=base_client,
output_dir=output_dir,
task_code=str(task_code),
run_id=int(run_id),
write_pretty=bool(write_pretty),
)

0
cli/__init__.py Normal file
View File

504
cli/main.py Normal file
View File

@@ -0,0 +1,504 @@
# -*- coding: utf-8 -*-
"""CLI主入口
支持两种执行模式：
1. 传统模式：指定任务列表直接执行
2. 管道模式：指定管道类型和处理模式，执行多层 ETL
处理模式说明：
- increment_only：仅增量 - 只执行增量数据处理
- verify_only：校验并修复 - 跳过增量，直接校验数据一致性并自动补齐
- 可选 --fetch-before-verify：校验前先从 API 获取数据
- increment_verify：增量+校验并修复 - 先增量处理，再校验补齐
示例：
# 传统模式
python -m cli.main --tasks ODS_MEMBER,ODS_ORDER
# 管道模式（仅增量）
python -m cli.main --pipeline api_full --processing-mode increment_only
# 管道模式（校验并修复，跳过增量）
python -m cli.main --pipeline api_full --processing-mode verify_only
# 管道模式（校验并修复，校验前先从 API 获取数据）
python -m cli.main --pipeline api_full --processing-mode verify_only --fetch-before-verify
# 管道模式（增量+校验并修复）
python -m cli.main --pipeline api_full --processing-mode increment_verify
# 带时间窗口的管道模式
python -m cli.main --pipeline api_ods_dwd --window-start "2026-02-01" --window-end "2026-02-02"
"""
import sys
import argparse
import logging
from datetime import datetime
from pathlib import Path
from config.settings import AppConfig
from orchestration.scheduler import ETLScheduler # 保留，task 9 处理薄包装层
# 新架构依赖
from database.connection import DatabaseConnection
from database.operations import DatabaseOperations
from orchestration.cursor_manager import CursorManager
from orchestration.run_tracker import RunTracker
from orchestration.task_registry import default_registry
from orchestration.task_executor import TaskExecutor
from orchestration.pipeline_runner import PipelineRunner
from api.client import APIClient
# 管道选项
PIPELINE_CHOICES = [
"api_ods", # API → ODS
"api_ods_dwd", # API → ODS → DWD
"api_full", # API → ODS → DWD → DWS汇总 → DWS指数
"ods_dwd", # ODS → DWD
"dwd_dws", # DWD → DWS汇总
"dwd_dws_index", # DWD → DWS汇总 → DWS指数
"dwd_index", # DWD → DWS指数
]
# 处理模式选项
PROCESSING_MODE_CHOICES = [
"increment_only", # 仅增量
"verify_only", # 校验并修复（跳过增量）
"increment_verify", # 增量 + 校验并修复
]
# 时间窗口切分选项
WINDOW_SPLIT_CHOICES = ["none", "day", "week", "month"]
def setup_logging():
"""设置日志（使用统一格式）"""
try:
from utils.logging_utils import UNIFIED_FORMAT, DATE_FORMAT
fmt = UNIFIED_FORMAT
datefmt = DATE_FORMAT
except ImportError:
fmt = "[%(asctime)s] %(levelname)-5s | %(name)s | %(message)s"
datefmt = "%Y-%m-%d %H:%M:%S"
logging.basicConfig(level=logging.INFO, format=fmt, datefmt=datefmt)
return logging.getLogger("etl_billiards")
def parse_args():
"""解析命令行参数"""
parser = argparse.ArgumentParser(
description="台球场ETL系统",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
示例：
# 传统任务模式
python -m cli.main --tasks ODS_MEMBER,ODS_ORDER --store-id 1
# 管道模式（仅增量）
python -m cli.main --pipeline api_ods_dwd --processing-mode increment_only
# 管道模式（校验并修复，跳过增量）
python -m cli.main --pipeline api_full --processing-mode verify_only
# 管道模式（校验并修复，先从 API 获取数据）
python -m cli.main --pipeline api_full --processing-mode verify_only --fetch-before-verify
# 管道模式（增量+校验并修复）
python -m cli.main --pipeline api_full --processing-mode increment_verify
# 指定时间窗口
python -m cli.main --pipeline api_ods --window-start "2026-02-01" --window-end "2026-02-02"
""",
)
# 基本参数
parser.add_argument("--store-id", type=int, help="门店ID")
parser.add_argument("--tasks", help="任务列表，逗号分隔（传统模式）")
parser.add_argument("--dry-run", action="store_true", help="试运行（不提交）")
# 管道参数（新增）
parser.add_argument(
"--pipeline",
choices=PIPELINE_CHOICES,
help="管道类型：api_ods, api_ods_dwd, api_full, ods_dwd, dwd_dws, dwd_dws_index, dwd_index",
)
parser.add_argument(
"--processing-mode",
dest="processing_mode",
choices=PROCESSING_MODE_CHOICES,
default="increment_only",
help="处理模式：increment_only（仅增量）/ verify_only（校验并修复）/ increment_verify（增量+校验并修复）",
)
parser.add_argument(
"--fetch-before-verify",
dest="fetch_before_verify",
action="store_true",
help="校验前先从 API 获取数据（仅在 verify_only 模式下有效）",
)
parser.add_argument(
"--verify-tables",
dest="verify_tables",
help="仅校验指定表（逗号分隔），用于单表验证",
)
parser.add_argument(
"--window-split",
dest="window_split",
choices=WINDOW_SPLIT_CHOICES,
default="none",
help="时间窗口切分：none（不切分）/ day / week / month",
)
parser.add_argument(
"--lookback-hours",
dest="lookback_hours",
type=int,
default=24,
help="回溯小时数（默认24小时）",
)
parser.add_argument(
"--overlap-seconds",
dest="overlap_seconds",
type=int,
default=3600,
help="冗余秒数（默认3600秒=1小时）",
)
# 数据库参数
parser.add_argument("--pg-dsn", help="PostgreSQL DSN")
parser.add_argument("--pg-host", help="PostgreSQL主机")
parser.add_argument("--pg-port", type=int, help="PostgreSQL端口")
parser.add_argument("--pg-name", help="PostgreSQL数据库名")
parser.add_argument("--pg-user", help="PostgreSQL用户名")
parser.add_argument("--pg-password", help="PostgreSQL密码")
# API参数
parser.add_argument("--api-base", help="API基础URL")
parser.add_argument("--api-token", "--token", dest="api_token", help="API令牌（Bearer Token）")
parser.add_argument("--api-timeout", type=int, help="API超时(秒)")
parser.add_argument("--api-page-size", type=int, help="分页大小")
parser.add_argument("--api-retry-max", type=int, help="API重试最大次数")
# 回溯/手动窗口
parser.add_argument(
"--window-start",
dest="window_start",
help="固定时间窗口开始（优先级高于游标，例如：2025-07-01 00:00:00）",
)
parser.add_argument(
"--window-end",
dest="window_end",
help="固定时间窗口结束（优先级高于游标，推荐用月末+1，例如：2025-08-01 00:00:00）",
)
parser.add_argument(
"--force-window-override",
action="store_true",
help="强制使用 window_start/window_end，不走 MAX(fetched_at) 兜底",
)
parser.add_argument(
"--window-split-unit",
dest="window_split_unit",
help="窗口切分单位（day/week/month/none），默认来自配置 run.window_split.unit",
)
parser.add_argument(
"--window-split-days",
dest="window_split_days",
type=int,
choices=[1, 10, 30],
help="按天切分的天数（1/10/30），默认来自配置 run.window_split.days",
)
parser.add_argument(
"--window-compensation-hours",
dest="window_compensation_hours",
type=int,
help="窗口前后补偿小时数，默认来自配置 run.window_split.compensation_hours",
)
# 目录参数
parser.add_argument("--export-root", help="导出根目录")
parser.add_argument("--log-root", help="日志根目录")
# 数据源模式（新参数，替代 --pipeline-flow）
parser.add_argument(
"--data-source",
dest="data_source",
choices=["online", "offline", "hybrid"],
default=None,
help="数据源模式：online（仅在线抓取）/ offline（仅本地入库）/ hybrid（抓取+入库）",
)
# 抓取/清洗管线（--pipeline-flow 已弃用，请使用 --data-source）
parser.add_argument("--pipeline-flow", choices=["FULL", "FETCH_ONLY", "INGEST_ONLY"], help="[已弃用] 请使用 --data-source")
parser.add_argument("--fetch-root", help="抓取JSON输出根目录")
parser.add_argument("--ingest-source", help="本地清洗入库源目录")
parser.add_argument("--write-pretty-json", action="store_true", help="抓取JSON美化输出")
# 运行窗口
parser.add_argument("--idle-start", help="闲时窗口开始(HH:MM)")
parser.add_argument("--idle-end", help="闲时窗口结束(HH:MM)")
parser.add_argument("--allow-empty-advance", action="store_true", help="允许空结果推进窗口")
return parser.parse_args()
def resolve_data_source(args) -> str:
"""解析 data_source 参数，处理旧参数 --pipeline-flow 的弃用映射。
优先级：--data-source > --pipeline-flow > 默认值 hybrid
"""
_FLOW_TO_DATA_SOURCE = {
"FULL": "hybrid",
"FETCH_ONLY": "online",
"INGEST_ONLY": "offline",
}
if args.data_source:
return args.data_source
if args.pipeline_flow:
import warnings
mapped = _FLOW_TO_DATA_SOURCE.get(args.pipeline_flow.upper(), "hybrid")
warnings.warn(
f"--pipeline-flow 已弃用，请使用 --data-source {mapped}",
DeprecationWarning,
stacklevel=2,
)
return mapped
return "hybrid" # 默认值
def build_cli_overrides(args) -> dict:
"""从命令行参数构建配置覆盖"""
overrides = {}
# 基本信息
if args.store_id is not None:
overrides.setdefault("app", {})["store_id"] = args.store_id
# 数据库
if args.pg_dsn:
overrides.setdefault("db", {})["dsn"] = args.pg_dsn
if args.pg_host:
overrides.setdefault("db", {})["host"] = args.pg_host
if args.pg_port:
overrides.setdefault("db", {})["port"] = args.pg_port
if args.pg_name:
overrides.setdefault("db", {})["name"] = args.pg_name
if args.pg_user:
overrides.setdefault("db", {})["user"] = args.pg_user
if args.pg_password:
overrides.setdefault("db", {})["password"] = args.pg_password
# API
if args.api_base:
overrides.setdefault("api", {})["base_url"] = args.api_base
if args.api_token:
overrides.setdefault("api", {})["token"] = args.api_token
if args.api_timeout:
overrides.setdefault("api", {})["timeout_sec"] = args.api_timeout
if args.api_page_size:
overrides.setdefault("api", {})["page_size"] = args.api_page_size
if args.api_retry_max:
overrides.setdefault("api", {}).setdefault("retries", {})["max_attempts"] = args.api_retry_max
# 目录
if args.export_root:
overrides.setdefault("io", {})["export_root"] = args.export_root
if args.log_root:
overrides.setdefault("io", {})["log_root"] = args.log_root
# 抓取/清洗管线（旧参数保留向后兼容）
if args.pipeline_flow:
overrides.setdefault("pipeline", {})["flow"] = args.pipeline_flow.upper()
# 数据源模式（新参数）
data_source = resolve_data_source(args)
overrides.setdefault("run", {})["data_source"] = data_source
if args.fetch_root:
overrides.setdefault("pipeline", {})["fetch_root"] = args.fetch_root
if args.ingest_source:
overrides.setdefault("pipeline", {})["ingest_source_dir"] = args.ingest_source
if args.write_pretty_json:
overrides.setdefault("io", {})["write_pretty_json"] = True
# 回溯/手动窗口
if args.window_start or args.window_end:
overrides.setdefault("run", {}).setdefault("window_override", {})
if args.window_start:
overrides["run"]["window_override"]["start"] = args.window_start
if args.window_end:
overrides["run"]["window_override"]["end"] = args.window_end
if args.force_window_override:
overrides.setdefault("run", {})["force_window_override"] = True
if args.window_split_unit:
overrides.setdefault("run", {}).setdefault("window_split", {})["unit"] = args.window_split_unit
if args.window_split_days is not None:
overrides.setdefault("run", {}).setdefault("window_split", {})["days"] = args.window_split_days
if args.window_compensation_hours is not None:
overrides.setdefault("run", {}).setdefault("window_split", {})[
"compensation_hours"
] = args.window_compensation_hours
# 运行窗口
if args.idle_start:
overrides.setdefault("run", {}).setdefault("idle_window", {})["start"] = args.idle_start
if args.idle_end:
overrides.setdefault("run", {}).setdefault("idle_window", {})["end"] = args.idle_end
if args.allow_empty_advance:
overrides.setdefault("run", {})["allow_empty_result_advance"] = True
# 任务
if args.tasks:
tasks = [t.strip().upper() for t in args.tasks.split(",") if t.strip()]
overrides.setdefault("run", {})["tasks"] = tasks
return overrides
def parse_datetime(s: str) -> datetime:
"""解析日期时间字符串"""
if not s:
return None
formats = [
"%Y-%m-%d %H:%M:%S",
"%Y-%m-%d %H:%M",
"%Y-%m-%d",
"%Y/%m/%d %H:%M:%S",
"%Y/%m/%d",
]
for fmt in formats:
try:
return datetime.strptime(s, fmt)
except ValueError:
continue
raise ValueError(f"无法解析日期时间: {s}")
def main():
"""主函数
资源生命周期由 CLI 层统一管理（try/finally），
TaskExecutor / PipelineRunner 通过依赖注入接收已创建的资源。
"""
logger = setup_logging()
args = parse_args()
try:
# 加载配置
cli_overrides = build_cli_overrides(args)
config = AppConfig.load(cli_overrides)
logger.info("配置加载完成")
logger.info("门店ID: %s", config.get('app.store_id'))
# ── 创建资源 ──────────────────────────────────────────
db_conn = DatabaseConnection(
dsn=config["db"]["dsn"],
session=config["db"].get("session"),
connect_timeout=config["db"].get("connect_timeout_sec"),
)
api_client = APIClient(
base_url=config["api"]["base_url"],
token=config["api"]["token"],
timeout=config["api"].get("timeout_sec", 20),
retry_max=config["api"].get("retries", {}).get("max_attempts", 3),
headers_extra=config["api"].get("headers_extra"),
)
try:
# ── 组装依赖 ──────────────────────────────────────
db_ops = DatabaseOperations(db_conn)
cursor_mgr = CursorManager(db_conn)
run_tracker = RunTracker(db_conn)
registry = default_registry
executor = TaskExecutor(
config, db_ops, api_client,
cursor_mgr, run_tracker, registry, logger,
)
data_source = resolve_data_source(args)
# ── 判断执行模式 ──────────────────────────────────
if args.pipeline:
# 管道模式
logger.info("执行模式: 管道模式")
logger.info("管道类型: %s", args.pipeline)
logger.info("处理模式: %s", args.processing_mode)
# 解析时间窗口
window_start = None
window_end = None
if args.window_start:
window_start = parse_datetime(args.window_start)
if args.window_end:
window_end = parse_datetime(args.window_end)
# 如果没有指定时间窗口，使用回溯
if window_start is None and window_end is None:
from datetime import timedelta
from zoneinfo import ZoneInfo
tz = ZoneInfo(config.get("app.timezone", "Asia/Shanghai"))
window_end = datetime.now(tz)
window_start = window_end - timedelta(hours=args.lookback_hours)
logger.info("使用回溯时间窗口: %s ~ %s", window_start, window_end)
# 将回溯窗口设置为 window_override，确保 ODS 任务使用指定窗口
config.config.setdefault("run", {}).setdefault("window_override", {})
config.config["run"]["window_override"]["start"] = window_start
config.config["run"]["window_override"]["end"] = window_end
# 任务过滤器
task_codes = None
if args.tasks:
task_codes = [t.strip().upper() for t in args.tasks.split(",") if t.strip()]
# 校验表过滤
verify_tables = None
if args.verify_tables:
verify_tables = [t.strip().lower() for t in args.verify_tables.split(",") if t.strip()]
# 组装 PipelineRunner 并执行
runner = PipelineRunner(
config, executor, registry,
db_conn, api_client, logger,
)
result = runner.run(
pipeline=args.pipeline,
processing_mode=args.processing_mode,
data_source=data_source,
window_start=window_start,
window_end=window_end,
window_split=args.window_split if args.window_split != "none" else None,
task_codes=task_codes,
fetch_before_verify=args.fetch_before_verify,
verify_tables=verify_tables,
)
logger.info("管道执行完成: %s", result.get("status"))
else:
# 传统模式
logger.info("执行模式: 传统模式")
task_codes = config.get("run.tasks")
logger.info("任务列表: %s", task_codes)
executor.run_tasks(task_codes, data_source=data_source)
finally:
# 确保资源释放（需求 6.1, 6.4）
db_conn.close()
logger.info("ETL运行完成")
return 0
except Exception as e:
logger.error("ETL运行失败: %s", e, exc_info=True)
return 1
if __name__ == "__main__":
sys.exit(main())

0
config/__init__.py Normal file
View File

177
config/defaults.py Normal file
View File

@@ -0,0 +1,177 @@
# -*- coding: utf-8 -*-
"""配置默认值定义"""
DEFAULTS = {
"app": {
"timezone": "Asia/Shanghai",
"store_id": "",
"schema_oltp": "billiards",
"schema_etl": "etl_admin",
},
"db": {
"dsn": "",
"host": "",
"port": "",
"name": "",
"user": "",
"password": "",
"connect_timeout_sec": 20,
"batch_size": 1000,
"session": {
"timezone": "Asia/Shanghai",
"statement_timeout_ms": 30000,
"lock_timeout_ms": 5000,
"idle_in_tx_timeout_ms": 600000,
},
},
"api": {
"base_url": "https://pc.ficoo.vip/apiprod/admin/v1",
"token": None,
"timeout_sec": 20,
"page_size": 200,
"params": {},
"retries": {
"max_attempts": 3,
"backoff_sec": [1, 2, 4],
},
"headers_extra": {},
},
"run": {
"data_source": "hybrid",
"tasks": [
"PRODUCTS",
"TABLES",
"MEMBERS",
"ASSISTANTS",
"PACKAGES_DEF",
"ORDERS",
"PAYMENTS",
"REFUNDS",
"COUPON_USAGE",
"INVENTORY_CHANGE",
"TOPUPS",
"TABLE_DISCOUNT",
"ASSISTANT_ABOLISH",
"LEDGER",
],
"dws_tasks": [],
"index_tasks": [],
"index_lookback_days": 60,
"window_minutes": {
"default_busy": 30,
"default_idle": 180,
},
"overlap_seconds": 600,
"snapshot_missing_delete": True,
"snapshot_allow_empty_delete": False,
"window_split": {
"unit": "day",
"days": 10,
"compensation_hours": 2,
},
"idle_window": {
"start": "04:00",
"end": "16:00",
},
"allow_empty_result_advance": True,
},
"io": {
"export_root": "export/JSON",
"log_root": "export/LOG",
"fetch_root": "export/JSON",
"ingest_source_dir": "",
"manifest_name": "manifest.json",
"ingest_report_name": "ingest_report.json",
"write_pretty_json": True,
"max_file_bytes": 50 * 1024 * 1024,
},
"pipeline": {
# 运行流程：FETCH_ONLY（仅在线抓取落盘）、INGEST_ONLY（本地清洗入库）、FULL（抓取 + 清洗入库）
"flow": "FULL",
# 在线抓取 JSON 输出根目录（按任务、run_id 与时间自动创建子目录）
"fetch_root": "export/JSON",
# 本地清洗入库时的 JSON 输入目录（为空则默认使用本次抓取目录）
"ingest_source_dir": "",
},
"clean": {
"log_unknown_fields": True,
"unknown_fields_limit": 50,
"hash_key": {
"algo": "sha1",
"salt": "",
},
"strict_numeric": True,
"round_money_scale": 2,
},
"security": {
"redact_in_logs": True,
"redact_keys": ["token", "password", "Authorization"],
"echo_token_in_logs": False,
},
"ods": {
# ODS 离线重建/回放相关（仅开发/运维使用）
"json_doc_dir": "export/test-json-doc",
"include_files": "",
"drop_schema_first": True,
},
"integrity": {
"mode": "history",
"history_start": "2025-07-01",
"history_end": "",
"include_dimensions": True,
"auto_check": False,
"auto_backfill": False,
"compare_content": True,
"content_sample_limit": 50,
"backfill_mismatch": True,
"recheck_after_backfill": True,
"ods_task_codes": "",
"force_monthly_split": True,
},
"verification": {
"skip_ods_when_fetch_before_verify": True,
"ods_use_local_json": True,
},
"dws": {
"monthly": {
"allow_history": False,
"prev_month_grace_days": 5,
"history_months": 0,
"new_hire_cap_effective_from": "2026-03-01",
"new_hire_cap_day": 25,
"new_hire_max_tier_level": 2,
},
"salary": {
"run_days": 5,
"allow_out_of_cycle": False,
"room_course_price": 138,
},
},
"dwd": {
"fact_upsert": True,
# 事实表补齐 UPSERT 批量参数（可按锁冲突情况调优）
"fact_upsert_batch_size": 1000,
"fact_upsert_min_batch_size": 100,
"fact_upsert_max_retries": 2,
"fact_upsert_retry_backoff_sec": [1, 2, 4],
# 仅对事实表 backfill 设置的锁等待超时（None 表示沿用 db.session.lock_timeout_ms）
"fact_upsert_lock_timeout_ms": None,
},
}
# 任务代码常量
TASK_ORDERS = "ORDERS"
TASK_PAYMENTS = "PAYMENTS"
TASK_REFUNDS = "REFUNDS"
TASK_INVENTORY_CHANGE = "INVENTORY_CHANGE"
TASK_COUPON_USAGE = "COUPON_USAGE"
TASK_MEMBERS = "MEMBERS"
TASK_ASSISTANTS = "ASSISTANTS"
TASK_PRODUCTS = "PRODUCTS"
TASK_TABLES = "TABLES"
TASK_PACKAGES_DEF = "PACKAGES_DEF"
TASK_TOPUPS = "TOPUPS"
TASK_TABLE_DISCOUNT = "TABLE_DISCOUNT"
TASK_ASSISTANT_ABOLISH = "ASSISTANT_ABOLISH"
TASK_LEDGER = "LEDGER"

213
config/env_parser.py Normal file
View File

@@ -0,0 +1,213 @@
# -*- coding: utf-8 -*-
"""环境变量解析"""
import os
import json
from pathlib import Path
from copy import deepcopy
ENV_MAP = {
"TIMEZONE": ("app.timezone",),
"STORE_ID": ("app.store_id",),
"SCHEMA_OLTP": ("app.schema_oltp",),
"SCHEMA_ETL": ("app.schema_etl",),
"PG_DSN": ("db.dsn",),
"PG_HOST": ("db.host",),
"PG_PORT": ("db.port",),
"PG_NAME": ("db.name",),
"PG_USER": ("db.user",),
"PG_PASSWORD": ("db.password",),
"PG_CONNECT_TIMEOUT": ("db.connect_timeout_sec",),
"API_BASE": ("api.base_url",),
"API_TOKEN": ("api.token",),
"FICOO_TOKEN": ("api.token",),
"API_TIMEOUT": ("api.timeout_sec",),
"API_PAGE_SIZE": ("api.page_size",),
"API_RETRY_MAX": ("api.retries.max_attempts",),
"API_RETRY_BACKOFF": ("api.retries.backoff_sec",),
"API_PARAMS": ("api.params",),
"EXPORT_ROOT": ("io.export_root",),
"LOG_ROOT": ("io.log_root",),
"MANIFEST_NAME": ("io.manifest_name",),
"INGEST_REPORT_NAME": ("io.ingest_report_name",),
"WRITE_PRETTY_JSON": ("io.write_pretty_json",),
"RUN_TASKS": ("run.tasks",),
"RUN_DWS_TASKS": ("run.dws_tasks",),
"RUN_INDEX_TASKS": ("run.index_tasks",),
"INDEX_LOOKBACK_DAYS": ("run.index_lookback_days",),
"OVERLAP_SECONDS": ("run.overlap_seconds",),
"WINDOW_BUSY_MIN": ("run.window_minutes.default_busy",),
"WINDOW_IDLE_MIN": ("run.window_minutes.default_idle",),
"IDLE_START": ("run.idle_window.start",),
"IDLE_END": ("run.idle_window.end",),
"IDLE_WINDOW_START": ("run.idle_window.start",),
"IDLE_WINDOW_END": ("run.idle_window.end",),
"ALLOW_EMPTY_RESULT_ADVANCE": ("run.allow_empty_result_advance",),
"ALLOW_EMPTY_ADVANCE": ("run.allow_empty_result_advance",),
"SNAPSHOT_MISSING_DELETE": ("run.snapshot_missing_delete",),
"SNAPSHOT_ALLOW_EMPTY_DELETE": ("run.snapshot_allow_empty_delete",),
"WINDOW_START": ("run.window_override.start",),
"WINDOW_END": ("run.window_override.end",),
"WINDOW_SPLIT_UNIT": ("run.window_split.unit",),
"WINDOW_SPLIT_DAYS": ("run.window_split.days",),
"WINDOW_COMPENSATION_HOURS": ("run.window_split.compensation_hours",),
"PIPELINE_FLOW": ("pipeline.flow",),
"JSON_FETCH_ROOT": ("pipeline.fetch_root",),
"JSON_SOURCE_DIR": ("pipeline.ingest_source_dir",),
"FETCH_ROOT": ("pipeline.fetch_root",),
"INGEST_SOURCE_DIR": ("pipeline.ingest_source_dir",),
"INTEGRITY_MODE": ("integrity.mode",),
"INTEGRITY_HISTORY_START": ("integrity.history_start",),
"INTEGRITY_HISTORY_END": ("integrity.history_end",),
"INTEGRITY_INCLUDE_DIMENSIONS": ("integrity.include_dimensions",),
"INTEGRITY_AUTO_CHECK": ("integrity.auto_check",),
"INTEGRITY_AUTO_BACKFILL": ("integrity.auto_backfill",),
"INTEGRITY_COMPARE_CONTENT": ("integrity.compare_content",),
"INTEGRITY_CONTENT_SAMPLE_LIMIT": ("integrity.content_sample_limit",),
"INTEGRITY_BACKFILL_MISMATCH": ("integrity.backfill_mismatch",),
"INTEGRITY_RECHECK_AFTER_BACKFILL": ("integrity.recheck_after_backfill",),
"INTEGRITY_ODS_TASK_CODES": ("integrity.ods_task_codes",),
"VERIFY_SKIP_ODS_ON_FETCH": ("verification.skip_ods_when_fetch_before_verify",),
"VERIFY_ODS_LOCAL_JSON": ("verification.ods_use_local_json",),
"DWD_FACT_UPSERT": ("dwd.fact_upsert",),
# DWS 月度/薪资配置
"DWS_MONTHLY_ALLOW_HISTORY": ("dws.monthly.allow_history",),
"DWS_MONTHLY_PREV_GRACE_DAYS": ("dws.monthly.prev_month_grace_days",),
"DWS_MONTHLY_HISTORY_MONTHS": ("dws.monthly.history_months",),
"DWS_MONTHLY_NEW_HIRE_CAP_EFFECTIVE_FROM": ("dws.monthly.new_hire_cap_effective_from",),
"DWS_MONTHLY_NEW_HIRE_CAP_DAY": ("dws.monthly.new_hire_cap_day",),
"DWS_MONTHLY_NEW_HIRE_MAX_TIER_LEVEL": ("dws.monthly.new_hire_max_tier_level",),
"DWS_SALARY_RUN_DAYS": ("dws.salary.run_days",),
"DWS_SALARY_ALLOW_OUT_OF_CYCLE": ("dws.salary.allow_out_of_cycle",),
"DWS_SALARY_ROOM_COURSE_PRICE": ("dws.salary.room_course_price",),
# ODS 离线回放配置
"ODS_JSON_DOC_DIR": ("ods.json_doc_dir",),
"ODS_INCLUDE_FILES": ("ods.include_files",),
"ODS_DROP_SCHEMA_FIRST": ("ods.drop_schema_first",),
}
def _deep_set(d, dotted_keys, value):
cur = d
for k in dotted_keys[:-1]:
cur = cur.setdefault(k, {})
cur[dotted_keys[-1]] = value
def _coerce_env(v: str):
if v is None:
return None
s = v.strip()
if s.lower() in ("true", "false"):
return s.lower() == "true"
try:
if s.isdigit() or (s.startswith("-") and s[1:].isdigit()):
return int(s)
except Exception:
pass
if (s.startswith("{") and s.endswith("}")) or (s.startswith("[") and s.endswith("]")):
try:
return json.loads(s)
except Exception:
return s
return s
def _strip_inline_comment(value: str) -> str:
"""去掉未被引号包裹的内联注释"""
result = []
in_quote = False
quote_char = ""
escape = False
for ch in value:
if escape:
result.append(ch)
escape = False
continue
if ch == "\\":
escape = True
result.append(ch)
continue
if ch in ("'", '"'):
if not in_quote:
in_quote = True
quote_char = ch
elif quote_char == ch:
in_quote = False
quote_char = ""
result.append(ch)
continue
if ch == "#" and not in_quote:
break
result.append(ch)
return "".join(result).rstrip()
def _unquote_value(value: str) -> str:
"""处理引号/原始字符串以及尾随逗号"""
trimmed = value.strip()
trimmed = _strip_inline_comment(trimmed)
trimmed = trimmed.rstrip(",").rstrip()
if not trimmed:
return trimmed
if len(trimmed) >= 2 and trimmed[0] in ("'", '"') and trimmed[-1] == trimmed[0]:
return trimmed[1:-1]
if (
len(trimmed) >= 3
and trimmed[0] in ("r", "R")
and trimmed[1] in ("'", '"')
and trimmed[-1] == trimmed[1]
):
return trimmed[2:-1]
return trimmed
def _parse_dotenv_line(line: str) -> tuple[str, str] | None:
"""解析 .env 文件中的单行"""
stripped = line.strip()
if not stripped or stripped.startswith("#"):
return None
if stripped.startswith("export "):
stripped = stripped[len("export ") :].strip()
if "=" not in stripped:
return None
key, value = stripped.split("=", 1)
key = key.strip()
value = _unquote_value(value)
return key, value
def _load_dotenv_values() -> dict:
"""从项目根目录读取 .env 文件键值"""
if os.environ.get("ETL_SKIP_DOTENV") in ("1", "true", "TRUE", "True"):
return {}
root = Path(__file__).resolve().parents[1]
dotenv_path = root / ".env"
if not dotenv_path.exists():
return {}
values: dict[str, str] = {}
for line in dotenv_path.read_text(encoding="utf-8", errors="ignore").splitlines():
parsed = _parse_dotenv_line(line)
if parsed:
key, value = parsed
values[key] = value
return values
def _apply_env_values(cfg: dict, source: dict):
for env_key, dotted in ENV_MAP.items():
val = source.get(env_key)
if val is None:
continue
v2 = _coerce_env(val)
for path in dotted:
if path in ("run.tasks", "run.dws_tasks", "run.index_tasks") and isinstance(v2, str):
v2 = [item.strip() for item in v2.split(",") if item.strip()]
_deep_set(cfg, path.split("."), v2)
def load_env_overrides(defaults: dict) -> dict:
cfg = deepcopy(defaults)
# 先读取 .env，再读取真实环境变量，确保 CLI 仍然最高优先级
_apply_env_values(cfg, _load_dotenv_values())
_apply_env_values(cfg, os.environ)
return cfg

3
config/scheduled_tasks.json Normal file
View File

@@ -0,0 +1,3 @@
{
"tasks": {}
}

127
config/settings.py Normal file
View File

@@ -0,0 +1,127 @@
# -*- coding: utf-8 -*-
"""配置管理主类"""
import warnings
from copy import deepcopy
from .defaults import DEFAULTS
from .env_parser import load_env_overrides
# pipeline.flow → run.data_source 值映射
_FLOW_TO_DATA_SOURCE = {
"FULL": "hybrid",
"FETCH_ONLY": "online",
"INGEST_ONLY": "offline",
}
class AppConfig:
"""应用配置管理器"""
def __init__(self, config_dict: dict):
self.config = config_dict
@classmethod
def load(cls, cli_overrides: dict = None):
"""加载配置: DEFAULTS < ENV < CLI"""
cfg = load_env_overrides(DEFAULTS)
if cli_overrides:
cls._deep_merge(cfg, cli_overrides)
# 规范化
cls._normalize(cfg)
cls._validate(cfg)
return cls(cfg)
@staticmethod
def _deep_merge(dst, src):
"""深度合并字典"""
for k, v in src.items():
if isinstance(v, dict) and isinstance(dst.get(k), dict):
AppConfig._deep_merge(dst[k], v)
else:
dst[k] = v
@staticmethod
def _normalize(cfg):
"""规范化配置"""
# 转换 store_id 为整数
try:
cfg["app"]["store_id"] = int(str(cfg["app"]["store_id"]).strip())
except Exception:
raise SystemExit("app.store_id 必须为整数")
# DSN 组装
if not cfg["db"]["dsn"]:
cfg["db"]["dsn"] = (
f"postgresql://{cfg['db']['user']}:{cfg['db']['password']}"
f"@{cfg['db']['host']}:{cfg['db']['port']}/{cfg['db']['name']}"
)
# connect_timeout 限定 1-20 秒
try:
timeout_sec = int(cfg["db"].get("connect_timeout_sec") or 5)
except Exception:
raise SystemExit("db.connect_timeout_sec 必须为整数")
cfg["db"]["connect_timeout_sec"] = max(1, min(timeout_sec, 20))
# 会话参数
cfg["db"].setdefault("session", {})
sess = cfg["db"]["session"]
sess.setdefault("timezone", cfg["app"]["timezone"])
for k in ("statement_timeout_ms", "lock_timeout_ms", "idle_in_tx_timeout_ms"):
if k in sess and sess[k] is not None:
try:
sess[k] = int(sess[k])
except Exception:
raise SystemExit(f"db.session.{k} 需为整数毫秒")
# ── 旧键 → 新键 兼容映射 ──
pipeline = cfg.get("pipeline", {})
run = cfg.setdefault("run", {})
io = cfg.setdefault("io", {})
# 1. pipeline.flow → run.data_source
# 仅当新键未被显式设置（缺失或仍为默认值 hybrid）时，才用旧键覆盖
old_flow = str(pipeline.get("flow", "")).upper()
if old_flow in _FLOW_TO_DATA_SOURCE:
mapped = _FLOW_TO_DATA_SOURCE[old_flow]
if run.get("data_source", "hybrid") == "hybrid" and mapped != "hybrid":
run["data_source"] = mapped
warnings.warn(
f"配置键 pipeline.flow={old_flow} 已弃用，"
f"已映射为 run.data_source={mapped}",
DeprecationWarning,
stacklevel=2,
)
# 2. pipeline.fetch_root → io.fetch_root（新键优先）
if pipeline.get("fetch_root") and not io.get("fetch_root"):
io["fetch_root"] = pipeline["fetch_root"]
# 3. pipeline.ingest_source_dir → io.ingest_source_dir（新键优先）
if pipeline.get("ingest_source_dir") and not io.get("ingest_source_dir"):
io["ingest_source_dir"] = pipeline["ingest_source_dir"]
@staticmethod
def _validate(cfg):
"""验证必填配置"""
missing = []
if not cfg["app"]["store_id"]:
missing.append("app.store_id")
if missing:
raise SystemExit("缺少必需配置: " + ", ".join(missing))
def get(self, key: str, default=None):
"""获取配置值（支持点号路径）"""
keys = key.split(".")
val = self.config
for k in keys:
if isinstance(val, dict):
val = val.get(k)
else:
return default
return val if val is not None else default
def __getitem__(self, key):
return self.config[key]

48
database/README.md Normal file
View File

@@ -0,0 +1,48 @@
# database/ — 数据库层
## 文件说明
| 文件 | 用途 |
|------|------|
| `connection.py` | 数据库连接管理（带超时的 psycopg2 封装） |
| `operations.py` | 批量操作（upsert、execute、query） |
| `base.py` | 数据库操作基础类 |
## DDL Schema 文件
| 文件 | Schema | 说明 |
|------|--------|------|
| `schema_ODS_doc.sql` | `billiards_ods` | ODS 层表结构（含字段注释） |
| `schema_dwd_doc.sql` | `billiards_dwd` | DWD 层表结构（维度 + 事实，含 SCD2 列） |
| `schema_dws.sql` | `billiards_dws` | DWS 层表结构（汇总表 + 配置表） |
| `schema_etl_admin.sql` | `etl_admin` | ETL 元数据（任务注册、游标、运行记录） |
| `schema_verify_perf_indexes.sql` | 各 Schema | 校验性能索引（仅索引 + ANALYZE） |
## 种子脚本
| 文件 | 用途 |
|------|------|
| `seed_ods_tasks.sql` | 注册 ODS 任务到 `etl_admin.etl_task` |
| `seed_scheduler_tasks.sql` | 初始化调度任务配置 |
| `seed_dws_config.sql` | DWS 配置数据（绩效档位、等级定价、技能映射等） |
| `seed_index_parameters.sql` | 指数算法参数（WBI/NCI/RS/OS/MS/ML） |
## 迁移脚本
位于 `migrations/` 子目录，纯 SQL，按日期前缀命名：
```
migrations/
└── 20260208_relation_index_manual_ml.sql
```
新增迁移时，文件名格式：`YYYYMMDD_描述.sql`
## Schema 约定
- 所有 DDL 使用 `CREATE TABLE IF NOT EXISTS`，支持幂等执行
- 表名小写蛇形，带 Schema 前缀（如 `billiards_dwd.dim_member`）
- 维度表包含 SCD2 列：`scd2_start_time`、`scd2_end_time`、`scd2_is_current`、`scd2_version`
- ODS 表包含元数据列：`content_hash`、`payload`、`fetched_at`、`source_file`
- 金额字段统一 `NUMERIC(12,2)`，ID 字段统一 `BIGINT`
- 不使用 ORM，所有 SQL 通过 `psycopg2` 直接执行

0
database/__init__.py Normal file
View File

112
database/base.py Normal file
View File

@@ -0,0 +1,112 @@
# -*- coding: utf-8 -*-
"""
数据库操作（批量、RETURNING支持）
"""
import re
from typing import List, Dict, Tuple
import psycopg2.extras
from .connection import DatabaseConnection
class DatabaseOperations(DatabaseConnection):
"""扩展数据库操作（包含批量upsert和returning支持）"""
def batch_execute(self, sql: str, rows: List[Dict], page_size: int = 1000):
"""批量执行SQL（不带RETURNING）"""
if not rows:
return
with self.conn.cursor() as c:
psycopg2.extras.execute_batch(c, sql, rows, page_size=page_size)
def batch_upsert_with_returning(self, sql: str, rows: List[Dict], page_size: int = 1000) -> Tuple[int, int]:
"""
批量 UPSERT 并统计插入/更新数
Args:
sql: 包含RETURNING子句的SQL
rows: 数据行列表
page_size: 批次大小
Returns:
(inserted_count, updated_count) 元组
"""
if not rows:
return (0, 0)
use_returning = "RETURNING" in sql.upper()
with self.conn.cursor() as c:
if not use_returning:
psycopg2.extras.execute_batch(c, sql, rows, page_size=page_size)
return (0, 0)
# 优先尝试向量化执行
try:
inserted, updated = self._execute_with_returning_vectorized(c, sql, rows, page_size)
return (inserted, updated)
except Exception:
# 回退到逐行执行
return self._execute_with_returning_row_by_row(c, sql, rows)
def _execute_with_returning_vectorized(self, cursor, sql: str, rows: List[Dict], page_size: int) -> Tuple[int, int]:
"""向量化执行（使用execute_values）"""
# 解析VALUES子句
m = re.search(r"VALUES\s*\((.*?)\)", sql, flags=re.IGNORECASE | re.DOTALL)
if not m:
raise ValueError("Cannot parse VALUES clause")
tpl = "(" + m.group(1) + ")"
base_sql = sql[:m.start()] + "VALUES %s" + sql[m.end():]
ret = psycopg2.extras.execute_values(
cursor, base_sql, rows, template=tpl, page_size=page_size, fetch=True
)
if not ret:
return (0, 0)
inserted = 0
for rec in ret:
flag = self._extract_inserted_flag(rec)
if flag:
inserted += 1
return (inserted, len(ret) - inserted)
def _execute_with_returning_row_by_row(self, cursor, sql: str, rows: List[Dict]) -> Tuple[int, int]:
"""逐行执行（回退方案）"""
inserted = 0
updated = 0
for r in rows:
cursor.execute(sql, r)
try:
rec = cursor.fetchone()
except Exception:
rec = None
flag = self._extract_inserted_flag(rec) if rec else None
if flag:
inserted += 1
else:
updated += 1
return (inserted, updated)
@staticmethod
def _extract_inserted_flag(rec) -> bool:
"""从返回记录中提取inserted标志"""
if isinstance(rec, tuple):
return bool(rec[0])
elif isinstance(rec, dict):
return bool(rec.get("inserted"))
else:
try:
return bool(rec["inserted"])
except Exception:
return False
# 为了向后兼容，提供Pg别名
Pg = DatabaseOperations

80
database/connection.py Normal file
View File

@@ -0,0 +1,80 @@
# -*- coding: utf-8 -*-
"""数据库连接管理器（限制最大连接超时时间）。"""
import psycopg2
import psycopg2.extras
class DatabaseConnection:
"""封装 psycopg2 连接，支持会话参数和超时保护。"""
def __init__(self, dsn: str, session: dict = None, connect_timeout: int = None):
self._dsn = dsn
self._session = session or {}
self._connect_timeout = connect_timeout
self.conn = self._open_connection()
def _open_connection(self):
"""创建并初始化连接（包含会话参数）。"""
timeout_val = self._connect_timeout if self._connect_timeout is not None else 5
# 生产环境要求：数据库连接超时不得超过 20 秒。
timeout_val = max(1, min(int(timeout_val), 20))
conn = psycopg2.connect(self._dsn, connect_timeout=timeout_val)
conn.autocommit = False
# 会话参数（时区、语句超时等）
if self._session:
with conn.cursor() as c:
if self._session.get("timezone"):
c.execute("SET TIME ZONE %s", (self._session["timezone"],))
if self._session.get("statement_timeout_ms") is not None:
c.execute(
"SET statement_timeout = %s",
(int(self._session["statement_timeout_ms"]),),
)
if self._session.get("lock_timeout_ms") is not None:
c.execute(
"SET lock_timeout = %s", (int(self._session["lock_timeout_ms"]),)
)
if self._session.get("idle_in_tx_timeout_ms") is not None:
c.execute(
"SET idle_in_transaction_session_timeout = %s",
(int(self._session["idle_in_tx_timeout_ms"]),),
)
return conn
def query(self, sql: str, args=None):
"""Execute a query and fetch all rows."""
with self.conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as c:
c.execute(sql, args)
return c.fetchall()
def execute(self, sql: str, args=None):
"""Execute a SQL statement without returning rows."""
with self.conn.cursor() as c:
c.execute(sql, args)
def commit(self):
"""Commit current transaction."""
self.conn.commit()
def rollback(self):
"""Rollback current transaction."""
self.conn.rollback()
def close(self):
"""Safely close the connection."""
try:
self.conn.close()
except Exception:
pass
def ensure_open(self) -> bool:
"""确保连接可用，若已关闭则尝试重连。"""
try:
if getattr(self.conn, "closed", 0):
self.conn = self._open_connection()
return True
except Exception:
return False

144
database/migrations/20260208_relation_index_manual_ml.sql Normal file
View File

@@ -0,0 +1,144 @@
-- =============================================================================
-- 关系指数与 ML 人工台账迁移脚本
-- 版本: 2026-02-08
-- 说明:
-- 1) 新增关系指数结果表 dws_member_assistant_relation_index
-- 2) 新增 ML 人工台账宽表/窄表
-- 3) 补充 RS/OS/MS/ML 参数并下线 INTIMACY
-- =============================================================================
BEGIN;
-- -----------------------------------------------------------------------------
-- 1) 关系指数结果表
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS billiards_dws.dws_member_assistant_relation_index (
relation_id BIGSERIAL PRIMARY KEY,
site_id BIGINT NOT NULL,
tenant_id BIGINT NOT NULL,
member_id BIGINT NOT NULL,
assistant_id BIGINT NOT NULL,
session_count INTEGER NOT NULL DEFAULT 0,
total_duration_minutes INTEGER NOT NULL DEFAULT 0,
basic_session_count INTEGER NOT NULL DEFAULT 0,
incentive_session_count INTEGER NOT NULL DEFAULT 0,
days_since_last_session INTEGER,
rs_f NUMERIC(14,6) NOT NULL DEFAULT 0,
rs_d NUMERIC(14,6) NOT NULL DEFAULT 0,
rs_r NUMERIC(14,6) NOT NULL DEFAULT 0,
rs_raw NUMERIC(14,6) NOT NULL DEFAULT 0,
rs_display NUMERIC(4,2) NOT NULL DEFAULT 0,
os_share NUMERIC(10,6) NOT NULL DEFAULT 0,
os_label VARCHAR(20) NOT NULL DEFAULT 'POOL',
os_rank INTEGER,
ms_f_short NUMERIC(14,6) NOT NULL DEFAULT 0,
ms_f_long NUMERIC(14,6) NOT NULL DEFAULT 0,
ms_raw NUMERIC(14,6) NOT NULL DEFAULT 0,
ms_display NUMERIC(4,2) NOT NULL DEFAULT 0,
ml_order_count INTEGER NOT NULL DEFAULT 0,
ml_allocated_amount NUMERIC(14,2) NOT NULL DEFAULT 0,
ml_raw NUMERIC(14,6) NOT NULL DEFAULT 0,
ml_display NUMERIC(4,2) NOT NULL DEFAULT 0,
calc_time TIMESTAMPTZ NOT NULL DEFAULT NOW(),
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
CONSTRAINT uk_dws_member_assistant_relation_index UNIQUE (site_id, member_id, assistant_id)
);
CREATE INDEX IF NOT EXISTS idx_dws_relation_member
ON billiards_dws.dws_member_assistant_relation_index (site_id, member_id, os_share DESC);
CREATE INDEX IF NOT EXISTS idx_dws_relation_assistant
ON billiards_dws.dws_member_assistant_relation_index (site_id, assistant_id, rs_display DESC);
CREATE INDEX IF NOT EXISTS idx_dws_relation_calc_time
ON billiards_dws.dws_member_assistant_relation_index (calc_time);
-- -----------------------------------------------------------------------------
-- 2) ML 人工台账宽表
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS billiards_dws.dws_ml_manual_order_source (
source_id BIGSERIAL PRIMARY KEY,
site_id BIGINT NOT NULL,
biz_date DATE NOT NULL,
external_id VARCHAR(128) NOT NULL,
member_id BIGINT NOT NULL DEFAULT 0,
pay_time TIMESTAMPTZ NOT NULL,
order_amount NUMERIC(14,2) NOT NULL DEFAULT 0,
currency VARCHAR(16) NOT NULL DEFAULT 'CNY',
assistant_id_1 BIGINT,
assistant_name_1 VARCHAR(128),
assistant_id_2 BIGINT,
assistant_name_2 VARCHAR(128),
assistant_id_3 BIGINT,
assistant_name_3 VARCHAR(128),
assistant_id_4 BIGINT,
assistant_name_4 VARCHAR(128),
assistant_id_5 BIGINT,
assistant_name_5 VARCHAR(128),
import_batch_no VARCHAR(64) NOT NULL,
import_file_name VARCHAR(255) NOT NULL,
import_scope_key VARCHAR(128) NOT NULL,
import_time TIMESTAMPTZ NOT NULL DEFAULT NOW(),
import_user VARCHAR(64),
row_no INTEGER NOT NULL,
remark TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
CONSTRAINT uk_dws_ml_manual_order_source UNIQUE (site_id, external_id, import_scope_key, row_no)
);
CREATE INDEX IF NOT EXISTS idx_dws_ml_source_scope
ON billiards_dws.dws_ml_manual_order_source (site_id, biz_date);
CREATE INDEX IF NOT EXISTS idx_dws_ml_source_external
ON billiards_dws.dws_ml_manual_order_source (site_id, external_id);
-- -----------------------------------------------------------------------------
-- 3) ML 人工台账窄表
-- -----------------------------------------------------------------------------
CREATE TABLE IF NOT EXISTS billiards_dws.dws_ml_manual_order_alloc (
alloc_id BIGSERIAL PRIMARY KEY,
site_id BIGINT NOT NULL,
biz_date DATE NOT NULL,
external_id VARCHAR(128) NOT NULL,
member_id BIGINT NOT NULL DEFAULT 0,
pay_time TIMESTAMPTZ NOT NULL,
order_amount NUMERIC(14,2) NOT NULL DEFAULT 0,
assistant_id BIGINT NOT NULL,
assistant_name VARCHAR(128),
share_ratio NUMERIC(14,8) NOT NULL DEFAULT 0,
allocated_amount NUMERIC(14,2) NOT NULL DEFAULT 0,
currency VARCHAR(16) NOT NULL DEFAULT 'CNY',
import_scope_key VARCHAR(128) NOT NULL,
import_batch_no VARCHAR(64) NOT NULL,
import_file_name VARCHAR(255) NOT NULL,
import_time TIMESTAMPTZ NOT NULL DEFAULT NOW(),
import_user VARCHAR(64),
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
CONSTRAINT uk_dws_ml_manual_order_alloc UNIQUE (site_id, external_id, assistant_id)
);
CREATE INDEX IF NOT EXISTS idx_dws_ml_alloc_scope
ON billiards_dws.dws_ml_manual_order_alloc (site_id, biz_date);
CREATE INDEX IF NOT EXISTS idx_dws_ml_alloc_member_assistant
ON billiards_dws.dws_ml_manual_order_alloc (site_id, member_id, assistant_id);
-- -----------------------------------------------------------------------------
-- 4) 参数切换
-- -----------------------------------------------------------------------------
UPDATE billiards_dws.cfg_index_parameters
SET effective_to = DATE '2025-12-31',
updated_at = NOW()
WHERE index_type = 'INTIMACY'
AND (effective_to IS NULL OR effective_to > DATE '2025-12-31');
INSERT INTO billiards_dws.cfg_index_parameters
(index_type, param_name, param_value, description, effective_from)
VALUES
('OS', 'ownership_gap_threshold', 0.150000, '主责与次席份额差阈值', DATE '2026-01-01'),
('ML', 'source_mode', 0.000000, '数据源模式：0=manual_only,1=last_touch_fallback', DATE '2026-01-01')
ON CONFLICT (index_type, param_name, effective_from) DO UPDATE SET
param_value = EXCLUDED.param_value,
description = EXCLUDED.description,
updated_at = NOW();
COMMIT;

107
database/operations.py Normal file
View File

@@ -0,0 +1,107 @@
# -*- coding: utf-8 -*-
"""数据库批量操作"""
import psycopg2.extras
import re
class DatabaseOperations:
"""数据库批量操作封装"""
def __init__(self, connection):
self._connection = connection
self.conn = connection.conn
def batch_execute(self, sql: str, rows: list, page_size: int = 1000):
"""批量执行SQL"""
if not rows:
return
with self.conn.cursor() as c:
psycopg2.extras.execute_batch(c, sql, rows, page_size=page_size)
def batch_upsert_with_returning(self, sql: str, rows: list,
page_size: int = 1000) -> tuple:
"""批量UPSERT并返回插入/更新计数"""
if not rows:
return (0, 0)
use_returning = "RETURNING" in sql.upper()
# 不带 RETURNING：直接批量执行即可
if not use_returning:
with self.conn.cursor() as c:
psycopg2.extras.execute_batch(c, sql, rows, page_size=page_size)
return (0, 0)
# 尝试向量化执行（execute_values + fetch returning）
vectorized_failed = False
m = re.search(r"VALUES\s*\((.*?)\)", sql, flags=re.IGNORECASE | re.DOTALL)
if m:
tpl = "(" + m.group(1) + ")"
base_sql = sql[:m.start()] + "VALUES %s" + sql[m.end():]
try:
with self.conn.cursor() as c:
ret = psycopg2.extras.execute_values(
c, base_sql, rows, template=tpl, page_size=page_size, fetch=True
)
if not ret:
return (0, 0)
inserted = sum(1 for rec in ret if self._is_inserted(rec))
return (inserted, len(ret) - inserted)
except Exception:
# 向量化失败后，事务通常处于 aborted 状态，需要先 rollback 才能继续执行。
vectorized_failed = True
if vectorized_failed:
try:
self.conn.rollback()
except Exception:
pass
# 回退：逐行执行
inserted = 0
updated = 0
with self.conn.cursor() as c:
for r in rows:
c.execute(sql, r)
try:
rec = c.fetchone()
except Exception:
rec = None
if self._is_inserted(rec):
inserted += 1
else:
updated += 1
return (inserted, updated)
@staticmethod
def _is_inserted(rec) -> bool:
"""判断是否为插入操作"""
if rec is None:
return False
if isinstance(rec, tuple):
return bool(rec[0])
if isinstance(rec, dict):
return bool(rec.get("inserted"))
return False
# --- 透传辅助方法 -------------------------------------------------
def commit(self):
"""提交事务（委托给底层连接）"""
self._connection.commit()
def rollback(self):
"""回滚事务（委托给底层连接）"""
self._connection.rollback()
def query(self, sql: str, args=None):
"""执行查询并返回结果"""
return self._connection.query(sql, args)
def execute(self, sql: str, args=None):
"""执行任意 SQL"""
self._connection.execute(sql, args)
def cursor(self):
"""暴露原生 cursor，供特殊操作使用"""
return self.conn.cursor()

2050
database/schema_ODS_doc.sql Normal file
View File

File diff suppressed because it is too large Load Diff

2083
database/schema_dwd_doc.sql Normal file
View File

File diff suppressed because it is too large Load Diff

1710
database/schema_dws.sql Normal file
View File

File diff suppressed because it is too large Load Diff

105
database/schema_etl_admin.sql Normal file
View File

@@ -0,0 +1,105 @@
-- 文件说明：etl_admin 调度元数据 DDL（独立文件，便于初始化任务单独执行）。
-- 包含任务注册表、游标表、运行记录表；字段注释使用中文。
CREATE SCHEMA IF NOT EXISTS etl_admin;
CREATE TABLE IF NOT EXISTS etl_admin.etl_task (
task_id BIGSERIAL PRIMARY KEY,
task_code TEXT NOT NULL,
store_id BIGINT NOT NULL,
enabled BOOLEAN DEFAULT TRUE,
cursor_field TEXT,
window_minutes_default INT DEFAULT 30,
overlap_seconds INT DEFAULT 600,
page_size INT DEFAULT 200,
retry_max INT DEFAULT 3,
params JSONB DEFAULT '{}'::jsonb,
created_at TIMESTAMPTZ DEFAULT now(),
updated_at TIMESTAMPTZ DEFAULT now(),
UNIQUE (task_code, store_id)
);
COMMENT ON TABLE etl_admin.etl_task IS '任务注册表：调度依据的任务清单（与 task_registry 中的任务码对应）。';
COMMENT ON COLUMN etl_admin.etl_task.task_code IS '任务编码，需与代码中的任务码一致。';
COMMENT ON COLUMN etl_admin.etl_task.store_id IS '门店/租户粒度，区分多门店执行。';
COMMENT ON COLUMN etl_admin.etl_task.enabled IS '是否启用此任务。';
COMMENT ON COLUMN etl_admin.etl_task.cursor_field IS '增量游标字段名（可选）。';
COMMENT ON COLUMN etl_admin.etl_task.window_minutes_default IS '默认时间窗口（分钟）。';
COMMENT ON COLUMN etl_admin.etl_task.overlap_seconds IS '窗口重叠秒数，用于防止遗漏。';
COMMENT ON COLUMN etl_admin.etl_task.page_size IS '默认分页大小。';
COMMENT ON COLUMN etl_admin.etl_task.retry_max IS 'API重试次数上限。';
COMMENT ON COLUMN etl_admin.etl_task.params IS '任务级自定义参数 JSON。';
COMMENT ON COLUMN etl_admin.etl_task.created_at IS '创建时间。';
COMMENT ON COLUMN etl_admin.etl_task.updated_at IS '更新时间。';
CREATE TABLE IF NOT EXISTS etl_admin.etl_cursor (
cursor_id BIGSERIAL PRIMARY KEY,
task_id BIGINT NOT NULL REFERENCES etl_admin.etl_task(task_id) ON DELETE CASCADE,
store_id BIGINT NOT NULL,
last_start TIMESTAMPTZ,
last_end TIMESTAMPTZ,
last_id BIGINT,
last_run_id BIGINT,
extra JSONB DEFAULT '{}'::jsonb,
created_at TIMESTAMPTZ DEFAULT now(),
updated_at TIMESTAMPTZ DEFAULT now(),
UNIQUE (task_id, store_id)
);
COMMENT ON TABLE etl_admin.etl_cursor IS '任务游标表：记录每个任务/门店的增量窗口及最后 run。';
COMMENT ON COLUMN etl_admin.etl_cursor.task_id IS '关联 etl_task.task_id。';
COMMENT ON COLUMN etl_admin.etl_cursor.store_id IS '门店/租户粒度。';
COMMENT ON COLUMN etl_admin.etl_cursor.last_start IS '上次窗口开始时间（含重叠偏移）。';
COMMENT ON COLUMN etl_admin.etl_cursor.last_end IS '上次窗口结束时间。';
COMMENT ON COLUMN etl_admin.etl_cursor.last_id IS '上次处理的最大主键/游标值（可选）。';
COMMENT ON COLUMN etl_admin.etl_cursor.last_run_id IS '上次运行ID，对应 etl_run.run_id。';
COMMENT ON COLUMN etl_admin.etl_cursor.extra IS '附加游标信息 JSON。';
COMMENT ON COLUMN etl_admin.etl_cursor.created_at IS '创建时间。';
COMMENT ON COLUMN etl_admin.etl_cursor.updated_at IS '更新时间。';
CREATE TABLE IF NOT EXISTS etl_admin.etl_run (
run_id BIGSERIAL PRIMARY KEY,
run_uuid TEXT NOT NULL,
task_id BIGINT NOT NULL REFERENCES etl_admin.etl_task(task_id) ON DELETE CASCADE,
store_id BIGINT NOT NULL,
status TEXT NOT NULL,
started_at TIMESTAMPTZ DEFAULT now(),
ended_at TIMESTAMPTZ,
window_start TIMESTAMPTZ,
window_end TIMESTAMPTZ,
window_minutes INT,
overlap_seconds INT,
fetched_count INT DEFAULT 0,
loaded_count INT DEFAULT 0,
updated_count INT DEFAULT 0,
skipped_count INT DEFAULT 0,
error_count INT DEFAULT 0,
unknown_fields INT DEFAULT 0,
export_dir TEXT,
log_path TEXT,
request_params JSONB DEFAULT '{}'::jsonb,
manifest JSONB DEFAULT '{}'::jsonb,
error_message TEXT,
extra JSONB DEFAULT '{}'::jsonb
);
COMMENT ON TABLE etl_admin.etl_run IS '运行记录表：记录每次任务执行的窗口、状态、计数与日志路径。';
COMMENT ON COLUMN etl_admin.etl_run.run_uuid IS '本次调度的唯一标识。';
COMMENT ON COLUMN etl_admin.etl_run.task_id IS '关联 etl_task.task_id。';
COMMENT ON COLUMN etl_admin.etl_run.store_id IS '门店/租户粒度。';
COMMENT ON COLUMN etl_admin.etl_run.status IS '运行状态（SUCC/FAIL/PARTIAL 等）。';
COMMENT ON COLUMN etl_admin.etl_run.started_at IS '开始时间。';
COMMENT ON COLUMN etl_admin.etl_run.ended_at IS '结束时间。';
COMMENT ON COLUMN etl_admin.etl_run.window_start IS '本次窗口开始时间。';
COMMENT ON COLUMN etl_admin.etl_run.window_end IS '本次窗口结束时间。';
COMMENT ON COLUMN etl_admin.etl_run.window_minutes IS '窗口跨度（分钟）。';
COMMENT ON COLUMN etl_admin.etl_run.overlap_seconds IS '窗口重叠秒数。';
COMMENT ON COLUMN etl_admin.etl_run.fetched_count IS '抓取/读取的记录数。';
COMMENT ON COLUMN etl_admin.etl_run.loaded_count IS '插入的记录数。';
COMMENT ON COLUMN etl_admin.etl_run.updated_count IS '更新的记录数。';
COMMENT ON COLUMN etl_admin.etl_run.skipped_count IS '跳过的记录数。';
COMMENT ON COLUMN etl_admin.etl_run.error_count IS '错误记录数。';
COMMENT ON COLUMN etl_admin.etl_run.unknown_fields IS '未知字段计数（清洗阶段）。';
COMMENT ON COLUMN etl_admin.etl_run.export_dir IS '抓取/导出目录。';
COMMENT ON COLUMN etl_admin.etl_run.log_path IS '日志路径。';
COMMENT ON COLUMN etl_admin.etl_run.request_params IS '请求参数 JSON。';
COMMENT ON COLUMN etl_admin.etl_run.manifest IS '运行产出清单/统计 JSON。';
COMMENT ON COLUMN etl_admin.etl_run.error_message IS '错误信息（若失败）。';
COMMENT ON COLUMN etl_admin.etl_run.extra IS '附加字段，保留扩展。';

173
database/schema_verify_perf_indexes.sql Normal file
View File

@@ -0,0 +1,173 @@
SET client_encoding TO "UTF8";
-- ============================================================================
-- 校验性能索引（ODS / DWD）
-- ----------------------------------------------------------------------------
-- 用途:
-- 1) 加速校验查询（主键查找、窗口扫描、当前版本扫描）。
-- 2) 保持数据语义不变（仅添加索引 + ANALYZE，不改写业务数据）。
--
-- 注意事项:
-- 1) 本脚本具有幂等性（`CREATE INDEX IF NOT EXISTS`）。
-- 2) 如有严格的在线 DDL 要求，请手动使用 `CREATE INDEX CONCURRENTLY`
-- 在维护安全模式下执行（不可在事务块内运行）。
-- ============================================================================
DO $$
DECLARE
rec RECORD;
pk_cols TEXT[];
pk_cols_sql TEXT;
idx_name TEXT;
BEGIN
FOR rec IN
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'billiards_ods'
AND table_type = 'BASE TABLE'
LOOP
IF EXISTS (
SELECT 1
FROM information_schema.columns
WHERE table_schema = 'billiards_ods'
AND table_name = rec.table_name
AND column_name = 'fetched_at'
) THEN
idx_name := left(format('idx_%s_vfy_fetched_at', rec.table_name), 50)
|| '_' || substr(md5(rec.table_name || '_vfy_fetched_at'), 1, 8);
EXECUTE format(
'CREATE INDEX IF NOT EXISTS %I ON billiards_ods.%I (fetched_at)',
idx_name, rec.table_name
);
SELECT array_agg(kcu.column_name ORDER BY kcu.ordinal_position)
INTO pk_cols
FROM information_schema.table_constraints tc
JOIN information_schema.key_column_usage kcu
ON tc.table_schema = kcu.table_schema
AND tc.table_name = kcu.table_name
AND tc.constraint_name = kcu.constraint_name
WHERE tc.table_schema = 'billiards_ods'
AND tc.table_name = rec.table_name
AND tc.constraint_type = 'PRIMARY KEY';
IF pk_cols IS NOT NULL AND coalesce(array_length(pk_cols, 1), 0) <= 3 THEN
SELECT string_agg(format('%I', c), ', ')
INTO pk_cols_sql
FROM unnest(pk_cols) AS c;
idx_name := left(format('idx_%s_vfy_fetched_pk', rec.table_name), 50)
|| '_' || substr(md5(rec.table_name || '_vfy_fetched_pk'), 1, 8);
EXECUTE format(
'CREATE INDEX IF NOT EXISTS %I ON billiards_ods.%I (fetched_at, %s)',
idx_name, rec.table_name, pk_cols_sql
);
END IF;
END IF;
END LOOP;
END
$$;
DO $$
DECLARE
rec RECORD;
tcol TEXT;
pk_cols TEXT[];
pk_cols_sql TEXT;
idx_name TEXT;
time_candidates TEXT[] := ARRAY[
'pay_time',
'create_time',
'start_use_time',
'scd2_start_time',
'calc_time',
'order_date',
'fetched_at'
];
BEGIN
FOR rec IN
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'billiards_dwd'
AND table_type = 'BASE TABLE'
LOOP
SELECT array_agg(kcu.column_name ORDER BY kcu.ordinal_position)
INTO pk_cols
FROM information_schema.table_constraints tc
JOIN information_schema.key_column_usage kcu
ON tc.table_schema = kcu.table_schema
AND tc.table_name = kcu.table_name
AND tc.constraint_name = kcu.constraint_name
WHERE tc.table_schema = 'billiards_dwd'
AND tc.table_name = rec.table_name
AND tc.constraint_type = 'PRIMARY KEY';
IF EXISTS (
SELECT 1
FROM information_schema.columns
WHERE table_schema = 'billiards_dwd'
AND table_name = rec.table_name
AND column_name = 'scd2_is_current'
) AND pk_cols IS NOT NULL
AND coalesce(array_length(pk_cols, 1), 0) BETWEEN 1 AND 4 THEN
SELECT string_agg(format('%I', c), ', ')
INTO pk_cols_sql
FROM unnest(pk_cols) AS c;
idx_name := left(format('idx_%s_vfy_pk_current', rec.table_name), 50)
|| '_' || substr(md5(rec.table_name || '_vfy_pk_current'), 1, 8);
EXECUTE format(
'CREATE INDEX IF NOT EXISTS %I ON billiards_dwd.%I (%s, scd2_is_current)',
idx_name, rec.table_name, pk_cols_sql
);
END IF;
FOREACH tcol IN ARRAY time_candidates
LOOP
IF EXISTS (
SELECT 1
FROM information_schema.columns
WHERE table_schema = 'billiards_dwd'
AND table_name = rec.table_name
AND column_name = tcol
) THEN
idx_name := left(format('idx_%s_vfy_%s', rec.table_name, tcol), 50)
|| '_' || substr(md5(rec.table_name || '_vfy_' || tcol), 1, 8);
EXECUTE format(
'CREATE INDEX IF NOT EXISTS %I ON billiards_dwd.%I (%I)',
idx_name, rec.table_name, tcol
);
IF pk_cols IS NOT NULL AND coalesce(array_length(pk_cols, 1), 0) <= 3 THEN
SELECT string_agg(format('%I', c), ', ')
INTO pk_cols_sql
FROM unnest(pk_cols) AS c;
idx_name := left(format('idx_%s_vfy_%s_pk', rec.table_name, tcol), 50)
|| '_' || substr(md5(rec.table_name || '_vfy_' || tcol || '_pk'), 1, 8);
EXECUTE format(
'CREATE INDEX IF NOT EXISTS %I ON billiards_dwd.%I (%I, %s)',
idx_name, rec.table_name, tcol, pk_cols_sql
);
END IF;
END IF;
END LOOP;
END LOOP;
END
$$;
DO $$
DECLARE
rec RECORD;
BEGIN
FOR rec IN
SELECT table_schema, table_name
FROM information_schema.tables
WHERE table_schema IN ('billiards_ods', 'billiards_dwd')
AND table_type = 'BASE TABLE'
LOOP
EXECUTE format('ANALYZE %I.%I', rec.table_schema, rec.table_name);
END LOOP;
END
$$;

389
database/seed_dws_config.sql Normal file
View File

@@ -0,0 +1,389 @@
-- =============================================================================
-- DWS 配置表初始数据
-- 版本: v3.0
-- 创建日期: 2026-02-01
-- 描述: 初始化配置表数据，包含绩效档位、等级定价、奖金规则、区域分类、技能映射
-- =============================================================================
-- NOTE: 当前数据库 cfg_* 配置表为空（以数据库现状为准）
-- 下方默认配置仅作参考，已整体注释
/*
-- =============================================================================
-- 1. cfg_performance_tier - 绩效档位配置（含历史口径）
-- 数据来源：DWS 数据库处理需求.md
-- 旧方案（历史口径，至2026-02-28）:
-- 0档 淘汰压力 H <100 28 50% 3
-- 1档 及格档（重点激励） 100≤ H <130 18 40% 4
-- 2档 良好档（重点激励） 130≤ H <160 15 38% 4
-- 3档 优秀档 160≤ H <190 13 35% 5
-- 4档 卓越加速档（高端人才倾斜） 190≤ H <220 10 33% 6
-- 5档 冠军加速档（高端人才倾斜） H ≥220 8 30% 休假自由
-- 新方案（2026-03-01起）:
-- 0档 淘汰压力 H <120 28 50% 3
-- 1档 及格档 120≤ H <150 18 40% 4
-- 2档 良好档 150≤ H <180 13 35% 5
-- 3档 优秀档 180≤ H <210 10 30% 6
-- 4档 销冠竞争 H ≥210 8 25% 休假自由
-- =============================================================================
TRUNCATE TABLE billiards_dws.cfg_performance_tier RESTART IDENTITY CASCADE;
INSERT INTO billiards_dws.cfg_performance_tier (
tier_code, tier_name, tier_level,
min_hours, max_hours,
base_deduction, bonus_deduction_ratio, vacation_days, vacation_unlimited,
is_new_hire_tier, effective_from, effective_to, description
) VALUES
-- 旧方案（至2026-02-28）
-- 0档 淘汰压力: H<100, 专业课抽成28元/小时, 打赏课抽成50%, 休假3天
('T0', '0档-淘汰压力', 0,
0, 100,
28.00, 0.50, 3, FALSE,
FALSE, '2000-01-01', '2026-02-28',
'旧方案：H<100，专业课抽成28元/小时，打赏课抽成50%，休假3天'),
-- 1档 及格档: 100≤H<130, 专业课抽成18元/小时, 打赏课抽成40%, 休假4天
('T1', '1档-及格档', 1,
100, 130,
18.00, 0.40, 4, FALSE,
FALSE, '2000-01-01', '2026-02-28',
'旧方案：100≤H<130，专业课抽成18元/小时，打赏课抽成40%，休假4天'),
-- 2档 良好档: 130≤H<160, 专业课抽成15元/小时, 打赏课抽成38%, 休假4天
('T2', '2档-良好档', 2,
130, 160,
15.00, 0.38, 4, FALSE,
FALSE, '2000-01-01', '2026-02-28',
'旧方案：130≤H<160，专业课抽成15元/小时，打赏课抽成38%，休假4天'),
-- 3档 优秀档: 160≤H<190, 专业课抽成13元/小时, 打赏课抽成35%, 休假5天
('T3', '3档-优秀档', 3,
160, 190,
13.00, 0.35, 5, FALSE,
FALSE, '2000-01-01', '2026-02-28',
'旧方案：160≤H<190，专业课抽成13元/小时，打赏课抽成35%，休假5天'),
-- 4档 卓越加速档: 190≤H<220, 专业课抽成10元/小时, 打赏课抽成33%, 休假6天
('T4', '4档-卓越加速档', 4,
190, 220,
10.00, 0.33, 6, FALSE,
FALSE, '2000-01-01', '2026-02-28',
'旧方案：190≤H<220，专业课抽成10元/小时，打赏课抽成33%，休假6天'),
-- 5档 冠军加速档: H≥220, 专业课抽成8元/小时, 打赏课抽成30%, 休假自由
('T5', '5档-冠军加速档', 5,
220, NULL,
8.00, 0.30, 0, TRUE,
FALSE, '2000-01-01', '2026-02-28',
'旧方案：H≥220，专业课抽成8元/小时，打赏课抽成30%，休假自由'),
-- 新方案（2026-03-01起）
-- 0档 淘汰压力: H<120, 专业课抽成28元/小时, 打赏课抽成50%, 休假3天
('T0', '0档-淘汰压力', 0,
0, 120,
28.00, 0.50, 3, FALSE,
FALSE, '2026-03-01', '9999-12-31',
'新方案：H<120，专业课抽成28元/小时，打赏课抽成50%，休假3天'),
-- 1档 及格档: 120≤H<150, 专业课抽成18元/小时, 打赏课抽成40%, 休假4天
('T1', '1档-及格档', 1,
120, 150,
18.00, 0.40, 4, FALSE,
FALSE, '2026-03-01', '9999-12-31',
'新方案：120≤H<150，专业课抽成18元/小时，打赏课抽成40%，休假4天'),
-- 2档 良好档: 150≤H<180, 专业课抽成13元/小时, 打赏课抽成35%, 休假5天
('T2', '2档-良好档', 2,
150, 180,
13.00, 0.35, 5, FALSE,
FALSE, '2026-03-01', '9999-12-31',
'新方案：150≤H<180，专业课抽成13元/小时，打赏课抽成35%，休假5天'),
-- 3档 优秀档: 180≤H<210, 专业课抽成10元/小时, 打赏课抽成30%, 休假6天
('T3', '3档-优秀档', 3,
180, 210,
10.00, 0.30, 6, FALSE,
FALSE, '2026-03-01', '9999-12-31',
'新方案：180≤H<210，专业课抽成10元/小时，打赏课抽成30%，休假6天'),
-- 4档 销冠竞争: H≥210, 专业课抽成8元/小时, 打赏课抽成25%, 休假自由
('T4', '4档-销冠竞争', 4,
210, NULL,
8.00, 0.25, 0, TRUE,
FALSE, '2026-03-01', '9999-12-31',
'新方案：H≥210，专业课抽成8元/小时，打赏课抽成25%，休假自由');
-- =============================================================================
-- 2. cfg_assistant_level_price - 助教等级定价
-- 说明:
-- - level_code 来自 dim_assistant.assistant_level
-- - 8=助教管理, 10=初级, 20=中级, 30=高级, 40=星级
-- - 价格为客户支付价格（对外价格），助教收入=客户支付-档位抽成
-- - 包厢课基础课统一138元/小时（不随等级变化）
-- - 数据来源：DWS 数据库处理需求.md
-- =============================================================================
TRUNCATE TABLE billiards_dws.cfg_assistant_level_price RESTART IDENTITY CASCADE;
INSERT INTO billiards_dws.cfg_assistant_level_price (
level_code, level_name,
base_course_price, bonus_course_price,
effective_from, effective_to, description
) VALUES
-- 初级助教：基础课对客户收费98元/小时
(10, '初级',
98.00, 190.00,
'2000-01-01', '9999-12-31',
'初级助教：基础课98元/时，附加课190元/时（客户支付价格）'),
-- 中级助教：基础课对客户收费108元/小时
(20, '中级',
108.00, 190.00,
'2000-01-01', '9999-12-31',
'中级助教：基础课108元/时，附加课190元/时（客户支付价格）'),
-- 高级助教：基础课对客户收费118元/小时
(30, '高级',
118.00, 190.00,
'2000-01-01', '9999-12-31',
'高级助教：基础课118元/时，附加课190元/时（客户支付价格）'),
-- 星级助教：基础课对客户收费138元/小时
(40, '星级',
138.00, 190.00,
'2000-01-01', '9999-12-31',
'星级助教：基础课138元/时，附加课190元/时（客户支付价格）'),
-- 助教管理：level_code=8，通常不参与客户服务计费，此处设置默认值
(8, '助教管理',
98.00, 190.00,
'2000-01-01', '9999-12-31',
'助教管理：不参与客户服务计费，默认按初级价格');
-- =============================================================================
-- 3. cfg_bonus_rules - 奖金规则配置
-- 说明:
-- - SPRINT: 冲刺奖金（历史口径，至2026-02-28）
-- - TOP_RANK: Top3排名奖金（2026-03-01起）
-- =============================================================================
TRUNCATE TABLE billiards_dws.cfg_bonus_rules RESTART IDENTITY CASCADE;
INSERT INTO billiards_dws.cfg_bonus_rules (
rule_type, rule_code, rule_name,
threshold_hours, rank_position, bonus_amount,
is_cumulative, priority,
effective_from, effective_to, description
) VALUES
-- 冲刺奖金: H>=190 得300元（历史口径）
('SPRINT', 'SPRINT_190', '冲刺奖金190',
190.00, NULL, 300.00,
FALSE, 1,
'2000-01-01', '2026-02-28',
'历史口径：业绩≥190小时，获得300元冲刺奖金（不累计）'),
-- 冲刺奖金: H>=220 得800元（历史口径，优先级更高，覆盖190档）
('SPRINT', 'SPRINT_220', '冲刺奖金220',
220.00, NULL, 800.00,
FALSE, 2,
'2000-01-01', '2026-02-28',
'历史口径：业绩≥220小时，获得800元冲刺奖金（覆盖190档）'),
-- Top1排名奖金: 1000元（2026-03-01起）
('TOP_RANK', 'TOP_1', 'Top1排名奖金',
NULL, 1, 1000.00,
FALSE, 0,
'2026-03-01', '9999-12-31',
'月度排名第一，获得1000元（并列都算）'),
-- Top2排名奖金: 600元（2026-03-01起）
('TOP_RANK', 'TOP_2', 'Top2排名奖金',
NULL, 2, 600.00,
FALSE, 0,
'2026-03-01', '9999-12-31',
'月度排名第二，获得600元（并列都算）'),
-- Top3排名奖金: 400元（2026-03-01起）
('TOP_RANK', 'TOP_3', 'Top3排名奖金',
NULL, 3, 400.00,
FALSE, 0,
'2026-03-01', '9999-12-31',
'月度排名第三，获得400元（并列都算）');
-- =============================================================================
-- 4. cfg_area_category - 台区分类映射
-- 说明:
-- - 将 dim_table.site_table_area_name 映射到财务报表区域分类
-- - 映射规则: 精确匹配 > 模糊匹配 > 默认兜底
-- - 数据来源: BD_manual_dim_table.md 中的 site_table_area_name 实际分布
-- 分类设计:
-- - BILLIARD: 台球散台（A区/B区/C区/TV台）
-- - BILLIARD_VIP: 台球VIP包厢
-- - SNOOKER: 斯诺克区
-- - MAHJONG: 麻将区
-- - KTV: K歌/KTV
-- - SPECIAL: 特殊（补时长等）
-- - OTHER: 其他
-- =============================================================================
TRUNCATE TABLE billiards_dws.cfg_area_category RESTART IDENTITY CASCADE;
INSERT INTO billiards_dws.cfg_area_category (
source_area_name, category_code, category_name,
match_type, match_priority, is_active, description
) VALUES
-- ============ 台球散台区（精确匹配）============
('A区', 'BILLIARD', '台球散台',
'EXACT', 10, TRUE, '台球散台：A区（18台）- 中八/追分'),
('B区', 'BILLIARD', '台球散台',
'EXACT', 10, TRUE, '台球散台：B区（15台）- 中八/追分'),
('C区', 'BILLIARD', '台球散台',
'EXACT', 10, TRUE, '台球散台：C区（6台）- 中八/追分'),
('TV台', 'BILLIARD', '台球散台',
'EXACT', 10, TRUE, '台球散台：TV台（1台）- 中八/追分'),
-- ============ 台球VIP包厢（精确匹配）============
('VIP包厢', 'BILLIARD_VIP', '台球VIP',
'EXACT', 10, TRUE, '台球VIP：VIP包厢（4台）- V1-V4中八, V5斯诺克'),
-- ============ 斯诺克区（精确匹配）============
('斯诺克区', 'SNOOKER', '斯诺克',
'EXACT', 10, TRUE, '斯诺克：斯诺克区（4台）'),
-- ============ 麻将区（精确匹配）============
('麻将房', 'MAHJONG', '麻将棋牌',
'EXACT', 10, TRUE, '麻将棋牌：麻将房（5台）'),
('M7', 'MAHJONG', '麻将棋牌',
'EXACT', 10, TRUE, '麻将棋牌：M7（2台）'),
('M8', 'MAHJONG', '麻将棋牌',
'EXACT', 10, TRUE, '麻将棋牌：M8（1台）'),
('666', 'MAHJONG', '麻将棋牌',
'EXACT', 10, TRUE, '麻将棋牌：666（2台）'),
('发财', 'MAHJONG', '麻将棋牌',
'EXACT', 10, TRUE, '麻将棋牌：发财（1台）'),
-- ============ KTV/K包（精确匹配）============
('K包', 'KTV', 'K歌娱乐',
'EXACT', 10, TRUE, 'K歌娱乐：K包（4台）'),
('k包活动区', 'KTV', 'K歌娱乐',
'EXACT', 10, TRUE, 'K歌娱乐：k包活动区（2台）'),
('幸会158', 'KTV', 'K歌娱乐',
'EXACT', 10, TRUE, 'K歌娱乐：幸会158（2台）'),
-- ============ 特殊区域（精确匹配）============
('补时长', 'SPECIAL', '补时长',
'EXACT', 10, TRUE, '特殊：补时长（7台）- 用于时长补录'),
-- ============ 模糊匹配规则（优先级较低）============
('%VIP%', 'BILLIARD_VIP', '台球VIP',
'LIKE', 50, TRUE, '模糊匹配：包含"VIP"的区域'),
('%斯诺克%', 'SNOOKER', '斯诺克',
'LIKE', 50, TRUE, '模糊匹配：包含"斯诺克"的区域'),
('%麻将%', 'MAHJONG', '麻将棋牌',
'LIKE', 50, TRUE, '模糊匹配：包含"麻将"的区域'),
('%K包%', 'KTV', 'K歌娱乐',
'LIKE', 50, TRUE, '模糊匹配：包含"K包"的区域'),
('%KTV%', 'KTV', 'K歌娱乐',
'LIKE', 50, TRUE, '模糊匹配：包含"KTV"的区域'),
-- ============ 默认兜底（优先级最低）============
('DEFAULT', 'OTHER', '其他',
'DEFAULT', 999, TRUE, '兜底规则：无法匹配的区域归入其他');
-- =============================================================================
-- 5. cfg_skill_type - 技能→课程类型映射
-- 说明:
-- - 将 skill_id 映射到课程类型
-- - 基础课/陪打: skill_id = 2791903611396869
-- - 附加课/超休: skill_id = 2807440316432197
-- - 避免依赖 skill_name 文本匹配
-- =============================================================================
TRUNCATE TABLE billiards_dws.cfg_skill_type RESTART IDENTITY CASCADE;
INSERT INTO billiards_dws.cfg_skill_type (
skill_id, skill_name,
course_type_code, course_type_name,
is_active, description
) VALUES
-- 基础课/陪打
(2791903611396869, '台球基础陪打',
'BASE', '基础课',
TRUE, '基础课：陪打服务，按助教等级计价'),
-- 附加课/超休
(2807440316432197, '台球超休服务',
'BONUS', '附加课',
TRUE, '附加课：超休/激励课，固定190元/小时'),
-- 包厢课（如有）
(2807440316432198, '包厢服务',
'BASE', '基础课',
TRUE, '包厢服务：归入基础课统计，统一按138元/小时计价');
-- =============================================================================
-- 6. 优惠类型配置（用于财务优惠明细分析）
-- 说明: 定义各类优惠的代码和名称，便于后续分析
-- =============================================================================
-- 此配置作为代码常量使用，不单独建表
-- GROUPBUY - 团购优惠
-- VIP - 会员折扣
-- GIFT_CARD - 赠送卡抵扣
-- MANUAL - 手动调整
-- ROUNDING - 抹零
-- BIG_CUSTOMER - 大客户优惠（待抽样分析确认）
-- OTHER - 其他优惠
-- =============================================================================
-- 7. 支出类型配置（用于Excel导入）
-- 说明: 定义各类支出的代码和名称
-- =============================================================================
-- 此配置作为代码常量使用，不单独建表
-- RENT - 房租
-- UTILITY - 水电费
-- PROPERTY - 物业费
-- SALARY - 工资
-- REIMBURSE - 报销
-- PLATFORM_FEE - 平台服务费
-- OTHER - 其他支出
-- =============================================================================
-- 8. 平台类型配置（用于Excel导入）
-- 说明: 定义各平台的代码和名称
-- =============================================================================
-- 此配置作为代码常量使用，不单独建表
-- MEITUAN - 美团
-- DOUYIN - 抖音
-- DIANPING - 大众点评
-- OTHER - 其他平台
-- =============================================================================
-- 验证数据插入
-- =============================================================================
DO $$
DECLARE
v_tier_count INTEGER;
v_price_count INTEGER;
v_bonus_count INTEGER;
v_area_count INTEGER;
v_skill_count INTEGER;
BEGIN
SELECT COUNT(*) INTO v_tier_count FROM billiards_dws.cfg_performance_tier;
SELECT COUNT(*) INTO v_price_count FROM billiards_dws.cfg_assistant_level_price;
SELECT COUNT(*) INTO v_bonus_count FROM billiards_dws.cfg_bonus_rules;
SELECT COUNT(*) INTO v_area_count FROM billiards_dws.cfg_area_category;
SELECT COUNT(*) INTO v_skill_count FROM billiards_dws.cfg_skill_type;
RAISE NOTICE '配置数据初始化完成:';
RAISE NOTICE ' - cfg_performance_tier: % 条', v_tier_count;
RAISE NOTICE ' - cfg_assistant_level_price: % 条', v_price_count;
RAISE NOTICE ' - cfg_bonus_rules: % 条', v_bonus_count;
RAISE NOTICE ' - cfg_area_category: % 条', v_area_count;
RAISE NOTICE ' - cfg_skill_type: % 条', v_skill_count;
END;
$$;
*/

226
database/seed_index_parameters.sql Normal file
View File

@@ -0,0 +1,226 @@
-- =============================================================================
-- 指数算法参数初始化脚本（与数据库现状对齐）
-- 版本: v2.0
-- 创建日期: 2026-02-07
-- 描述: 对齐 RS / OS / MS / ML / NCI / WBI 指数参数快照（兼容保留 RECALL / INTIMACY）
-- =============================================================================
-- 清空旧数据（如需重置）
-- DELETE FROM billiards_dws.cfg_index_parameters
-- WHERE index_type IN ('RS', 'OS', 'MS', 'ML', 'NCI', 'WBI', 'RECALL', 'INTIMACY');
INSERT INTO billiards_dws.cfg_index_parameters
(index_type, param_name, param_value, description, effective_from)
VALUES
('INTIMACY', 'amount_base', 500.000000, 'amount compression base', DATE '2026-02-06'),
('INTIMACY', 'burst_gamma', 0.600000, 'burst gamma', DATE '2026-02-06'),
('INTIMACY', 'ewma_alpha', 0.200000, 'EWMA alpha', DATE '2026-02-06'),
('INTIMACY', 'halflife_last', 10.000000, 'last-contact half-life (days)', DATE '2026-02-06'),
('INTIMACY', 'halflife_long', 30.000000, 'long-term burst half-life (days)', DATE '2026-02-06'),
('INTIMACY', 'halflife_recharge', 21.000000, 'recharge half-life (days)', DATE '2026-02-06'),
('INTIMACY', 'halflife_session', 14.000000, 'session half-life (days)', DATE '2026-02-06'),
('INTIMACY', 'halflife_short', 7.000000, 'short-term burst half-life (days)', DATE '2026-02-06'),
('INTIMACY', 'incentive_weight', 1.500000, 'incentive multiplier', DATE '2026-02-06'),
('INTIMACY', 'lookback_days', 60.000000, 'lookback window (days)', DATE '2026-02-06'),
('INTIMACY', 'percentile_lower', 5.000000, 'lower percentile', DATE '2026-02-06'),
('INTIMACY', 'percentile_upper', 95.000000, 'upper percentile', DATE '2026-02-06'),
('INTIMACY', 'recharge_attribute_hours', 1.000000, 'recharge attribution window (hours)', DATE '2026-02-06'),
('INTIMACY', 'session_merge_hours', 4.000000, 'session merge gap (hours)', DATE '2026-02-06'),
('INTIMACY', 'weight_duration', 0.500000, 'duration weight', DATE '2026-02-06'),
('INTIMACY', 'weight_frequency', 2.000000, 'frequency weight', DATE '2026-02-06'),
('INTIMACY', 'weight_recency', 1.500000, 'recency weight', DATE '2026-02-06'),
('INTIMACY', 'weight_recharge', 2.000000, 'recharge weight', DATE '2026-02-06'),
('NCI', 'active_new_penalty', 0.200000, 'active-new suppression multiplier', DATE '2026-02-06'),
('NCI', 'active_new_recency_days', 7.000000, 'active-new recency window (days)', DATE '2026-02-06'),
('NCI', 'active_new_visit_threshold_14d', 2.000000, 'active-new threshold in 14d visits', DATE '2026-02-06'),
('NCI', 'amount_base_M0', 300.000000, 'spend log base M0', DATE '2026-02-06'),
('NCI', 'balance_base_B0', 500.000000, 'balance log base B0', DATE '2026-02-06'),
('NCI', 'compression_mode', 0.000000, 'compression mode', DATE '2026-02-06'),
('NCI', 'enable_stop_high_balance_exception', 0.000000, 'enable high-balance STOP exception', DATE '2026-02-06'),
('NCI', 'ewma_alpha', 0.200000, 'EWMA alpha', DATE '2026-02-06'),
('NCI', 'h_recharge', 7.000000, 'recharge decay half-life (days)', DATE '2026-02-06'),
('NCI', 'high_balance_threshold', 1000.000000, 'high-balance threshold', DATE '2026-02-06'),
('NCI', 'lookback_days_recency', 60.000000, 'recency lookback window (days)', DATE '2026-02-06'),
('NCI', 'new_days_threshold', 30.000000, 'new member days threshold', DATE '2026-02-06'),
('NCI', 'new_recharge_max_visits', 10.000000, 'max visits for new-recharge grouping', DATE '2026-02-06'),
('NCI', 'new_visit_threshold', 2.000000, 'new member visit threshold', DATE '2026-02-06'),
('NCI', 'no_touch_days_new', 3.000000, 'no-touch threshold (days)', DATE '2026-02-06'),
('NCI', 'percentile_lower', 5.000000, 'lower percentile', DATE '2026-02-06'),
('NCI', 'percentile_upper', 95.000000, 'upper percentile', DATE '2026-02-06'),
('NCI', 'recharge_recent_days', 14.000000, 'recent recharge window (days)', DATE '2026-02-06'),
('NCI', 'salvage_end', 60.000000, 'salvage decay end day', DATE '2026-02-06'),
('NCI', 'salvage_start', 30.000000, 'salvage decay start day', DATE '2026-02-06'),
('NCI', 't2_target_days', 7.000000, 'second-visit target window (days)', DATE '2026-02-06'),
('NCI', 'use_smoothing', 1.000000, 'enable smoothing', DATE '2026-02-06'),
('NCI', 'value_w_bal', 0.800000, 'value weight for balance', DATE '2026-02-06'),
('NCI', 'value_w_spend', 1.000000, 'value weight for spend', DATE '2026-02-06'),
('NCI', 'visit_lookback_days', 180.000000, 'visit history lookback (days)', DATE '2026-02-06'),
('NCI', 'w_need', 1.600000, 'need weight', DATE '2026-02-06'),
('NCI', 'w_re', 0.800000, 'recharge pressure weight', DATE '2026-02-06'),
('NCI', 'w_value', 1.000000, 'value weight', DATE '2026-02-06'),
('NCI', 'w_welcome', 1.000000, 'welcome-stage weight', DATE '2026-02-06'),
('NCI', 'welcome_window_days', 3.000000, 'welcome outreach window for first touch (days)', DATE '2026-02-06'),
('RECALL', 'ewma_alpha', 0.200000, 'EWMA alpha', DATE '2026-02-06'),
('RECALL', 'halflife_new', 7.000000, 'new member half-life (days)', DATE '2026-02-06'),
('RECALL', 'halflife_recharge', 10.000000, 'recharge half-life (days)', DATE '2026-02-06'),
('RECALL', 'lookback_days', 60.000000, 'recall lookback window (days)', DATE '2026-02-06'),
('RECALL', 'percentile_lower', 5.000000, 'lower percentile', DATE '2026-02-06'),
('RECALL', 'percentile_upper', 95.000000, 'upper percentile', DATE '2026-02-06'),
('RECALL', 'sigma_min', 2.000000, 'minimum sigma for volatility', DATE '2026-02-06'),
('RECALL', 'weight_hot', 1.000000, 'hotness weight', DATE '2026-02-06'),
('RECALL', 'weight_new', 1.000000, 'new member weight', DATE '2026-02-06'),
('RECALL', 'weight_overdue', 3.000000, 'overdue weight', DATE '2026-02-06'),
('RECALL', 'weight_recharge', 1.000000, 'recharge weight', DATE '2026-02-06'),
('WBI', 'amount_base_M0', 300.000000, 'spend log base M0', DATE '2026-02-06'),
('WBI', 'balance_base_B0', 500.000000, 'balance log base B0', DATE '2026-02-06'),
('WBI', 'compression_mode', 0.000000, 'compression mode', DATE '2026-02-06'),
('WBI', 'enable_stop_high_balance_exception', 0.000000, 'enable high-balance STOP exception', DATE '2026-02-06'),
('WBI', 'ewma_alpha', 0.200000, 'EWMA alpha', DATE '2026-02-06'),
('WBI', 'h_recharge', 7.000000, 'recharge decay half-life (days)', DATE '2026-02-06'),
('WBI', 'high_balance_threshold', 1000.000000, 'high-balance threshold', DATE '2026-02-06'),
('WBI', 'lookback_days_recency', 60.000000, 'recency lookback window (days)', DATE '2026-02-06'),
('WBI', 'new_days_threshold', 30.000000, 'new member days threshold', DATE '2026-02-06'),
('WBI', 'new_recharge_max_visits', 10.000000, 'max visits for new-recharge grouping', DATE '2026-02-06'),
('WBI', 'new_visit_threshold', 2.000000, 'new member visit threshold', DATE '2026-02-06'),
('WBI', 'overdue_alpha', 2.000000, 'overdue fallback alpha', DATE '2026-02-06'),
('WBI', 'overdue_weight_blend_min_samples', 8.000000, 'minimum samples to fully trust weighted overdue CDF', DATE '2026-02-07'),
('WBI', 'overdue_weight_halflife_days', 30.000000, 'overdue weighted-CDF interval half-life (days)', DATE '2026-02-07'),
('WBI', 'percentile_lower', 5.000000, 'lower percentile', DATE '2026-02-06'),
('WBI', 'percentile_upper', 95.000000, 'upper percentile', DATE '2026-02-06'),
('WBI', 'recency_gate_days', 14.000000, 'recency suppression gate center (days)', DATE '2026-02-06'),
('WBI', 'recency_gate_slope_days', 3.000000, 'recency suppression slope (days)', DATE '2026-02-06'),
('WBI', 'recency_hard_floor_days', 14.000000, 'hard floor for winback recency (days)', DATE '2026-02-06'),
('WBI', 'recharge_recent_days', 14.000000, 'recent recharge window (days)', DATE '2026-02-06'),
('WBI', 'use_smoothing', 1.000000, 'enable smoothing', DATE '2026-02-06'),
('WBI', 'value_w_bal', 1.000000, 'value weight for balance', DATE '2026-02-06'),
('WBI', 'value_w_spend', 1.000000, 'value weight for spend', DATE '2026-02-06'),
('WBI', 'visit_lookback_days', 180.000000, 'visit history lookback (days)', DATE '2026-02-06'),
('WBI', 'w_drop', 1.000000, 'drop weight', DATE '2026-02-06'),
('WBI', 'w_over', 2.000000, 'overdue weight', DATE '2026-02-06'),
('WBI', 'w_re', 0.400000, 'recharge pressure weight', DATE '2026-02-06'),
('WBI', 'w_value', 1.200000, 'value weight', DATE '2026-02-06')
ON CONFLICT (index_type, param_name, effective_from) DO UPDATE SET
param_value = EXCLUDED.param_value,
description = EXCLUDED.description,
updated_at = NOW();
-- =============================================================================
-- 关系指数（RS/OS/MS/ML）参数
-- 生效时间：北京时间 2026-01-01（按数据库日期管理）
-- =============================================================================
-- 下线旧版 INTIMACY 参数（兼容保留历史记录）
UPDATE billiards_dws.cfg_index_parameters
SET effective_to = DATE '2025-12-31',
updated_at = NOW()
WHERE index_type = 'INTIMACY'
AND (effective_to IS NULL OR effective_to > DATE '2025-12-31');
INSERT INTO billiards_dws.cfg_index_parameters
(index_type, param_name, param_value, description, effective_from)
VALUES
-- RS（关系强度）
('RS', 'lookback_days', 60.000000, '服务行为回溯窗口（天）', DATE '2026-01-01'),
('RS', 'session_merge_hours', 4.000000, '会话合并阈值（小时）', DATE '2026-01-01'),
('RS', 'incentive_weight', 1.500000, '激励课权重', DATE '2026-01-01'),
('RS', 'halflife_session', 14.000000, '会话半衰期（天）', DATE '2026-01-01'),
('RS', 'halflife_last', 10.000000, '最近一次服务半衰期（天）', DATE '2026-01-01'),
('RS', 'weight_f', 1.000000, '频次项权重', DATE '2026-01-01'),
('RS', 'weight_d', 0.700000, '时长项权重', DATE '2026-01-01'),
('RS', 'gate_alpha', 0.600000, '最近服务门控指数', DATE '2026-01-01'),
('RS', 'percentile_lower', 5.000000, '展示分下分位', DATE '2026-01-01'),
('RS', 'percentile_upper', 95.000000, '展示分上分位', DATE '2026-01-01'),
('RS', 'compression_mode', 1.000000, '压缩模式：0=none,1=log1p,2=asinh', DATE '2026-01-01'),
('RS', 'use_smoothing', 1.000000, '是否启用分位平滑', DATE '2026-01-01'),
('RS', 'ewma_alpha', 0.200000, 'EWMA平滑系数', DATE '2026-01-01'),
-- OS（归属份额）
('OS', 'min_rs_raw_for_ownership', 0.050000, '参与归属计算的最小RS_raw', DATE '2026-01-01'),
('OS', 'min_total_rs_raw', 0.100000, '形成稳定归属的最小sum_rs', DATE '2026-01-01'),
('OS', 'ownership_main_threshold', 0.600000, '主责阈值', DATE '2026-01-01'),
('OS', 'ownership_comanage_threshold', 0.350000, '共管阈值', DATE '2026-01-01'),
('OS', 'ownership_gap_threshold', 0.150000, '主责与次席份额差阈值', DATE '2026-01-01'),
('OS', 'eps', 0.000001, '数值稳定项', DATE '2026-01-01'),
-- MS（升温动量）
('MS', 'lookback_days', 60.000000, '服务行为回溯窗口（天）', DATE '2026-01-01'),
('MS', 'session_merge_hours', 4.000000, '会话合并阈值（小时）', DATE '2026-01-01'),
('MS', 'incentive_weight', 1.500000, '激励课权重', DATE '2026-01-01'),
('MS', 'halflife_short', 7.000000, '短期半衰期（天）', DATE '2026-01-01'),
('MS', 'halflife_long', 30.000000, '长期半衰期（天）', DATE '2026-01-01'),
('MS', 'eps', 0.000001, '数值稳定项', DATE '2026-01-01'),
('MS', 'percentile_lower', 5.000000, '展示分下分位', DATE '2026-01-01'),
('MS', 'percentile_upper', 95.000000, '展示分上分位', DATE '2026-01-01'),
('MS', 'compression_mode', 1.000000, '压缩模式：0=none,1=log1p,2=asinh', DATE '2026-01-01'),
('MS', 'use_smoothing', 1.000000, '是否启用分位平滑', DATE '2026-01-01'),
('MS', 'ewma_alpha', 0.200000, 'EWMA平滑系数', DATE '2026-01-01'),
-- ML（付费关联）
('ML', 'lookback_days', 60.000000, '充值行为回溯窗口（天）', DATE '2026-01-01'),
('ML', 'source_mode', 0.000000, '数据源模式：0=manual_only,1=last_touch_fallback', DATE '2026-01-01'),
('ML', 'recharge_attribute_hours', 1.000000, 'last-touch备用归因窗口（小时）', DATE '2026-01-01'),
('ML', 'amount_base', 500.000000, '金额压缩基准', DATE '2026-01-01'),
('ML', 'halflife_recharge', 21.000000, '充值半衰期（天）', DATE '2026-01-01'),
('ML', 'percentile_lower', 5.000000, '展示分下分位', DATE '2026-01-01'),
('ML', 'percentile_upper', 95.000000, '展示分上分位', DATE '2026-01-01'),
('ML', 'compression_mode', 1.000000, '压缩模式：0=none,1=log1p,2=asinh', DATE '2026-01-01'),
('ML', 'use_smoothing', 1.000000, '是否启用分位平滑', DATE '2026-01-01'),
('ML', 'ewma_alpha', 0.200000, 'EWMA平滑系数', DATE '2026-01-01')
ON CONFLICT (index_type, param_name, effective_from) DO UPDATE SET
param_value = EXCLUDED.param_value,
description = EXCLUDED.description,
updated_at = NOW();
-- =============================================================================
-- 验证
-- =============================================================================
DO $$
DECLARE
rs_count INTEGER;
os_count INTEGER;
ms_count INTEGER;
ml_count INTEGER;
nci_count INTEGER;
wbi_count INTEGER;
BEGIN
SELECT COUNT(*) INTO rs_count
FROM billiards_dws.cfg_index_parameters
WHERE index_type = 'RS';
SELECT COUNT(*) INTO os_count
FROM billiards_dws.cfg_index_parameters
WHERE index_type = 'OS';
SELECT COUNT(*) INTO ms_count
FROM billiards_dws.cfg_index_parameters
WHERE index_type = 'MS';
SELECT COUNT(*) INTO ml_count
FROM billiards_dws.cfg_index_parameters
WHERE index_type = 'ML';
SELECT COUNT(*) INTO nci_count
FROM billiards_dws.cfg_index_parameters
WHERE index_type = 'NCI';
SELECT COUNT(*) INTO wbi_count
FROM billiards_dws.cfg_index_parameters
WHERE index_type = 'WBI';
RAISE NOTICE 'RS 参数数量: %', rs_count;
RAISE NOTICE 'OS 参数数量: %', os_count;
RAISE NOTICE 'MS 参数数量: %', ms_count;
RAISE NOTICE 'ML 参数数量: %', ml_count;
RAISE NOTICE '新客转化参数数量: %', nci_count;
RAISE NOTICE '唤回指数参数数量: %', wbi_count;
END $$;
SELECT
index_type,
param_name,
param_value,
description,
effective_from
FROM billiards_dws.cfg_index_parameters
ORDER BY index_type, param_name, effective_from;

41
database/seed_ods_tasks.sql Normal file
View File

@@ -0,0 +1,41 @@
-- 将新的 ODS 任务注册到 etl_admin.etl_task（按需替换 store_id）。
-- 使用方式（示例）：
-- psql "$PG_DSN" -f etl_billiards/database/seed_ods_tasks.sql
-- 或在 psql 中直接执行本文件内容。
WITH target_store AS (
SELECT 2790685415443269::bigint AS store_id -- TODO: 替换为实际 store_id
),
task_codes AS (
SELECT unnest(ARRAY[
-- Must match tasks/ods_tasks.py (ENABLED_ODS_CODES)
'ODS_ASSISTANT_ACCOUNT',
'ODS_ASSISTANT_LEDGER',
'ODS_ASSISTANT_ABOLISH',
'ODS_SETTLEMENT_RECORDS',
'ODS_TABLE_USE',
'ODS_PAYMENT',
'ODS_REFUND',
'ODS_PLATFORM_COUPON',
'ODS_MEMBER',
'ODS_MEMBER_CARD',
'ODS_MEMBER_BALANCE',
'ODS_RECHARGE_SETTLE',
'ODS_GROUP_PACKAGE',
'ODS_GROUP_BUY_REDEMPTION',
'ODS_INVENTORY_STOCK',
'ODS_INVENTORY_CHANGE',
'ODS_TABLES',
'ODS_GOODS_CATEGORY',
'ODS_STORE_GOODS',
'ODS_STORE_GOODS_SALES',
'ODS_TABLE_FEE_DISCOUNT',
'ODS_TENANT_GOODS',
'ODS_SETTLEMENT_TICKET'
]) AS task_code
)
INSERT INTO etl_admin.etl_task (task_code, store_id, enabled)
SELECT t.task_code, s.store_id, TRUE
FROM task_codes t CROSS JOIN target_store s
ON CONFLICT (task_code, store_id) DO UPDATE
SET enabled = EXCLUDED.enabled;

54
database/seed_scheduler_tasks.sql Normal file
View File

@@ -0,0 +1,54 @@
-- Seed scheduler-compatible tasks into etl_admin.etl_task.
--
-- Notes:
-- - These task_code values must match orchestration/task_registry.py.
-- - ODS_* tasks are intentionally excluded here because they don't follow the
-- BaseTask(cursor_data) scheduler interface in this repo version.
--
-- Usage (example):
-- psql "%PG_DSN%" -f etl_billiards/database/seed_scheduler_tasks.sql
--
WITH target_store AS (
SELECT 2790685415443269::bigint AS store_id -- TODO: replace with your store_id
),
task_codes AS (
SELECT unnest(ARRAY[
'ASSISTANT_ABOLISH',
'ASSISTANTS',
'COUPON_USAGE',
'CHECK_CUTOFF',
'DWD_LOAD_FROM_ODS',
'DWD_QUALITY_CHECK',
'INIT_DWD_SCHEMA',
'INIT_DWS_SCHEMA',
'INIT_ODS_SCHEMA',
'INVENTORY_CHANGE',
'LEDGER',
'MANUAL_INGEST',
'MEMBERS',
'MEMBERS_DWD',
'ODS_JSON_ARCHIVE',
'ORDERS',
'PACKAGES_DEF',
'PAYMENTS',
'PAYMENTS_DWD',
'PRODUCTS',
'REFUNDS',
'TABLE_DISCOUNT',
'TABLES',
'TICKET_DWD',
'TOPUPS',
'DWS_BUILD_ORDER_SUMMARY',
'DWS_WINBACK_INDEX',
'DWS_NEWCONV_INDEX',
'DWS_INTIMACY_INDEX',
'DWS_RELATION_INDEX',
'DWS_ML_MANUAL_IMPORT'
]) AS task_code
)
INSERT INTO etl_admin.etl_task (task_code, store_id, enabled)
SELECT t.task_code, s.store_id, TRUE
FROM task_codes t CROSS JOIN target_store s
ON CONFLICT (task_code, store_id) DO UPDATE
SET enabled = EXCLUDED.enabled,
updated_at = now();

19
docs/20260212/建立一个Deleted文件夹，将删除的文件统一移动到这里，注意保持删除前的目录结.ini Normal file
View File

@@ -0,0 +1,19 @@
建立一个Deleted文件夹，将删除的文件统一移动到这里，注意保持删除前的目录结构。比如在docs下删除1.md，那么将的1.md移动至Deleted/docs/1.md。
删除，移动到Deleted文件夹：
1 可直接删除的垃圾文件（~100+ 个：空目录、快捷方式、缓存、无名文件、一次性输出）
2 tmp/ 下有参考价值的临时脚本（~35 个，建议统一归档）
3 logs/、export/、scripts/logs/ 运行时产出（建议清空并加入 .gitignore）
告诉我每个文件的作用：
根目录散落文件（~12 个，需要你逐个决定去留）
fetch-test/ 目录（需要你决定是保留、移动还是删除）
docs/ 下的临时文档和数据导出（~18 个，需要你决定）
tests/ 下的散落文件（4 个）
等修改完后，统一处理：
.gitignore 补充建议
-------------------
另外，可以将文件归类的目录更科学合理，合理层级，多层级。

16
docs/20260212/我首次使用Kiro。.ini Normal file
View File

@@ -0,0 +1,16 @@
我首次使用Kiro。
我已经买好了会员。
我打开了我的项目目录。
我要做2件事：
一 Kiro的初始配置：
1.1 告诉我在使用前需要完成的配置设置等。或者对于项目的必要准备或初始化？
1.2 语言环境：我需要让Kiro使用中文对话。文档，代码注释，CLI输出内容，LOG等说明内容性的字符全部使用用中文。注意这些环节，中文的编码处理。
二 我想使用Spec模式，让krio完成项目文件管理，业务的精简和代码重构，我应该如何操作：
2.1 现状：项目杂乱无序，旧功能没有删除，文档文件位置错乱，代码和文档对齐失真严重。整个目录需要整理。
2.2 分析每个文件和目录，进行移动归类。
2.3 分析项目的整个流程（流程树），细致到每个子流程和子模块和子逻辑。
2.4 开始精简并重构项目：
2.4.1 每一个子流程和子模块进行遍历告诉我是怎么处理的，通过对话方式，或者文档方式让我知道，我来逐一决定每个业务逻辑的删除或保留。
2.4.2 针对我的要求，最终实现进行项目精简和重构。以及对应文档内容的对齐。

24
docs/README.md Normal file
View File

@@ -0,0 +1,24 @@
# docs/ — 项目文档
## 子目录索引
| 目录 | 内容 |
|------|------|
| `audit/` | 仓库审计报告（由 `scripts/audit/` 自动生成：文件清单、调用流、文档对齐） |
| `bd_manual/` | 业务数据手册 — DWD/DWS 表的字段说明与口径定义 |
| `bd_manual/DWD/` | DWD 层表手册（main 表 + Ex 扩展表） |
| `bd_manual/dws/` | DWS 层表手册（助教、财务、会员、指数等） |
| `dictionary/` | 数据字典（表级字段清单，与 DDL 对照） |
| `index/` | 指数算法文档（WBI/NCI/RS/OS/MS/ML 计算逻辑与参数说明） |
| `requirements/` | 需求文档（功能需求、变更记录） |
| `reports/` | 分析报告（数据质量、一致性检查等输出） |
| `data_exports/` | 数据导出文档与 CSV 样本 |
| `templates/` | 模板文件（Excel 导入模板，如 ML 人工台账） |
| `test-json-doc/` | API 测试 JSON 样本与字段分析 |
| `开发笔记/` | 开发备忘与历史记录 |
## 维护约定
- 代码变更涉及表结构或口径时，同步更新 `bd_manual/` 和 `dictionary/`
- 审计报告通过 `python -m scripts.audit.run_audit` 重新生成，不要手动编辑
- 文档统一 UTF-8 编码，中文撰写

6
docs/ai_audit/README.md Normal file
View File

@@ -0,0 +1,6 @@
# AI 审计目录（docs/ai_audit）
本目录用于记录 AI 驱动的每次变更的审计信息，确保可追溯、可回滚、可验证。
- prompt_log.md：记录每次用户 Prompt（含 Prompt-ID）
- changes/：每次变更一份审计记录（<YYYY-MM-DD>__<slug>.md）

0
docs/ai_audit/changes/.gitkeep Normal file
View File

16
docs/ai_audit/changes/2026-02-13__api-reference-batch2.md Normal file
View File

@@ -0,0 +1,16 @@
# 审计记录：API 参考文档批量生成（第二批 6 个）
- **日期**：2026-02-13
- **原始原因**：用户 Prompt — 为飞球 ETL 系统生成 6 个高质量 API 参考文档（member_profiles、member_stored_value_cards、member_balance_changes、platform_coupon_redemption_records、group_buy_packages、group_buy_redemption_records），按标杆文档 assistant_accounts_master.md 格式
- **直接原因**：按标杆文档格式重写高质量 API 参考文档，替代旧版 test-json-doc 中的分析文档
- **Changed**：
- `docs/api-reference/member_profiles.md`（新建，15 个字段）
- `docs/api-reference/member_stored_value_cards.md`（新建，68 个字段）
- `docs/api-reference/member_balance_changes.md`（新建，25 个字段）
- `docs/api-reference/platform_coupon_redemption_records.md`（新建，26 个字段）
- `docs/api-reference/group_buy_packages.md`（新建，35 个字段）
- `docs/api-reference/group_buy_redemption_records.md`（新建，43 个字段）
- **Risk/Verify**：
- 纯文档变更，无运行时影响
- 验证方式：对比 endpoints/、samples/、test-json-doc/ 源文件确认字段覆盖完整
- 每个文档均包含 AI_CHANGELOG HTML 注释

48
docs/ai_audit/changes/2026-02-13__api-reference-overhaul.md Normal file
View File

@@ -0,0 +1,48 @@
# 2026-02-13 API 参考文档全面重构
## 日期
2026-02-13 (Asia/Taipei)
## 原始原因
用户 Prompt（跨多轮对话）：
> P20260213-170000: "继续"（续接 Task 3 — API 文档全面重构）
> P20260213-171500: "继续"（完成文档生成、索引、清理、审计）
原始需求来自更早的 Prompt（上下文传递）：对所有 23+ API 文档进行全面重构，标准化 API 请求/参数存储，为每个 API 生成独立 .md 文档，重命名/迁移目录，废弃旧 test-json-doc 目录。
## 直接原因
旧 `docs/test-json-doc/` 目录命名不规范，文档格式不统一，缺少标准化的 API 参数注册表。需要创建结构化的 `docs/api-reference/` 目录体系。
## 修改文件清单
### 新增文件
- `docs/api-reference/README.md` — 索引文档
- `docs/api-reference/api_registry.json` — 25 个 API 的标准化定义
- `docs/api-reference/_api_call_results.json` — API 调用结果（字段提取）
- `docs/api-reference/endpoints/*.md` — 25 个端点文档
- `docs/api-reference/samples/*.json` — 24 个响应样本
### 修改文件
- `.kiro/steering/structure.md` — 添加 api-reference 目录描述，标记 test-json-doc 为废弃
### 临时文件（已创建并删除）
- `scripts/gen_api_docs.py` — 一次性 API 调用脚本 v1（已删除）
- `scripts/gen_api_docs_v2.py` — 一次性 API 调用脚本 v2（已删除）
- `scripts/gen_api_md_docs.py` — 一次性 Markdown 生成脚本（已删除）
## 变更性质判定
**无逻辑改动。** 全部为纯文档生成和目录结构描述调整，不涉及：
- 业务规则/计算口径
- 数据处理/ETL 逻辑
- API 行为（未修改 `api/`、`tasks/`、`loaders/` 等运行时代码）
- 数据库 schema/表结构
- 鉴权/权限
## Risk/Verify
- 风险：极低，纯文档变更
- 回归范围：无（不影响任何运行时代码）
- 验证步骤：
1. 确认 `docs/api-reference/endpoints/` 下有 25 个 .md 文件
2. 确认 `docs/api-reference/api_registry.json` 包含 25 个 API 定义
3. 确认 `docs/api-reference/samples/` 下有 24 个 .json 文件（settlement_ticket_details 跳过）
4. 确认 `.kiro/steering/structure.md` 中 api-reference 和 test-json-doc 描述正确

30
docs/ai_audit/changes/2026-02-13__field-drift-report-update.md Normal file
View File

@@ -0,0 +1,30 @@
# 2026-02-13 — API 字段漂移报告修正更新
## 日期
2026-02-13 (Asia/Taipei)
## 原始原因
上下文传递续接：前次对话中发现 settlement_records / recharge_settlements / payment_transactions 三个端点因使用 `pageSize`/`pageNo` 参数导致 HTTP 1400 失败。用户确认这些端点需要使用 `limit` 参数（最大 100）。
## 直接原因
需要用正确的 `limit` 参数重新调用这 3 个端点，提取实际 API 字段并与本地 JSON 样本比对，更新字段漂移报告。
## Changed
- `docs/reports/api_field_drift_report_20260213.json` — 更新 3 个实体的比对结果 + 摘要统计
- `docs/reports/api_field_drift_report_20260213.md` — 同步更新 MD 格式报告，新增漂移详情、分页参数兼容性说明
- 删除临时文件：`_retry_1400.py`、`_retry_goods.py`、`_field_drift_retry.py`、`_retry_results.json`
## 比对结果
| 实体 | 本地字段 | API 字段 | 新增 | 移除 |
|------|---------|---------|------|------|
| settlement_records | 86 | 91 | 5 | 0 |
| recharge_settlements | 86 | 91 | 5 | 0 |
| payment_transactions | 10 | 10 | 0 | 0 |
新增字段（settlement_records / recharge_settlements 共同）：
- `electricityAdjustMoney`、`electricityMoney`、`realElectricityMoney` — 电费相关
- `merVouSalesAmount`、`plCouponSaleAmount` — 商户券/平台券销售额
## Risk/Verify
- 风险：纯文档更新，无代码逻辑变更
- 验证：重新运行比对脚本可复现结果；检查 JSON 报告 summary 数值一致性

137
docs/ai_audit/prompt_log.md Normal file
View File

@@ -0,0 +1,137 @@
# Prompt Log
> 由 Hook（Prompt Submit）自动追加写入。请勿手工改写历史记录（如需修订，请追加更正说明）。
---
## P20260213-114500
- 时间：2026-02-13 11:45:00 (Asia/Taipei)
- Prompt 原文：
> 给我输出各表格，表头：API接口|作用|是否返回成功|JSON字段数量|对应ODS表|ODS表字段数量|差异分析
- 摘要：用户要求将 API 字段漂移比对结果以指定表头格式输出，包含 API 接口、作用、返回状态、JSON 字段数、ODS 表名、ODS 字段数及差异分析。
---
## P20260213-153000
- 时间：2026-02-13 15:30:00 (Asia/Taipei)
- Prompt 原文：
> （上下文传递续接）继续完成 API 字段漂移比对任务：清理临时文件、用 limit 参数重新调用 settlement_records / recharge_settlements / payment_transactions 三个端点、提取字段比对、更新报告。
- 摘要：续接上下文，用 limit 参数修正 3 个 HTTP 1400 端点的字段比对，更新 JSON/MD 报告（ok 17→20, drift 9→11, new_fields 36→46），清理临时脚本。
---
## P20260213-160000
- 时间：2026-02-13 16:00:00 (Asia/Taipei)
- Prompt 原文：
> 完善之前的表格
- 摘要：用户要求重新输出完整的 23 个实体汇总表格（含修正后的 settlement_records / recharge_settlements / payment_transactions 比对结果及 ODS 字段数），查询 PostgreSQL 获取 ODS 字段数后输出。
---
## P20260213-163000
- 时间：2026-02-13 16:30:00 (Asia/Taipei)
- Prompt 原文（已脱敏）：
> 给你正确的fetch吧！fetch("https://pc.ficoo.vip/apiprod/admin/v1/TenantGoods/GetGoodsSalesList", {... body: {"isSalesBind":0,"startTime":"...","endTime":"...","goodsSalesType":0,"page":1,"limit":20} ...}); fetch("https://pc.ficoo.vip/apiprod/admin/v1/TenantGoods/GetGoodsInventoryList", {... body: {"goodsSecondCategoryId":[],"goodsState":0,"enableStatus":0,"siteId":[REDACTED],"existsGoodsStock":0,"page":1,"limit":20} ...}); 完善结果
>
> （Authorization header 中的 Bearer token 已脱敏为 [REDACTED]）
- 摘要：用户提供浏览器抓包的正确 fetch 请求参数，用于修正 GetGoodsSalesList 和 GetGoodsInventoryList 两个端点的字段比对。关键发现：siteId 需为数组格式，GetGoodsSalesList 需传 isSalesBind/goodsSalesType 等参数。
---
## P20260213-170000
- 时间：2026-02-13 17:00:00 (Asia/Taipei)
- Prompt 原文：
> 继续
- 摘要：续接 Task 3（API 文档全面重构），执行文档生成脚本、创建 25 个 API 端点文档和 README 索引、更新 structure.md、清理临时脚本、写审计记录。
---
## P20260213-171500
- 时间：2026-02-13 17:15:00 (Asia/Taipei)
- Prompt 原文：
> 继续
- 摘要：续接 Task 3，完成 API 文档生成后的收尾工作：验证文档质量、创建 api-reference/README.md 索引、更新 structure.md 反映新目录、清理 3 个临时脚本、写审计记录和 prompt log。
---
## P20260213-173000
- 时间：2026-02-13 17:30:00 (Asia/Taipei)
- Prompt 原文：
> （系统触发变更影响审查）
- 摘要：对 Task 3（API 文档重构）执行变更影响审查，判定为无逻辑改动，补全 structure.md 的 AI_CHANGELOG，更新审计记录文件。
---
## P20260213-190000
- 时间：2026-02-13 19:00:00 (Asia/Taipei)
- Prompt 原文：
> （上下文传递续接）继续完成 Task 3 Phase 2 API 文档重构：验证子代理生成的 24 个 API 文档质量是否达到 assistant_accounts_master.md 模板标准。
- 摘要：续接 Task 3，抽查 8 个子代理生成的 API 文档（settlement_records、assistant_service_records、payment_transactions、group_buy_packages、member_profiles、role_area_association、goods_stock_movements、table_fee_transactions、tenant_member_balance_overview、recharge_settlements），确认全部 25 个文档格式一致、字段分组详解完整、跨表关联齐全，质量达标。
---
## P20260213-193000
- 时间：2026-02-13 19:30:00 (Asia/Taipei)
- Prompt 原文：
> 25个文件，逐一检查，不要抽查
- 摘要：用户要求对 docs/api-reference/ 下全部 25 个 API 参考文档逐一检查质量（不允许抽查），对照模板 assistant_accounts_master.md 验证六大章节结构、字段分组、枚举标注、跨表关联等是否达标。结果：25/25 全部达标。
---
## P20260213-200000
- 时间：2026-02-13 20:00:00 (Asia/Taipei)
- Prompt 原文：
> （上下文传递续接）系统自动触发的上下文传递，包含 Task 1（BD Manual 全量同步）、Task 2（API 字段漂移报告）、Task 3（API 文档全面重构）的完整状态摘要。三项任务均已完成。
- 摘要：上下文传递续接，确认 Task 1/2/3 全部完成，读取关键参考文件（prompt_log、api_registry.json、README、模板文档、API.txt）恢复上下文。无新增工作请求。
---
## P20260213-200500
- 时间：2026-02-13 20:05:00 (Asia/Taipei)
- Prompt 原文：
> 帮我GIT操作：1 删除本地仓库。2 添加一个仓库https://git.langlangzhuoqiu.cn/root/ZQYY.FQ-ETL.git，注意这是一个新的，空仓库。3 将代码提交到这个空仓库中
- 摘要：用户要求执行 Git 操作：删除本地 .git 仓库、初始化新仓库并添加远程地址 git.langlangzhuoqiu.cn/root/ZQYY.FQ-ETL.git、将全部代码提交并推送到该空仓库。

117
docs/api-reference/README.md Normal file
View File

@@ -0,0 +1,117 @@
# API 参考文档
> 飞球 ETL 系统上游 SaaS API 的标准化文档。
> 自动生成于 2026-02-13，基于实时 API 调用 + 本地 JSON 样本。
## 目录结构
```
docs/api-reference/
├── README.md # 本文件（索引）
├── api_registry.json # API 注册表（标准化参数存储）
├── _api_call_results.json # API 调用结果（字段提取）
├── endpoints/ # 每个 API 一个 .md 文档
│ ├── assistant_accounts_master.md
│ ├── ...（共 25 个）
│ └── tenant_member_balance_overview.md
└── samples/ # 每个 API 的响应样本（单条记录 JSON）
├── assistant_accounts_master.json
├── ...
└── tenant_member_balance_overview.json
```
## API 总览（25 个接口）
### 人事管理
| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [SearchAssistantInfo](endpoints/assistant_accounts_master.md) | 助教账号主数据 | `assistant_accounts_master` | 61 |
| [GetOrderAssistantDetails](endpoints/assistant_service_records.md) | 助教服务流水 | `assistant_service_records` | 64 |
| [GetAbolitionAssistant](endpoints/assistant_cancellation_records.md) | 助教撤销记录 | `assistant_cancellation_records` | 13 |
### 订单与结算
| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [GetAllOrderSettleList](endpoints/settlement_records.md) | 结账记录 | `settlement_records` | 92 |
| [GetSiteTableOrderDetails](endpoints/table_fee_transactions.md) | 台费流水 | `table_fee_transactions` | 39 |
| [GetTaiFeeAdjustList](endpoints/table_fee_discount_records.md) | 台费优惠记录 | `table_fee_discount_records` | 20 |
| [GetOrderSettleTicketNew](endpoints/settlement_ticket_details.md) | 结账小票明细 | `settlement_ticket_details` | ⚠️ 不可用 |
### 支付与退款
| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [GetPayLogListPage](endpoints/payment_transactions.md) | 支付流水 | `payment_transactions` | 11 |
| [GetRefundPayLogList](endpoints/refund_transactions.md) | 退款流水 | `refund_transactions` | 32 |
| [GetRechargeSettleList](endpoints/recharge_settlements.md) | 充值结算记录 | `recharge_settlements` | 92 |
### 会员
| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [GetTenantMemberList](endpoints/member_profiles.md) | 会员档案 | `member_profiles` | 15 |
| [GetTenantMemberCardList](endpoints/member_stored_value_cards.md) | 会员储值卡 | `member_stored_value_cards` | 68 |
| [GetMemberCardBalanceChange](endpoints/member_balance_changes.md) | 会员余额变动 | `member_balance_changes` | 25 |
### 优惠券与团购
| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [GetOfflineCouponConsumePageList](endpoints/platform_coupon_redemption_records.md) | 平台券核销记录 | `platform_coupon_redemption_records` | 26 |
| [QueryPackageCouponList](endpoints/group_buy_packages.md) | 团购套餐定义 | `group_buy_packages` | 35 |
| [GetSiteTableUseDetails](endpoints/group_buy_redemption_records.md) | 团购核销记录 | `group_buy_redemption_records` | 43 |
### 商品与库存
| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [QueryTenantGoods](endpoints/tenant_goods_master.md) | 租户商品主数据 | `tenant_goods_master` | 31 |
| [GetGoodsSalesList](endpoints/store_goods_sales_records.md) | 门店商品销售记录 | `store_goods_sales_records` | 50 |
| [GetGoodsInventoryList](endpoints/store_goods_master.md) | 门店商品库存主数据 | `store_goods_master` | 45 |
| [QueryPrimarySecondaryCategory](endpoints/stock_goods_category_tree.md) | 商品分类树 | `stock_goods_category_tree` | 2 |
| [QueryGoodsOutboundReceipt](endpoints/goods_stock_movements.md) | 库存出入库流水 | `goods_stock_movements` | 19 |
| [GetGoodsStockReport](endpoints/goods_stock_summary.md) | 库存汇总报表 | `goods_stock_summary` | 14 |
### 台桌
| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [GetSiteTables](endpoints/site_tables_master.md) | 台桌主数据 | `site_tables_master` | 25 |
### 新增 API（尚未建 ODS 表）
| API | 中文名 | ODS 表 | 字段数 |
|-----|--------|--------|--------|
| [QueryRoleAreaAssociation](endpoints/role_area_association.md) | 角色区域关联 | 无 | 1 |
| [TenantMemberBalanceOverview](endpoints/tenant_member_balance_overview.md) | 会员余额总览 | 无 | 9 |
## 关键发现
### 分页参数差异
- 大多数端点接受 `page` + `limit`
- `GetAllOrderSettleList`、`GetRechargeSettleList`、`GetPayLogListPage` 拒绝 `pageSize`/`pageNo`（HTTP 1400），必须用 `limit`
- `limit` 最大值为 100
### 特殊参数格式
- `GetGoodsInventoryList` 的 `siteId` 必须为数组格式 `[sid]`
- `GetGoodsSalesList` 需要 `isSalesBind`/`goodsSalesType` 业务过滤参数
- `QueryPackageCouponList` 的 `areaId` 为数组格式
### 响应结构差异
- 大多数端点：`{code, data: {list: [...], total}}`
- `settlement_records` / `recharge_settlements`：`{code, data: {settleList: [{siteProfile, settleList: {...}}]}}`
- `stock_goods_category_tree`：`{code, data: {goodsCategoryList: [...]}}`
- `payment_transactions` / `refund_transactions`：记录中嵌套 `siteProfile` 对象
## 与旧文档的关系
旧文档位于 `docs/test-json-doc/`（已废弃），包含：
- `*.json` — 本地 JSON 样本文件（仍可用于离线回放）
- `*-Analysis.md` — 详细字段分析文档（内容已迁移至本目录各端点文档的"详细字段分析"章节）
新文档优势：
- 标准化结构（请求参数表 + 响应字段表 + 详细分析）
- `api_registry.json` 提供机器可读的 API 定义
- `samples/` 目录提供最新响应样本

4360
docs/api-reference/_api_call_results.json Normal file
View File

File diff suppressed because it is too large Load Diff

641
docs/api-reference/api_registry.json Normal file
View File

@@ -0,0 +1,641 @@
[
{
"id": "assistant_accounts_master",
"name_zh": "助教账号主数据",
"module": "PersonnelManagement",
"action": "SearchAssistantInfo",
"method": "POST",
"ods_table": "assistant_accounts_master",
"description": "查询门店下所有助教账号的基础信息（人事档案维表）",
"body": {
"workStatusEnum": 0,
"dingTalkSynced": 0,
"leaveId": 0,
"criticismStatus": 0,
"signStatus": -1,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": false,
"data_path": "data.list"
},
{
"id": "settlement_records",
"name_zh": "结账记录",
"module": "Site",
"action": "GetAllOrderSettleList",
"method": "POST",
"ods_table": "settlement_records",
"description": "查询门店结账（台费+商品+助教）汇总记录",
"body": {
"settleType": 0,
"rangeStartTime": "2026-02-01 08:00:00",
"rangeEndTime": "2026-02-13 08:00:00",
"siteId": 2790685415443269,
"siteTableAreaIdList": [],
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"rangeStartTime",
"rangeEndTime"
],
"data_path": "data.settleList"
},
{
"id": "assistant_service_records",
"name_zh": "助教服务流水",
"module": "AssistantPerformance",
"action": "GetOrderAssistantDetails",
"method": "POST",
"ods_table": "assistant_service_records",
"description": "查询助教服务明细（含订单关联、计费、确认状态）",
"body": {
"siteId": 2790685415443269,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"IsConfirm": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "assistant_cancellation_records",
"name_zh": "助教撤销记录",
"module": "AssistantPerformance",
"action": "GetAbolitionAssistant",
"method": "POST",
"ods_table": "assistant_cancellation_records",
"description": "查询助教服务被撤销/取消的记录",
"body": {
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"siteId": 2790685415443269,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "table_fee_transactions",
"name_zh": "台费流水",
"module": "Site",
"action": "GetSiteTableOrderDetails",
"method": "POST",
"ods_table": "table_fee_transactions",
"description": "查询台桌开台/结账的台费订单明细",
"body": {
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"siteId": 2790685415443269,
"isSaleManUser": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "table_fee_discount_records",
"name_zh": "台费优惠记录",
"module": "Site",
"action": "GetTaiFeeAdjustList",
"method": "POST",
"ods_table": "table_fee_discount_records",
"description": "查询台费调整/优惠明细",
"body": {
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"siteId": 2790685415443269,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "payment_transactions",
"name_zh": "支付流水",
"module": "PayLog",
"action": "GetPayLogListPage",
"method": "POST",
"ods_table": "payment_transactions",
"description": "查询支付日志（含在线/线下/余额等多种支付方式）",
"body": {
"StartPayTime": "2026-02-01 08:00:00",
"EndPayTime": "2026-02-13 08:00:00",
"siteId": 2790685415443269,
"OnlinePayChannel": 0,
"paymentMethod": 0,
"relateType": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"StartPayTime",
"EndPayTime"
],
"data_path": "data.list"
},
{
"id": "refund_transactions",
"name_zh": "退款流水",
"module": "Order",
"action": "GetRefundPayLogList",
"method": "POST",
"ods_table": "refund_transactions",
"description": "查询退款记录明细",
"body": {
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"siteId": 2790685415443269,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "platform_coupon_redemption_records",
"name_zh": "平台券核销记录",
"module": "Promotion",
"action": "GetOfflineCouponConsumePageList",
"method": "POST",
"ods_table": "platform_coupon_redemption_records",
"description": "查询线下/平台优惠券核销明细",
"body": {
"couponChannel": 0,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"siteId": 2790685415443269,
"couponUseStatus": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "tenant_goods_master",
"name_zh": "租户商品主数据",
"module": "TenantGoods",
"action": "QueryTenantGoods",
"method": "POST",
"ods_table": "tenant_goods_master",
"description": "查询租户级商品定义（含成本、折扣、状态）",
"body": {
"costPriceType": 0,
"ableDiscount": -1,
"tenantGoodsStatus": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": false,
"data_path": "data.list"
},
{
"id": "store_goods_sales_records",
"name_zh": "门店商品销售记录",
"module": "TenantGoods",
"action": "GetGoodsSalesList",
"method": "POST",
"ods_table": "store_goods_sales_records",
"description": "查询门店商品销售明细（含绑定销售、独立销售）",
"body": {
"isSalesBind": 0,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"siteId": 2790685415443269,
"goodsSalesType": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "store_goods_master",
"name_zh": "门店商品库存主数据",
"module": "TenantGoods",
"action": "GetGoodsInventoryList",
"method": "POST",
"ods_table": "store_goods_master",
"description": "查询门店商品库存列表（含分类、状态、库存量）",
"body": {
"goodsSecondCategoryId": [],
"goodsState": 0,
"enableStatus": 0,
"siteId": [
2790685415443269
],
"existsGoodsStock": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": false,
"data_path": "data.list"
},
{
"id": "stock_goods_category_tree",
"name_zh": "商品分类树",
"module": "TenantGoodsCategory",
"action": "QueryPrimarySecondaryCategory",
"method": "POST",
"ods_table": "stock_goods_category_tree",
"description": "查询商品一级/二级分类树",
"body": null,
"pagination": null,
"time_range": false,
"data_path": "data"
},
{
"id": "goods_stock_movements",
"name_zh": "库存出入库流水",
"module": "GoodsStockManage",
"action": "QueryGoodsOutboundReceipt",
"method": "POST",
"ods_table": "goods_stock_movements",
"description": "查询商品出入库单据明细",
"body": {
"siteId": 2790685415443269,
"stockType": 0,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "member_profiles",
"name_zh": "会员档案",
"module": "MemberProfile",
"action": "GetTenantMemberList",
"method": "POST",
"ods_table": "member_profiles",
"description": "查询门店会员基础信息列表",
"body": {
"isMemberInBlackList": 0,
"status_Revoked": 0,
"isBindOrg": 0,
"registerSource": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": false,
"data_path": "data.list"
},
{
"id": "member_stored_value_cards",
"name_zh": "会员储值卡",
"module": "MemberProfile",
"action": "GetTenantMemberCardList",
"method": "POST",
"ods_table": "member_stored_value_cards",
"description": "查询会员储值卡列表（含余额、折扣、状态）",
"body": {
"siteId": 2790685415443269,
"cardPhysicsType": 0,
"status": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": false,
"data_path": "data.list"
},
{
"id": "recharge_settlements",
"name_zh": "充值结算记录",
"module": "Site",
"action": "GetRechargeSettleList",
"method": "POST",
"ods_table": "recharge_settlements",
"description": "查询充值结算汇总记录",
"body": {
"settleType": 0,
"paymentMethod": 0,
"rangeStartTime": "2026-02-01 08:00:00",
"rangeEndTime": "2026-02-13 08:00:00",
"siteId": 2790685415443269,
"isFirst": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"rangeStartTime",
"rangeEndTime"
],
"data_path": "data.settleList"
},
{
"id": "member_balance_changes",
"name_zh": "会员余额变动",
"module": "MemberProfile",
"action": "GetMemberCardBalanceChange",
"method": "POST",
"ods_table": "member_balance_changes",
"description": "查询会员储值卡余额变动明细",
"body": {
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"fromType": 0,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "group_buy_packages",
"name_zh": "团购套餐定义",
"module": "PackageCoupon",
"action": "QueryPackageCouponList",
"method": "POST",
"ods_table": "group_buy_packages",
"description": "查询团购/套餐券定义列表",
"body": {
"areaId": [],
"commonShowStatus": 1,
"offlineCouponChannel": 0,
"systemGroupType": 1,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": false,
"data_path": "data.list"
},
{
"id": "group_buy_redemption_records",
"name_zh": "团购核销记录",
"module": "Site",
"action": "GetSiteTableUseDetails",
"method": "POST",
"ods_table": "group_buy_redemption_records",
"description": "查询团购券/套餐券核销明细",
"body": {
"siteId": 2790685415443269,
"offlineCouponChannel": 0,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"page": 1,
"limit": 100,
"queryType": 1
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "goods_stock_summary",
"name_zh": "库存汇总报表",
"module": "TenantGoods",
"action": "GetGoodsStockReport",
"method": "POST",
"ods_table": "goods_stock_summary",
"description": "查询商品库存汇总报表",
"body": {
"siteId": 2790685415443269,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": true,
"time_keys": [
"startTime",
"endTime"
],
"data_path": "data.list"
},
{
"id": "site_tables_master",
"name_zh": "台桌主数据",
"module": "Table",
"action": "GetSiteTables",
"method": "POST",
"ods_table": "site_tables_master",
"description": "查询门店台桌列表（含区域、状态、虚拟桌）",
"body": {
"showStatus": 0,
"virtualTableType": -1,
"page": 1,
"limit": 100
},
"pagination": {
"type": "page_limit",
"page_key": "page",
"limit_key": "limit",
"max_limit": 100
},
"time_range": false,
"data_path": "data.list"
},
{
"id": "settlement_ticket_details",
"name_zh": "结账小票明细",
"module": "Order",
"action": "GetOrderSettleTicketNew",
"method": "POST",
"ods_table": "settlement_ticket_details",
"description": "查询结账小票明细（暂不可用）",
"body": null,
"pagination": null,
"time_range": false,
"data_path": null,
"skip": true
},
{
"id": "role_area_association",
"name_zh": "角色区域关联",
"module": "User",
"action": "QueryRoleAreaAssociation",
"method": "POST",
"ods_table": null,
"description": "查询角色与区域的关联关系（统计某种卡的合计情况）",
"body": {
"roleId": 12
},
"pagination": null,
"time_range": false,
"data_path": "data"
},
{
"id": "tenant_member_balance_overview",
"name_zh": "会员余额总览",
"module": "MemberProfile",
"action": "TenantMemberBalanceOverview",
"method": "POST",
"ods_table": null,
"description": "查询各类会员卡统计一览（余额汇总）",
"body": null,
"pagination": null,
"time_range": false,
"data_path": "data"
}
]

281
docs/api-reference/assistant_accounts_master.md Normal file
View File

@@ -0,0 +1,281 @@
# 助教账号主数据 — SearchAssistantInfo
> 模块：`PersonnelManagement` · ODS 表：`assistant_accounts_master` · 维度表（快照）
---
## 一、接口概述
查询门店下所有助教账号的基础信息，包括人事档案、等级配置、薪资开关、在线状态等。每条记录对应一名助教账号，是典型的维度表，与助教流水等事实表通过 `id` / `user_id` / `team_id` 关联。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /PersonnelManagement/SearchAssistantInfo` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要（全量快照） |
---
## 二、请求
### 请求体（JSON）
```json
{
"workStatusEnum": 0,
"dingTalkSynced": 0,
"leaveId": 0,
"criticismStatus": 0,
"signStatus": -1,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `workStatusEnum` | int | 是 | 工作状态筛选。`0` = 全部，`1` = 在岗，`2` = 离岗 |
| `dingTalkSynced` | int | 是 | 钉钉同步状态筛选。`0` = 全部，`1` = 已同步 |
| `leaveId` | int | 是 | 离职状态筛选。`0` = 全部，`1` = 已离职 |
| `criticismStatus` | int | 是 | 投诉状态筛选。`0` = 全部，`1` = 正常，`2` = 有投诉 |
| `signStatus` | int | 是 | 合同签署状态筛选。`-1` = 全部，`0` = 未签署 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 50
}
}
```
`data.list` 中每个对象即为一条助教记录，共 61 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（61 个字段）
### 4.1 主键与账号身份
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2947562271297029` | 助教账号主键 ID。所有助教相关事实表（助教流水、排班等）通过此 ID 关联。在助教流水中对应 `site_assistant_id` |
| `user_id` | int | `2947562270838277` | 系统级用户账号 ID，对应登录账号。用于统一人员在不同角色/模块下的身份，区别于岗位级的 `id`。在助教流水中有同名字段 |
| `assistant_no` | string | `"31"` | 助教工号/编号，便于业务侧识别。编号不唯一（不同助教可能重复）。在助教流水中对应 `assistantNo` |
| `job_num` | string | `""` | 备用工号字段，当前门店未启用，全部为空字符串 |
| `serial_number` | int | `0` | 系统内部序列号/排序标识，部分为 0，部分为较大整数（如 2738），用于全局排序或数据迁移 |
| `system_role_id` | int | `10` | 系统角色 ID，标识该账号在系统中的角色类型 |
### 4.2 个人基础信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `real_name` | string | `"张静然"` | 助教真实姓名。在助教流水中对应 `assistantName` |
| `nickname` | string | `"小然"` | 前台展示昵称，用于顾客侧展示，与真实姓名区分。在助教流水中有同名字段 |
| `gender` | int | `0` | 性别枚举：`0` = 未填/保密，`1` = 男，`2` = 女 |
| `birth_date` | string | `"0001-01-01 00:00:00"` | 出生日期。`0001-01-01` 为默认无效日期（未填写），少量为真实日期 |
| `mobile` | string | `"15119679931"` | 手机号（11 位），用于登录绑定、通知、钉钉同步。每个账号基本唯一 |
| `avatar` | string | `"https://oss.ficoo.vip/...defaultAvatar.png"` | 头像 URL。大量为默认头像，少量为自定义头像 |
| `introduce` | string | `""` | 个人简介文案，预留字段，当前全部为空 |
| `video_introduction_url` | string | `""` | 个人视频介绍 URL（OSS 存储），绝大多数为空，极少数有值 |
| `height` | float | `0.0` | 身高（厘米）。`0` 表示未填写，有值时如 163.0、170.0 |
| `weight` | float | `0.0` | 体重（公斤）。`0` 表示未填写，有值时如 55.0、90.0 |
### 4.3 组织、团队与门店
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tenant_id` | int | `2790683160709957` | 品牌/租户 ID，所有记录相同。多门店场景下用于区分不同商户 |
| `site_id` | int | `2790685415443269` | 门店 ID，所有记录相同。与其他业务表（台费流水、库存等）的 `site_id` 一致 |
| `shop_name` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
| `team_id` | int | `2792011585884037` | 助教所属团队 ID。在助教流水中对应 `assistant_team_id` |
| `team_name` | string | `"1组"` | 团队名称，展示用，与 `team_id` 一一对应 |
| `group_id` | int | `0` | 上层分组 ID（集团/事业部），预留字段，当前门店未使用 |
| `group_name` | string | `""` | `group_id` 对应名称，当前为空 |
| `person_org_id` | int | `2947562271215109` | 人事组织 ID，表示"门店-助教部-小组"等层级。每条记录不同。在助教流水中有同名字段。用于人力组织维度统计和权限控制 |
| `staff_id` | int | `0` | 人事系统员工 ID，预留字段，当前未接入外部 HR 系统 |
| `staff_profile_id` | int | `0` | 人事档案 ID，预留字段，当前未启用 |
### 4.4 等级、计费与薪资
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `level` | int | `20` | 助教等级枚举：`8` = 助教管理/管理员，`10` = 初级，`20` = 中级，`30` = 高级，`40` = 资深/专家。在助教流水中以 `assistant_level` + `levelName` 体现 |
| `charge_way` | int | `2` | 计费方式枚举：`2` = 计时收费（当前门店），其他值（1、3）可能对应按局、按课时 |
| `pd_unit_price` | float | `0.0` | 普通时段单价，当前未在账号层面配置（实际单价在助教商品/套餐配置中） |
| `cx_unit_price` | float | `0.0` | 促销时段单价，当前未在账号层面配置 |
| `allow_cx` | int | `1` | 是否允许参与促销计费：`1` = 允许，其他值 = 不允许 |
| `is_guaranteed` | int | `1` | 是否配置保底薪酬/保底时长：`1` = 有保底规则 |
| `salary_grant_enabled` | int | `2` | 薪资发放配置开关。`2` 为当前门店统一值，具体含义需参照系统配置 |
| `assistant_grade` | float | `0.0` | 助教综合评分（平均分快照），当前未启用评分功能 |
| `sum_grade` | float | `0.0` | 评分总和，用于计算平均分（`assistant_grade = sum_grade / get_grade_times`） |
| `get_grade_times` | int | `0` | 累计被评分次数，当前为 0 |
### 4.5 入职、离职与合同签署
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `entry_time` | string | `"2025-11-02 08:00:00"` | 入职时间 |
| `resign_time` | string | `"2025-11-03 08:00:00"` | 离职日期。在职员工使用远未来日期（如 `2225-xx-xx`）作为占位，已离职员工为真实日期 |
| `entry_type` | int | `1` | 入职类型：`1` = 正式入职，其他值可能表示实习/兼职（当前未出现） |
| `entry_sign_status` | int | `0` | 入职协议签署状态：`0` = 未签署（当前未启用电子签功能） |
| `resign_sign_status` | int | `0` | 离职协议签署状态：`0` = 未签署 |
| `leave_status` | int | `1` | 离职状态：`0` = 在职（`resign_time` 为远未来占位），`1` = 已离职（`resign_time` 为真实日期） |
| `work_status` | int | `2` | 工作状态：`1` = 在岗/可排班（`leave_status=0` 时），`2` = 离岗/停止安排（`leave_status=1` 时） |
### 4.6 账号启用、展示与在线状态
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `assistant_status` | int | `1` | 账号启用状态：`1` = 启用，`2` = 停用/冻结（可能未离职但账号被禁用） |
| `show_status` | int | `1` | 前台展示状态：`1` = 在助教选择界面展示 |
| `show_sort` | int | `31` | 前台展示排序权重，数值越小排序越靠前，与 `assistant_no` 有一定对应关系 |
| `online_status` | int | `1` | 在线状态：`1` = 在线 |
| `is_delete` | int | `0` | 逻辑删除标记：`0` = 未删除，`1` = 已逻辑删除（数据保留，前台不可见） |
### 4.7 评价与投诉
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `criticism_status` | int | `1` | 投诉/差评状态：`1` = 正常/无投诉，`2` = 有投诉记录 |
> `assistant_grade` / `sum_grade` / `get_grade_times` 见 4.4 节。当前全部为 0，表示该门店尚未产生助教评价数据。
### 4.8 时间元数据与最近服务
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-02 15:55:26"` | 账号创建时间 |
| `update_time` | string | `"2025-11-03 18:32:07"` | 账号最近修改时间（如修改等级、昵称等） |
| `start_time` | string | `"2025-11-01 08:00:00"` | 当前配置生效开始日期（周期性排班/合同周期），多为整月开始 |
| `end_time` | string | `"2025-12-01 08:00:00"` | 当前配置生效结束日期 |
| `last_table_id` | int | `0` | 最近一次服务的球台 ID，`0` 表示无记录 |
| `last_table_name` | string | `""` | 最近服务球台名称（展示用），如 `"TV"`、`"888"` |
| `last_update_name` | string | — | 最近修改该账号配置的管理员名称，如 `"助教管理员:黄月柳"` |
| `order_trade_no` | int | `0` | 最近一次关联的订单号，`0` 表示无记录。仅为"影子值"，真正的订单明细在订单表中 |
### 4.9 系统集成（钉钉 / 灯控）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ding_talk_synced` | int | `1` | 是否已同步至钉钉：`1` = 已同步 |
| `site_light_cfg_id` | int | `0` | 门店灯控配置 ID，当前门店未在助教维度启用 |
| `light_equipment_id` | string | `""` | 灯控设备 ID，用于"助教开台自动控灯"场景，当前未启用 |
| `light_status` | int | `2` | 灯光控制状态：`2` = 不启用（预留字段） |
### 4.10 其他标志
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_team_leader` | int | `0` | 是否为团队长/组长：`0` = 普通助教，`1` = 团队长（当前门店未指定） |
---
## 五、响应样例（单条记录）
```json
{
"id": 2947562271297029,
"user_id": 2947562270838277,
"assistant_no": "31",
"job_num": "",
"serial_number": 0,
"system_role_id": 10,
"real_name": "张静然",
"nickname": "小然",
"gender": 0,
"birth_date": "0001-01-01 00:00:00",
"mobile": "15119679931",
"avatar": "https://oss.ficoo.vip/maUiImages/images/defaultAvatar.png",
"introduce": "",
"video_introduction_url": "",
"height": 0.0,
"weight": 0.0,
"tenant_id": 2790683160709957,
"site_id": 2790685415443269,
"shop_name": "朗朗桌球",
"team_id": 2792011585884037,
"team_name": "1组",
"group_id": 0,
"group_name": "",
"person_org_id": 2947562271215109,
"staff_id": 0,
"staff_profile_id": 0,
"level": 20,
"charge_way": 2,
"pd_unit_price": 0.0,
"cx_unit_price": 0.0,
"allow_cx": 1,
"is_guaranteed": 1,
"salary_grant_enabled": 2,
"assistant_grade": 0.0,
"sum_grade": 0.0,
"get_grade_times": 0,
"entry_time": "2025-11-02 08:00:00",
"resign_time": "2025-11-03 08:00:00",
"entry_type": 1,
"entry_sign_status": 0,
"resign_sign_status": 0,
"leave_status": 1,
"work_status": 2,
"assistant_status": 1,
"show_status": 1,
"show_sort": 31,
"online_status": 1,
"is_delete": 0,
"criticism_status": 1,
"create_time": "2025-11-02 15:55:26",
"update_time": "2025-11-03 18:32:07",
"start_time": "2025-11-01 08:00:00",
"end_time": "2025-12-01 08:00:00",
"last_table_id": 0,
"last_table_name": "",
"order_trade_no": 0,
"ding_talk_synced": 1,
"site_light_cfg_id": 0,
"light_equipment_id": "",
"light_status": 2,
"is_team_leader": 0
}
```
---
## 六、跨表关联
### 与助教流水（`assistant_service_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `site_assistant_id` | 助教主键 → 流水中的助教 ID |
| `user_id` | `user_id` | 系统用户 ID，完全一致 |
| `team_id` | `assistant_team_id` | 团队 ID |
| `person_org_id` | `person_org_id` | 人事组织 ID |
| `level` | `assistant_level` | 助教等级（流水中还有 `levelName` 文本） |
| `nickname` | `nickname` | 昵称 |
> 助教流水是事实表，本表是对应的助教维表。
### 与门店维度
所有业务表的 `tenant_id`、`site_id` 一致，共享门店维度。台费流水、销售记录、库存变化等表通过 `site_id` / `shop_name` 关联。
### 与订单相关表
`order_trade_no` 仅为"最近订单号"的影子值，真正的订单明细在订单表/小票详情中。助教与订单的关联通过助教流水这张桥接事实表实现。
### 与外部系统
- `ding_talk_synced` / `staff_profile_id` / `staff_id`：企业内部人事系统/钉钉集成预留字段
- `site_light_cfg_id` / `light_equipment_id` / `light_status`：灯控设备联动预留字段，当前未启用

194
docs/api-reference/assistant_cancellation_records.md Normal file
View File

@@ -0,0 +1,194 @@
# 助教撤销记录 — GetAbolitionAssistant
> 模块：`AssistantPerformance` · ODS 表：`assistant_cancellation_records` · 事件表（增量）
---
## 一、接口概述
查询门店下助教服务被撤销（废除）的记录。每条记录对应一次"助教排钟后被取消"的事件，包含台桌、助教、已计费时长、废除金额等信息。本表是助教流水的配套事件表，专门记录废除操作的明细，用于运营审计和对账。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /AssistantPerformance/GetAbolitionAssistant` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | `startTime` / `endTime`（必填） |
---
## 二、请求
### 请求体（JSON）
```json
{
"startTime": "2025-11-01 08:00:00",
"endTime": "2025-11-10 08:00:00",
"siteId": 2790685415443269,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `startTime` | string | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `endTime` | string | 是 | 查询结束时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `siteId` | int | 是 | 门店 ID |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 15
}
}
```
`data.list` 中每个对象即为一条助教撤销记录，共 13 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（13 个字段）
### 4.1 主键与门店
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957675849518789` | 撤销记录主键 ID，唯一标识一条废除事件 |
| `siteId` | int | `2790685415443269` | 门店 ID，与 `siteProfile.id` 一致 |
| `siteProfile` | object | `{...}` | 门店信息快照（冗余），包含门店名称、地址、经纬度等 26 个子字段。结构与其他接口的 `siteProfile` 完全一致，此处为空壳式冗余，不再逐字段展开 |
### 4.2 台桌维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tableId` | int | `2793016660660357` | 台桌 ID，对应台桌配置表的主键。标识废除发生在哪张台 |
| `tableName` | string | `"C1"` | 台桌名称/编号，冗余展示字段。常见值如 `"C1"`、`"B9"`、`"VIP1"`、`"A4"`、`"666"`、`"董事办"` 等 |
| `tableAreaId` | int | `2791963816579205` | 台桌所在区域 ID，对应区域配置表主键 |
| `tableArea` | string | `"C区"` | 台桌所属区域名称。已知值：`"A区"`、`"B区"`、`"C区"`、`"VIP包厢"`、`"K包"`、`"补时长"`、`"666"` |
### 4.3 助教维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `assistantOn` | string | `"27"` | 助教编号（工号），虽为字符串类型但内容为纯数字。对应助教账号表的 `assistant_no`、助教流水的 `assistantNo` |
| `assistantName` | string | `"泡芙"` | 助教姓名/昵称，冗余展示字段。对应助教账号表的 `nickname` / `real_name` |
### 4.4 时间与时长
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `createTime` | string | `"2025-11-09 19:23:29"` | 废除记录创建时间，即系统记录废除操作的时刻。格式 `YYYY-MM-DD HH:MM:SS` |
| `pdChargeMinutes` | int | `214` | 废除前已累计的计费时长，单位为**分钟**。`0` 表示刚排钟即撤销，尚未产生有效计费时间。注意：助教流水中类似字段（`real_use_seconds`）单位为秒 |
### 4.5 金额与原因
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `assistantAbolishAmount` | float | `5.83` | 助教废除金额（元/人民币），本次废除操作对应的金额数值。`0.0` 表示纯记录操作，未产生金额变动 |
| `trashReason` | string | `""` | 废除原因，自由文本字段。当前数据中全部为空字符串，说明系统允许不填原因。预留用于记录如"顾客临时取消""录入错误""更换助教"等说明 |
---
## 五、响应样例（单条记录）
```json
{
"siteProfile": {
"id": 2790685415443269,
"org_id": 2790684179467077,
"shop_name": "朗朗桌球",
"avatar": "https://oss.ficoo.vip/admin/hXcE4E_1752495052016.jpg",
"business_tel": "13316068642",
"full_address": "广东省广州市天河区丽阳街12号",
"address": "广东省广州市天河区天园街道朗朗桌球",
"longitude": 113.360321,
"latitude": 23.133629,
"tenant_site_region_id": 156440100,
"tenant_id": 2790683160709957,
"auto_light": 1,
"attendance_distance": 0,
"wifi_name": "",
"wifi_password": "",
"customer_service_qrcode": "",
"customer_service_wechat": "",
"fixed_pay_qrCode": "",
"prod_env": 1,
"light_status": 1,
"light_type": 0,
"site_type": 1,
"light_token": "",
"site_label": "A",
"attendance_enabled": 1,
"shop_status": 1
},
"createTime": "2025-11-09 19:23:29",
"id": 2957675849518789,
"siteId": 2790685415443269,
"tableAreaId": 2791963816579205,
"tableId": 2793016660660357,
"tableArea": "C区",
"tableName": "C1",
"assistantOn": "27",
"assistantName": "泡芙",
"pdChargeMinutes": 214,
"assistantAbolishAmount": 5.83,
"trashReason": ""
}
```
---
## 六、跨表关联
### 与助教流水（`assistant_service_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `assistantOn` | `assistantNo` | 助教编号 |
| `assistantName` | `assistantName` | 助教姓名 |
| `siteId` | `site_id` | 门店 ID |
| `tableId` | `site_table_id` | 台桌 ID |
> 本表**没有** `order_trade_no` 等硬外键字段，无法直接关联到具体哪条助教流水。需通过"门店 + 助教 + 台桌 + 相近时间"的组合条件做软匹配。助教流水中的 `is_trash` 字段从主流水视角标记"已废除"状态，本表则以"废除事件"为主视角记录明细。
### 与助教账号（`assistant_accounts_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `assistantOn` | `assistant_no` | 助教工号 |
| `assistantName` | `nickname` / `real_name` | 助教姓名 |
### 与台桌配置
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tableId` | 台桌列表 `id` | 台桌主键 |
| `tableName` | 台桌列表 `table_name` | 台桌名称 |
| `tableAreaId` | 区域配置表主键 | 台桌区域 ID |
| `tableArea` | 区域配置表 `area_name` | 区域名称 |
### 与门店维度
`siteId` 与所有业务表的 `site_id` 一致，共享门店维度。`siteProfile` 为冗余快照。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/assistant_cancellation_records.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

294
docs/api-reference/assistant_service_records.md Normal file
View File

@@ -0,0 +1,294 @@
# 助教服务流水 — GetOrderAssistantDetails
> 模块：`AssistantPerformance` · ODS 表：`assistant_service_records` · 事实表（增量）
---
## 一、接口概述
查询门店在指定时间范围内的助教服务流水记录。每条记录对应一次助教服务明细（一位助教在一张桌上的一段服务），是助教业绩核算、薪资计算的核心数据源。
助教流水是事实表，通过 `order_trade_no` / `order_settle_id` 与结账记录、台费流水、小票详情等表关联，构成同一笔订单下的不同消费子项目。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /AssistantPerformance/GetOrderAssistantDetails` |
| 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",
"IsConfirm": 0,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `startTime` | string | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `endTime` | string | 是 | 查询结束时间 |
| `IsConfirm` | int | 是 | 确认状态筛选。`0` = 全部，`1` = 待确认，`2` = 已确认 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 1200
}
}
```
`data.list` 中每个对象即为一条助教服务流水记录，共 64 个字段（含嵌套 `siteProfile` 对象），按逻辑分组说明如下。
---
## 四、响应字段详解（64 个字段）
### 4.1 订单与关联 ID
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957913441292165` | 助教流水记录主键 ID（流水唯一标识） |
| `order_trade_no` | int | `2957784612605829` | 订单交易号。与台费流水、商品销售、团购流水等表的同名字段一致，用于串联同一笔订单下的各类消费明细 |
| `order_settle_id` | int | `2957913171693253` | 订单结算 ID（结账单号）。与结账记录的 `id`、小票详情的 `orderSettleId` 对应 |
| `order_assistant_id` | int | `2957788717240005` | 订单中助教项目明细的内部 ID。同一订单有多条助教项目时（换助教、多时段），此字段唯一标识每条明细 |
| `order_assistant_type` | int | `1` | 助教服务类型枚举：`1` = 常规服务（基础课），`2` = 附加类服务（附加课）。与 `skillName` 对应 |
| `order_pay_id` | int | `0` | 关联支付记录的主键 ID。`0` = 无直接支付关联（通过结账记录间接关联） |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，全表固定 |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `site_assistant_id` | int | `2946266869435205` | 门店维度的助教 ID。与助教账号表的 `id` 对应，是助教档案的外键 |
| `user_id` | int | `2946266868976453` | 助教的系统用户账号 ID。与助教账号表的 `user_id` 一致，区别于岗位级的 `site_assistant_id` |
| `person_org_id` | int | `2946266869336901` | 助教所属人事组织/部门 ID。与助教账号表的 `person_org_id` 一致 |
| `assistant_team_id` | int | `2792011585884037` | 助教所属团队 ID。与助教账号表的 `team_id` 对应，用于排班/团队统计 |
| `tenant_member_id` | int | `0` | 商户维度会员 ID。`0` = 非会员；非零时与会员档案的 `id` 一致 |
| `system_member_id` | int | `0` | 系统级会员 ID（全集团统一）。与会员档案的 `system_member_id` 对应，用于跨门店/跨卡种串联 |
| `skill_id` | int | `2790683529513797` | 助教服务课程/技能 ID，对应课程配置表主键 |
### 4.2 助教维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `assistantNo` | string | `"27"` | 助教编号/工号。与助教账号表的 `assistant_no` 对应 |
| `assistantName` | string | `"何海婷"` | 助教真实姓名。与助教账号表的 `real_name` 一致 |
| `nickname` | string | `"泡芙"` | 助教对外昵称（非顾客昵称）。在小票/商品名中常以"编号-昵称"组合出现（如 `ledger_name = "27-泡芙"`） |
| `assistant_level` | int | `10` | 助教等级枚举：`8` = 助教管理，`10` = 初级，`20` = 中级，`30` = 高级。与助教账号表的 `level` 对应 |
| `levelName` | string | `"初级"` | 助教等级名称，与 `assistant_level` 一一对应，展示用冗余字段 |
| `skillName` | string | `"基础课"` | 当前服务对应的课程/技能名称。`order_assistant_type=1` 时多为"基础课"，`=2` 时为"附加课" |
| `ledger_name` | string | `"27-泡芙"` | 台账显示名称，"编号-昵称"组合，用于报表和前端展示 |
| `ledger_group_name` | string | `""` | 助教项目所属计费分组/套餐分组名称，当前未使用 |
### 4.3 桌台与门店维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tableName` | string | `"S1"` | 助教服务所在球台名称。与台桌列表的 `table_name` / `table_no` 对应 |
| `site_table_id` | int | `2793020259897413` | 球台 ID。对应台桌列表的 `id` |
| `siteProfile` | object | `{id, shop_name, ...}` | 门店信息快照（嵌套对象），包含 `id`、`shop_name`、`address`、`longitude`/`latitude` 等。与其他接口的 `siteProfile` 结构一致。**注意：此处 siteProfile 包含真实门店数据**（区别于结账记录中的空壳） |
### 4.4 时间与时长
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 23:25:11"` | 流水记录创建时间，接近结算/下单时间 |
| `start_use_time` | string | `"2025-11-09 21:18:18"` | 助教实际开始服务时间。正常情况下与 `ledger_start_time` 相同 |
| `last_use_time` | string | `"2025-11-09 23:24:50"` | 最后一次使用时间。正常结束时与 `ledger_end_time` 相同 |
| `ledger_start_time` | string | `"2025-11-09 21:18:18"` | 台账计费起始时间 |
| `ledger_end_time` | string | `"2025-11-09 23:24:50"` | 台账计费结束时间。`real_use_seconds=0` 时开始=结束，表示仅预约未实际服务 |
| `income_seconds` | int | `7560` | 计费秒数（应计收入对应时间）。值通常为 60 的倍数，配合 `ledger_unit_price` 计算应计金额 |
| `real_use_seconds` | int | `7592` | 实际使用时长（秒）。与 `ledger_count` 基本一致（±1 秒差）。`0` = 已预约但未消耗 |
| `ledger_count` | int | `7592` | 台账计时总秒数，即本条服务真正消耗的总时长 |
| `add_clock` | int | `0` | 加钟秒数（临时追加时长）。值为 60 的倍数，如 `600` = 10 分钟 |
| `returns_clock` | int | `0` | 退钟秒数（取消加钟或提前结束退回的时间）。当前未出现退钟场景 |
### 4.5 金额与折扣
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_unit_price` | float | `98.0` | 助教服务标准单价（每小时/每节课），如 98.0、108.0、190.0 |
| `ledger_amount` | float | `206.67` | 按标准单价计算的应收金额（近似 = `ledger_unit_price × income_seconds / 3600`），未扣除优惠 |
| `projected_income` | float | `168.0` | 实际结算计入门店的金额（已考虑折扣、卡权益、券等）。通常 `projected_income < ledger_amount` |
| `coupon_deduct_money` | float | `0.0` | 优惠券/代金券/团购券直接抵扣到本条助教服务的金额。与平台验券记录/团购流水联动 |
| `manual_discount_amount` | float | `0.0` | 收银员手动减免金额（人工改价） |
| `member_discount_amount` | float | `0.0` | 会员卡折扣产生的优惠金额。实际折扣可能已体现在 `projected_income` 与 `ledger_amount` 的差额中 |
| `service_money` | float | `0.0` | 平台预留的成本/分成字段，当前未启用 |
### 4.6 评价相关
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `skill_grade` | int | `0` | 顾客对技能表现的评分。`0` = 未评价 |
| `service_grade` | int | `0` | 顾客对服务态度的评分。`0` = 未评价 |
| `composite_grade` | float | `0.0` | 综合评分（技能+服务加权平均） |
| `sum_grade` | float | `0.0` | 累计评分总和，用于计算平均分 |
| `get_grade_times` | int | `0` | 被评价次数 |
| `grade_status` | int | `1` | 评价状态：`1` = 未评价/正常 |
| `composite_grade_time` | string | `"0001-01-01 00:00:00"` | 最近评价时间。`0001-01-01` = 无效占位（未评价） |
### 4.7 状态与标志位
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 流水记录状态：`1` = 正常有效。其他值可能对应"未结算""已作废" |
| `is_confirm` | int | `2` | 确认状态：`1` = 待确认，`2` = 已确认/已完成 |
| `is_single_order` | int | `1` | 是否单独订单结算：`1` = 单独结算，`0` = 与其他项目打包在综合订单中 |
| `is_not_responding` | int | `0` | 是否爽约/未响应：`0` = 正常，`1` = 有爽约 |
| `is_trash` | int | `0` | 是否已废除：`0` = 正常，`1` = 已废除（对应助教撤销记录表） |
| `is_delete` | int | `0` | 逻辑删除标志：`0` = 未删除，`1` = 已删除。与 `is_trash` 不同：`is_trash` 是业务废除，`is_delete` 是系统级删除 |
### 4.8 员工 / 销售人员
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 操作员 ID（录入/结算该服务的员工） |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员名称，含角色前缀 |
| `salesman_name` | string | `""` | 营业员/销售员姓名（提成归属），当前未配置 |
| `salesman_user_id` | int | `0` | 营业员用户 ID |
| `salesman_org_id` | int | `0` | 营业员所属组织/部门 ID |
### 4.9 作废 / 废除相关
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `trash_applicant_id` | int | `0` | 废除申请人员工 ID。`0` = 未发生废除 |
| `trash_applicant_name` | string | `""` | 废除申请人姓名 |
| `trash_reason` | string | `""` | 废除原因文本，如"顾客取消""录入错误"等 |
> 当 `is_trash = 1` 时，废除详情同时记录在助教撤销记录表（`assistant_cancellation_records`）中。
---
## 五、响应样例（单条记录）
```json
{
"assistantNo": "27",
"nickname": "泡芙",
"levelName": "初级",
"assistantName": "何海婷",
"tableName": "S1",
"siteProfile": {
"id": 2790685415443269,
"org_id": 2790684179467077,
"shop_name": "朗朗桌球",
"avatar": "https://oss.ficoo.vip/admin/hXcE4E_1752495052016.jpg",
"business_tel": "13316068642",
"full_address": "广东省广州市天河区丽阳街12号",
"address": "广东省广州市天河区天园街道朗朗桌球",
"longitude": 113.360321,
"latitude": 23.133629,
"tenant_site_region_id": 156440100,
"tenant_id": 2790683160709957,
"auto_light": 1,
"site_type": 1,
"site_label": "A",
"attendance_enabled": 1,
"shop_status": 1
},
"skillName": "基础课",
"id": 2957913441292165,
"order_trade_no": 2957784612605829,
"site_id": 2790685415443269,
"tenant_id": 2790683160709957,
"operator_id": 2790687322443013,
"operator_name": "收银员:郑丽珊",
"order_settle_id": 2957913171693253,
"ledger_name": "27-泡芙",
"ledger_unit_price": 98.0,
"ledger_count": 7592,
"ledger_amount": 206.67,
"create_time": "2025-11-09 23:25:11",
"assistant_level": 10,
"ledger_start_time": "2025-11-09 21:18:18",
"ledger_end_time": "2025-11-09 23:24:50",
"site_assistant_id": 2946266869435205,
"order_assistant_type": 1,
"site_table_id": 2793020259897413,
"projected_income": 168.0,
"income_seconds": 7560,
"real_use_seconds": 7592,
"is_confirm": 2,
"grade_status": 1
}
```
> 样例已精简，完整字段见 `samples/assistant_service_records.json`。
---
## 六、跨表关联
### 与助教账号（`assistant_accounts_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `site_assistant_id` | `id` | 助教主键（核心外键） |
| `user_id` | `user_id` | 系统用户 ID |
| `assistant_team_id` | `team_id` | 团队 ID |
| `person_org_id` | `person_org_id` | 人事组织 ID |
| `assistant_level` | `level` | 助教等级 |
> 助教流水是事实表，助教账号是对应的维表。
### 与结账记录（`settlement_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_settle_id` | `id` | 结账单号 |
| `order_trade_no` | `settleRelateId` | 交易号 |
> 结账记录中的 `assistantPdMoney` = 本表对应订单下 `ledger_amount` 的汇总。
### 与会员档案（`member_profiles`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tenant_member_id` | `id` | 商户维度会员 ID |
| `system_member_id` | `system_member_id` | 系统级会员 ID |
### 与台桌（`site_tables_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `site_table_id` | `id` | 球台 ID |
### 与助教撤销记录（`assistant_cancellation_records`）
当 `is_trash = 1` 时，废除详情在撤销记录表中。`trash_reason`、`trash_applicant_id/name` 是废除信息在本表中的快照。
### 新增字段说明（相对旧版 JSON 样本）
| 字段 | 说明 |
|------|------|
| `assistantTeamName` | 助教团队名称（展示用） |
| `real_service_money` | 实际服务金额 |
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-180000 — 上下文传递续接，继续 Phase 2 API 文档重构
- 直接原因: 按标杆文档格式重写 assistant_service_records 高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/assistant_service_records.md，64 个字段按 9 个逻辑分组详解，含时长计算说明、跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

811
docs/api-reference/endpoints/assistant_accounts_master.md Normal file
View File

@@ -0,0 +1,811 @@
# 助教账号主数据（SearchAssistantInfo）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `PersonnelManagement/SearchAssistantInfo` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/PersonnelManagement/SearchAssistantInfo` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `assistant_accounts_master` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要 |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `workStatusEnum` | int | `0` | 工作状态（0=全部） |
| `dingTalkSynced` | int | `0` | 钉钉同步状态（0=全部） |
| `leaveId` | int | `0` | 离职状态（0=全部） |
| `criticismStatus` | int | `0` | 投诉状态（0=全部） |
| `signStatus` | int | `-1` | 签署状态（-1=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 61 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `job_num` | string | '' |
| 2 | `shop_name` | string | '朗朗桌球' |
| 3 | `group_id` | int | 0 |
| 4 | `group_name` | string | '' |
| 5 | `staff_profile_id` | int | 0 |
| 6 | `ding_talk_synced` | int | 1 |
| 7 | `entry_type` | int | 1 |
| 8 | `team_name` | string | '1组' |
| 9 | `entry_sign_status` | int | 0 |
| 10 | `resign_sign_status` | int | 0 |
| 11 | `system_role_id` | int | 10 |
| 12 | `criticism_status` | int | 1 |
| 13 | `salary_grant_enabled` | int | 2 |
| 14 | `leave_status` | int | 1 |
| 15 | `id` | int | 2947562271297029 |
| 16 | `allow_cx` | int | 1 |
| 17 | `assistant_no` | string | '31' |
| 18 | `assistant_status` | int | 1 |
| 19 | `avatar` | string | 'https://oss.ficoo.vip/maUiImages/images/defaultAvatar.png' |
| 20 | `birth_date` | string | '0001-01-01 00:00:00' |
| 21 | `charge_way` | int | 2 |
| 22 | `create_time` | string | '2025-11-02 15:55:26' |
| 23 | `cx_unit_price` | float | 0.0 |
| 24 | `end_time` | string | '2025-12-01 08:00:00' |
| 25 | `entry_time` | string | '2025-11-02 08:00:00' |
| 26 | `gender` | int | 0 |
| 27 | `height` | float | 0.0 |
| 28 | `introduce` | string | '' |
| 29 | `is_delete` | int | 0 |
| 30 | `is_guaranteed` | int | 1 |
| 31 | `is_team_leader` | int | 0 |
| 32 | `last_table_id` | int | 0 |
| 33 | `last_table_name` | string | '' |
| 34 | `level` | int | 20 |
| 35 | `light_equipment_id` | string | '' |
| 36 | `light_status` | int | 2 |
| 37 | `mobile` | string | '15119679931' |
| 38 | `nickname` | string | '小然' |
| 39 | `online_status` | int | 1 |
| 40 | `order_trade_no` | int | 0 |
| 41 | `pd_unit_price` | float | 0.0 |
| 42 | `person_org_id` | int | 2947562271215109 |
| 43 | `real_name` | string | '张静然' |
| 44 | `resign_time` | string | '2025-11-03 08:00:00' |
| 45 | `serial_number` | int | 0 |
| 46 | `show_sort` | int | 31 |
| 47 | `show_status` | int | 1 |
| 48 | `site_id` | int | 2790685415443269 |
| 49 | `site_light_cfg_id` | int | 0 |
| 50 | `staff_id` | int | 0 |
| 51 | `start_time` | string | '2025-11-01 08:00:00' |
| 52 | `team_id` | int | 2792011585884037 |
| 53 | `tenant_id` | int | 2790683160709957 |
| 54 | `update_time` | string | '2025-11-03 18:32:07' |
| 55 | `user_id` | int | 2947562270838277 |
| 56 | `video_introduction_url` | string | '' |
| 57 | `weight` | float | 0.0 |
| 58 | `work_status` | int | 2 |
| 59 | `assistant_grade` | float | 0.0 |
| 60 | `sum_grade` | float | 0.0 |
| 61 | `get_grade_times` | int | 0 |
## 详细字段分析
> 以下内容迁移自旧版 `assistant_accounts_master-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
一、文件整体定位与结构
业务含义（内容类型）
该文件是 “助教账号/人事档案维表”，记录的是某门店下所有助教（含管理类账号）的账号配置、人事状态、可见性、计费策略等基础信息。
每条记录对应 一名助教账号，是一张典型的“维度表”（在数据模型中，与“助教流水”等事实表通过 id / user_id / team_id / site_id 等字段关联）。
二、记录级字段详解（按逻辑分组）
1. 主键 / 账号身份类字段
id
类型：int
含义：助教账号主键 ID，在“助教流水.json”中对应 site_assistant_id。
作用：所有与助教相关的事实表（助教流水、助教排班等）都会通过这个 ID 关联到该维表。
user_id
类型：int
含义：系统级“用户账号 ID”，通常对应登录账号。
关联：
在“助教流水.json”中有同名字段 user_id，与此完全一致。
用途：用于统一人员在不同角色/模块下的账号，区别于岗位级的 id。
assistant_no
类型：string
观测值：'1' ~ '39' 等编号，重复时对应不同助教（编号不唯一）。
含义（结合字段名推测）：助教工号 / 编号，便于业务侧识别。
关联：在“助教流水.json”中有 assistantNo，与此字段对应。
job_num
类型：string
观测：全为 ''（空字符串）。
含义：备用工号字段，目前未在该门店启用。
serial_number
类型：int
观测：部分为 0，部分是较大的整数（例如 2738, 2698, 2534…）。
含义（推测）：系统内部生成的序列号或排序标识，用于全局排序或迁移。
2. 个人基础信息字段
real_name
类型：string
含义：助教真实姓名，如“何海婷”“梁婷婷”等。
关联：在“助教流水.json”的 assistantName 与此一致。
nickname
类型：string
含义：助教在前台展示的昵称，如“佳怡”“周周”“球球”等。
用途：与真实姓名区分，用于顾客侧展示。如在助教流水中 nickname 就是这个值。
gender
类型：int，枚举。
观测值：
0 × 40
1 × 1
2 × 9
含义（结合常见约定与值分布推测）：
0：未填/保密
1：男
2：女
birth_date
类型：string，时间格式。
观测值：
大部分为 "0001-01-01 00:00:00"（显然是默认无效日期）
少量为真实日期，如 "2007-01-14 00:00:00" 等。
含义：助教出生日期。
mobile
类型：string
观测：11 位手机号，每个账号基本唯一。
含义：助教手机号，用于登录绑定、通知、钉钉同步等。
avatar
类型：string
观测：
大量为默认头像 URL，如 .../defaultAvatar.png
少量为具体头像图片 URL。
含义：助教头像地址。
introduce
类型：string
观测：当前导出中全部为空字符串。
含义：个人简介文案，预留给助教自我介绍使用。
video_introduction_url
类型：string
观测：
49 条为 ''
1 条为视频 URL（oss 存储路径）
含义：助教个人视频介绍地址。
height
类型：float
观测：
多数为 0.0，少量为 163.0, 166.0, 167.0, 165.0, 170.0 等。
含义：身高（单位：厘米）。0 表示未填写。
weight
类型：float
观测：
多数为 0.0
少量为 55.0, 90.0, 100.0 等。
含义：体重（单位：公斤）。0 表示未填写。
3. 组织、团队与门店维度字段
tenant_id
类型：int
观测：所有记录相同。
含义：品牌/租户 ID，对应“非球科技”系统中该商户的唯一标识。
用途：多门店时用来区分不同商户。
site_id
类型：int
观测：所有记录相同。
含义：门店 ID，对应本次数据的这家球房（朗朗桌球）。
关联：与其它 JSON（台费流水、库存、销售等）中的 site_id 一致。
shop_name
类型：string
观测：全部为 "朗朗桌球"。
含义：门店名称，冗余字段，用于展示。
team_id
类型：int
观测：所有记录同一个值（唯一团队）。
含义：助教所属团队 ID。
关联：在“助教流水.json”中 assistant_team_id 与此一致。
team_name
类型：string
观测：全部为 "1组"。
含义：团队名称，展示用，和 team_id 一一对应。
group_id
类型：int
观测：全部为 0。
含义（推测）：上层“分组 ID”预留字段（例如集团/事业部），本门店未使用。
group_name
类型：string
观测：全部为 ''。
含义：group_id 对应的名称，目前为空。
person_org_id
类型：int
观测：每条记录一个不同的 ID。
含义：人事组织 ID，通常表示“某某门店-助教部-某小组”等层级组织。
关联：
在“助教流水.json”中同名字段 person_org_id 与此一致。
用途：用于人力组织维度统计、权限控制。
staff_id
类型：int
观测：全部为 0。
含义（推测）：预留给“人事系统员工 ID”的字段，目前未接入或未启用。
staff_profile_id
类型：int
观测：全部为 0。
含义（推测）：人事档案 ID，与第三方 HR 系统或内部员工档案集成使用，当前未启用。
4. 等级、计费与薪资配置字段
level
类型：int，枚举。
观测值：
10 × 24
20 × 18
30 × 4
40 × 3
8 × 1
含义（结合“助教流水中的 assistant_level / levelName 推测”）：
8：助教管理/管理员（和流水里的 "助教管理" 对应）
10：初级助教
20：中级助教
30：高级助教
40：更高等级（可能是“资深/专家”，该等级在流水里暂未出现）。
关联：在“助教流水.json”里以 assistant_level+levelName 体现。
assistant_grade
类型：float
观测：全部为 0.0。
含义（推测）：助教综合评分（员工维度的平均分 snapshot），当前尚未启用评分。
sum_grade
类型：float
观测：全为 0.0。
含义：评分总和，用于计算平均分（assistant_grade = sum_grade / get_grade_times），当前为 0。
get_grade_times
类型：int
观测：全为 0。
含义：累计被评分次数。
charge_way
类型：int，枚举。
观测：全为 2。
含义（推测）：计费方式：
2 代表当前门店为“计时收费”，其他值（1、3 等）可能对应按局、按课时等，当前未出现。
pd_unit_price
类型：float
观测：全为 0.0。
含义（推测）：某种标准单价（例如“普通时段单价”），这里未在账号上配置（实际单价在助教商品或套餐配置中）。
cx_unit_price
类型：float
观测：全为 0.0。
含义（推测）：促销时段的单价，本门店未在账号表层面设置。
allow_cx
类型：int，枚举。
观测：全为 1。
含义（从字段名推测）：
是否允许此助教参与“促销价（促销=促销/促销场）”：
1：允许参与促销计费。
其他值（未出现）可能为不允许。
is_guaranteed
类型：int，枚举。
观测：全为 1。
含义（从字段名推测）：是否配置“保底薪酬/保底时长”：
1：有保底规则。
其他值可能表示无保底。
salary_grant_enabled
类型：int，枚举。
观测：全为 2。
含义（推测）：薪资发放配置开关：
2：一种固定含义（例如“参与薪资发放方案”或相反），具体码值需看系统配置。
仅从这份数据无法区分是否“启用/禁用”，只能确认这是一个薪酬相关开关字段。
5. 入职 / 离职 / 考勤签署相关字段
entry_time
类型：string
观测：各类日期 "2025-07-16 08:00:00", "2025-09-01 08:00:00" 等。
含义：入职时间。
resign_time
类型：string
观测：
对在职员工：类似 "2225-11-01 17:57:41" 这类非常未来的年份，显然是“占位默认值”。
对已离职员工：正常的近时间，如 "2025-10-13 08:00:00" 等。
含义：离职日期；使用“远未来日期”作为“未离职”的占位。
entry_type
类型：int，枚举。
观测：全为 1。
含义（推测）：入职类型：
1：正式入职。
其他值可能表示实习、兼职等，当前未出现。
entry_sign_status
类型：int，枚举。
观测：全为 0。
含义（推测）：入职协议/合同签署状态：
0：未签署。
其他值可能表示已签署（目前未启用电子签功能）。
resign_sign_status
类型：int，枚举。
观测：全为 0。
含义（推测）：离职协议签署状态，类似上面。
leave_status
类型：int，枚举。
观测：
0 × 21
1 × 29
结合 work_status 和 resign_time 可以明确判断：
0：在职（resign_time 为 2225 年占位）
1：已离职（resign_time 为真实近日期）
work_status
类型：int，枚举。
观测：
当 leave_status = 0 时，work_status = 1
当 leave_status = 1 时，work_status = 2
推断含义：
1：在岗/可排班
2：离岗/停止安排（与离职状态挂钩）。
6. 账号启用、展示与在线状态字段
assistant_status
类型：int，枚举。
观测：
1 × 48
2 × 2
含义（推测）：账号启用状态：
1：启用
2：停用 / 冻结（这两条仍处于 leave_status = 0，说明未离职但账号被禁用）。
show_status
类型：int，枚举。
观测：全为 1。
含义（推测）：前台展示状态：
1：在助教选择界面展示。
其他值可能是不展示。
show_sort
类型：int
观测：多值，如 1, 3, 7, 9, 10, 11, 12, 16, 21, 25, 30, 36, 38, 39, 100 等。
含义：前台展示排序权重，值越小/越大对应不同的排序策略（当前看起来与 assistant_no 有一定对应关系）。
online_status
类型：int，枚举。
观测：全为 1。
含义（推测）：在线状态；当前门店所有助教账号均为在线状态。
is_delete
类型：int，枚举。
观测：全为 0。
含义：逻辑删除标记：
0：未删除
1：已逻辑删除（数据保留，前台不可见）。
7. 评价与投诉相关字段
criticism_status
类型：int，枚举。
观测：
1 × 49
2 × 1
含义（推测）：投诉/差评状态：
1：无投诉或正常
2：有投诉记录。
assistant_grade / sum_grade / get_grade_times
已在上文等级部分说明：
当前全部为 0，表示该门店尚未产生助教评价数据，但字段结构已经做好。
8. 时间元数据与最近服务记录
create_time
类型：string
含义：账号创建时间。
update_time
类型：string
含义：账号最近一次被修改的时间（例如修改等级、昵称等）。
start_time
类型：string
观测：多为整月开始，如 "2025-07-01 08:00:00", "2025-09-01 08:00:00" 等。
含义（推测）：当前配置生效的开始日期。
end_time
类型：string
观测：对应结束日期，如 "2025-08-01 08:00:00", "2025-10-01 08:00:00" 等。
含义：当前配置生效的结束日期（例如一个周期性的排班/合同周期）。
last_table_id
类型：int
观测：
大多为 0
少量为实际台桌 ID。
含义：该助教最近一次服务的球台 ID。
last_table_name
类型：string
观测：大多为 ''，少量为 "TV", "888" 等。
含义：最近服务球台名称（展示用）。
last_update_name
类型：string
观测：如 "助教管理员:黄月柳", "管理员：郑丽珊"。
含义：最近修改该账号配置的管理员名称。
order_trade_no
类型：int
观测：
绝大多数为 0
少量为非 0 的订单号。
含义（推测）：该助教最近一次关联的订单号，用于快速跳转或回溯最近服务行为。
9. 灯控、钉钉等系统集成相关字段
ding_talk_synced
类型：int，枚举。
观测：全为 1。
含义（从字段名推测）：是否已同步至钉钉：
1：已同步
其他值：未同步/错误等。
site_light_cfg_id
类型：int
观测：全为 0。
含义：门店灯控配置 ID，本门店未在助教账号维度启用。
light_equipment_id
类型：string
观测：全为 ''。
含义：灯控设备 ID，如果开启“助教开台自动控制灯”，会通过该字段关联到灯控硬件。
light_status
类型：int，枚举。
观测：全为 2。
含义（推测）：灯光控制状态，如 1=启用控制、2=不启用 或相反。
由于所有记录是同一个值，只能确认这是一个预留状态字段。
10. 其他标志字段
is_team_leader
类型：int，枚举。
观测：全为 0。
含义：是否为团队长/组长：
0：普通助教
1：团队长（当前门店未指定团队长）。
三、与其他 JSON 的字段级关联（从结构角度）
仍然只从“结构 / 关联键”角度说明，不做任何经营或盈利分析：
与《助教流水.json》的关联
助教流水.site_assistant_id ↔ 助教账号.id
助教流水.user_id ↔ 助教账号.user_id
助教流水.assistant_team_id ↔ 助教账号.team_id
助教流水.person_org_id ↔ 助教账号.person_org_id
助教流水.assistant_level ↔ 助教账号.level（以及 levelName）
助教流水.nickname ↔ 助教账号.nickname
说明：助教流水是事实表，这个文件是对应的助教维表。
与门店维度 / 其它业务表
所有表的 tenant_id、site_id 一致，说明这些记录全部属于同一商户、同一门店。
台费流水、销售记录、库存变化等表通过 site_id、shop_name 共享门店维。
与订单相关表（小票、结账）
此文件中的 order_trade_no 仅是“最近订单号”的影子值，真正的订单明细仍以订单表、小票详情中的 order_trade_no 和 orderSettleId 为主。
在“助教流水”中，order_trade_no、order_settle_id 与助教账号并无直接外键关系，而是通过“助教流水”这张桥接事实表关联起来。
与外部系统（钉钉 / 灯控）
ding_talk_synced / staff_profile_id / staff_id 等为与企业内部人事系统、钉钉等集成预留的字段。
site_light_cfg_id / light_equipment_id / light_status 为与灯控设备联动预留的字段，目前在该门店未实际启用。

444
docs/api-reference/endpoints/assistant_cancellation_records.md Normal file
View File

@@ -0,0 +1,444 @@
# 助教撤销记录（GetAbolitionAssistant）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `AssistantPerformance/GetAbolitionAssistant` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/AssistantPerformance/GetAbolitionAssistant` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `assistant_cancellation_records` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 13 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
| 2 | `createTime` | string | '2025-11-09 19:23:29' |
| 3 | `id` | int | 2957675849518789 |
| 4 | `siteId` | int | 2790685415443269 |
| 5 | `tableAreaId` | int | 2791963816579205 |
| 6 | `tableId` | int | 2793016660660357 |
| 7 | `tableArea` | string | 'C区' |
| 8 | `tableName` | string | 'C1' |
| 9 | `assistantOn` | string | '27' |
| 10 | `assistantName` | string | '泡芙' |
| 11 | `pdChargeMinutes` | int | 214 |
| 12 | `assistantAbolishAmount` | float | 5.83 |
| 13 | `trashReason` | string | '' |
## 详细字段分析
> 以下内容迁移自旧版 `assistant_cancellation_records-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
1. 门店相关字段
1.1 siteProfile
类型：对象（Object）
含义：门店信息快照。
结构：包含以下子字段（26 个左右）：
id：门店 ID（与其他 JSON 中的 site_id 一致）。
org_id：组织 ID（总部/品牌组织）。
shop_name：店名，如“朗朗桌球”。
avatar：门店头像图片 URL。
business_tel：门店电话。
full_address：详细地址。
address：简化地址描述。
longitude / latitude：经纬度。
tenant_site_region_id：区域行政编码。
tenant_id：租户 ID（品牌商户 ID）。
auto_light：是否自动控灯（0/1 枚举）。
attendance_distance：考勤打卡范围。
wifi_name / wifi_password：WiFi 账号和密码。
customer_service_qrcode / customer_service_wechat：客服二维码、微信号。
fixed_pay_qrCode：固定收款码。
prod_env：环境标记（测试/生产等）。
light_status / light_type / light_token：灯控相关配置。
site_type：门店类型枚举。
site_label：门店标签（如“A”）。
attendance_enabled：是否启用考勤（0/1）。
shop_status：门店状态（1=营业等）。
特点：
与其他 JSON 中的 siteProfile 完全同构，是冗余的门店信息快照。
真正的主键是 siteProfile.id，且与同记录的 siteId 一致。
1.2 siteId
类型：整数（long）
观测：所有记录均为同一值 2790685415443269。
含义：门店 ID，即该废除记录所在门店。
关联：
与 siteProfile.id 一致。
与其他 JSON 中所有 site_id 字段相同（同一门店的数据）。
2. 台桌维度字段
这几个字段描述废除发生在哪张桌、哪个区域。
2.1 tableId
类型：整数（long）
含义：球台/桌子的 ID。
关联：
对应 “台桌列表.json” 中的 id 字段。
用于定位具体哪一张台桌上发生了助教废除。
2.2 tableName
类型：字符串（string）
示例值：
"C1", "C2", "B9", "VIP1", "A4", "666", "董事办", "补时长5", "Ｍ1" 等。
含义：台桌名称/编号，供人阅读。
关系：
与台桌列表中的 table_name 或 table_no 文本一致。
作为冗余字段存在，即使不联表也能看出是哪个桌。
2.3 tableAreaId
类型：整数（long）
示例：2791963816579205 等。
含义：台桌所在区域 ID。
关联：
应对应“区域配置表”的主键（本次导出未包含该表）。
与其他 JSON 中出现的 tableAreaId（比如台费流水、助教流水里的区域字段）是一致的。
2.4 tableArea
类型：字符串（string）
示例值：
"C区", "B区", "A区", "VIP包厢", "K包", "补时长", "666"。
含义：台桌所属区域名称。
说明：
用于展示和报表分区。
与 tableAreaId 一起从“区域维表”中可以查出区域层级信息（本次数据未导出该表）。
3. 助教维度字段
反映是哪一个助教被废除。
3.1 assistantOn
类型：字符串（string）
观测值（本次 15 条记录中）：
'2', '4', '9', '16', '23', '27', '52', '15', '99'
含义：助教编号（工号/序号）。
说明：
虽然是字符串，但内容上是纯数字，实际是编号，不是业务金额。
与 助教流水.json 中的 assistantNo 字段是一致的。
与“助教账号1/2.json” 中的 assistant_no 字段相同，用于识别哪位助教。
枚举性质：
在当前门店范围内，assistantOn 实际上是枚举集合（有限个编号）。
具体编号-姓名的映射关系在“助教账号”表中定义，不在本文件中。
3.2 assistantName
类型：字符串（string）
观测值（本次 15 条中）：
'佳怡'、'璇子'、'周周'、'球球'、'泡芙'、'婉婉'、'小柔'、'七七'、'Amy'
含义：助教姓名/对外展示名称。
关系：
与“助教账号”档案中的 real_name / nickname 对应。
与 助教流水.json 里的 assistantName 字段一致。
注意：
这是被废除的那位助教，不是顾客姓名。
4. 时间与时长字段
4.1 createTime
类型：字符串（string），格式 YYYY-MM-DD HH:MM:SS
示例："2025-11-09 19:23:29"
含义：这条“助教废除记录”被创建的时间，即系统正式记录“废除”操作的时刻。
与其他时间字段关系：
在 助教流水.json 里有 create_time / ledger_start_time / ledger_end_time 等，本字段通常会落在这些时间点之后，表示在某次服务计时过程后发生了废除操作。
数据特征：
所有记录都有非空时间，精确到秒。
4.2 pdChargeMinutes
类型：整数（int）
示例值：214, 10800, 3602, 3600, 2379, 14400, 10605, 10608, 10611, 0 等。
含义（结构层面）：
“已发生的计费时长（分钟）”，即这次助教服务在被废除前已经累计了多少分钟。
特点：
单位是“分钟”，不是秒。
绝大部分是较大的整数（如 10800 分钟这样的数字，显然系统里有异常/默认值，具体业务含义要结合上下文看，这里只从字段命名和类型说明）。
也有 0 的情况，表示发生废除时尚未有有效计费时间产生（例如刚排钟就撤销）。
与其他字段的关系（结构层面推断，不做业务结论）：
这类字段很可能用于后续计算“应退时长”或“扣费时长”。
对应 助教流水 里关于 real_use_seconds、income_seconds 的记录，可用来判断“废除时已经消耗了多少时间”。
5. 金额字段
5.1 assistantAbolishAmount
类型：浮点数（float）
示例值：
5.83, 570.0, 108.06, 190.0, 71.37, 392.0, 465.44, 318.24, 318.33, 以及 0.0。
含义（结构层面）：
与“助教废除”关联的金额字段。字面上是“助教废除金额”。
可以理解为本次废除操作对应的一笔金额数值（是扣除、退还、补差，由业务规则决定，这里不做盈利/收益分析）。
特点：
为浮点数，单位为元。
存在 0 值，表示这条废除记录没有产生额外金额变动（纯记录操作）。
可能的用途（从字段角色角度，而不是结论）：
后续在账务模块中，可以用 assistantAbolishAmount 这类字段与其他表（如退款记录、余额变更记录）进行金额对账和逻辑匹配。
6. 废除原因字段
6.1 trashReason
类型：字符串（string）
当前数据观测：所有 15 条记录都是空字符串 ""。
含义：
用于记录“废除原因”的文本描述，例如“顾客临时有事取消”“录入错误”“更换助教”等。
特点：
可为空字符串，说明系统允许不填原因。
从结构上看，这是一个自由文本字段，不是枚举，不会做严格约束。
与其他字段的关系：
当配合 is_trash（在 助教流水.json 中）使用时，trashReason 可以为那条流水提供“为什么被废除”的说明。
本表专门记录“废除事件”的列表，因此 trashReason 是这张表记录的重要附加信息。
三、字段之间的结构关系与外部关联
虽然本文件字段不多，但从字段设计可以看出它在整个系统中的位置。这里只从“字段结构”和“关联键”的角度说明，不做业务/盈利分析。
1. 与门店表 / 全局维度的关系
siteId 与 siteProfile.id 一致，且与其他 JSON 中的 site_id 一致。
说明：这是典型的“门店维度外键 + 冗余快照”设计：
siteId 作为外键；
siteProfile 作为冗余快照，方便直接展示店名、地址等。
2. 与台桌列表（台桌列表.json）的关系
对应关系：
tableId ↔ 台桌列表中的 id
tableName ↔ 台桌列表中的 table_name / table_no
tableAreaId ↔ 台桌列表中的 area_id（通过区域表可以进一步找到区域名称）
tableArea ↔ 台桌列表中的 area_name
结论（结构层面）：
助教废除.json 中关于桌台的四个字段，是对“台桌维度”信息的引用 + 冗余快照。
当用 tableId 去联查台桌列表时，可以获取更多静态信息（如台费设置、是否可预约等），本文件只保留了最基础的桌号和区域。
3. 与助教档案 / 助教流水的关系
对助教的标识字段：
assistantOn ↔ 助教流水中的 assistantNo ↔ 助教账号中的 assistant_no
assistantName ↔ 助教流水中的 assistantName ↔ 助教账号中的姓名字段
结构上的含义：
助教废除.json 可以看作是“助教服务流水”的一个特殊子集：只记录被废除的部分。
在 助教流水.json 中，存在字段 is_trash、trash_reason 等，它们从主流水视角记录“此条流水已经被废除”这一状态。
在 助教废除.json 中，則以“废除事件”为主视角，列出每一次废除操作的明细（在哪张桌、哪个助教、多少分钟、金额多少）。
需要注意的结构事实：
助教废除.json 里 没有 订单号类字段（例如 order_trade_no、order_assistant_id），因此如果要从“废除事件”反查到具体哪一条助教流水，目前只能通过组合条件关联，例如：
相同门店 siteId；
相同助教 assistantOn + assistantName；
相同台桌 tableId / tableName；
相近时间（createTime 对应助教流水的 create_time/ledger_end_time 附近）。
这说明系统在设计时，把“废除事件”作为独立表存储，但没有在导出中包含可直接联表的订单 ID。结构上就导致“硬外键”缺失，只能做“软匹配”。
4. 与资金/账户类表的潜在关系（结构层面）
关键金额字段：
assistantAbolishAmount 是本表唯一金额字段。
结合字段命名和位置，可以推断结构关系：
如果废除操作产生金额变动（例如退还部分费用或扣除违约金），那么在：
退款记录.json 中可能有对应一笔退款记录；
余额变更记录.json 中可能有对应一条会员卡余额变动（若退到卡里）。
这些表中不会直接有 assistantAbolishAmount 字段，但会有金额字段 + 关联 ID，结构上可能通过金额和时间进行逻辑匹配。
需要强调：
这里只指出“这个字段在系统里承担的是一个‘金额变量’的角色”，不做盈利/损益层面的任何分析或结论。
四、本表本身暴露出的结构性线索
清晰的单一职责
助教废除.json 不包含订单号、支付信息、会员信息等字段，只保留：
门店/桌台维度；
助教维度；
时间、分钟数；
一个金额字段；
文本原因字段。
说明这个表的设计就是“专门记录助教废除事件”的事件表，倾向于作为运营日志或审计用途，而不是主结算表。
软外键的设计取向
没有 order_trade_no、order_settle_id 等硬外键字段。
需要通过“时间 + 助教 + 桌台”的组合条件与 助教流水、订单/结算 进行软关联。
在迁移或对接新系统时，如果希望建立强外键，建议在新结构中给废除表补充 order_assistant_id 或 order_trade_no 之类的字段，以便直接关联。
分钟与秒的混用
pdChargeMinutes 单位是“分钟”；
在 助教流水.json 中，同类字段如 income_seconds / real_use_seconds 是“秒”。
结构层面说明：系统在不同接口/表中用了不同的时间单位。
在做结构统一或数据建模时，最好统一为一个单位（全部转为秒或全部转为分钟），否则容易出现比较/汇总混乱。
废除原因文本未被使用但结构预留完备
当前 15 条记录中，trashReason 全部为空，说明实际运营中并没有强制填写原因。
但结构上预留了这个字段，将来如果要做“废除原因统计”或“内部稽核”，无需修改结构，只要要求前台填写即可。
数量很少但字段完整
当前总记录数只有 15 条，但已经有完整的门店、桌台、助教、时长、金额、原因字段。
说明设计不是临时补的，而是参照完整流水表（助教流水）设计的一张配套表，只是当前时间范围内“废除事件”确实不多。

852
docs/api-reference/endpoints/assistant_service_records.md Normal file
View File

@@ -0,0 +1,852 @@
# 助教服务流水（GetOrderAssistantDetails）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `AssistantPerformance/GetOrderAssistantDetails` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/AssistantPerformance/GetOrderAssistantDetails` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `assistant_service_records` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `siteId` | int | `2790685415443269` | 门店 ID |
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `IsConfirm` | int | `0` | 是否已确认（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 64 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `assistantNo` | string | '27' |
| 2 | `nickname` | string | '泡芙' |
| 3 | `levelName` | string | '初级' |
| 4 | `assistantName` | string | '何海婷' |
| 5 | `tableName` | string | 'S1' |
| 6 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
| 7 | `skillName` | string | '基础课' |
| 8 | `id` | int | 2957913441292165 |
| 9 | `order_trade_no` | int | 2957784612605829 |
| 10 | `site_id` | int | 2790685415443269 |
| 11 | `tenant_id` | int | 2790683160709957 |
| 12 | `operator_id` | int | 2790687322443013 |
| 13 | `operator_name` | string | '收银员:郑丽珊' |
| 14 | `order_settle_id` | int | 2957913171693253 |
| 15 | `ledger_name` | string | '27-泡芙' |
| 16 | `ledger_group_name` | string | '' |
| 17 | `ledger_unit_price` | float | 98.0 |
| 18 | `ledger_count` | int | 7592 |
| 19 | `ledger_amount` | float | 206.67 |
| 20 | `order_pay_id` | int | 0 |
| 21 | `create_time` | string | '2025-11-09 23:25:11' |
| 22 | `is_delete` | int | 0 |
| 23 | `assistant_team_id` | int | 2792011585884037 |
| 24 | `assistant_level` | int | 10 |
| 25 | `ledger_start_time` | string | '2025-11-09 21:18:18' |
| 26 | `ledger_end_time` | string | '2025-11-09 23:24:50' |
| 27 | `is_single_order` | int | 1 |
| 28 | `order_assistant_id` | int | 2957788717240005 |
| 29 | `site_assistant_id` | int | 2946266869435205 |
| 30 | `order_assistant_type` | int | 1 |
| 31 | `ledger_status` | int | 1 |
| 32 | `site_table_id` | int | 2793020259897413 |
| 33 | `projected_income` | float | 168.0 |
| 34 | `is_not_responding` | int | 0 |
| 35 | `income_seconds` | int | 7560 |
| 36 | `user_id` | int | 2946266868976453 |
| 37 | `trash_applicant_id` | int | 0 |
| 38 | `trash_applicant_name` | string | '' |
| 39 | `is_trash` | int | 0 |
| 40 | `trash_reason` | string | '' |
| 41 | `real_use_seconds` | int | 7592 |
| 42 | `add_clock` | int | 0 |
| 43 | `returns_clock` | int | 0 |
| 44 | `is_confirm` | int | 2 |
| 45 | `member_discount_amount` | float | 0.0 |
| 46 | `manual_discount_amount` | float | 0.0 |
| 47 | `service_money` | float | 0.0 |
| 48 | `person_org_id` | int | 2946266869336901 |
| 49 | `last_use_time` | string | '2025-11-09 23:24:50' |
| 50 | `salesman_name` | string | '' |
| 51 | `salesman_user_id` | int | 0 |
| 52 | `salesman_org_id` | int | 0 |
| 53 | `coupon_deduct_money` | float | 0.0 |
| 54 | `skill_id` | int | 2790683529513797 |
| 55 | `start_use_time` | string | '2025-11-09 21:18:18' |
| 56 | `tenant_member_id` | int | 0 |
| 57 | `system_member_id` | int | 0 |
| 58 | `skill_grade` | int | 0 |
| 59 | `service_grade` | int | 0 |
| 60 | `composite_grade` | float | 0.0 |
| 61 | `sum_grade` | float | 0.0 |
| 62 | `get_grade_times` | int | 0 |
| 63 | `grade_status` | int | 1 |
| 64 | `composite_grade_time` | string | '0001-01-01 00:00:00' |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `assistantTeamName` | string |
| `real_service_money` | float |
## 详细字段分析
> 以下内容迁移自旧版 `assistant_service_records-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
二、记录级字段完整清单与说明
下面按逻辑分组来讲字段。数据类型和枚举值，是根据导出数据实际值推断出来的。
1. 订单与关联 ID 类字段
这些字段主要用来跟其他表做关联（订单、支付、会员、助教档案等）：
id
类型：int
含义：本条助教流水记录的主键 ID（流水唯一标识）。
作用：在系统内部唯一定位这一条助教服务记录。
order_trade_no
类型：int
含义：订单交易号，整个订单层面的编号。
关联：
与台费流水、门店销售记录、团购套餐流水等表中的同名字段是一致的，用于把 同一笔订单下的各类消费明细（台费/商品/助教/套餐）串起来。
order_settle_id
类型：int
含义：订单结算 ID，相当于“结账单号”的内部主键。
关联：
与小票详情中的 orderSettleId 对应。
正常情况下也应对应结账记录表中的结算主键（本次导出结账记录为空，但字段设计明显就是用来关联的）。
order_assistant_id
类型：int
含义：订单中“助教项目明细”的内部 ID。
作用：如果订单里有多条助教项目（比如换助教、多个时间段），此字段唯一标识这一条助教明细。
order_assistant_type
类型：int，枚举。
观测值：1 和 2。
含义（推测）：
1：常规助教服务（主课/基础课）。
2：附加类助教服务（如“附加课”），和字段 skillName 的值相对应（本数据里，skillName 有 “基础课”和“附加课” 两类）。
实际含义以系统内部配置为准，但可以确定是 助教服务类型枚举。
order_pay_id
类型：int
含义：关联到“支付记录”的主键 ID。
作用：可以和支付记录中的 id / relate_id 等字段对应，找到这条助教服务对应的支付流水。
tenant_id
类型：int
含义：租户/品牌 ID；你这份数据中是固定值（同一个商户）。
关联：全库所有表都有，作为“商户维度”的过滤键。
site_id
类型：int
含义：门店 ID，本数据中指“朗朗桌球”这一家门店。
关联：
与其他所有 JSON 中的 site_id 一致，用于判断记录属于哪家门店。
与内嵌的 siteProfile.id 一致。
site_assistant_id
类型：int
含义：门店维度的助教 ID。
关联：
在 助教账号1/2.json 中，字段 id 就是这个 site_assistant_id。
即：助教流水.site_assistant_id = 助教账号.id → 这是助教档案的外键。
user_id
类型：int
含义：助教对应的“用户账号 ID”（系统级用户）。
关联：
在助教账号表中有同名字段 user_id，与这里完全一致。
一般是登录账号的主键，区别于 site_assistant_id（岗位/角色 ID）。
person_org_id
类型：int
含义：助教所属“人事组织/部门 ID”。
关联：
在助教账号表中同样存在 person_org_id 字段，值完全一致。
用来做人员组织维度的归属，如“朗朗桌球-助教部”。
assistant_team_id
类型：int
含义：助教所属团队 ID。
特点：当前数据中所有记录都是同一个 team_id。
关联：
在助教账号表中有 team_id 字段，对应相同值。
此字段常用于排班/团队统计。
tenant_member_id
类型：int
含义：商户维度会员 ID（门店/品牌内的会员主键）。
观测值：有不少为 0，表示非会员；非零时与会员档案中的 id 一致。
关联：
**会员档案（tenantMemberInfos）**中的 id = 此处的 tenant_member_id。
用来联表查出对应会员的基本资料。
system_member_id
类型：int
含义：系统级会员 ID（全集团统一 ID）。
观测：大部分非 0 记录，对应会员档案中的 system_member_id。
关联：
会员档案中的 system_member_id 字段。
说明：system_member_id 把一个会员在不同门店/不同卡种的账号串起来；tenant_member_id 则是本商户的那一条记录。
skill_id
类型：int
含义：助教服务“课程/技能”ID。
观测：当前数据中只有一个技能 ID（同一类“基础课/附加课”）。
关联：应对应某个“课程/技能配置表”的主键（你这次导出里没见那个表）。
2. 助教维度字段
这些字段描述“是哪位助教、什么级别、属于哪个组”等：
assistantNo
类型：string
含义：助教编号，例如 "27"。
关联：在助教账号表里也有 assistant_no 字段，对应工号/编号。
assistantName
类型：string
含义：助教姓名，如“何海婷”“胡敏”等。
备注：和助教账号档案里的 real_name 一致。
nickname
类型：string
含义：助教对外昵称，如“佳怡”“周周”“球球”等。
说明：从数据看，这个 nickname 是“助教昵称”，不是顾客昵称（容易混淆）。
关联：在很多小票、商品名里，会把 “编号-昵称” 组合使用（如 ledger_name = "2-佳怡"）。
assistant_level
类型：int，枚举。
观测值与 levelName 对应关系（从数据中直接推出来）：
8 → levelName = "助教管理"（管理角色）
10 → "初级"
20 → "中级"
30 → "高级"
说明：这是助教级别的数值编码，对应助教账号表中的 level 字段。
levelName
类型：string
含义：助教等级名称，与 assistant_level 一一对应（初级/中级/高级/助教管理）。
备注：属于展示用的冗余字段。
assistant_team_id
已在上一节说明（团队 ID）。
skillName
类型：string
观测值："基础课" 或 "附加课"。
含义：当前这条助教服务所对应的“课程/技能名称”。
当 order_assistant_type = 1 时，多为“基础课”。
当 order_assistant_type = 2 时，为“附加课”。
skill_grade
类型：int
观测：全为 0。
含义（推测）：顾客对“技能表现”的评分（整数或打分等级）。
当前数据中还未产生评分记录，所以都是默认值 0。
service_grade
类型：int
观测：全为 0。
含义（推测）：顾客对“服务态度”的评分。
composite_grade
类型：float
观测：全为 0.0。
含义：综合评分（例如技能+服务加权后的平均分），当前数据没有实际评分。
sum_grade
类型：float
观测：全为 0.0。
含义：累计评分总和（可能用于计算平均分），当前为 0。
get_grade_times
类型：int
观测：全为 0。
含义：该条记录对应的评价次数（或该助教被评价次数快照）。
grade_status
类型：int，枚举。
观测：全为 1。
含义（推测）：评价状态，比如：
1 = 未评价/正常；
其他值可能表示“已评价”“屏蔽”等，当前数据没有别的值，具体含义需要系统配置表。
composite_grade_time
类型：string（时间）
观测：全为 "0001-01-01 00:00:00"。
含义（推测）：最近一次评价时间/综合评分更新时间。现在都是默认“无效时间”。
3. 桌台 / 门店维度字段
tableName
类型：string
含义：助教服务所在的球台名称（如 "A17"、"S1"）。
关联：
与台桌列表中的 table_name / table_no 对应（通过 site_table_id）。
site_table_id
类型：int
含义：球台 ID。
关联：
对应台桌列表中的 id 字段，表示具体是哪一张桌。
siteProfile
类型：object
含义：门店信息快照，包括 id、shop_name、address 等，和其他 JSON 里的 siteProfile 一致。
作用：冗余门店信息，方便查看（而不是每次都联表看门店档案）。
4. 时间 / 时长相关字段
4.1 时间点（字符串时间）
create_time
类型：string，格式 YYYY-MM-DD HH:MM:SS
含义：这条助教流水记录创建时间（一般接近结算/下单时间）。
start_use_time
类型：string
含义：助教实际开始服务时间。
特点：正常情况下与 ledger_start_time 相同。
last_use_time
类型：string
含义：最后一次使用（实际服务）时间。
特点：正常结束时与 ledger_end_time 相同；如果服务还未真正开始或立即结束，开始/结束时间可能相同。
ledger_start_time
类型：string
含义：台账层面记录的开始时间。
说明：与 start_use_time 在当前数据中完全一致，可以视为“计费起始时间”。
ledger_end_time
类型：string
含义：台账层面的结束时间。
说明：与 last_use_time 一致，可以视为“计费结束时间”。对于 real_use_seconds = 0 的记录，开始和结束时间相同，说明只是预约/录入，并未实际服务。
4.2 时长（秒）
这几个字段单位都是“秒”。
income_seconds
类型：int
含义：计费秒数 / 应计收入对应的时间。
特点：
值基本是 60 的倍数（2700、3600、7200、10800 等），即按分钟整点计费的秒数。
用这个字段配合 ledger_unit_price 计算应计金额（原价或折扣价）。
real_use_seconds
类型：int
含义：实际使用时长（秒）。
特点：
大多数情况下，real_use_seconds ≈ ledger_count（有少量 ±1 秒差）。
对于还没真正消费的记录，该值为 0，表示“已预约/已排钟但还没消耗”。
ledger_count
类型：int
含义：台账记录的计时总秒数。
特点：
正常结束的记录中，与 real_use_seconds 基本一致。
可以理解为“本条助教服务真正消耗的总时长（秒）”。
add_clock
类型：int（秒）
观测值：多为 0，有少量为 240, 300, 420, 600, 900, 2400, 2700, 3600, 32400 等。
含义（推测）：加钟秒数，即在原有预约/服务基础上临时追加的时长。
说明：值均为 60 的倍数（分钟级加钟），如 600 秒=10 分钟。
returns_clock
类型：int（秒）
观测：全部为 0。
含义（推测）：退钟秒数（取消加钟或提前结束退回的时间）。
当前数据里没有退钟场景，所以全为 0，但字段设计已经预留。
5. 金额与折扣相关字段
ledger_unit_price
类型：float
含义：助教服务 标准单价（通常是标价：每小时、每节课的单价）。
特点：如 98.0、108.0、190.0 等。
ledger_amount
类型：float
含义：按标准单价计算出来的应收金额（近似 = ledger_unit_price × income_seconds / 3600）。
说明：从数据看，这个金额对应“按原价计费”的金额，未扣除各种优惠。
projected_income
类型：float
含义：实际结算计入门店的金额（已经考虑折扣、卡权益、券等后的结果）。
从数据：projected_income 明显低于 ledger_amount，说明中间有折扣，但折扣的明细并不全由下面几个字段体现（很多是卡权益内生折扣）。
coupon_deduct_money
类型：float
观测值：大多数为 0.0，有少量记录为 195.73、431.1 等。
含义：由“优惠券/代金券/团购券”等 直接抵扣到这条助教服务上的金额。
说明：
当 >0 时，表明这一条助教服务使用了券抵扣了这么多金额。
与平台验券记录 / 团购套餐流水中的券相关字段联动。
manual_discount_amount
类型：float
观测：全部为 0.0。
含义：收银员手动给予的减免金额（人工改价）。
当前导出时间段内暂未出现手动打折的情况。
member_discount_amount
类型：float
观测：全部为 0.0。
含义：由会员卡折扣产生的优惠金额。
说明：尽管字段里是 0，但实际折扣可能已经体现在 projected_income 与 ledger_amount 的差额中，这里只是未单独拆出。
service_money
类型：float
观测：全部为 0.0。
含义（推测）：用于记录与助教结算的金额（平台预留的“成本/分成”字段）。
当前数据中未启用这个机制，所以全为 0。
6. 状态 / 标志字段
ledger_status
类型：int，枚举。
观测：全部为 1。
含义（推测）：助教流水记录状态：
1：正常有效。
其他值（例如 0、2）可能对应“未结算”“已作废”等，当前数据未出现。
is_confirm
类型：int，枚举。
观测：全部为 2。
含义（推测）：确认状态，例如：
1：待确认；
2：已确认 / 已完成。
从全部为 2 推断：导出时选的是已经确认的流水。
is_single_order
类型：int，枚举。
观测：全部为 1。
含义（推测）：是否单独订单：
1：本助教服务作为单独订单结算（或单独拆项）。
0：与其他项目（台费、商品）一起打包在综合订单里。
当前门店显然采用“助教单独结算”的模式，故全为 1。
is_not_responding
类型：int，枚举。
观测：全为 0。
含义（推测）：是否存在“爽约/未响应”情况：
0：正常；
1：有爽约等异常情况。
当前时间段没有记录被标记为爽约。
is_trash
类型：int，枚举。
观测：全为 0。
含义：是否已废除/作废：
0：正常有效；
1：已废除（对应“助教废除.json”里的记录）。
一旦为 1，一般会配合 trash_reason 等字段，并在“助教废除”表中有对应记录。
is_delete
类型：int，枚举。
观测：全为 0。
含义：逻辑删除标志。
0：未删除；
1：已删除（逻辑删除，历史保留）。
和 is_trash 不同：is_trash 表示业务上的“废除”，is_delete 表示系统级删除。
7. 会员/顾客维度（在本表中的影子）
system_member_id / tenant_member_id
已在“关联 ID 类字段”里说明：
system_member_id 对应会员在整个系统的唯一 ID；
tenant_member_id 对应当前租户中的会员 ID（会员档案的主键 id）。
注意：这份助教流水里没有直接出现“顾客姓名”字段，只通过这两个 ID 与会员档案、储值卡等表关联。
8. 员工 / 销售人员相关字段
salesman_name
类型：string
含义：关联的“营业员/销售员姓名”，用于提成归属。
观测：本数据中多数为空字符串，说明助教流水没有配置单独的营业员。
salesman_user_id
类型：int
含义：营业员用户 ID。
观测：多为 0，代表未指定。
salesman_org_id
类型：int
含义：营业员所属组织/部门 ID。
观测：多为 0。
operator_id
类型：int
含义：操作员 ID（录入/结算这条助教服务的员工）。
关联：可与员工/账号表对应（本次导出未单独给员工表，但其他 JSON 里多处出现该 ID）。
operator_name
类型：string
含义：操作员姓名，与 operator_id 一起使用，便于直接阅读。
user_id
已在“关联 ID 类字段”说明：助教的系统用户 ID，与助教账号表中的 user_id 一致。
person_org_id
同样在上文说明：助教所属人事组织 ID。
9. 作废 / 废除相关字段
这几个字段在当前数据中值都为 0 或空串，但从命名可以看出专门用于记录“助教废除”的信息，与 助教废除.json 表配合使用。
trash_applicant_id
类型：int
含义：提出废除申请的员工 ID（通常是操作员/管理员）。
当前数据全为 0，因此短期内没有发生废除操作。
trash_applicant_name
类型：string
含义：废除申请人姓名。
trash_reason
类型：string
含义：废除原因（文本说明），例如“顾客取消”“录入错误”等。
当前数据为空字符串，说明当前导出时间段没有被废除的助教流水记录。
10. 其他字段
ledger_group_name
类型：string
观测：全部为空字符串。
含义（推测）：助教项目所属的“计费分组/套餐分组名称”，例如某种助教套餐或业务组名称。
目前未被实际使用。
三、助教流水与其它 JSON 的关键关系（从字段角度再强调一下）
虽然你这次提问重点是字段本身，但从字段设计可以看出它在整个系统里的“位置”，这里简要点一下（不做数值分析）：
与助教账号（助教账号1/2.json）
site_assistant_id ↔ 助教账号表的 id
user_id ↔ 助教账号表的 user_id
assistant_team_id ↔ 助教账号表的 team_id
person_org_id ↔ 助教账号表的 person_org_id
assistant_level ↔ 助教账号表的 level
说明：助教流水是“事实表”，助教账号是“维表”。
与会员档案（会员档案.json）
system_member_id ↔ 会员档案中的 system_member_id
tenant_member_id ↔ 会员档案中的 id
说明：通过这两个字段可以追溯到哪个会员预约/购买了这次助教服务。
与台桌（台桌列表.json）
site_table_id ↔ 台桌表中的 id
tableName ↔ 台桌表中的 table_name/table_no
说明：标记助教服务在哪张桌上进行。
与订单/小票（小票详情.json / 结账记录.json）
order_trade_no、order_settle_id 与其它消费明细（台费、商品、套餐流水）共享，构成一次订单下的不同子项目。
小票详情中的 orderSettleId 与这里的 order_settle_id 对应。
与支付/退款（支付记录.json / 退款记录.json）
order_pay_id 对应支付记录中的 ID 或 relate_id。
支付记录通过 relate_type 区分是订单支付还是其他业务（如充值）；这里的助教流水对应的是订单类支付。
与助教废除（助教废除.json）
当 is_trash = 1 时，对应的废除详情（原因、废除时间等）会记录在“助教废除.json”里。
字段 trash_reason、trash_applicant_id/name 就是废除信息在当前流水记录中的快照。

468
docs/api-reference/endpoints/goods_stock_movements.md Normal file
View File

@@ -0,0 +1,468 @@
# 库存出入库流水（QueryGoodsOutboundReceipt）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `GoodsStockManage/QueryGoodsOutboundReceipt` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/GoodsStockManage/QueryGoodsOutboundReceipt` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `goods_stock_movements` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `siteId` | int | `2790685415443269` | 门店 ID |
| `stockType` | int | `0` | 库存类型（0=全部） |
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 19 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `siteGoodsStockId` | int | 2957911857581957 |
| 2 | `siteGoodsId` | int | 2793026183532613 |
| 3 | `siteId` | int | 2790685415443269 |
| 4 | `tenantId` | int | 2790683160709957 |
| 5 | `stockType` | int | 1 |
| 6 | `goodsName` | string | '阿萨姆' |
| 7 | `createTime` | string | '2025-11-09 23:23:34' |
| 8 | `startNum` | int | 28 |
| 9 | `endNum` | int | 27 |
| 10 | `changeNum` | int | -1 |
| 11 | `unit` | string | '瓶' |
| 12 | `price` | float | 8.0 |
| 13 | `operatorName` | string | '收银员:郑丽珊' |
| 14 | `changeNumA` | int | 0 |
| 15 | `startNumA` | int | 0 |
| 16 | `endNumA` | int | 0 |
| 17 | `remark` | string | '' |
| 18 | `goodsCategoryId` | int | 2790683528350539 |
| 19 | `goodsSecondCategoryId` | int | 2790683528350540 |
## 详细字段分析
> 以下内容迁移自旧版 `goods_stock_movements-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
二、记录级字段逐一分析（共 19 个）
1. 商品与库存标识 / 关联类字段
siteGoodsStockId
类型：int
含义：门店某个“商品库存记录”的主键 ID。
特点：每条库存变动记录对应一个 siteGoodsStockId，同一个商品可能在不同库存记录中出现（例如不同仓位或不同批次）。
结构用途：
与“库存现状/库存汇总”类表（库存现状.json，文件名 20251110_043308_...）中的主键对应。
用于从“单条变动记录”追溯到该商品当前的整体库存信息。
siteGoodsId
类型：int
含义：门店维度的商品 ID。
特点：
同一种商品（例如“农夫山泉苏打水”）在所有库存变化记录中都会使用同一个 siteGoodsId。
对应商品档案中的主键（门店商品表），在“小票详情.json”和“库存现状.json”等文件中也出现。
结构关联：
库存变化记录.siteGoodsId = 库存现状.siteGoodsId
库存变化记录.siteGoodsId = 小票详情.siteGoodsId
通过此字段，可以把“库存变化”与“销售/出库明细”以及“当前库存”关联起来。
siteId
类型：int
含义：门店 ID。
观测：本文件中所有记录的 siteId 都相同，对应“朗朗桌球”这家门店。
结构作用：
和其他所有 JSON 中的 siteId 一致，用于在多门店场景下按门店过滤。
与 siteProfile.id（出现在其他文件中）一致。
tenantId
类型：int
含义：租户/品牌 ID。
观测：全部记录相同值，说明属于同一商户。
作用：作为上层品牌维度，与其他表（销售、库存、会员等）保持一致。
goodsCategoryId
类型：int
含义：商品一级分类 ID。
观测：当前 100 条样本中约有 5 个不同 ID，对应如“酒水类”“食品小吃类”“香烟类”等大类（仅从命名与商品名推断）。
结构关联：
在其他 JSON（如商品列表/库存现状）中也出现同名字段，作为商品分类维表的外键。
实际的分类名称不在本表体现，需要通过分类表或其他视图查询。
goodsSecondCategoryId
类型：int
含义：商品二级分类 ID。
观测：样本中约有 7 个不同 ID，如饮料中的“矿泉水/功能饮料/碳酸饮料”等。
结构作用：
与商品二级分类维表对应，进一步区分商品细类。
在库存现状或商品档案 JSON 中也出现，用于报表按分类汇总库存。
2. 商品基本信息字段
goodsName
类型：string
含义：商品名称。
示例值：
"农夫山泉苏打水"
"阿萨姆"
"哇哈哈矿泉水"
"鸡翅三个一份"
"普通扑克"
"软玉溪", "钻石荷花"（香烟）
特点：
对应门店商品表中的 goods_name，为当时的名称快照。
与 siteGoodsId 一一对应，但保留在变更记录中便于直接阅读，不用再去商品表查。
unit
类型：string，枚举。
观测值（本样本）：
"瓶"、"包"、"盒"、"根"、"个"、"桶"、"份".
含义：库存计量单位。
说明：库存数量（startNum、endNum、changeNum）均以这里的单位计数。
price
类型：float
含义：商品单价（单位金额）。
观测特征：
常见值：5.0、8.0、15.0、6.0、2.0、10.0、45.0 等。
对同一个 siteGoodsId，所有记录的 price 完全一致——说明这是该商品在门店的当前单价快照。
结构作用：
虽然库存变化记录中并未直接出现金额字段，但通过 price × changeNum 可以算出这次变动对应的金额（如果需要金额层面分析的话）。
在结构上，这是为后续报表（如按进销存金额统计）预留的关键字段。
3. 库存数量变动类字段
startNum
类型：int
含义：变动前（这次出入库之前）的库存数量。
示例：
如记录：startNum = 28, changeNum = -1, endNum = 27。
特点：样本中有 80+ 个不同值，覆盖几十到几百的库存数。
endNum
类型：int
含义：变动后（出入库之后）的库存数量。
结构关系：
全部记录满足：
endNum = startNum + changeNum
这一点在样本中经检验无一例外。
意义：确保库存变动画账逻辑正确，是库存平衡的核心约束。
changeNum
类型：int
含义：本次库存数量变化值。
特点及取值：
常见值：-1、-2、-3、-6、-12、-36 等负数，也有少量正数（如 1、2、12、36 等）。
数据验证：
当 changeNum < 0 时，startNum > endNum；
当 changeNum > 0 时，startNum < endNum。
结构逻辑：
在配合 stockType 使用时，正负号对应该变动是“出库还是入库”：
对 stockType = 1：全部都是负数，代表从库存中扣减（销售或其他出库）。
对 stockType = 4：全部是正数，代表库存增加（入库/调整）。
startNumA
类型：int
观测：所有记录为 0。
含义（推测）：辅助计量单位的起始库存（例如件/箱等第二单位）。
当前门店在样本时间段内没有启用多单位库存管理，因此全部为 0。
endNumA
类型：int
观测：全部为 0。
含义：辅助单位的变动后库存，同样未启用。
changeNumA
类型：int
观测：全部为 0。
含义：辅助单位的变化量（与 changeNum 对应的第二计量单位变化），当前未使用。
结论：
startNumA / endNumA / changeNumA 是为“一个商品有两种计量单位（如箱与瓶）”而设计的预留字段。
目前门店只在单一单位层面管理库存，故全部为 0。
4. 库存变动类型字段
stockType
类型：int，枚举。
观测值（本样本）：
1：89 条
4：11 条
与 changeNum 的联合特征：
(stockType=1, changeNum<0) 出现 89 次；
(stockType=4, changeNum>0) 出现 11 次；
不存在 stockType=1 且 changeNum>0 或 stockType=4 且 changeNum<0 的情况。
含义（基于数据行为推断）：
1：出库类变动
典型情况是销售出库，库存减少 1 或 2；例如顾客点了一瓶饮料，对应一条 stockType=1, changeNum=-1 的记录。
4：入库/盘盈/调整增加
举例：某条记录为 stockType=4, changeNum=2，startNum=13, endNum=15，说明库存被人工或系统增加了 2。
结构意义：
用 stockType 区分变动原因大类（销售/退货/盘点/报损等），再由 changeNum 的正负体现增减。
当前样本里只出现了两个枚举值，但从命名推测，系统中还可能存在其它类型（例如报损出库、盘亏减少等），只是这段时间内未发生。
5. 操作与时间字段
createTime
类型：string，格式 YYYY-MM-DD HH:MM:SS
含义：这条库存变动记录的创建时间，即发生库存变更的时间点。
特点：
样本覆盖 2025-11-09 晚上一段时间，且有多条记录在同一秒内（同桌多商品一起销售时）。
是库存流水的时间轴关键字段，可与小票时间、台费时间等交叉校验。
operatorName
类型：string
含义：执行此次库存变动的操作人。
观测值：
"收银员:郑丽珊"：99 条
"系统"：1 条
说明：
大部分库存变化由前台收银员操作（录入销售单、小票）触发。
个别记录由系统自动生成（如自动盘点调整、系统修正等），操作人显示为“系统”。
6. 备注字段
remark
类型：string
观测：全部为空字符串 ""。
含义：备注信息，用于手工记录本次变更的特殊原因说明（例如“盘点差异调整”“报损”）。
当前样本中没有填入任何备注，但字段已预留，适用于盘点或手工调整场景。
三、与其他 JSON 的结构关联关系（从字段角度）
仅从字段命名和你这批文件中出现的位置来看，“库存变化记录1.json”在整体系统中的结构位置大致如下：
与商品档案 / 库存现状
siteGoodsId：
在 库存现状.json（20251110_043308_...）中同名出现，对应门店商品库存汇总表。
在“小票详情.json”（20251110_035904_...）中也有 siteGoodsId，用于标记每条销售明细对应的商品。
siteGoodsStockId：
是具体库存记录主键，与库存现状中的记录一一对应。
goodsCategoryId / goodsSecondCategoryId：
在商品定义/库存现状 JSON 中同样出现，对应商品分类维表。
结构链路可以概括为：
商品档案/库存现状（siteGoodsId, goodsCategoryId...）
↕
库存变化记录（siteGoodsId, siteGoodsStockId, changeNum...）
↕
小票详情/销售明细（siteGoodsId, 数量）
与门店维度
tenantId / siteId：
与所有业务 JSON 中的同名字段一致，表示这条库存变动属于哪一个品牌、哪一家门店。
对你这批数据来说，这两个字段在所有文件中取值固定，都是“非球科技 · 某门店（朗朗桌球）”。
与操作员/员工信息
operatorName：
以字符串形式记录操作员，“收银员:郑丽珊”与其他 JSON 中的操作员信息（如结账记录、小票记录中的 operator_name）一致。
虽然本表中没有 operatorId，但其他表（如结账记录）有时会记录 ID；可通过姓名+门店，在员工档案或账号表中匹配。
与销售/出库行为
当 stockType = 1, changeNum < 0 时，明显是销售导致的库存减少。
对应的小票/销售明细也会有同一时间点的消费记录（通过 createTime、siteGoodsId、商品名 等组合可以对齐）。
对“盘点增加/入库类”的记录（stockType = 4, changeNum > 0），则可能与采购入库或盘盈记录关联到其他表。
四、结构层面的重要线索（不涉及金额/盈利分析）
从字段设计和样本值可以看出，这个“库存变化记录”表在系统结构上有一些关键特征：
库存平衡公式显式存在
所有记录满足：
endNum = startNum + changeNum。
这意味着系统把每一次增减记录为一条流水，而不是只记录最后库存量。
通过把所有变动记录按时间排序叠加，可以完全重放库存数变化过程。
统一支持双计量单位但本门店未启用
startNumA / endNumA / changeNumA 全为 0，说明目前只使用主单位（瓶/包/盒等）。
但字段已经为“箱/瓶”这种双单位场景预留了结构，可以在未来随时启用。
库存变动类型（stockType）与变化方向强绑定
样本中，stockType=1 永远对应负数 changeNum，stockType=4 永远对应正数。
说明系统在设计时，不是单纯依赖 changeNum 的正负来判断业务含义，而是：
用 stockType 表示业务场景（销售出库/盘点/入库等），
用 changeNum 的正负表达实际的增或减。
其它可能的 stockType（如报损出库/盘亏/退货等）本批样本中未出现，但结构已经预留可扩展。
价格在本表中是“静态快照”，而不是动态计算字段
对同一个 siteGoodsId，所有记录的 price 一致，表明：
price 是当时商品价格的快照副本。
真实的“标准价/进价/零售价”仍以商品档案为准，只是在库存变动记录中复制一份方便报表使用。
这一设计避免了之后价格调整导致历史库存记录无法按当时价格还原的问题。
操作员信息体现“人工 vs 系统”两类来源
大部分记录由“收银员”操作，说明库存减少主要来自前台销售。
个别记录由“系统”操作，说明系统本身会根据某些规则自动生成库存变动记录（例如盘点差异自动入库/出库、库存初始化等）。
结构上不需要额外字段即可从 operatorName 粗略判断记录来源。
与商品分类强绑定，方便结构化报表
通过 goodsCategoryId / goodsSecondCategoryId，这张库存变动明细表可以非常方便地按“饮料/香烟/小食”等分类对库存变动进行结构化分析。
虽然你不希望做“大数据/盈利分析”，但从结构角度看，这两个字段是后续任意统计的关键维度。

547
docs/api-reference/endpoints/goods_stock_summary.md Normal file
View File

@@ -0,0 +1,547 @@
# 库存汇总报表（GetGoodsStockReport）
> 自动生成于 2026-02-13 | 数据来源：实时 API
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/GetGoodsStockReport` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/TenantGoods/GetGoodsStockReport` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `goods_stock_summary` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `siteId` | int | `2790685415443269` | 门店 ID |
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 14 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `siteGoodsId` | int | 3089190204491141 |
| 2 | `goodsName` | string | '小合味道' |
| 3 | `goodsUnit` | string | '桶' |
| 4 | `goodsCategoryId` | int | 2791941988405125 |
| 5 | `goodsCategorySecondId` | int | 2793236829620037 |
| 6 | `rangeStartStock` | int | 0 |
| 7 | `rangeEndStock` | int | 22 |
| 8 | `rangeIn` | int | 24 |
| 9 | `rangeOut` | int | -2 |
| 10 | `rangeInventory` | int | 0 |
| 11 | `rangeSale` | int | 2 |
| 12 | `rangeSaleMoney` | float | 16.0 |
| 13 | `currentStock` | int | 22 |
| 14 | `categoryName` | string | '零食' |
## 详细字段分析
> 以下内容迁移自旧版 `goods_stock_summary-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
每个元素就是某个 门店商品（siteGoodsId）在一个查询时间区间内的库存汇总。
二、字段分组说明（含类型 / 是否枚举 / 枚举值）
1. 商品主键与基本信息
1.1 siteGoodsId
类型：int
特征：
161 条记录中 161 个唯一值。
与 “门店商品档案” (20251110_051132_…1.json) 中 orderGoodsList 里的 id 完全一一对应。
含义：
门店商品 ID，本库存汇总表的主键，对应某个具体商品在本店的唯一标识。
关联：
库存汇总.siteGoodsId = 门店商品档案.id
也与库存变动记录（库存变化记录1）里的 siteGoodsId 对应（库存流水的外键）。
1.2 goodsName
类型：string
特征：
每条记录一个商品名，共 161 个不同值（与 siteGoodsId 一一对应）。
例："东方树叶", "红烧牛肉面", "薯片" 等。
含义：
商品名称，冗余于门店商品档案的 goods_name。
结构意义：
方便直接阅读汇总报表，无需再次联表取商品档案。
1.3 goodsUnit
类型：string
特征：
典型取值（枚举）：
"包"：59 条
"瓶"：46 条
"个"：17 条
"份"：13 条
"根"：10 条
"盒", "杯", "桶", "盘", "支" 等
与门店商品档案中的 unit 字段完全一致。
含义：
商品的计量单位（售卖单位）。
小结：siteGoodsId + goodsName + goodsUnit 在结构上确定一条“门店商品”的维度信息，和“门店商品档案”的字段是完全对齐的。
2. 分类维度字段
2.1 goodsCategoryId
类型：int
特征：
非空，161 条记录中有 9 个不同的 ID。
每一个 goodsCategoryId 对应 唯一一个 categoryName（一对一）。
含义：
一级商品分类 ID。
枚举映射（由数据直接推得）：
2791941988405125 → "零食"
2790683528350539 → "酒水"
2792062778003333 → "香烟"
2793217944864581 → "其他"
2791942087561093 → "雪糕"
2790683528350535 → "器材"
2793220945250117 → "小吃"
2790683528350533 → "槟榔"
2790683528350545 → "果盘"
（ID 是系统内部编码，你这边可以当“分类主键”。）
2.2 goodsCategorySecondId
类型：int
特征：
非空，有 14 个不同的 ID。
每个二级 ID 对应一个更细的类目（比如不同品牌/系列），但名称在本文件中没有给出。
含义：
二级（次级）商品分类 ID，是 goodsCategoryId 的下级分类。
关联：
在库存变动类 JSON / 商品分类 JSON（之前看到的分类导出）中，有完整的分类树，可通过这些 ID 找回二级分类名称。
2.3 categoryName
类型：string
特征：
枚举值恰好 9 个，分别是：
"零食", "酒水", "香烟", "其他", "雪糕", "器材", "小吃", "槟榔", "果盘"
与 goodsCategoryId 一一对应。
含义：
一级分类名称，属于冗余字段，用于直接展示。
结构结论：
分类主键：goodsCategoryId（一级）＋ goodsCategorySecondId（二级）
分类名称：categoryName 仅给了一级中文名，二级名需要到分类表/门店商品档案中再查。
3. 库存数量相关字段（全部为整数）
3.1 rangeStartStock
类型：int
特征：
非空，有 61 个不同数值。
示例值：0, 1, 2, 4, 7, 8, 29 ...
含义：
查询区间 起始时刻 的库存数量（期初库存）。
结构作用：
与下方各类“变动量”一起构成库存平衡公式。
3.2 rangeEndStock
类型：int
特征：
非空，有 61 个不同数值。
示例值： 0, 1, 5, 7, 8, 16 ...
含义：
查询区间 结束时刻 的库存数量（期末库存）。
3.3 rangeIn
类型：int
特征：
非空，多为正整数或 0。
示例值：0, 30, 90, 450 ...
含义：
查询区间内的 入库数量汇总（正值），包括采购入库、调拨入库等。
3.4 rangeOut
类型：int
特征：
有 64 个不同值，且全部为 0 或负数：
0（36次）、-1、-2、-3、-4、-7、-8、-14、-35 ……
含义：
查询区间内的 出库数量汇总，以 负数 表示从库存扣减（出库/销售）。
结构公式验证（关键）：
对每一条记录，都满足：
rangeStartStock + rangeIn + rangeInventory + rangeOut = rangeEndStock
即：期初 + 入库 + 盘点调整 + 出库 = 期末
当前数据中 rangeInventory 全为 0，那么简化为：
rangeStartStock + rangeIn + rangeOut = rangeEndStock。
3.5 rangeInventory
类型：int
特征：
所有 161 条记录均为 0。
含义：
查询区间内的 盘点调整净变动量（盘盈–盘亏）。
当前数据状态：
这段时间内没有发生盘点或盘点对库存无净影响，所以全为 0。
结构意义：
在有盘点的场景，这个字段会承担“非正常出入库”的调整职责，并参与上面的平衡公式。
3.6 currentStock
类型：int
特征：
非空，61 个不同值。
示例值：0, 1, 2, 3, 4, 5, 6, 7, 10, 14 ...
大部分记录里，currentStock 与 rangeEndStock 相等；但有 17 条 存在差异（通常是小差值，例如 rangeEndStock=74, currentStock=72）。
含义（推断）：
导出时刻的实时库存数量。
与 rangeEndStock 关系：
rangeEndStock 是“查询时间段结束瞬间”的库存；
currentStock 是“导出时当前瞬间”的库存。
这说明：在查询区间之后，可能又发生了一些出入库，导致当前库存与期末库存略有差异。
结构小结：
(rangeStartStock, rangeIn, rangeOut, rangeInventory, rangeEndStock) 构成一个严格的库存平衡关系。
currentStock 则是另一个时间点的库存快照，在结构上属于“附加状态字段”，不参与那个公式。
4. 销量与销售金额（汇总）
4.1 rangeSale
类型：int
特征：
非空，有 65 个不同的整数。
示例：0, 1, 2, 3, 4, 5, 6, 8, 13, 14 ...
含义：
查询区间内，该商品的 销售数量汇总（售出多少“包/瓶/份”等）。
与 rangeOut 的关系（结构上）：
对绝大多数以“销售出库”为主的商品，rangeOut 的绝对值与 rangeSale 大致一致（也可能有非销售出库，比如报损/调拨），这一点需要结合库存变动明细来判断，但属于业务层逻辑，这里不展开。
4.2 rangeSaleMoney
类型：float
特征：
非空，有 102 个不同的浮点值。
示例：0.0, 48.0, 30.0, 40.0, 280.0, 60.0, 50.0, 15.0 ...
很多数值看起来是整数金额，但用 float 存储，为以后兼容小数价格预留空间。
含义：
查询区间内，该商品销售的 金额小计（按商品维度汇总）。
结构特征（不做业绩解读，只谈结构）：
对于有销量的记录，可以通过简单比例验证：
单品成交单价 ≈ rangeSaleMoney / rangeSale
如某商品记录：
rangeSale = 62
rangeSaleMoney = 744.0
求比值 ≈ 12.0 → 对应门店商品档案中的 sale_price。
也就是说：在结构上，rangeSaleMoney 与 “汇总数量 × 单价” 对应关系非常一致，说明这个字段确实是商品维度的销售金额汇总。
这里我仅确认字段之间的 计量逻辑与结构关系，不做任何“好/坏”的业务评价。
三、与其它 JSON 的关联关系（结构层面）
1. 与“门店商品档案” JSON 的关系
通过实际比对：
库存汇总.siteGoodsId = 门店商品档案.orderGoodsList.id
库存汇总.goodsName = 门店商品档案.goods_name
库存汇总.goodsUnit = 门店商品档案.unit
库存汇总.goodsCategoryId = 门店商品档案.goods_category_id
库存汇总.goodsCategorySecondId = 门店商品档案.goods_second_category_id
结构含义：
门店商品档案：静态维度表，包含商品的售价、成本、是否计库存、分类名称等。
库存汇总：针对同一批 id 做的“某一时间范围内的库存+销量汇总”。
因此，你可以把“库存汇总”看成是对“门店商品档案”的一个衍生事实表，按照商品维度聚合库存与销售信息。
2. 与“库存变化记录”（库存流水）的关系
虽然你这份导出里“库存变化记录”在另外一个 JSON 中（字段里有 siteGoodsId、stockType 等），但从字段名和使用方式可以推断：
库存变化记录：
粒度：一条库存变动（一笔入库/出库/盘点等）。
重要字段：
siteGoodsId：对应库存汇总中的 siteGoodsId。
stockType：入库、出库、盘点等类型枚举。
changeNum：每次变动数量。
库存汇总：
粒度：某商品在查询区间内的汇总。
字段：rangeIn, rangeOut, rangeInventory 等就是对库存变化记录按 siteGoodsId + 时间区间 汇总出来的结果。
结构关系可以概括为：
库存变化记录（明细表）
↓ 按 siteGoodsId + 时间范围聚合
库存汇总（汇总表）
这使得你在需要追查明细时，可以从“汇总 → 明细”下钻。
3. 与“门店销售记录”的关系
从字段设计看：
门店销售记录中有：
site_goods_id：门店商品 ID
ledger_amount：单条销售明细金额
ledger_count：销售数量
库存汇总中有：
siteGoodsId：门店商品 ID
rangeSale：总销售数量（在时间范围内）
rangeSaleMoney：总销售金额（在时间范围内）
结构上可以理解为：
门店销售记录 是 每一个销售明细；
库存汇总 是在某时间段对这些明细按商品维度做的 汇总。
两者之间通过 siteGoodsId/site_goods_id 联接，同时需要根据时间条件约束订单时间，这一点在结构上是清晰的。
4. 与商品分类树（库存变化记录2 / 分类 JSON）的关系
在之前分类 JSON 中，你有一个分类树结构（有 id, pid, category_name, categoryBoxes 等）：
库存汇总.goodsCategoryId 对应 分类树中的某个一级分类 id。
库存汇总.goodsCategorySecondId 对应其子分类（分类树中某个 pid=一级分类id 的节点）。
categoryName 与分类树中的 category_name 对应（一级节点）。
结构关系：
分类树 JSON （全局分类维表）
↑ ↑
goodsCategoryId goodsCategorySecondId
↑ ↑
库存汇总 （事实表）
四、结构层面可以注意的一些“关系和约束”
全部是字段设计/数值关系层面，不涉及盈利或经营分析：
库存平衡公式存在且逐条成立
对每一条记录，都可以验证：
rangeStartStock + rangeIn + rangeInventory + rangeOut = rangeEndStock
当前导出中 rangeInventory = 0，所以简化公式为：
rangeStartStock + rangeIn + rangeOut = rangeEndStock
严格成立说明：
系统在生成库存汇总时，确实是从明细出入库数据做了完整计算，而不是凭输入数据临时凑数。
出库量采用“负数”表示
rangeOut 不再定义为“出库数量（正数）”，而是直接记 负数。
好处是：公式中无需写“–出库量”，直接做代数求和。
这个习惯在后续做数据集成或迁移时需要注意，避免重复取绝对值/重复取负。
区分“期末库存”与“当前库存”两个时间点
rangeEndStock：查询时间段的期末库存。
currentStock：导出那一刻的库存快照。
二者不一定相等（有部分记录存在差 1–4 的差值），说明结构上清晰区分了查询区间和当前状态。
汇总粒度清晰：每个 siteGoodsId 仅一条记录
siteGoodsId 在本文件中不重复，说明这是按商品聚合后的汇总层，没有再分仓库、批次、货位等维度。
如果未来需要按仓/货位维度汇总，结构可能会出现类似 warehouseId 之类的新字段，从这份数据来看目前没有。
金额与数量之间存在一致的单价模式
对于 rangeSale > 0 的商品，rangeSaleMoney / rangeSale 与门店商品档案中的 sale_price 一致，这只是结构上的一致性检查：
说明 rangeSaleMoney 并不是某种复杂的计算结果，而是“销售数量 × 单价”的汇总。
这在系统设计上有利于做“金额与数量对账”。
分类 ID 与中文名称一一对应
goodsCategoryId 和 categoryName 的关系是一对一，没有出现“同一 categoryName 对应多 ID”的情况。
这说明在该门店中，一级分类的结构比较干净，没有重复创建多个 ID 对应相同名称的情况；对你的后续系统对接来说，这一层结构相对简单，只需要维护一套映射即可。
五、小结
20251110_043308_库存汇总.json 本质上是：
以 门店商品（siteGoodsId） 为粒度，
在某个查询时间范围内，对该商品的：
期初库存（rangeStartStock）
入库量（rangeIn）
出库量（rangeOut，负数）
盘点调整（rangeInventory）
期末库存（rangeEndStock）
销售数量（rangeSale）
销售金额（rangeSaleMoney）
做了一次结构化汇总；
同时给出了当前时点库存快照（currentStock），并冗余了商品名、单位、一级分类名等维度信息。
在全局数据模型里，它与 门店商品档案 / 库存变动明细 / 门店销售明细 / 分类树 等文件通过主键（siteGoodsId、分类 ID）和时间条件构成一套“明细–汇总–维度”相互嵌套的结构，这对于后续做数据迁移、数据仓库建模或者跨系统字段映射都比较有价值。

731
docs/api-reference/endpoints/group_buy_packages.md Normal file
View File

@@ -0,0 +1,731 @@
# 团购套餐定义（QueryPackageCouponList）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `PackageCoupon/QueryPackageCouponList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/PackageCoupon/QueryPackageCouponList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `group_buy_packages` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要 |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `areaId` | array | `[]` | 区域 ID 列表（空=全部） |
| `commonShowStatus` | int | `1` | 展示状态（1=展示中） |
| `offlineCouponChannel` | int | `0` | 线下券渠道（0=全部） |
| `systemGroupType` | int | `1` | 系统分组类型（1=默认） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 35 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `site_name` | string | '朗朗桌球' |
| 2 | `effective_status` | int | 1 |
| 3 | `id` | int | 2939215004469573 |
| 4 | `site_id` | int | 2790685415443269 |
| 5 | `tenant_id` | int | 2790683160709957 |
| 6 | `package_name` | string | '早场特惠一小时' |
| 7 | `table_area_id` | string | '0' |
| 8 | `table_area_name` | string | 'A区' |
| 9 | `selling_price` | float | 0.0 |
| 10 | `duration` | int | 3600 |
| 11 | `start_time` | string | '2025-10-27 00:00:00' |
| 12 | `end_time` | string | '2026-10-28 00:00:00' |
| 13 | `is_enabled` | int | 1 |
| 14 | `is_delete` | int | 0 |
| 15 | `type` | int | 2 |
| 16 | `package_id` | int | 1814707240811572 |
| 17 | `usable_count` | int | 9999999 |
| 18 | `create_time` | string | '2025-10-27 18:24:09' |
| 19 | `creator_name` | string | '店长:郑丽珊' |
| 20 | `tenant_table_area_id` | string | '0' |
| 21 | `table_area_id_list` | string | '' |
| 22 | `tenant_table_area_id_list` | string | '2791960001957765' |
| 23 | `start_clock` | string | '00:00:00' |
| 24 | `end_clock` | string | '1.00:00:00' |
| 25 | `add_start_clock` | string | '00:00:00' |
| 26 | `add_end_clock` | string | '1.00:00:00' |
| 27 | `date_info` | string | '' |
| 28 | `date_type` | int | 1 |
| 29 | `group_type` | int | 1 |
| 30 | `usable_range` | string | '' |
| 31 | `coupon_money` | float | 0.0 |
| 32 | `area_tag_type` | int | 1 |
| 33 | `system_group_type` | int | 1 |
| 34 | `max_selectable_categories` | int | 0 |
| 35 | `card_type_ids` | string | '0' |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `is_first_limit` | int |
| `sort` | int |
| `tableAreaNameList` | array |
| `tenantCouponSaleOrderItemId` | int |
| `tenantTableAreaIdList` | array |
## 详细字段分析
> 以下内容迁移自旧版 `group_buy_packages-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
一、文件整体内容与结构
内容类型：
该文件记录的是 “团购套餐定义列表”，即门店可用的各类团购套餐（早场一小时、斯诺克两小时、KTV 四小时等）的配置。
每一条记录对应一种团购套餐的“规则定义”，包括：
套餐名称；
面值（coupon_money）；
有效起止日期；
每日可用时间段；
限定台区；
状态（上架/下架/是否过期）等
二、记录级字段完整说明
下面对 packageCouponList 中每条记录的 35 个字段逐一说明，按业务逻辑分组。
1. 基本信息与主键类字段
id
类型：int
含义：门店侧套餐 ID，本文件内部的主键。
特点：17 条记录中均为不同的大整数 ID。
关联（结构推断）：
平台验券记录表中常见 group_package_id 字段，通常会指向这里的 id，即：平台券核销记录指向哪一个团购套餐配置。
tenant_id
类型：int
含义：租户 ID（品牌/商户 ID）。
特点：全表值相同，说明所有套餐定义属于同一商户（同一品牌）。
site_id
类型：int
含义：门店 ID。
特点：全表值相同，且与其他 JSON 文件中的 site_id 一致，对应“朗朗桌球”这家门店。
site_name
类型：string
含义：门店名称。
观测值：全部为 "朗朗桌球"。
说明：这是对 site_id 的冗余，可直接展示门店名称。
package_id
类型：int
含义：“上层套餐 ID” 或“总部/系统级套餐 ID”。
特点：
多个 id 不同的记录可能共享同一个 package_id，表示同一种业务套餐在不同门店或不同版本下的本地配置。
在本门店数据里，package_id 和 id 不是一一对应的，有复用情况。
package_name
类型：string
含义：团购套餐名称，用于前台展示和核销界面。
示例：
"早场特惠一小时"
"B区桌球一小时"
"午夜一小时"
"中八、斯诺克包厢两小时"
"助理教练竞技教学两小时"
"KTV欢唱四小时"
"麻将 、掼蛋包厢四小时"
说明：可以从名称直观看出这是台费类、包厢类、助教教学类、KTV 类等不同套餐。
creator_name
类型：string
含义：创建人信息，一般包含“角色：姓名”。
示例："管理员：郑丽珊"
说明：用于追溯是谁在后台创建了该团购套餐，方便权限追踪。
create_time
类型：string，格式 YYYY-MM-DD HH:MM:SS
含义：该套餐在系统中创建的时间。
特点：每条记录各不相同，覆盖了 2025-07 至 2025-10 的创建时间。
2. 金额与价值字段
selling_price
类型：float
观测值：所有记录均为 0.0。
含义（结合字段命名）：
语义上应该是“团购售卖价”（顾客在平台购买券时的成交价格）。
本门店这份导出中全部为 0，说明：
要么平台实际售卖价保存在别的表/平台侧，并未在本地落地；
要么这个字段在当前版本中未被使用。
结构结论：这是一个预留的价格字段，但当前数据源没有真实值。
coupon_money
类型：float
含义：券面值或内部结算面值，表示该套餐在门店侧对应的金额额度。
示例（对应套餐名称）：
早场特惠一小时 → coupon_money = 40.0
全天A区中八一小时 → 80.0
KTV欢唱四小时 → 200.0
麻将 、掼蛋包厢四小时 → 160.0
使用方式（结构层面）：
当平台验券或套餐流水使用该套餐时，会根据这个金额执行抵扣记账，即“本券在店内能抵扣多少金额”。
usable_count
类型：int
观测值：所有记录均为 9999999。
含义：可使用次数上限。
数据特征说明：
9999999 典型用法是当作“无限次”的哨兵值。
即当前所有套餐在配置上不限制使用次数（只受时间、日期等条件限制）。
3. 有效期与日期限制相关字段
start_time
类型：string，格式 YYYY-MM-DD HH:MM:SS
含义：套餐开始生效的日期时间。
示例："2025-07-20 00:00:00" 等。
说明：一般是某天的 00:00:00，表示从该日开始可以使用此套餐。
end_time
类型：string，格式同上。
含义：套餐失效的日期时间（到这个时间点后不可使用）。
示例：形如 "2025-11-30 23:59:59"，部分记录使用 9999-12-31 23:59:59 风格的极大日期表示长期有效（本数据中如有这种值，可解读为“长期有效”）。
date_type
类型：int，枚举。
观测值：全部为 1。
含义（推测）：
典型用法：区分“全部日期可用 / 工作日 / 周末 / 指定日期”等。
当前数据全部为 1，可能表示“通用（每天都可以使用）”。
结构上：这是一个日期限制类型枚举字段，但本门店所有套餐统一设置为同一类型。
usable_range
类型：string
观测值：全部为空字符串 ""。
含义（推测）：
一般用于文字描述可用日期范围（例如“周一至周五”）。
当前全部为空，说明没有填写文字说明，只依赖 date_type 或其他逻辑限制。
date_info
类型：string
观测值：绝大多数为 ""，只有一条为 "0"。
含义（推测）：
预留字段，通常用来存储更细粒度的日期信息，如具体日期列表、节假日特殊规则（可能是 JSON 字符串或编码）。
当前几乎空置，说明本门店在团购套餐上并未配置复杂日期规则。
结构意义：这是将来可以支持“指定日期才能使用”的扩展字段。
4. 每日时段限制相关字段
这几个字段控制“每天什么时间段可以使用该套餐”。
start_clock
类型：string
观测值示例：
"10:00:00"
"00:00:00"
含义：每日可用起始时间点（第一段）。
说明：配合 end_clock 使用，定义一个日内时段。
end_clock
类型：string
观测值示例：
"18:00:00"
"23:59:00"
"23:59:59"
含义：每日可用的结束时间点（第一段）。
结构说明：
与 start_clock 一起构成 [start_clock, end_clock] 这段时间内可以核销使用该券。
add_start_clock
类型：string
观测值：
"00:00:00"（15条）
"10:00:00"（2条）
含义（推测）：附加可用时间段的起始时间（第二段）。
例如有的套餐可以在两个不连续的时段使用：早场 + 夜场，则可用第一段 start_clock / end_clock 和第二段 add_start_clock / add_end_clock 组合。
add_end_clock
类型：string
观测值：
"1.00:00:00"（15条）
"18:00:00"（1条）
"23:59:00"（1条）
特别注意：
"1.00:00:00" 这种格式明显是 “天.时:分:秒” 的表示方式，即“第 1 天的 00:00:00”，也就是跨日截止（比 00:00:00+1天）。
用来定义“跨午夜”的可用区间，比如从晚上 18:00 一直用到第二天 0 点。
含义：附加时段结束时间，多数情况配合 "00:00:00" 或 "10:00:00" 使用。
整体理解：
start_clock / end_clock：第一时间段。
add_start_clock / add_end_clock：第二时间段；当 add_end_clock 是 "1.00:00:00" 时，可以认为是从当天某时刻到次日凌晨。
当前配置中，大部分套餐是“全天可用 + 夜场延伸”的模式，因此看到 00:00:00 → 1.00:00:00 这样的组合。
5. 区域 / 台桌限制相关字段
area_tag_type
类型：int，枚举。
观测值：全部为 1。
含义（推测）：区域标记类型：
1 很可能代表“按台区标签限制”，例如 A区、中八区、包厢、KTV 等。
由于没有看到其它值，具体枚举含义需结合系统配置，但可以确认：这个字段是“区域约束的模式选择”。
table_area_name
类型：string
观测值：（举例）
"A区中八"、"B区中八"、"斯诺克"、"包厢"、"KTV" 等。
含义：套餐适用的“门店台区名称”，用于显示和筛选。
说明：这个字段是对区域 ID 维度的文字描述，便于直观理解。
table_area_id
类型：int
观测值：全部为 0。
含义（推测）：
原始设计应为“单一台区 ID”，当套餐只限一个区域可以用这个字段存储。
但当前版本已经使用“列表字段”进行多选，导致单值字段全部为 0（未启用）。
tenant_table_area_id
类型：int
观测值：全部为 0。
含义（推测）：
与 table_area_id 类似，是租户层级的台区 ID，原本用于单区选择。
由于引入多选逻辑后，实际使用转移到 tenant_table_area_id_list 字段，这里被弃用。
tenant_table_area_id_list
类型：在导出中为 int 类型（严格看是数字，但语义上是“多选集合”）。
观测值：每条记录都是一个不同的大整数（例如 2791960001957765, 2791960521691013 等）。
含义（推测）：
实际代表“台区集合 ID”或“租户台区配置 ID”，用来限制套餐可用的台区范围。
设计上是可以支持多个区域，因此字段名用了“list”，但在当前数据中，每个套餐只有一组区域组合，所以存的是单一 ID。
结构逻辑：
套餐定义 → tenant_table_area_id_list → 台区分组表（未在本次导出中看到，但可推断存在），该分组中包含实际的一个或多个 table_area_id。
table_area_id_list
类型：string
观测值：全部为空字符串 ""。
含义（推测）：
用来存放具体台区 ID 列表（例如 "1,2,3"），实现更细粒度的台桌限制。
当前门店的配置可能只用了“台区分组”而没有配置到具体单个台号，因此留空。
总结区域字段结构：
area_tag_type：选择约束方式（这里统一为 1，表示按台区标签）。
table_area_name：文字名称，给人看的。
tenant_table_area_id_list：真正起约束作用的 ID（指向台区分组）。
table_area_id / tenant_table_area_id / table_area_id_list：历史单选/多选字段，当前配置中未实际使用（全部为 0 / 空串）。
6. 适用卡种相关字段
card_type_ids
类型：int
观测值：全部为 0。
含义（推测）：
原意是“适用会员卡类型 ID 列表”，例如某套餐只允许某几种会员卡使用，可以在此配置。
当前统一为 0，说明未限定卡种，任何顾客/任何会员卡均可按平台规则使用该团购券。
结构上：这是一个“未来可以细化到卡种”的扩展字段，本店目前未用。
7. 状态 / 类型类字段
is_enabled
类型：int，枚举。
观测值：全部为 1。
含义：启用状态。
从其他表的统一风格来看，1 一般表示“启用 / 上架”，2 表示“停用 / 下架”。
当前数据全部为 1，说明导出时所有 17 个套餐处于“启用”状态（但是否“有效”，还要看 effective_status）。
is_delete
类型：int，枚举。
观测值：全部为 0。
含义：逻辑删除标志。
0：正常；
1：已删除（仅逻辑删除，数据仍保留）。
当前没有任何套餐被标记为删除。
effective_status
类型：int，枚举。
观测值：
1：13 条
3：4 条
含义（结合命名和数据特征推断）：
1：有效（在当前时间区间内、配置正常，可核销使用）。
3：已过期或失效（虽然 is_enabled 仍为 1，但由于 end_time 已过期，或其他原因，被标记为不可用）。
说明：is_enabled 更偏向“是否上架配置”；effective_status 是动态计算出的“当前是否处于可用状态”。
group_type
类型：int，枚举。
观测值：全部为 1。
含义（推测）：
团购类型，例如：
1：计时类/台费类套餐；
其他值：可能用于区别商品类、代金券类等。
本门店所有 17 个套餐的 group_type 均为 1，说明都归于同一大类。
system_group_type
类型：int，枚举。
观测值：全部为 1。
含义（推测）：
系统内对团购类型更底层的划分，比如：
1：券码类团购（需要凭码核销）；
其它类型：如卡内套餐、内部套餐等。
当前全部为 1，说明这些套餐都属于同一系统团购类型（标准券类）。
type
类型：int，枚举。
观测值：
1：13 条
2：4 条
含义（推测）：
内部业务子类型，具体含义需要结合系统文档；仅从数据无法确定是“台费类 vs 包厢类”还是“平台套餐 vs 自定义套餐”。
结构上：此字段用来进一步细分团购套餐类别，有两种子类型。
8. 其他字段
duration
类型：int
观测值（秒）：
3600（1 小时）
7200（2 小时）
14400（4 小时）
含义：套餐内包含的时长（秒）。
与名称一致：
“一小时”类套餐 → 3600
“两小时”类 → 7200
“四小时”类 → 14400
结构用途：当券被核销时，可以用 duration 直接换算成应赠送/应抵扣的台费时间。
usable_range
已在日期部分说明（文字描述），这里只列入清单。
三、与其他 JSON 文件的结构关联（字段层面）
虽然你这次只问这一个文件，但按照结构分析的习惯，简单标一下这个“团购套餐定义表”和其它数据之间的关系：
与门店/租户维度：
tenant_id、site_id、site_name：
与所有其他 JSON（台费流水、助教流水、门店销售记录、库存、会员等）的同名字段一致。
用于在多门店部署场景下按门店过滤数据。
site_name 冗余，但在所有记录中保持为“朗朗桌球”。
与平台验券记录（平台验券记录.json）：
验券记录中有 group_package_id 字段（我们之前已分析过），对应这里的 id：
platform_coupon_use.group_package_id = 团购套餐.id
这样，验券记录知道：某张券是按照哪一个“团购套餐配置”被核销的，从而可以根据这里的 duration、coupon_money、时段限制等字段判断是否符合规则。
与团购套餐流水（团购套餐流水.json）：
团购套餐流水记录单笔订单中某个券/套餐的使用情况。
从字段命名风格看，流水记录会引用：
套餐名称（冗余 ledger_name / package_name）；
券码 coupon_code 与验券记录相连；
通过验券记录的 group_package_id 再指向本表的 id。
结构链路大致为：
团购套餐定义（本文件） → 平台验券记录（券码与套餐ID） → 团购套餐流水（订单明细里的券使用记录）。
与台桌/台区配置（台桌列表、台区配置相关 JSON）：
tenant_table_area_id_list 与台区配置表中的“台区组合 ID”关联。
table_area_name 与台区配置中 area_name 字段含义吻合（A区中八/B区中八/斯诺克/KTV/包厢等）。
通过该关联，系统在核销时可以校验：
当前使用的台桌所属区域是否在该套餐允许的区域范围内。
与会员卡/储值卡体系：
card_type_ids 字段设计上用来限制“哪些卡种可以用这个团购套餐”。
当前值均为 0，表示不限卡种。但一旦 >0，则应该可以通过该字段与“卡类型定义表”关联（本次导出中没有单独的卡种定义 JSON，只有储值卡列表，此处只能从结构上推断）。
四、结构层面的一些重要线索（非业务/盈利分析）
从字段设计和实际值可以看出一些系统设计上的特点和潜在规则：
“无限次”通过大数哨兵实现：
usable_count = 9999999 明显是一个“无限使用次数”的标记，而不是一个有业务意义的真实上限。
这类字段如果未来要限制使用次数，只需把这个值改成有限数即可。
时间段支持跨日和双时段：
start_clock / end_clock + add_start_clock / add_end_clock 的组合，以及 add_end_clock 中的 "1.00:00:00"，表明系统支持：
单日内多段时间限制；
跨午夜的可用时间段，比如“晚场到第二天凌晨”的场景。
这种设计比简单的 HH:MM 模式更灵活，但也更复杂。
区域限制采用“分组 ID + 名称”双层设计：
单值字段 table_area_id、tenant_table_area_id 已基本弃用（全为0），实际使用的是 tenant_table_area_id_list 配合 table_area_name。
这种设计允许一个套餐适用多个具体区域，而不仅仅是一个；只是本数据中每个套餐只有一个区域组合 ID，尚未用到真正的“多选”能力。
状态字段拆成“启用/删除/有效”：
is_enabled：是否上架（配置层面）。
is_delete：是否逻辑删除（数据层面）。
effective_status：是否在当前时间点视为有效（动态计算结果）。
这种三层拆分，便于保留历史配置（is_delete）和允许“预设但未到期/已过期”的套餐（effective_status）。
价格字段“selling_price”目前未落地：
所有记录 selling_price = 0.0，但 coupon_money 有实际金额。
这说明：在门店数据里，只关心“券在店内的抵扣价值”（coupon_money），而“平台对顾客的售卖价格”可能在外部系统（团购平台）或其他表中维护。
从结构上看，这保留了未来把平台售价同步到本地的扩展空间。
卡种限制预留但未使用：
card_type_ids = 0 表明目前团购套餐未限制特定卡种。
一旦业务需要特定会员卡才能享用某些团购，可以通过非零值（以及列表编码）实现，同样是结构级扩展。
字段命名的一致性与冗余：
site_id + site_name 的组合和其他 JSON 一致，说明整个系统在多模快数据里都采用相同的门店维度标识。
多个字段采用“xxx_id + xxx_name”的模式（如台区、门店、套餐名称），有利于在不做联表查询的情况下直接展示内容。

734
docs/api-reference/endpoints/group_buy_redemption_records.md Normal file
View File

@@ -0,0 +1,734 @@
# 团购核销记录（GetSiteTableUseDetails）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Site/GetSiteTableUseDetails` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/Site/GetSiteTableUseDetails` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `group_buy_redemption_records` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `siteId` | int | `2790685415443269` | 门店 ID |
| `offlineCouponChannel` | int | `0` | 线下券渠道（0=全部） |
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
| `queryType` | int | `1` | 查询类型（1=默认） |
## 响应字段（共 43 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `tableName` | string | 'A17' |
| 2 | `tableAreaName` | string | 'A区' |
| 3 | `siteName` | string | '朗朗桌球' |
| 4 | `goodsOptionPrice` | float | 0.0 |
| 5 | `id` | int | 2957924029615941 |
| 6 | `order_trade_no` | int | 2957858167230149 |
| 7 | `table_id` | int | 2793003705192517 |
| 8 | `site_id` | int | 2790685415443269 |
| 9 | `tenant_id` | int | 2790683160709957 |
| 10 | `operator_id` | int | 2790687322443013 |
| 11 | `operator_name` | string | '收银员:郑丽珊' |
| 12 | `order_settle_id` | int | 2957922914357125 |
| 13 | `ledger_name` | string | '全天A区中八一小时' |
| 14 | `ledger_group_name` | string | '' |
| 15 | `ledger_unit_price` | float | 29.9 |
| 16 | `ledger_count` | int | 3600 |
| 17 | `ledger_amount` | float | 48.0 |
| 18 | `order_pay_id` | int | 0 |
| 19 | `create_time` | string | '2025-11-09 23:35:57' |
| 20 | `is_delete` | int | 0 |
| 21 | `promotion_activity_id` | int | 2957858166460101 |
| 22 | `promotion_coupon_id` | int | 2798727423528005 |
| 23 | `is_single_order` | int | 1 |
| 24 | `order_coupon_id` | int | 2957858168229573 |
| 25 | `order_coupon_channel` | int | 1 |
| 26 | `ledger_status` | int | 1 |
| 27 | `promotion_seconds` | int | 3600 |
| 28 | `coupon_origin_id` | int | 2957858168229573 |
| 29 | `table_charge_seconds` | int | 3600 |
| 30 | `offer_type` | int | 1 |
| 31 | `coupon_money` | float | 48.0 |
| 32 | `tenant_table_area_id` | int | 2791960001957765 |
| 33 | `assistant_promotion_money` | float | 0.0 |
| 34 | `assistant_service_promotion_money` | float | 0.0 |
| 35 | `table_service_promotion_money` | float | 0.0 |
| 36 | `goods_promotion_money` | float | 0.0 |
| 37 | `reward_promotion_money` | float | 0.0 |
| 38 | `recharge_promotion_money` | float | 0.0 |
| 39 | `salesman_user_id` | int | 0 |
| 40 | `salesman_name` | string | '' |
| 41 | `salesman_role_id` | int | 0 |
| 42 | `sales_man_org_id` | int | 0 |
| 43 | `coupon_code` | string | '0107892475999' |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `assistant_service_share_money` | float |
| `assistant_share_money` | float |
| `coupon_sale_id` | int |
| `good_service_share_money` | float |
| `goods_share_money` | float |
| `member_discount_money` | float |
| `recharge_share_money` | float |
| `table_service_share_money` | float |
| `table_share_money` | float |
## 详细字段分析
> 以下内容迁移自旧版 `group_buy_redemption_records-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
二、记录级字段逐项说明（共 43 个）
我按业务逻辑分组说明：台桌 / 门店维度、订单与关联 ID、金额与时间字段、券字段、促销拆账字段、状态字段、操作员/销售字段等。
1. 台桌 / 门店维度字段
tableName
类型：string
示例："A7", "A11", "B1", "斯1", "麻1" 等。
含义：本次使用券所关联的 球台名称/台号。
关联：对应台桌列表中的 table_name / table_no，通过 table_id 进一步关联。
tableAreaName
类型：string
观测值（枚举）："A区", "B区", "斯诺克区", "麻将房"。
含义：该球台所属的 台区名称。
关联：与台区配置中的 area_name 含义一致，与团购套餐定义中的 table_area_name 一致。
table_id
类型：int
含义：球台 ID。
关联：
对应“台桌列表”表中的 id 字段。
用于联表确定该记录具体是哪一张桌。
table_charge_seconds
类型：int（秒）
示例：3600, 7200, 10800, 14400，以及一些非整小时值如 10247, 7168 等。
含义：本次结算中该球台总计计费的秒数（整台的台费计费时间）。
结构特点：
当券完全覆盖整个台的时长时，table_charge_seconds 通常 = ledger_count。
当台上有多种计费组合（比如部分时间是券，部分时间是正常计时）时，table_charge_seconds 可能大于 ledger_count 和 promotion_seconds。
siteName
类型：string
观测值：全部为 "朗朗桌球"。
含义：门店名称，冗余展示用。
site_id
类型：int
含义：门店 ID，与其它 JSON 中一致。
关联：
与“团购套餐定义”、“助教流水”、“台费流水”、“门店销售记录”等文件中的 site_id 完全一致，用于统一按门店过滤。
tenant_id
类型：int
含义：租户/品牌 ID。
特点：全表值相同，说明所有记录属于同一租户。
tenant_table_area_id
类型：int
观测值（枚举，4 个值）：
2791960001957765（占 164 条）
2791960521691013（19 条）
2791961347968901（16 条）
2791962314215301（1 条）
含义：租户级台区分组 ID，表示当前使用券的台桌所属的区域组合。
关联：
与“团购套餐定义”中的 tenant_table_area_id_list 对应（那边是字符串形态，这里是数值形态），表明该券只能在某些台区组合上使用。
结构作用：用于校验券的适用台区与实际台桌是否匹配。
2. 订单与关联 ID 类字段
id
类型：int
含义：本条“团购套餐流水”记录的 主键 ID。
作用：唯一标识一条券使用到台费上的记录。
order_trade_no
类型：int
含义：订单交易号，和其它消费明细（台费、商品、助教、团购）共用的订单主键。
关联：
与“小票详情”、“台费流水”、“助教流水”等的 order_trade_no 一致，用于将同一笔结账中的所有子项目关联起来。
order_settle_id
类型：int
含义：结算单 ID（小票结账主键）。
关联：
与“小票详情”中的 orderSettleId 相对应。
与“结账记录”中的结算 ID 一致。
order_pay_id
类型：int
观测：部分记录为 0，部分为非零 ID。
含义（推测）：
指向支付记录表中的支付流水 ID。
当为 0 时，可能表示该券使用记录在导出范围内未能联到具体支付记录（或为非现金支付方式）。
order_coupon_id
类型：int
观测：200 条记录全部唯一。
含义：订单中“券使用记录”的 ID。
结构特点：
与 coupon_origin_id 当前完全相等，可以视作同一主键在不同上下文中的命名方式。
与“平台验券记录”或“券核销记录”表中的主键对应。
coupon_origin_id
类型：int
观测：200 条记录全唯一，数值与 order_coupon_id 完全一致。
含义（推测）：
平台/上游系统中的券记录主键 ID，“券来源 ID”。
系统中通过这个 ID 能从平台验券记录中查到券的完整来源信息（来源平台、活动等）。
promotion_activity_id
类型：int
观测：200 条记录全部不重复。
含义（推测）：团购/促销活动 ID。
对应平台或内部促销活动的主键，每个活动通常绑定一个或多个具体套餐（promotion_coupon_id）。
promotion_coupon_id
类型：int
观测：9 个不同值。
含义：团购套餐定义 ID。
关联：
与 20251110_043255_团购套餐.json 中的 id 字段一一对应，即：
团购套餐流水.promotion_coupon_id = 团购套餐定义.id。
通过这个字段可以知道：当前这条券使用的是哪一种团购套餐配置。
order_coupon_channel
类型：int，枚举。
观测值：1（181 条）、2（19 条）。
含义（推测）：
券渠道类型，例如：
1：渠道 A（某平台/来源）；
2：渠道 B（另一个平台/来源或内部券）。
具体对应的渠道需要看系统配置，但可以确定这是“券渠道枚举”。
3. 金额与时间相关字段（本表的核心）
3.1 金额字段（券抵扣金额）
ledger_unit_price
类型：float
观测值（枚举）：29.9, 39.9, 59.9, 69.9, 11.11, 128.0 等。
含义：对应台费的标准单价，单位元/小时（从数值来看是类似29.9/小时这种定价）。
作用：配合 ledger_count 用于计算这一条券在台费层面对应的金额（理论上应接近 = 单价 × 秒数/3600）。
ledger_count
类型：int（秒）
观测值：以 3600, 7200 为主，也有 6429, 3047, 3568 等不整小时的数值。
含义：按此次优惠实际计算的“核销秒数”。
结构观察：
大部分记录满足：ledger_count = promotion_seconds（即券定义的标准时长）。
少数记录中 ledger_count 与 promotion_seconds 略有差异（比如 3047 秒 vs 3600 秒），说明券实际核销到本次台费的时间略少于券 nominal 时长（可能是台上实际计费情况导致，不推断原因，只确认结构现象）。
ledger_amount
类型：float
观测值（部分）：48.0, 96.0, 116.0, 68.0, 58.0 等，少数为 2 位小数（如 49.09, 44.85）。
含义：本次券实际冲抵台费的金额。
结构关系：
绝大部分记录中，ledger_amount 与下方的 coupon_money 完全相等。
少量记录中出现小数（例如 49.09），说明在“单价×时间”的换算中产生了非整数金额，并以实际换算结果为准。
coupon_money
类型：float
观测值（枚举）：48.0, 68.0, 58.0, 96.0, 116.0, 288.0。
含义：本次核销时，这张券在门店侧对应的金额额度（“可抵扣金额”）。
结构关系：
按 promotion_coupon_id 聚合可以看到：同一种套餐对应固定的 coupon_money 和固定的 promotion_seconds，例如：
某套餐 ID → 全部记录 promotion_seconds = 3600 且 coupon_money = 48.0。
某套餐 ID → promotion_seconds = 7200 且 coupon_money = 96.0 或 116.0 等。
因此可以认为：每种团购套餐在实际使用时，对应一个固定的“抵扣时长 + 金额组合”，只是在定义表中 coupon_money 没有填，实际金额是在流水里体现。
promotion_seconds
类型：int（秒）
观测值（枚举）：3600, 7200, 14400。
含义：团购套餐定义的“标准时长”（券本身标称的可用时长）。
结构关系：
每一个 promotion_coupon_id 对应一个固定值：
部分套餐是 1 小时（3600）、部分是 2 小时（7200）、部分是 4 小时（14400）。
与“团购套餐定义”中的 duration 字段一致：两个表通过 promotion_coupon_id / id 关联后，可以验证 promotion_seconds = duration。
goodsOptionPrice
类型：float
观测：全部为 0.0。
含义（按命名推测）：商品规格价格，用于商品类促销分摊时使用。
当前在“团购套餐流水”中未被实际使用。
goods_promotion_money
类型：float
观测：全部为 0.0。
含义：本次券使用中，分摊到“商品”部分的促销金额。
当前数据中，所有团购券都只用于抵扣台费，没有用来抵扣商品，因此该字段为 0。
table_service_promotion_money
类型：float
观测：全部为 0.0。
含义：本次券使用中，分摊到“台费服务费”部分的促销金额。
当前样本中，促销金额都在 ledger_amount 中体现，该字段未单独拆出。
assistant_promotion_money
类型：float
观测：全部为 0.0。
含义：分摊到“助教服务”的促销金额。
当前场景下，团购券只与台费相关，未涉及助教的金额抵扣。
assistant_service_promotion_money
类型：float
观测：全部为 0.0。
含义：进一步细分助教服务的促销金额。
当前未使用。
reward_promotion_money
类型：float
观测：全部为 0.0。
含义：本次促销中，属于“奖励金/积分抵扣”的金额。
当前没有使用此维度的促销。
recharge_promotion_money
类型：float
观测：全部为 0.0。
含义：来自“充值类优惠”的分摊金额（例如储值赠送部分）。
当前所有数据为 0，但结构上已经预留了“多来源促销金额分摊”的能力。
小结（金额结构）：
核心金额在 ledger_amount 与 coupon_money 上，其他几个 xxx_promotion_money 字段为不同业务子模块预留，目前数据未用。
ledger_unit_price + ledger_count + promotion_seconds + coupon_money 四者构成了“券抵扣时长和金额”的结构关系，而不涉及任何盈利分析。
4. 券本身的标识字段
coupon_code
类型：string
观测：每条记录唯一，类似 "0107892475999" 这样的券码。
含义：团购券券码，核销时扫描/录入的字符串。
关联：
与平台验券记录表中的 coupon_code 完全一致，通过该字段可以串起“平台 → 核销 → 台费流水”全链路。
offer_type
类型：int，枚举。
观测值：全部为 1。
含义（推测）：优惠类型。
在券适用多个优惠方式的系统中，一般用来区分“满减/折扣/代金券/套餐券”等。
当前全部为 1，说明本门店使用的团购券全部属于同一类型（例如“套餐券”）。
5. 业务状态与标志字段
ledger_status
类型：int，枚举。
观测值：全部为 1。
含义（推测）：流水状态。
1：正常有效；
其他可能值（未在本数据中出现）可能表示“作废/撤销/未生效”等。
当前导出时，仅包含状态为 1 的正常使用记录。
is_single_order
类型：int，枚举。
观测值：1（199 条）、0（1 条）。
含义（推测）：是否单独作为一条订单行。
1：以独立条目方式进行结算（绝大部分记录如此）。
0：嵌在某种组合结算中（仅 1 条异常记录）。
is_delete
类型：int，枚举。
观测值：全部为 0。
含义：逻辑删除标志：
0：正常；
1：已删除（逻辑删除，历史仍保留）。
当前时间范围内没有删除过的团购套餐流水记录。
6. 操作员 / 销售员相关字段
operator_id
类型：int
观测：所有记录相同，均为某一员工 ID。
含义：执行本次核销/结算操作的 操作员 ID。
关联：可以与员工档案表中的 id 对应（当前导出中员工表未单独给出，但风格和其它表一致）。
operator_name
类型：string
观测：全部为 "收银员:郑丽珊"。
含义：操作员名称（包含角色说明），与 operator_id 对应的冗余展示字段。
salesman_user_id
类型：int
观测：全部为 0。
含义：营业员/业务员用户 ID。
当前所有团购套餐流水都未指定独立的营业员。
salesman_name
类型：string
观测：全部为空字符串 ""。
含义：营业员姓名。
salesman_role_id
类型：int
观测：全部为 0。
含义：营业员角色 ID。
sales_man_org_id
类型：int
观测：全部为 0。
含义：营业员所属组织 ID。
以上 4 个销售相关字段在当前门店的团购套餐使用中都未启用，仅作为结构预留。
7. 其他字段
ledger_name
类型：string
示例："全天A区中八一小时", "B区桌球一小时", "中八、斯诺克包厢两小时" 等。
含义：台费侧关联的“团购项目名称”（记账名）。
结构上通常来源于团购套餐定义的 package_name，或由系统在创建活动时生成。
ledger_group_name
类型：string
观测：全部为空字符串。
含义（推测）：团购项目所属的“记账分组名称”（例如“团购台费”“团购包厢”等）。
当前门店未对团购项目做进一步分组。
create_time
类型：string（时间），格式 YYYY-MM-DD HH:MM:SS
含义：本条团购套餐使用流水创建时间（即券核销时间，或与结账时间接近）。
用法：可用于按时间范围过滤团购使用记录。
三、与其他 JSON 之间的结构关系（字段级）
仅从字段角度，团购套餐流水的关联关系可以浓缩为几条主线：
与团购套餐定义（20251110_043255_团购套餐.json）
关键字段：
promotion_coupon_id ↔ 团购套餐定义表的 id
由此可获得：
套餐名称 package_name
套餐标准时长 duration
套餐适用台区 table_area_name / tenant_table_area_id_list
每日可用时间段 start_clock/end_clock/add_start_clock/add_end_clock
同时本流水中的 promotion_seconds 与定义表中的 duration 在结构上是一致的。
与“订单/小票”相关表
通过以下字段建立关联：
order_trade_no：订单号 → 将这张券使用记录与同一笔订单中的台费、助教、商品等明细串联起来。
order_settle_id：结算单 ID → 对应小票详情、结账记录中的主键。
order_pay_id：支付记录 ID → 对应支付记录表中的流水（若非 0）。
这样可以从一个订单角度看到：台费、券抵扣、实付方式等整体结构。
与台桌维度 / 台区配置
table_id ↔ 台桌表 id：确定具体是哪一张桌。
tableAreaName ↔ 台区配置的区名。
tenant_table_area_id ↔ 团购套餐定义中的 tenant_table_area_id_list：
套餐定义允许使用的台区组合；
流水记录表示实际使用时所在的台区组合；
结构上可用于校验“是否在允许区域内使用”。
与平台券 / 验券记录表（未在本问题中展开）
coupon_code：平台券码 → 对应平台验券记录中的同名字段。
coupon_origin_id / order_coupon_id：
当前数据中二者完全相等，可视作平台券记录主键；
在平台券表中，一般会记录来源平台、原始套餐 ID、是否已使用等信息。
通过这两个字段，可以完整追踪券从“购买 → 核销 → 记账”整个过程。
与门店/租户维度
tenant_id、site_id、siteName：
与其它所有 JSON 一致，保证所有表可以在多门店部署下按品牌/门店维度统一过滤。
四、结构层面的重要线索（非盈利/非大数据分析）
从字段设计和数据现状，可以归纳出这些结构性信息：
这一张表是“券 → 台费”的专用流水表
通过字段命名（siteTableUseDetailsList、table_charge_seconds、ledger_unit_price 等）可以看出：
它专门描述“团购券/平台券使用在台费上的明细”；
与助教、商品、充值等促销虽然共享同一套促销拆账字段（xxx_promotion_money），但在当前数据中都为 0，说明本门店这类券只用于抵扣台费，不用于其它业务模块。
时长结构：区分“券时长”和“整台时长”
promotion_seconds：套餐定义的标准时长（券自身的时间权益）。
ledger_count：此次券实际核销的时间秒数（可能等于也可能略小于 promotion_seconds）。
table_charge_seconds：本次结算中该台整体计费秒数（可能大于券时长，因为有部分未被券覆盖）。
这种三层区分，为之后做“券覆盖率”、“券部分抵扣”、“超出部分正常计费”等逻辑提供了结构基础，但你要求不做数值分析，在此只保留结构描述。
金额结构：核心金额集中在两字段
ledger_amount：券在本次台费中实际抵扣的金额。
coupon_money：本次核销时该券对应的金额额度（几乎与 ledger_amount 一致）。
其他 assistant_promotion_money、goods_promotion_money、reward_promotion_money 等字段全部为 0，说明当前门店仅使用了最简单的“整券抵扣台费”的结构，但设计上已经支持更复杂的多业务分摊。
状态结构：启用/删除/有效在其他表中，而本表只保留“正常流水”
本表有 ledger_status / is_delete / is_single_order 等状态位：
ledger_status 全为 1，说明导出的都是正常状态的券使用记录；
is_delete 全为 0，说明没有被逻辑删除；
is_single_order 只有一条为 0，其余为 1，绝大部分券使用是以独立条目方式挂靠到订单上。
类似于团购套餐定义中的 is_enabled、effective_status，但本表只承接“已经发生”的流转结果，不承载定义层面的上下架逻辑。
渠道和活动维度已经结构化独立出来
promotion_activity_id、promotion_coupon_id、order_coupon_channel 三个字段，将券使用从三个维度刻画：
活动维度（来自哪个团购活动）；
套餐维度（使用的是哪个套餐定义）；
渠道维度（来自哪个平台/渠道）。
这种设计使得将来只要联上“活动表”“渠道配置表”，就可以从多维视角审视券的使用结构，而无需改动流水表结构本身。
整体来看，20251110_043302_团购套餐流水.json 是“团购套餐定义 + 台费流水 + 平台券核销”之间的中间桥接表，它用一条记录，把 某张券、某个套餐配置、某个订单、某张桌、某段时间、某个金额 绑在一起。

589
docs/api-reference/endpoints/member_balance_changes.md Normal file
View File

@@ -0,0 +1,589 @@
# 会员余额变动（GetMemberCardBalanceChange）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `MemberProfile/GetMemberCardBalanceChange` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/MemberProfile/GetMemberCardBalanceChange` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `member_balance_changes` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `fromType` | int | `0` | 来源类型（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 25 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `memberCardTypeName` | string | '储值卡' |
| 2 | `paySiteName` | string | '朗朗桌球' |
| 3 | `registerSiteName` | string | '朗朗桌球' |
| 4 | `memberName` | string | '曾丹烨' |
| 5 | `memberMobile` | string | '13922213242' |
| 6 | `id` | int | 2957881605869253 |
| 7 | `account_data` | float | -120.0 |
| 8 | `after` | float | 696.3 |
| 9 | `before` | float | 816.3 |
| 10 | `card_type_id` | int | 2793249295533893 |
| 11 | `create_time` | string | '2025-11-09 22:52:48' |
| 12 | `from_type` | int | 1 |
| 13 | `is_delete` | int | 0 |
| 14 | `operator_id` | int | 2790687322443013 |
| 15 | `operator_name` | string | '收银员:郑丽珊' |
| 16 | `payment_method` | int | 0 |
| 17 | `refund_amount` | float | 0.0 |
| 18 | `register_site_id` | int | 2790685415443269 |
| 19 | `relate_id` | int | 2957881518788421 |
| 20 | `remark` | string | '' |
| 21 | `site_id` | int | 2790685415443269 |
| 22 | `system_member_id` | int | 2799212844549893 |
| 23 | `tenant_id` | int | 2790683160709957 |
| 24 | `tenant_member_card_id` | int | 2799219999295237 |
| 25 | `tenant_member_id` | int | 2799212845565701 |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `principal_after` | float |
| `principal_before` | float |
| `principal_data` | float |
## 详细字段分析
> 以下内容迁移自旧版 `member_balance_changes-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
二、记录级字段逐项说明（含类型、含义、枚举/规律）
下面按逻辑分类（ID/关联、会员维度、卡种信息、金额余额、类型来源、支付方式、时间、站点/操作员、状态标志、备注等）逐项说明。
1. 主键与关联 ID 类字段
id
类型：int
含义：余额变更记录的主键 ID，唯一标识这一条“账户余额变化事件”。
relate_id
类型：int
值分布：共 167 个不同值，0 约 18 次，绝大部分为非 0 的长整型。
含义（推测）：关联业务记录的 ID：
例如某次充值记录的 ID、某张订单/结算单 ID、某次活动抵用券核销记录 ID 等。
为 0 时，通常表示没有挂接具体业务单（例如纯后台调整）。
与其它表的关系：
视 from_type 而定，可能对应：
充值记录（如果有导出）；
订单结算记录；
活动抵用券账单等。
tenant_id
类型：int
含义：租户/商户 ID，本数据中是固定值（同一品牌/商户）。
site_id
类型：int
值分布：
2790685415443269（朗朗桌球）出现 198 条；
0 出现 2 条。
含义：
非 0：记录所属的具体门店 ID（与其他 JSON 内的 site_id 一致）。
0：特殊场景，通常代表“跨门店/虚拟站点/平台级操作”。在本数据中，这两条记录恰好是“活动抵用券”相关的退款/冲销记录。
关联：可与门店档案（siteProfile.id）对应。
register_site_id
类型：int
值：全为 2790685415443269
含义：会员卡的“注册门店 ID”，即办卡所在门店。
对比：
register_site_id 表示“卡当初在哪家店办的”，
site_id 表示“本次余额变动发生在哪家店”。本数据两者绝大部分情况一致，只有活动抵用券退款那两条 site_id=0、register_site_id 仍是该门店。
2. 会员与会员卡维度字段
tenant_member_id
类型：int
含义：商户维度的会员 ID（租户内会员主键）。
关联：
对应“会员档案（20251110_043209_…）”中的 id 字段，即同一个租户下的会员主键。
作用：
在本表与会员档案之间形成外键关系：
余额变更记录.tenant_member_id = 会员档案.id
system_member_id
类型：int
含义：系统级（全局）会员 ID。
关联：
对应会员档案中的 system_member_id 字段。
说明：
允许一个会员在多个租户/门店下有不同的 tenant_member_id，但共享同一个 system_member_id。
在你当前的数据里，只存在一个门店，所以两个 ID 一般一一对应同一个会员，但本质上设计是“集团级 ID + 租户级 ID”双键。
tenant_member_card_id
类型：int
含义：会员卡账户 ID，在租户内唯一标识某张卡。
关联：
对应“会员档案/储值卡列表”中的 id（卡账户 ID）。
作用：
一名会员可以有多张卡（储值卡、台费卡、酒水卡、活动券等），tenant_member_card_id 指明这条余额变更是针对哪一张卡。
card_type_id
类型：int
值分布（与 memberCardTypeName 一一对应）：
2793249295533893 → “储值卡”（132 条）
2793266846533445 → “活动抵用券”（52 条）
2794699703437125 → “酒水卡”（9 条）
2791990152417157 → “台费卡”（7 条）
含义：卡种类型 ID，用于区分不同卡种。
memberCardTypeName
类型：string
值："储值卡", "活动抵用券", "酒水卡", "台费卡"
含义：卡种名称，与 card_type_id 一一对应，是一个 卡种枚举名称。
memberName
类型：string
含义：会员姓名或称呼（非昵称字段）。
说明：例如“陈腾鑫”“胡先生”“江先生”等，多为中文姓名或带“先生”称呼。
memberMobile
类型：string
含义：会员手机号。
说明：字符型存储，完整手机号，用来识别会员与联系客户。
3. 门店名称与办卡门店名称
paySiteName
类型：string
值分布：
"朗朗桌球"：198 条
""（空字符串）：2 条
含义：发生本次余额变更的门店名称（即本次消费/充值所在门店）。
对应关系：
当 site_id = 朗朗桌球的ID 时，是该门店名称；
当 site_id = 0 时，这里为空，说明这两条记录是特殊的“活动抵用券退款”场景，不归属具体营业门店。
registerSiteName
类型：string
值：全为 "朗朗桌球"
含义：卡片的注册门店名称（办卡地点），和 register_site_id 配套。
特点：与 paySiteName 不同，强调“办卡地”，而不是“交易发生地”。
4. 金额与余额字段
这是本表的核心：余额变化量与变化前后余额。
before
类型：float
含义：本次变动前，该卡账户的余额（元）。
说明：
样本中有 0、数百、数千等各种值。
account_data
类型：float
含义：本次变动的金额（元），正数表示增加，负数表示减少。
特点：
无 0 值，所有记录要么增加要么扣减。
常见值：
正数：100、500、1000、3000、5000 等（充值或调整增加）；
负数：-5、-8、-10、-120、-144、-5000、-10000 等（消费扣款或退款冲减）。
与 from_type 强烈相关（详见后文）。
after
类型：float
含义：本次变动后，该卡账户的余额（元）。
重要关系：
所有记录都满足：
before + account_data = after（浮点精度下完全成立）。
这是本表最重要的结构性约束之一。
refund_amount
类型：float
值：全为 0.0
含义（推测）：与退款业务相关的金额字段，但在当前这份导出中实际未使用：
可能用于标记“其中有多少金额是以‘退款’形式回流的”，或区分“退回余额”和“原路退回”两种模式。
当前所有记录没有单独标记，字段处于空置状态。
5. 变动来源类型（from_type）
from_type
类型：int，关键枚举字段
值分布：
1：163 条
3：16 条
4：16 条
7：2 条（备注为“充值退款”）
9：2 条（活动抵用券余额冲减）
2：1 条（正数增额）
含义（根据金额符号与 remark 综合推断）：
1：日常消费扣款
account_data 均为负数（-120、-144、-114.61 等），payment_method=0。
表示“用卡消费扣除余额”（例如用储值卡、台费卡支付消费）。
3：充值增加
account_data 均为正数（1000、3000、5000 等），payment_method=4。
对应实际有外部支付行为的充值（如扫码充值），为卡增加余额。
4：调整增加 / 赠送增加
account_data 多为 100、500、888 等，payment_method=3。
很可能是“后台赠送/活动赠送/调整加款”，不是顾客直接付款。
7：充值退款（明确）
两条记录 remark 字段均为 "充值退款"，account_data 为 -5000、-10000 元，payment_method=0。
结合上面 3 类充值记录，可以看出是“对前期充值的退款，以减少卡内余额的方式处理”。
9：活动抵用券相关余额冲减
两条记录的 memberCardTypeName 均为“活动抵用券”，account_data 为 -888、-1888，site_id=0，paySiteName 为空。
推测是“将活动抵用券额度从‘活动抵用券卡’里扣回/结算”，属于活动资金回收类。
2：其他增加（仅 1 条，正数 1865.8 元）
可能是某种“赠送+充值混合”的业务类型，当前只有单一案例，很难精确命名，但可确定是增额类型。
总体上，from_type 是本表中最重要的业务类型枚举，控制 account_data 的“方向”和解释：
1/7/9 为减余额类（消费扣款、退款冲减、活动冲减等），
2/3/4 为加余额类（充值、赠送、调整加款等）。
6. 支付方式字段
payment_method
类型：int，枚举
值分布：
0：168 条
3：16 条
4：16 条
结合 from_type 分析：
from_type=1/2/7/9 时，payment_method=0：
表示这类“内部扣减/内部调整/退款冲减”，并没有直接发生新的实收支付（或者实收在原单中记录，余额变动仅是内部记账）。
from_type=3 时，payment_method=4：
对应“充值类交易”，是顾客真实付款（扫码/银行卡等），这里记录的是付款渠道枚举之一（如微信/支付宝/银行卡等）。
from_type=4 时，payment_method=3：
一类“赠送/后台调账”渠道编码，表示这部分余额增加不是顾客直接付钱，而是后台发放或内部调整。
无法在不看系统配置的前提下精确说出 3/4 分别对应哪一个具体渠道（微信/支付宝/银行卡等），但可以明确：
0：内部结算/非外部支付；
3、4：外部支付或赠送渠道枚举。
7. 时间字段
create_time
类型：string，格式 YYYY-MM-DD HH:MM:SS
含义：本条余额变更记录的创建时间，通常接近交易发生时间。
说明：可与订单、支付记录的时间做对齐，构造时序链路（但你现在不要求做时序分析，这里只说明结构）。
8. 站点与操作员信息
register_site_id / registerSiteName
已在前文说明：办卡门店的 ID 与名称，所有记录一致，说明所有卡均在“朗朗桌球”注册。
site_id / paySiteName
表示本次余额变动的发生门店，绝大多数也在“朗朗桌球”，少数特殊业务（活动抵用券结算）显示为 site_id=0、paySiteName 为空。
operator_id
类型：int
值分布：3 个不同值：
主操作员工 ID：出现 192 次；
另外两位店长/管理员各有若干条记录。
含义：执行此次余额变更操作的员工 ID。
operator_name
类型：string
值示例：
'收银员:郑丽珊'（占绝大多数）
'店长:郑丽珊'
'店长:谢晓洪'
'店长:蒋雨轩'
'管理员：郑丽珊'
含义：操作员姓名（带职位前缀），是对 operator_id 的可读冗余字段。
9. 状态字段与标志
is_delete
类型：int
值：全部为 0
含义：逻辑删除标记：
0：正常；
1：逻辑删除（这类记录在系统中被标记为删除，但数据库中保留）。
当前导出数据中没有被逻辑删除的余额变更记录。
10. 备注字段
remark
类型：string
值分布：
""（空）：198 条
"充值退款"：2 条
含义：
当为空时，说明这条变动没有额外备注说明。
"充值退款" 明确标记该条记录是“充值退款”业务，这与 from_type=7 的两条记录完全对应，用于给操作者和报表更明确的文本说明。
三、余额变更记录与其他 JSON 的结构性关联（字段层面）
虽然你此问题主要关注字段本身，但这些字段设计是有明显的跨表关联意图的，这里从“字段结构”的角度简要列一下关键关联，不做任何金额/盈利分析。
与会员档案（20251110_043209_…）
tenant_member_id ↔ 会员档案 id
system_member_id ↔ 会员档案 system_member_id
这形成：
余额变更记录 ——(会员 ID)→ 会员基本信息（手机号、注册时间等）。
与储值卡/会员卡档案（储值卡列表/会员档案内卡记录）
tenant_member_card_id ↔ 卡档案 id（每一张卡的账户主键）。
card_type_id ↔ 卡种定义表的主键（从当前 JSON 看不到卡种定义表本身，但可以通过 memberCardTypeName，以及在其他表中的 member_card_grade_code 推测对应关系）。
这形成：
余额变更流水 ——(tenant_member_card_id)→ 某个具体卡账户 ——(card_type_id)→ 卡种类型（储值卡/酒水卡/台费卡/活动抵用券）。
与支付记录（20251110_035941_…）
逻辑上，充值类的记录（from_type=3）应该对应一条支付记录：
支付记录中 relate_type 标记为“充值”，relate_id 对应某条充值记录 ID；
而余额变更记录中 relate_id 很可能就是充值记录 ID。
同样，payment_method 在两边都是枚举字段，应保持一致（如 4 代表某个线上支付渠道）。
由于你当前的充值记录 JSON 为空，完整链路难以直接验证，但结构设计就是通过 relate_id + from_type + payment_method 来将余额变动与支付流水相互印证。
与订单/消费类流水
当 from_type=1（消费扣款）或 from_type=9（活动抵用券相关冲减）时：
relate_id 通常对应某单据（订单/结算单/活动扣款单）的主键；
通过 relate_id 可以与台费流水、助教流水、门店销售记录中的 order_settle_id 或其他业务 ID 建立关系。
结构上，这些额度层面的变动记录，就是消费类流水在“会员账户余额维度”的映射。
四、结构层面的额外线索（不做任何盈利/统计）
从字段和值的规律，可以看到一些结构上的特征，对你后续做数据建模或迁移有用：
严格的余额恒等关系
所有记录都满足：
after = before + account_data
说明这个表是“余额快照 +变动量”的纯记账结构，不掺杂其他衍生数值（例如手续费等）进来。
from_type+payment_method 的组合语义很清晰
from_type 决定业务类型（消费、充值、赠送、退款等）；
payment_method 决定是否有外部支付以及大致支付渠道；
对应关系稳定且方向明确（加额/减额与 from_type 显著相关），这是后续做“业务类型维度表”的重要线索。
卡种类型在本表中已经完全可识别
通过 card_type_id ↔ memberCardTypeName，本表已经给出了储值卡、酒水卡、台费卡、活动抵用券四种卡型及各自的 ID；
与“会员档案”里 member_card_grade_code / member_card_grade_name 可以配套构成更完整的“卡种维度”。
办卡门店与交易门店的区分
register_site_id/registerSiteName 始终是办卡门店；
site_id/paySiteName 则是余额变更发生门店；
少数记录的 site_id=0 提示了“平台级/活动结算”等场景，说明系统在结构上已经考虑跨店或虚拟门店场景。
remark 与 from_type 的配合使用
尽管 remark 大多为空，但“充值退款”这两个字只出现在 from_type=7 的记录上；
说明系统使用 remark 为部分场景提供更直观的文本说明，但逻辑判断仍以 from_type 为主。
逻辑删除与业务废除分离
本表只有 is_delete 字段（全 0），没有诸如 is_trash 之类业务性废除标记；
说明在余额变更层面，系统倾向于“不可逆记账”（不直接作废账户流水），业务层面若要冲销，是通过新的相反方向变动（负充值或正向退款）来体现，而不是逻辑删除记录。
整体来看，余额变更记录.json 是会员卡层面的“总账/明细账表”，与“充值记录”“消费结算记录”“会员档案”“卡类型、卡实例”之间，通过一整套 ID 和枚举字段建立了清晰的结构关系，而本次你给的这家门店只是该结构在一个门店上的数据切片。

465
docs/api-reference/endpoints/member_profiles.md Normal file
View File

@@ -0,0 +1,465 @@
# 会员档案（GetTenantMemberList）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `MemberProfile/GetTenantMemberList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/MemberProfile/GetTenantMemberList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `member_profiles` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要 |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `isMemberInBlackList` | int | `0` | 是否黑名单（0=全部） |
| `status_Revoked` | int | `0` | 是否已注销（0=全部） |
| `isBindOrg` | int | `0` | 是否绑定组织（0=全部） |
| `registerSource` | int | `0` | 注册来源（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 15 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `id` | int | 2955204541320325 |
| 2 | `create_time` | string | '2025-11-08 01:29:33' |
| 3 | `member_card_grade_code` | int | 2790683528022853 |
| 4 | `mobile` | string | '18620043391' |
| 5 | `nickname` | string | '胡先生' |
| 6 | `register_site_id` | int | 2790685415443269 |
| 7 | `site_name` | string | '朗朗桌球' |
| 8 | `member_card_grade_name` | string | '储值卡' |
| 9 | `system_member_id` | int | 2955204540009605 |
| 10 | `tenant_id` | int | 2790683160709957 |
| 11 | `referrer_member_id` | int | 0 |
| 12 | `point` | float | 0.0 |
| 13 | `user_status` | int | 1 |
| 14 | `status` | int | 1 |
| 15 | `growth_value` | float | 0.0 |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `pay_money_sum` | float |
| `person_tenant_org_id` | int |
| `person_tenant_org_name` | string |
| `recharge_money_sum` | float |
| `register_source` | int |
## 详细字段分析
> 以下内容迁移自旧版 `member_profiles-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
三、主键 / 会员标识类字段
1. id
类型：int
非空：200 条
唯一值个数：199（有 1 个 ID 出现了 2 次，完全重复记录）
含义：
这是“租户内会员账户”的主键 ID。
对应一个 会员在当前租户下的一条账户档案（通常是一张卡/一个账户）。
和其它表的关系（从字段命名推断）：
在余额变更、储值卡列表等表中，通常会有 member_card_id 或类似字段，按系统习惯，这类字段一般就对应这里的 id。
重复记录说明：
id=2799212615616261 的记录在文件中出现了两次，所有字段完全相同，明显是导出过程重复，不是设计层面的问题。
2. system_member_id
类型：int
唯一值个数：199（同样有一个值出现了 2 次，对应上面的重复记录）
含义（结合其它文件）：
这是“系统级会员 ID”，在全平台唯一，用来把一个会员在不同门店/不同卡类型下的账户统一到一个“人”的维度上。
在其它 JSON（例如助教流水）里也出现了 system_member_id，用来标识消费对应哪个会员。
结构关系：
在“会员档案”这张表里，system_member_id 与 id 是一对多的关系（理论上：一人可有多张卡），只是本次截取的数据里恰好只有一人一条记录（除那条导出重复）。
3. member_card_grade_code / member_card_grade_name
这两个字段是成对出现的：一个数值码，一个中文名称。
member_card_grade_code
类型：int
唯一值个数：4
member_card_grade_name
类型：string
唯一值个数：4
从数据可得对应关系：
member_card_grade_code -> member_card_grade_name
2790683528022853 -> "储值卡"
2790683528022855 -> "台费卡"
2790683528022856 -> "活动抵用券"
2790683528022857 -> "月卡"
含义：
这是“会员卡种类/等级”的定义字段。
member_card_grade_code 是内部编码（枚举 ID），member_card_grade_name 是展示用名称。
统计分布（只是为了说明结构，不做盈利分析）：
储值卡：112 条
台费卡：82 条
活动抵用券：4 条
月卡：2 条
结构上的意义：
从设计上看，这张“会员档案”实际上是 “会员 × 卡种” 级别的账户记录：
system_member_id 表示“谁”；
member_card_grade_code/name 表示“哪种卡”；
id 则是这张卡在当前租户下的账号 ID。
四、联系方式与会员展示信息
4. mobile
类型：string
唯一值个数：199（1 个号码重复，对应重复记录）
特征：
全部是 11 位手机号字符串，未发现空字符串或明显无效值。
含义：
会员绑定的手机号码。
结构意义：
在普通业务里，“手机号 + tenant_id”通常具备“会员唯一性”的作用（禁止同租户重复注册同一个手机号）。
在本数据中，手机号重复仅出现在那条重复的会员记录上，可以判断是导出重复，而非同一手机号注册多个账户。
5. nickname
类型：string
唯一值个数：200（每条记录昵称都不同）
含义：
会员在当前租户下的显示名称（可以是姓名，也可以是昵称）。
与助教流水里的 nickname 区分：
助教流水中的 nickname 是“助教昵称”（服务人员），这里的 nickname 是“会员昵称”，虽然字段名相同，但含义不同，关联时要注意表的上下文。
五、注册门店 / 租户维度
6. register_site_id
类型：int
唯一值个数：1
所有记录都是同一个值：2790685415443269
含义：
会员的注册门店 ID。
结构关系：
与其它 JSON 中普遍存在的 site_id 相同（都是“朗朗桌球”这家店的 ID）。
说明本文件的 200 条会员账户，全部是在这家门店注册的。
7. site_name
类型：string
唯一值个数：1
全部为 "朗朗桌球"
含义：
注册门店名称，属于冗余字段，用于直接展示。
与 register_site_id 关系：
register_site_id → 逻辑外键
site_name → 冗余的门店名称快照
8. tenant_id
类型：int
唯一值个数：1
全部为 2790683160709957
含义：
租户/品牌 ID。
确认这批会员都是属于同一个租户“朗朗桌球”（而非连锁多店场景）。
六、推荐关系与成长值字段
9. referrer_member_id
类型：int
唯一值个数：1
全部为 0
含义（按命名推断）：
推荐人会员 ID，用于记录该会员是由哪位老会员推荐。
目前数据的状态：
本批数据中全部为 0，意味着在导出时间范围内，这些会员账户没有记录任何推荐关系（或该功能未使用）。
10. point
类型：float
唯一值个数：1
全部为 0.0
含义：
当前积分余额（这条会员账户的积分值）。
当前状态：
所有账户积分为 0，说明要么积分体系刚启用，要么此数据截取点时，积分未开始累积或未导出非零记录。
11. growth_value
类型：float
唯一值个数：1
全部为 0.0
含义（按常见会员体系设计）：
成长值 / 经验值，用于会员等级晋升的累计指标。
当前状态：
与 point 一样，全部为 0，说明成长体系虽然有字段，但目前没有实际使用或数据尚在初期。
从这三个字段可以看出：
系统预留了“推荐关系 + 积分 + 成长值”的完整会员运营链路，但这家门店在当前截取时间点上基本还处于“只建档案、不玩复杂运营”的状态。结构上功能完备，只是业务上尚未填充数据。
七、状态 / 启用标志相关字段
12. user_status
类型：int，枚举
唯一值个数：1
全部为 1
含义（结合行业惯例）：
用户账号状态（偏“用户逻辑”层面的状态）。
典型枚举可能为：
1：正常启用
0：禁用 / 冻结
其他值：例如已注销等（本数据尚未出现）
当前数据：
全为 1，说明导出的都是正常有效的会员账户。
13. status
类型：int，枚举
唯一值个数：1
全部为 1
含义（按命名推断）：
帐户状态（偏“卡状态/档案状态”）。
在你之前的其它 JSON 里，“status = 1”通常也是“正常”，4 等值用来表示删除/失效等。
当前数据：
同样全部为 1，表示这些档案都是有效的卡档案，没有注销/停用记录被导出。
这里有一个设计上的细节：
user_status 和 status 都是状态字段，属于“业务状态 + 系统状态”并存的设计。
很多系统会用：
user_status 管用户层面（是否允许登录、是否冻结等）；
status 管卡账户本身（卡是否作废、是否挂失）。
在你这份数据里，两者当前值完全一致（都是 1），但从结构上可以看出未来可以出现两者不一致的场景（例如用户已注销但卡余额仍在清算中等）。
八、时间字段
14. create_time
类型：string
格式：YYYY-MM-DD HH:MM:SS
唯一值个数：86
典型样例：
'2025-07-20 20:46:38'（出现 5 次）
'2025-07-20 20:46:36'（5 次）
…
含义：
会员账户的创建时间（即这条档案/这张卡在系统中被创建的时间）。
数据特征：
很多时间戳成批出现（同一时间出现 5 条），高度怀疑是“批量导入/老系统迁移”或“批量开卡”的结果，而不是一条条手动录入。
和其它业务数据（例如消费流水）相比，时间集中在 2025-07-20 晚间，说明这批会员是某个时间点一次性导入的。
九、综合结构判断与和其它 JSON 的关系
从字段设计可以得出以下结构层面的结论（仅从结构出发，不做任何盈利/行为分析）：
记录粒度
每一条 tenantMemberInfos 记录，是一个“会员在当前租户下某个卡种/账户”的档案。
关键组合键可以理解为：
(tenant_id, system_member_id, member_card_grade_code)
或更加具体的主键 id。
与其它表的关联键
与消费流水（台费、助教、商品等）
通过 system_member_id 把会员消费流水与会员档案关联起来。
一些表里还会出现 member_card_id 或类似字段，对应这里的 id。
与储值卡/余额变更/充值等表：
这些表的 member_card_id / system_member_id / tenant_member_id（在不同表叫法略有差异）会与这里的 id 和 system_member_id 做主外键关系。
与门店（site）：
register_site_id 与其他表的 site_id 援用同一门店 ID；site_name 是冗余名称。
枚举字段总结
卡种枚举（明确）：
member_card_grade_code / member_card_grade_name 四种：
储值卡 / 台费卡 / 活动抵用券 / 月卡
状态枚举（当前只见到一种值，但显然是枚举型设计）：
user_status：1（正常）
status：1（正常）
其它预留枚举（当前值全部为单一值）：
referrer_member_id：目前全为 0（“无推荐人”状态）
字段使用状态
已投入使用的字段：
id, system_member_id, member_card_grade_*, mobile, nickname, register_site_id, site_name, tenant_id, create_time, user_status, status。
这些字段组合起来，足以支持基本的会员识别、卡种区分和简单状态管理。
结构上预留但目前几乎未被使用的字段：
referrer_member_id（推荐体系）
point（积分体系）
growth_value（成长值/等级成长体系）
这些字段从结构上完整存在，但在当前数据截面上全部为默认值 0，说明门店尚未使用这些高级运营功能。
分页与导出行为的结构线索
data.total = 438，而本次两个 page 合并只有 200 条，说明：
该接口是典型的分页接口（每页 100 条）；
当前只导出了前两页（或者是时间/条件过滤导致只取到部分）。
id 和 system_member_id 各有一个值重复了两次，且所有字段完全相同：
很可能是分页处理时边界重叠导致的重复（比如页 1 末尾的记录又出现在页 2 的开头），不是数据设计错误。
十、小结：会员档案.json 的角色
从纯字段与结构角度，可以把 20251110_043209_会员档案.json 概括为：
它不是“纯粹的人头表”，而是“会员 × 卡种 的账户档案表”，一条记录既包含“谁”（system_member_id / mobile / nickname），也包含“是什么卡”（member_card_grade_xxx）。
它作为 会员维度的核心参照表，被其它业务表通过 system_member_id 和 id 广泛引用：
消费流水中的会员消费，回来可以通过这些键指向这一表；
储值余额变动、充值、退款等资金类流水，最终也会落到某个 id 所代表的“会员账户/卡”上。
从字段现状可见：门店目前主要使用的是“储值卡 + 台费卡 + 少量月卡/抵用券”的基本功能，重点在“建档与卡种区分”，尚未真正利用积分、成长值、推荐等高级字段。这是“结构完备、业务使用部分开启”的典型状态。

801
docs/api-reference/endpoints/member_stored_value_cards.md Normal file
View File

@@ -0,0 +1,801 @@
# 会员储值卡（GetTenantMemberCardList）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `MemberProfile/GetTenantMemberCardList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/MemberProfile/GetTenantMemberCardList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `member_stored_value_cards` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要 |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `siteId` | int | `2790685415443269` | 门店 ID |
| `cardPhysicsType` | int | `0` | 卡物理类型（0=全部） |
| `status` | int | `0` | 状态（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 68 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `site_name` | string | '朗朗桌球' |
| 2 | `member_name` | string | '胡先生' |
| 3 | `member_mobile` | string | '18620043391' |
| 4 | `member_card_type_name` | string | '活动抵用券' |
| 5 | `table_service_discount` | float | 10.0 |
| 6 | `assistant_service_discount` | float | 10.0 |
| 7 | `coupon_discount` | float | 10.0 |
| 8 | `goods_service_discount` | float | 10.0 |
| 9 | `is_allow_give` | int | 0 |
| 10 | `able_cross_site` | int | 1 |
| 11 | `cardSettleDeduct` | float | 0.0 |
| 12 | `tenantAvatar` | string | '' |
| 13 | `tenantName` | string | '' |
| 14 | `member_card_grade_code_name` | string | '活动抵用券' |
| 15 | `table_discount_sub_switch` | int | 2 |
| 16 | `tableAreaId` | array | [] |
| 17 | `goods_discount_sub_switch` | int | 2 |
| 18 | `goodsCategoryId` | array | [] |
| 19 | `assistant_discount_sub_switch` | int | 2 |
| 20 | `pdAssisnatLevel` | array | [] |
| 21 | `assistant_reward_discount_sub_switch` | int | 2 |
| 22 | `cxAssisnatLevel` | array | [] |
| 23 | `goods_discount_range_type` | int | 1 |
| 24 | `use_scene` | string | '' |
| 25 | `balance` | float | 0.0 |
| 26 | `table_deduct_radio` | float | 100.0 |
| 27 | `table_service_deduct_radio` | float | 100.0 |
| 28 | `goods_deduct_radio` | float | 100.0 |
| 29 | `goods_service_deduct_radio` | float | 100.0 |
| 30 | `assistant_deduct_radio` | float | 100.0 |
| 31 | `assistant_service_deduct_radio` | float | 100.0 |
| 32 | `assistant_reward_deduct_radio` | float | 100.0 |
| 33 | `coupon_deduct_radio` | float | 100.0 |
| 34 | `tableCardDeduct` | float | 0.0 |
| 35 | `tableServiceCardDeduct` | float | 0.0 |
| 36 | `goodsCarDeduct` | float | 0.0 |
| 37 | `goodsServiceCardDeduct` | float | 0.0 |
| 38 | `assistantCardDeduct` | float | 0.0 |
| 39 | `assistantServiceCardDeduct` | float | 0.0 |
| 40 | `assistantRewardCardDeduct` | float | 0.0 |
| 41 | `couponCardDeduct` | float | 0.0 |
| 42 | `deliveryFeeDeduct` | float | 0.0 |
| 43 | `is_allow_order_deduct` | int | 0 |
| 44 | `id` | int | 2955206162843781 |
| 45 | `assistant_discount` | float | 10.0 |
| 46 | `assistant_reward_discount` | float | 10.0 |
| 47 | `bind_password` | string | '' |
| 48 | `card_no` | string | '' |
| 49 | `card_physics_type` | int | 1 |
| 50 | `card_type_id` | int | 2793266846533445 |
| 51 | `create_time` | string | '2025-11-08 01:31:12' |
| 52 | `denomination` | float | 0.0 |
| 53 | `disable_end_time` | string | '0001-01-01 00:00:00' |
| 54 | `disable_start_time` | string | '0001-01-01 00:00:00' |
| 55 | `effect_site_id` | int | 0 |
| 56 | `end_time` | string | '2225-01-01 00:00:00' |
| 57 | `goods_discount` | float | 10.0 |
| 58 | `is_delete` | int | 0 |
| 59 | `last_consume_time` | string | '2025-11-09 07:48:23' |
| 60 | `member_card_grade_code` | int | 2790683528022856 |
| 61 | `register_site_id` | int | 2790685415443269 |
| 62 | `sort` | int | 1 |
| 63 | `start_time` | string | '2025-11-08 01:31:12' |
| 64 | `status` | int | 1 |
| 65 | `system_member_id` | int | 2955204540009605 |
| 66 | `table_discount` | float | 10.0 |
| 67 | `tenant_id` | int | 2790683160709957 |
| 68 | `tenant_member_id` | int | 2955204541320325 |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `able_share_member_discount` | int |
| `electricityCardDeduct` | float |
| `electricity_deduct_radio` | float |
| `electricity_discount` | float |
| `member_grade` | int |
| `principal_balance` | float |
| `rechargeFreezeBalance` | float |
## 详细字段分析
> 以下内容迁移自旧版 `member_stored_value_cards-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
一、文件整体类型与结构
1. 内容类型
从结构看，这个文件其实是 “会员卡列表 / 储值类卡片列表”，并不只包含“储值卡”，而是一个“卡片视图”：
一条记录 = 一张会员卡（已经开通的具体卡）。
记录中同时包含：
卡本身的定义属性（卡种、适用范围、折扣规则等）。
当前账户余额。
持卡会员的基本信息快照（姓名、手机号）。
有效期、最近消费时间等状态信息。
根据字段值，这一页数据中主要有五类卡：
储值卡
活动抵用券
台费卡
酒水卡
月卡
因此，这个 JSON 更准确地理解为：门店下所有储值/次卡/券类会员卡的列表视图。
二、卡片记录字段逐项说明
以下按逻辑分组：卡种信息 / 折扣规则 / 金额与余额 / 时间与有效期 / 会员信息 / 门店与适用范围 / 状态与开关类字段 / 预留扩展字段。
1. 卡种 / 类别相关字段
1.1 卡种主键与类别名称
card_type_id
类型：int
含义：卡种 ID（定义“这是哪一种卡”）。
枚举（按数据分布）：
2793249295533893
2793266846533445
2791990152417157
2794699703437125
2793306611533637
这些 ID 对应不同的卡种配置，具体含义在系统内部的“卡种配置表”中。
member_card_grade_code
类型：int
含义：卡等级/卡类代码，和下面两个名称字段一一对应。
枚举：
2790683528022853 → 储值卡
2790683528022856 → 活动抵用券
2790683528022855 → 台费卡
2790683528022858 → 酒水卡
2790683528022857 → 月卡
member_card_grade_code_name
类型：string
含义：卡等级/卡类名称。
枚举值（与上面 code 一一对应）：
"储值卡"
"活动抵用券"
"台费卡"
"酒水卡"
"月卡"
member_card_type_name
类型：string
含义：卡类型名称，实际与 member_card_grade_code_name 一致。
枚举值同上。
说明：更偏展示用的冗余字段。
结论：虽然文件名叫“储值卡列表”，但从字段看是“会员卡列表”，包含五类卡；card_type_id / member_card_grade_code / member_card_grade_code_name / member_card_type_name 共同定义“这张卡属于哪一类”。
card_physics_type
类型：int
含义：物理卡类型。
当前数据：全部为 1。
推测枚举：
1：实体卡或标准卡；
其他值（未出现）可能代表虚拟卡、第三方卡等。
card_no
类型：string
当前数据：全部为 ""（空）。
含义（推测）：实体卡物理卡号／条码号。当前这批卡看起来全部为“无物理卡号”（可能是全部虚拟卡或卡号隐藏不导出）。
bind_password
类型：string
当前数据：全部 ""。
含义：卡绑定密码，用于消费或查询验证（目前未启用）。
use_scene
类型：string
当前数据：全部 ""。
含义：卡使用场景说明（比如“仅店内使用”“仅团建”等），本门店尚未使用此字段。
2. 会员信息与关联字段
这些字段把卡和会员档案关联起来。
member_name
类型：string 或 null
含义：持卡会员姓名快照。
特点：存在 null（20 张卡没有绑定会员名字）。
member_mobile
类型：string 或 null
含义：持卡会员手机号快照。
特点：与 member_name 对应，多数有值，少量为 null。
system_member_id
类型：int
含义：系统级会员 ID（跨门店统一主键）。
枚举特征：
0：约 20 条，为“未绑定具体会员”或“散客卡”。
非 0：与“会员档案.json”中的 system_member_id 对应。
tenant_member_id
类型：int
含义：当前商户（品牌/租户）中会员的主键 ID。
枚举特征：
0：同样是未绑定会员的卡。
非 0：与“会员档案.json”中的 id 对应。
关系：
这两个字段共同完成“卡 → 会员”的双钥匙关联：
system_member_id：全局会员；
tenant_member_id：本租户内会员档案主键。
3. 门店与适用范围字段
site_name
类型：string
当前值：全部为 "朗朗桌球"。
含义：卡归属门店名称（视图中的展示字段）。
tenantName
类型：string
当前值：全部为 ""。
含义：租户/品牌名称（当前导出为空）。
tenantAvatar
类型：string
当前值：全部为 ""。
含义：品牌头像 URL（未配置）。
tenant_id
类型：int
含义：租户/品牌 ID，与其他 JSON 中 tenant_id 一致。
register_site_id
类型：int
当前值：全部 2790685415443269。
含义：卡首次办理的门店 ID。
对应门店的 site_id；本数据中所有卡都是在同一家门店开卡。
effect_site_id
类型：int
当前值：全部 0。
含义（推测）：卡片限定生效门店 ID。
为 0 时，配合 able_cross_site=1，可解释为“所有门店可用”。
able_cross_site
类型：int，枚举。
当前值：全部 1。
含义：是否允许跨店使用。
1：可以跨门店使用；
0：仅限开卡门店。
结合 effect_site_id=0 可以解读为：当前卡种都配置为“全门店通用”。
4. 金额与余额类字段
balance
类型：float
含义：当前卡内余额（主要针对储值卡、部分券卡）。
特征：
有 59 个不同的值，大部分是 0.0，其它有 985、500、若干小数等。
对于“活动抵用券”“月卡”等，有可能余额意义不同（只是当前视图统一用 balance 作为额度字段）。
denomination
类型：float
当前值：全部 0.0。
含义（推测）：面额/初始储值额度。
本页数据未填充此字段；可能在分类型卡（如次卡/券）中才有意义，或者另有配置表。
5. 各类折扣与抵扣规则字段
这一块字段非常多，但结构有明显统一性：
按“消费场景 × 折扣类型”来区分。
三大消费场景：
台费：table_*
商品：goods_*
助教：assistant_* / assistant_reward_* / assistant_service_*
再叠加：
discount：折扣（打几折）
service_discount：服务类折扣
discount_sub_switch：折扣是否叠加/替代
deduct_radio：这类消费是否允许扣卡 & 扣卡比例（百分比）
CardDeduct：扣卡金额
ServiceCardDeduct、RewardCardDeduct：扣卡金额的不同“资金子账户”（储值金 / 服务金 / 奖励金）
5.1 折扣百分比类（打几折）
table_discount / goods_discount / assistant_discount / assistant_reward_discount / table_service_discount / goods_service_discount / assistant_service_discount
类型：float
当前值：全部 10.0（所有字段）。
含义：
采用“几折”的记法：10=不打折，9=九折，8=八折。
现状：当前这批卡，在所有场景/子场景（台费、商品、助教、奖励金）上的折扣统一都是 10.0，表示没有折扣设置。
5.2 折扣叠加开关
table_discount_sub_switch / goods_discount_sub_switch / assistant_discount_sub_switch / assistant_reward_discount_sub_switch
类型：int，枚举。
当前值：全部 2。
含义（推测）：“折扣是否叠加/替换其他折扣”的开关。
可能枚举：
1：叠加其他折扣；
2：不叠加，仅用卡折扣；
具体枚举值需看后台配置，但从命名能看出是折扣叠加策略字段。
5.3 抵扣比例类（%）
table_deduct_radio / goods_deduct_radio / assistant_deduct_radio / table_service_deduct_radio / goods_service_deduct_radio / assistant_service_deduct_radio / coupon_deduct_radio
类型：float
当前值：全部 100.0。
含义：允许从该卡余额中抵扣的比例（百分比）。
100.0 表示允许 100% 用卡余额支付该类消费；
如果是 0，通常表示不允许该类消费抵扣。
当前：卡配置为“理论上所有消费场景都可以全额用卡支付”，只是在折扣、金额层面没有特别设定。
5.4 实际扣卡金额设置（配置层）
cardSettleDeduct
类型：float
当前值：0.0。
含义：结算时从卡中扣除的金额上限/规则配置（视图级；实际扣款在交易流水里体现）。
tableCardDeduct / goodsCarDeduct / assistantCardDeduct
类型：float
当前值：全部 0.0。
含义：针对台费/商品/助教三类消费的扣卡金额配置（类似“每小时从卡里扣 xx 元”或“每次抵扣 xx 元”的规则）。
当前：所有为 0，说明在卡定义层面并没有指定固定扣卡金额，而是按照一般储值逻辑消费。
tableServiceCardDeduct / goodsServiceCardDeduct / assistantServiceCardDeduct
类型：float
当前值：全部 0.0。
含义：如果系统中区分“储值金、服务金、奖励金”等子账户，这三个字段对应“服务金”子账户的扣款配置。
当前未启用。
assistantRewardCardDeduct
类型：float
当前值：0.0。
含义：助教奖励金方向扣款的配置。
当前未启用。
assistantRewardCardDeduct（拼写略有不同）
实际字段名是 assistantRewardCardDeduct，同上意义，当前为 0。
couponCardDeduct
类型：float
当前值：0.0。
含义：与卡绑定的“券额度扣除配置”。
deliveryFeeDeduct
类型：float
当前值：0.0。
含义：配送费可否/多少从卡中抵扣，目前无业务发生。
综合来看：本门店的卡片在“规则配置层”预留了大量细粒度控制字段，但目前实际使用只体现在“balance”和“可用范围”，折扣和具体扣卡规则基本都未启用（全部保持默认值 10 折、100%比例、0 扣款），真正扣款逻辑在交易流水中体现。
6. 时间与有效期相关字段
create_time
类型：string，格式 YYYY-MM-DD HH:MM:SS
含义：卡片创建时间（开卡时间）。
start_time
类型：string
含义：卡片生效开始时间（有效期起始）。
end_time
类型：string
含义：卡片有效期结束时间。
start_time / end_time 组合就是卡的有效期。不同卡种有效期配置不同，如储值卡长效、月卡固定一个月等。
disable_start_time / disable_end_time
类型：string
当前值：全部 "0001-01-01 00:00:00"。
含义：停用时间段（比如临时冻结卡的起止时间）。
当前未启用，所有卡都是“未进入停用窗口”。
last_consume_time
类型：string
含义：最近一次消费时间。
特点：
对未消费过的卡，值为 "1970-01-01 00:00:00"（典型“未初始化时间”的占位值）。
对已消费卡，则记录最后一次交易时间。
7. 卡状态与逻辑标志
status
类型：int，枚举。
取值：
1：196 条；
4：4 条。
含义（推测）：
1：正常可用；
4：过期/停用/作废（具体哪一种需要结合系统配置和有效期判断）。
从结构看，这是卡当前状态的核心字段。
is_delete
类型：int，枚举。
当前值：0。
含义：逻辑删除标志。
0：未删除；
1：逻辑删除（软删除）。
is_allow_give
类型：int，枚举。
当前值：0。
含义：是否允许转赠/转让给其他会员。
0：不允许；
1：允许转赠。
is_allow_order_deduct
类型：int，枚举。
当前值：0。
含义：是否允许在“订单层面统一扣款”。
0：不允许（仅按项目扣卡）；
1：允许整单抵扣。
8. 适用范围扩展字段（列表）
tableAreaId
类型：list
当前值：全部 []。
含义：限定可使用的台区 ID 列表。
为空表示“不限制台区”。
goodsCategoryId
类型：list
当前值：全部 []。
含义：可用的商品分类 ID 列表。
为空表示对所有商品分类有效。
pdAssisnatLevel
类型：list
当前值：全部 []。
含义：允许使用的“陪打/助教等级”列表。
为空表示不限制助教等级。
cxAssisnatLevel
类型：list
当前值：全部 []。
含义：可能是“促销活动中的助教等级限制”（命名中 cx 多为“促销”缩写）。
当前未设置任何限制。
9. 其他字段
cardSettleDeduct
已在扣卡规则部分说明，当前为 0。
tableAreaId / goodsCategoryId / pdAssisnatLevel / cxAssisnatLevel
已上文说明：均为扩展限定维度，当前全部为空列表。
sort
类型：int
含义：在前端展示或某些列表中的排序权重。
具体取值分布不重要，主要反映展示优先级。
三、与其他 JSON 的结构性关联（从字段角度）
只从字段关系来讲，不做任何金额/盈利分析：
与《会员档案.json》：
tenant_member_id ↔ 会员档案中的 id
system_member_id ↔ 会员档案中的 system_member_id
卡片列表是“余额视图”，会员档案是“会员主体信息维表”。
与储值/卡交易流水（如果有单独的“储值卡交易明细” JSON）：
应通过某个卡 ID（本文件中未见显式“card_id”，推测是 tenant_member_id + card_type_id 组合或还有一个隐藏键）。
本文件记录的是“当前余额”和规则；交易流水才是每次充值/消费的明细。
与台费流水 / 助教流水 / 门店销售记录：
折扣/抵扣规则维度：
台费相关：table_discount、table_deduct_radio 等；
商品相关：goods_discount、goods_deduct_radio 等；
助教相关：assistant_discount、assistant_deduct_radio 等。
在真正的消费记录里，会根据这些规则确定“从卡中扣多少”、“实际应收多少”，对应字段往往是“coupon_deduct_money”、“member_discount_amount”等。
与门店档案 / 台桌列表：
通过 register_site_id & site_name 与门店档案关联；
扩展字段 tableAreaId 理论上可以和台桌区域表关联（当前为 []，即不限制）。
与“门店销售汇总/对账视图”：
这个文件本质上是“卡余额视图”，余额字段会被用于对账和资产统计，但对应明细还是要依赖卡交易流水。
四、结构层面的几个重要线索（不涉及大数据和盈利分析）
从字段结构可以看出：
这是一个高度通用的“会员卡规则+余额视图”
同一张卡可以同时配置“台费折扣/商品折扣/助教折扣”，“储值金/服务金/奖励金”等多个子账户的使用规则。
当前门店只启用了“普通储值余额 + 全默认折扣”的简单模式，但字段结构明显支持更复杂的业务。
卡与会员，是多对一关系
一个会员可以有多张卡（不同 card_type_id / member_card_grade_code）。
每条记录都持有 system_member_id 和 tenant_member_id，即随时能从卡追溯到会员。
卡的有效期体系是严密的
有效期：start_time + end_time
停用窗口：disable_start_time + disable_end_time（当前未启用）
状态位：status、is_delete
最近使用：last_consume_time
这套结构足以支持：正常→停用→恢复→过期等多阶段。
适用范围具有多维度控制能力
门店维度：able_cross_site、effect_site_id、register_site_id
台区维度：tableAreaId
商品分类维度：goodsCategoryId
助教等级维度：pdAssisnatLevel、cxAssisnatLevel
当前门店这些维度都未限制，但字段设计说明系统支持非常细的策略，例如“某卡只在特定台区/特定商品/特定等级助教时可用”。
折扣与抵扣机制被拆得非常细
折扣（discount 系列）、抵扣比例（deduct_radio 系列）、抵扣金额（CardDeduct 系列），再叠加“服务金”“奖励金”这种资金子账户。
结构上完全可以做到：“这张卡台费九折、但最多只允许 50% 金额由卡支付，剩余必须现金；助教可全额抵扣但不打折”等非常复杂的组合。
当前导出数据处于“规则未开启、余额为主”的轻量使用阶段
折扣全部是 10.0；
抵扣比例全部 100.0；
各类 CardDeduct 字段全部为 0；
disable_* 时间全部为 0001-01-01；
很多扩展维度字段为空列表。
说明：门店暂时只使用了“储值余额 + 卡类型 + 有效期 + 会员关联”几块核心功能。

459
docs/api-reference/endpoints/payment_transactions.md Normal file
View File

@@ -0,0 +1,459 @@
# 支付流水（GetPayLogListPage）
> 自动生成于 2026-02-13 | 数据来源：实时 API
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `PayLog/GetPayLogListPage` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/PayLog/GetPayLogListPage` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `payment_transactions` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（StartPayTime / EndPayTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `StartPayTime` | string | `"2026-02-01 08:00:00"` | 支付起始时间 |
| `EndPayTime` | string | `"2026-02-13 08:00:00"` | 支付结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `OnlinePayChannel` | int | `0` | 在线支付渠道（0=全部） |
| `paymentMethod` | int | `0` | 支付方式（0=全部） |
| `relateType` | int | `0` | 关联类型（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 11 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
| 2 | `create_time` | string | '2026-02-13 04:49:48' |
| 3 | `pay_amount` | float | 0.0 |
| 4 | `pay_status` | int | 2 |
| 5 | `pay_time` | string | '2026-02-13 04:49:48' |
| 6 | `online_pay_channel` | int | 0 |
| 7 | `relate_type` | int | 2 |
| 8 | `relate_id` | int | 3092711340902597 |
| 9 | `site_id` | int | 2790685415443269 |
| 10 | `id` | int | 3092712422508741 |
| 11 | `payment_method` | int | 4 |
## 详细字段分析
> 以下内容迁移自旧版 `payment_transactions-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
二、字段逐一说明（含类型、枚举、可能含义）
1. 门店维度字段
1.1 siteProfile
类型：对象（Object）
含义：门店信息快照，与其他 JSON 中的 siteProfile 结构一致。
关键子字段（只列最重要的，结构与前面文件相同）：
id：门店 ID（本数据中固定为 2790685415443269）。
org_id：组织 ID。
shop_name：店名（例如“朗朗桌球”）。
full_address / address：详细地址 / 简要地址。
business_tel：门店电话。
longitude / latitude：经纬度。
tenant_id：租户 ID。
site_label：门店标签（如 “A”）。
shop_status：门店状态枚举（本数据中为 1，表示正常营业）。
以及 WIFI、灯控、客服二维码等配置字段。
说明：
siteProfile.id 与本记录的 site_id 完全一致。
在整个系统中，这是一份门店维度的冗余快照，方便前端和报表使用。
1.2 site_id
类型：整数（long）
观测：所有记录均为 2790685415443269。
含义：支付记录所属的门店 ID。
关联关系：
与其他所有 JSON 中的 site_id / siteId 对应，是全局的门店外键。
与 siteProfile.id 相同，保证“门店维度”一致。
2. 支付流水主键与业务关联
2.1 id
类型：整数（long）
特征：200 条记录中的 id 全部唯一。
含义：支付流水记录的主键 ID。
作用：
在“支付记录”这个表内部，唯一标识一条支付流水（包括金额为 0 的记录）。
2.2 relate_type
类型：整数（int），明显是 枚举字段。
观测到的枚举值及数量：
2：出现 196 次。
5：出现 3 次。
1：出现 1 次。
含义（从结构与其他表关联推断）：
表示“这条支付记录关联的业务类型”。
不同的 relate_type，relate_id 指向不同业务表：
relate_type = 2：
通过数据实际比对，可以确认：
relate_id 对应 结账记录.json 中的 settleList.id（即结账单 ID / order_settle_id）。
本类型是“结账单支付流水”。
relate_type = 5：
通过与 会员卡流水（tenantMemberCardLogs） 的比对：
在 tenantMemberCardLogs 中，存在字段 relate_id = 本表.relate_id，from_type = 3，且有充值金额 account_data。
因此可以判断：relate_type = 5 对应“会员卡余额/充值类业务”的支付流水。
relate_type = 1：
当前样本中只有 1 条，且在其他 JSON 中没有找到同 ID 的记录，具体业务类型不明，结构上可先视作“其他业务类型（预留枚举值）”。
总结：relate_type 是“支付关联业务类型”的枚举，至少包括：
2：结账单支付；
5：会员卡充值/账户操作支付；
1：其他少见业务类型（暂不确定）。
2.3 relate_id
类型：整数（long）
特征：
200 条记录中，relate_id 全部互不重复（n_unique=200）。
含义：关联业务记录的主键 ID（按 relate_type 不同指向不同表）。
具体关联关系：
当 relate_type = 2：
relate_id = 结账记录表（结账记录.json）中 settleList.id。
即：一条结账单，会在本表中对应一条支付记录（当前样本里是一对一，结构上允许扩展为一对多）。
当 relate_type = 5：
relate_id = 会员卡流水（tenantMemberCardLogs）中的 relate_id 字段，而非该表的主键 id。
说明：充值/余额变更有自己的“业务单号”，该单号在支付记录和会员卡流水中共享。
当 relate_type = 1：
未在其他已解析表中找到对应 ID，只能确认它是一种保留业务类型。
3. 支付金额与时间字段
3.1 pay_amount
类型：浮点数（float）
观测数据：
不同取值共 36 个。
最小值：0.0，最大值：3000.0。
分布特征（只看结构）：
0.0：出现 140 次。
其他典型值：4.0, 5.0, 6.0, 10.0, 14.0, 15.0, 20.0, 48.0, 96.0, 1000.0, 3000.0 等。
含义（结构层面）：
本条支付流水的“支付金额”，单位为元。
特别情况：
140 条 pay_amount = 0 的记录，其 (relate_type, payment_method) 组合全部为 (2, 2)。
从结构角度看，可以解读为：
这部分支付流水记录通过 payment_method=2 标记了某种支付渠道，但金额为 0；
金额实际可能由其他渠道/卡券抵扣（具体业务逻辑不在本次分析范围）。
这里仅说明“0 元支付记录在结构上是合法且被大量使用的”。
3.2 create_time
类型：字符串（string），格式 "YYYY-MM-DD HH:MM:SS"
特征：
200 条记录中，create_time 全部唯一。
含义：
支付记录创建时间，通常与发起支付请求的时间一致（创建支付流水的时间戳）。
3.3 pay_time
类型：字符串（string），格式同上。
特征：
200 条记录中，pay_time 也全部唯一。
在数据中 create_time 与 pay_time 多数完全一致，说明支付完成较快。
含义：
实际支付完成时间（支付状态变为成功的时间戳）。
从结构角度：
create_time 可以用来追踪“付费动作发起时间”。
pay_time 记录“支付成功时间”。
在异步支付场景，二者有可能不一致（当前样本中大多相同）。
4. 支付状态与渠道、方式字段
4.1 pay_status
类型：整数（int），枚举。
样本情况：所有记录 pay_status = 2。
含义（结合命名和导出结果推断）：
支付状态枚举字段。
当前导出只包含状态为 2 的记录，很明显是“支付成功”的状态。
其他可能存在的枚举值（未出现在本数据中）：
例如 0=未支付，1=支付中，3=支付失败，4=已退款等（仅示例，具体需参考系统配置）。
结论（结构）：
导出的 支付记录.json 是“成功支付流水”的子集，其他状态被过滤掉。
4.2 payment_method
类型：整数（int），枚举。
样本分布：
2：140 条记录。
4：60 条记录。
含义：
支付方式枚举，例如微信、支付宝、现金、银行卡、储值卡等某一种。
当前数据中只出现了 2 种枚举值，但没有文字说明映射关系。
从结构角度的判断：
这是区分不同支付“方式/通道”的关键字段；
应与系统中的“支付方式配置表”存在映射关系（本次导出未包含该配置表）。
需要注意：
虽然可以猜测 2 和 4 可能对应常见通道（如微信/支付宝等），但在缺乏配置表的情况下不宜直接下结论，这里只确认它是“支付方式枚举”的字段。
4.3 online_pay_channel
类型：整数（int），枚举。
样本情况：所有记录 online_pay_channel = 0。
含义（命名层面）：
线上支付渠道枚举，例如：
0：无 / 线下；
1：微信；
2：支付宝；
……
但当前时间范围内，所有记录均为 0，没有其他枚举值出现。
结构特点：
这个字段是为细分“在线支付通道”准备的；
当前门店在本次导出时间段内，可能没有使用该字段（或所有支付统一走某种方式未拆分）。
5. 其他结构性字段
这里主要就是前面已经涉及的：
siteProfile：门店快照（对象）。
site_id：门店 ID，所有记录相同。
id：支付流水主键。
relate_type & relate_id：业务关联键。
没有额外隐藏字段，本表结构很精简、单一职责较强。
三、与其他 JSON 的关联关系（从字段角度）
本表核心作用：承载“支付结果”层面的信息，通过 relate_type + relate_id 把不同业务域的流水（结账单、会员卡流水等）统一串到“支付系统”上。
1. 与结账记录（结账记录.json）的关系
关联字段：
当 relate_type = 2 时：
支付记录.relate_id = 结账记录.settleList.id
结构含义：
每一笔结账单（settleList.id）对应一条支付记录（当前样本中是一条记录，relate_id 唯一）。
通过这个关系，可以：
从结账记录跳转到对应的支付记录；
从支付记录反查对应的结账单。
补充：
在整个系统中，结账记录.id 也对应各类明细表的 order_settle_id（台费、助教等），因此：
支付记录 间接成为连接“支付系统”与“台费/助教/商品明细”的桥梁。
2. 与会员卡流水（tenantMemberCardLogs）/ 余额变更记录的关系
对于 relate_type = 5 的记录：
在 tenantMemberCardLogs 中存在：
tenantMemberCardLogs.relate_id = 支付记录.relate_id
tenantMemberCardLogs.payment_method = 支付记录.payment_method
tenantMemberCardLogs.account_data = 充值金额（例如 1000.0）。
结构含义：
这些支付记录对应的业务类型是“会员卡余额充值/账户变动”。
relate_id 在这里扮演“充值业务单号”的角色，在支付表和会员卡流水中共享。
3. 与门店维度的关系
site_id 与各个表（结账记录、台费流水、助教流水等）的 site_id 一致。
siteProfile 作为冗余的门店信息快照，与其他文件中的门店快照结构一致。
4. 与结算/小票维度的间接关系
支付记录 →（通过 relate_id）→ 结账记录 →（通过 id/orderSettleId）→ 小票详情/台费/助教明细。
结构上，这构成一条完整的链路：
业务明细表（台费/助教等）只记录“消费内容”；
结账记录汇总明细，形成一条“结算单”；
支付记录在“结算单”基础上记录“实际支付行为”。
四、本表暴露出的结构性设计特点和线索
从纯结构、字段设计角度，本表有几个明显的设计意图和特点：
强烈的“统一支付网关”设计
通过 (relate_type, relate_id) 组合，支付系统不直接关心支付的是“台费单、结账单还是会员卡充值单”，而是：
不同业务系统约定一个 relate_type；
将各自的业务主键（或业务单号）写入 relate_id。
这样整个支付层可以统一处理资金动作，而上层业务只需按约定填字段。
支付成功流水视角，非全量支付事件日志
pay_status 全部为 2；
没有看到待支付、失败、关闭等状态。
说明当前导出的 支付记录.json 实际上是“支付成功流水卡片”，而不是“完整交易生命周期日志”。
对数据建模时，应该把“支付记录”视为 成功资金落地的事实表。
支付方式与线上渠道双层枚举结构
payment_method：高层次区分支付方式（现金/卡/微信/支付宝/储值卡等）；
online_pay_channel：更细粒度区分“线上支付通道”（按实际配置可能划分微信/支付宝等）。
当前样本中 online_pay_channel 全为 0，说明这个维度还没被实际利用，但结构已经预留，用于以后精细化拆分。
允许一单多笔支付的设计空间
结构上，relate_id 并没有强制唯一，可以允许：
同一个 relate_id + 不同 payment_method；
同一结账单部分现金、部分在线等组合支付。
虽然本时间段样本中每个 relate_id 只出现一次（对 relate_type=2 来说），但从设计上看，完全可以扩展为一对多。
在后续建模时不要假定“一个 relate_id 一定只对应一条支付记录”，这只是当前时间段的实际情况。
0 元支付流水的大量存在
规模：200 条记录中，有 140 条 pay_amount = 0，且全部 (relate_type=2, payment_method=2)。
结构意义：
系统会对“金额为 0 的支付动作”也产生支付流水记录，这可能是为了：
记录“某个支付方式参与了本单，但实际金额由其他方式/卡券承担”；
或记录内部结算/记账动作。
对后续分析和建模来说，不能简单按“pay_amount > 0”过滤数据，否则会丢失一大批结构上真实存在的支付行为。
门店维度冗余一致性
site_id 与 siteProfile.id 始终一致；
该模式与台费流水、助教流水、结账记录中的门店设计完全统一。
这种“一份数字外键 + 一份冗余快照”的模式，对于你后面做数据中台/数仓建模有直接影响：
在数仓中一般会把 site_id 建成维度外键；
siteProfile 只在上游 ODS 层保留快照，DW 层不一定全量展开。

718
docs/api-reference/endpoints/platform_coupon_redemption_records.md Normal file
View File

@@ -0,0 +1,718 @@
# 平台券核销记录（GetOfflineCouponConsumePageList）
> 自动生成于 2026-02-13 | 数据来源：实时 API
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Promotion/GetOfflineCouponConsumePageList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/Promotion/GetOfflineCouponConsumePageList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `platform_coupon_redemption_records` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `couponChannel` | int | `0` | 优惠券渠道（0=全部） |
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `couponUseStatus` | int | `0` | 优惠券使用状态（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 26 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
| 2 | `id` | int | 3092405812332869 |
| 3 | `tenant_id` | int | 2790683160709957 |
| 4 | `site_id` | int | 2790685415443269 |
| 5 | `sale_price` | float | 20.26 |
| 6 | `coupon_code` | string | '0108919359400' |
| 7 | `coupon_channel` | int | 1 |
| 8 | `site_order_id` | int | 3092345641453701 |
| 9 | `coupon_free_time` | int | 0 |
| 10 | `use_status` | int | 1 |
| 11 | `create_time` | string | '2026-02-12 23:37:54' |
| 12 | `is_delete` | int | 0 |
| 13 | `coupon_name` | string | '【全天可用】中八桌球一小时（大厅A区）' |
| 14 | `coupon_cover` | string | '' |
| 15 | `coupon_remark` | string | '' |
| 16 | `channel_deal_id` | int | 1128411555 |
| 17 | `group_package_id` | int | 0 |
| 18 | `consume_time` | string | '2026-02-12 23:37:55' |
| 19 | `groupon_type` | int | 1 |
| 20 | `coupon_money` | float | 48.0 |
| 21 | `operator_id` | int | 2790687322443013 |
| 22 | `operator_name` | string | '收银员:郑丽珊' |
| 23 | `table_id` | int | 2793002808987781 |
| 24 | `certificate_id` | string | '5017032743553662850' |
| 25 | `verify_id` | string | '' |
| 26 | `deal_id` | int | 1345108507 |
## 详细字段分析
> 以下内容迁移自旧版 `platform_coupon_redemption_records-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
2. 记录内容类型
每条记录对应 一次第三方团购券的核销事件，属于“平台券（如美团等）在门店被实际使用”的流水：
一张券被核销一次 → 产生一条记录；
包含与外部平台有关的信息（券码、平台 dealId、certificateId 等）；
包含与门店内部业务关联的信息（门店 ID、订单 ID、球台 ID、操作员等）。
二、字段逐项详解（含类型与枚举）
下面按逻辑分组逐一说明所有字段。
1. 门店 / 商户相关字段
1.1 tenant_id
类型：int
含义：商户/租户 ID（品牌级别）。
特点：本文件中为固定值（同一个品牌“朗朗桌球”）。
关联：
与其他所有 JSON 中的 tenant_id 一致，用于区分不同品牌/商户的数据域。
枚举：非枚举，是长整型主键。
1.2 site_id
类型：int
含义：门店 ID。
特点：本数据集中恒定为同一数值，对应同一家门店。
关联：
对应 siteProfile.id；
在其他 JSON（台费流水、门店销售记录、会员档案等）中也作为门店维度字段出现。
枚举：非枚举，长整型主键。
1.3 siteProfile
类型：object
含义：门店信息快照。
主要子字段（只列结构性有用的）：
id：站点 ID，与上面的 site_id 相同。
org_id：组织 ID（上级组织/集团内组织结构）。
shop_name：门店名称（例如“朗朗桌球”）。
business_tel：门店电话。
full_address / address：完整地址 / 显示地址。
longitude / latitude：经纬度。
tenant_site_region_id：地域编码。
auto_light：是否自动控灯（1/0 枚举）。
attendance_enabled：是否启用考勤（1/0 枚举）。
shop_status：门店状态（1=营业中；其他值可能代表停业、装修等）。
作用：为每条验券记录提供门店维度的冗余信息，方便报表直接展示，无需再联表查门店档案。
枚举字段集中出现在 siteProfile 内，但这些枚举在本文件分析的重点不在此，就不展开逐个枚举值。
2. 券本身的身份字段
这些字段用于标识“是哪一张券、来自哪个平台、是哪一种团购产品”。
2.1 coupon_code
类型：string
含义：券码，顾客出示的团购券密码/编号。
特点：
本文件 200 条记录中，coupon_code 全部互不相同，是天然的业务唯一键（自然主键）。
用途：
业务上用于核销时输入/扫码；
技术上可作为查询、去重、幂等控制的重要索引。
枚举：非枚举，业务唯一标识符。
2.2 certificate_id
类型：string
含义：平台侧的凭证 ID（通常由第三方团购平台生成的券实例 ID）。
特点：
大部分是 16~19 位的纯数字字符串。
有重复值（同一个 certificate_id 在本文件中可出现 2 条记录，说明该凭证在不同 context 下被处理过）。
用途：对接第三方接口时用于对账、查询核销结果。
枚举：非枚举，外部主键。
2.3 verify_id
类型：string
含义：平台核销记录 ID（某些平台会为每一次核销生成一个唯一 ID）。
特点：
绝大部分记录为空字符串 ""；
少量记录有非空值（共 19 个不同值），说明仅部分平台或部分版本会回传这个 ID。
用途：当存在时，可以精准反查平台侧核销记录。
枚举：非枚举，外部主键，允许为空。
2.4 coupon_name
类型：string
含义：团购券产品名称（即第三方平台上向顾客展示的名称）。
示例：
【全天可用】中八桌球一小时（A区）
【全天可用】中八桌球两小时（B区）
1小时中八台球|【11月特惠】（A区）
【双11特惠】中八桌球一小时（A区）
等共 9 种名称。
特点：
与 deal_id、sale_price、coupon_money 一起，可以唯一描述一个团购商品的“规格”。
枚举：值域有限，但从设计上看是普通字符串，不是严格意义的枚举字段（新增套餐时会增加新名字）。
2.5 coupon_channel
类型：int（枚举）
观测值：1、2
含义：券来源渠道（第三方平台渠道编号）。
1：平台渠道 1（例如：某团购主平台）。
2：平台渠道 2（例如：同集团的另一 App，或不同入口）。
备注：具体“1 对应哪家平台，需要查系统配置”，从字段名和数值分布只能确认“它是平台渠道枚举”。
2.6 groupon_type
类型：int（枚举）
观测值：全部为 1
含义：团购券类型。目前只出现一种类型，可能含义：
1 = 标准团购券；
其他值（未在本数据中出现）可能代表“次卡、套餐券、权益券”等类型。
说明：从结构设计看是枚举字段，只是当前导出时间段只有一种类型。
2.7 channel_deal_id
类型：int
含义：渠道侧 dealId / 产品 ID，一般是第三方平台给该团购商品定义的主键。
特点：
值域有限，有约 9 个不同取值；
与 coupon_name 一一对应（不同名称对应不同 channel_deal_id）。
用途：
对接平台接口时，反查“是哪一个团购商品”；
对账时，用于按平台产品维度统计核销量。
2.8 deal_id
类型：int
含义：另一个层次的团购产品 ID。
特点：
大部分记录为非 0 的整数（如 1345108507 等），也有部分记录 deal_id = 0。
与 coupon_name 的对应关系：
例如：
【全天可用】中八桌球一小时（A区） → deal_id = 1345108507
【全天可用】中八桌球两小时（A区） → 1346103574
1小时中八台球|【11月特惠】（A区） → 1364921087
部分“斯诺克两小时”“双11特惠”类券 → deal_id = 0（内部未配置或未同步）。
推断：
deal_id 更像是平台/系统内部统一的产品 ID；
channel_deal_id 则偏向“渠道侧产品 ID”（当 deal_id 为 0 时，仍有 channel_deal_id，说明渠道信息完整，而内部映射缺失）。
2.9 group_package_id
类型：int
观测值：本文件中 全部为 0。
设计含义（根据命名推断）：
用于关联内部“团购套餐”定义表的主键，对应“团购套餐.json”中某个套餐的 id。
现状：
当前导出数据里，平台券没有被映射到内部“团购套餐”，所以一直是 0；
字段从结构上看是预留的外键字段。
3. 金额 / 面值相关字段
3.1 sale_price
类型：float
含义：顾客在第三方平台上实际支付的价格（团购售价）。
观测值（有限集合）：
11.11、29.9、39.9、59.9、69.9、128.0
特点：
与 coupon_name、coupon_money 一起描述出商品的销售策略；
始终小于对应的 coupon_money（体现“折扣价/团购价”这一结构事实）。
3.2 coupon_money
类型：float
含义：券面值 / 套餐价值（系统层面的“可抵扣金额或对应套餐价值”）。
观测值：
48.0、58.0、68.0、96.0、116.0、288.0
特点：
固定组合关系，例如：
coupon_name = 【全天可用】中八桌球一小时（A区）
→ sale_price = 29.9，coupon_money = 48.0
coupon_name = 1小时中八台球|【11月特惠】（A区）
→ sale_price = 11.11，coupon_money = 48.0
这体现出系统层面区分“顾客支付价”和“券可抵扣价值”。
3.3 coupon_free_time
类型：int
单位：秒
观测值：本文件中全部为 0
含义（根据命名）：
券附带的“免费时长”字段（例如送多少分钟台费）；
若券中包含赠送时长，则理论上应是正数，当前数据中没有此情况。
现状：字段结构已预留，但当前导出时间段内均无赠送时长。
4. 使用状态与时间字段
4.1 use_status
类型：int（枚举）
观测分布：
值 1：198 条
值 2：2 条
含义（结合常见券系统习惯推断）：
1：已使用 / 已核销（正常消耗）；
2：已退款 / 已撤销 / 使用后反冲（极少数记录）。
结构说明：
这是判断券当前生命周期状态的核心字段；
与 is_delete 不同，is_delete 是逻辑删除标志，而 use_status 是业务状态。
4.2 create_time
类型：string
格式："YYYY-MM-DD HH:MM:SS"
含义：验券记录在本系统中创建的时间（记录入库时间）。
特点：
与 consume_time 通常只相差 1 秒左右。
可视为“系统记录时间”。
4.3 consume_time
类型：string
格式同上。
含义：券被核销/使用的业务时间。
特点：
在所有记录中都非空；
对于 use_status=2 的记录，consume_time 仍有值，说明先发生“使用”，后续才在其他流程中被退/撤。
结构上的结论：
create_time 更偏向“记录生成时间”，
consume_time 是“业务使用时间”，后者更意义上代表核销时间。
5. 订单 / 球台 / 操作员关联字段
5.1 site_order_id
类型：int
含义：门店内部的订单 ID（平台券核销时对应的店内订单）。
关联：
与台费流水、门店销售记录、助教流水等中出现的订单 ID 字段对应，用于把“平台券核销记录”挂到一笔本地订单上。
后续可以用 site_order_id 去对照：
该订单有哪些台费记录；
是否有商品销售记录；
是否用了其他优惠（储值卡、折扣等）。
索引意义：
可以作为查询入口之一（按订单维度查看该订单有没有用平台券）。
5.2 table_id
类型：int
含义：使用券的球台 ID。
关联：
与“台桌列表”中的 id 对应；
间接关联到 table_name、table_area 等静态信息（在本文件中不重载这些名称，统一在台桌档案中维护）。
结构意义：
用于统计每张台桌通过平台券带来的使用量；
与台费、助教流水一起，可从结构上看到“同一台桌由平台券带来的流量”。
5.3 operator_id
类型：int
含义：操作员 ID（执行验券操作的收银员/员工）。
特点：
本文件中几乎固定为同一个 ID，说明当前数据时间段只有一个收银员在验券。
关联：
可与员工档案或账号表中的 id 对应（其他 JSON 中也有同样的 operator_id 字段）。
索引意义：
按操作员维度过滤或统计验券记录（结构上可支持这种需求）。
5.4 operator_name
类型：string
含义：操作员姓名，例如 "收银员:郑丽珊"。
特点：
是 operator_id 的冗余展示字段；
即使员工账号发生变化，历史记录仍保留当时的文字信息。
6. 记录主键与删除标志
6.1 id
类型：int
含义：本条平台验券记录在本系统内的主键 ID。
特点：
长整型，看上去类似分布式 ID（如雪花算法），全库范围内唯一。
结构角色：
数据库层面的主键；
程序内部用于定位、更新这条记录。
6.2 is_delete
类型：int（枚举）
观测值：全部为 0。
含义：
0：未删除；
1：已逻辑删除。
与 use_status 的区分：
use_status 是业务行为状态（使用/撤销），即使 use_status=2 也不一定 is_delete=1；
is_delete 表示这条记录是否在系统层面被标记为无效（通常用于误操作回退等）。
三、字段之间的结构关系与索引设计
这里只谈字段设计层面的关系和潜在索引，不做任何金额/盈利层面的分析。
1. 本表内部的主键 / 候选键
id：系统主键（技术主键）。
coupon_code：
在当前 200 条数据中，coupon_code 完全唯一；
可视为业务自然主键；
很适合作为查询索引（按券码查验券记录）。
(coupon_channel, coupon_code) 组合键：
当系统需要支持多平台同时使用类似码段时，可以把二者视为联合业务主键；
从目前数据（channel 只有 1/2）来看，单 coupon_code 即可唯一，但结构上两者组合更稳健。
certificate_id：
有重复值，不能单独作为唯一键；
配合 coupon_channel 可作为对接外部平台的联合索引。
2. 与其他表的结构关联键
从字段命名和含义看，可与其他 JSON 建立如下结构关联（这里不依赖具体数值匹配，只看设计）：
与订单 / 结账相关表：
键：site_order_id
作用：把平台验券记录挂到本门店的一条订单上。
推断：
订单主表（结账记录）中会有与 site_order_id 对应的主键；
小票详情可通过结算 ID（例如 order_settle_id）和 site_order_id 间接建立关系。
与球台（台桌列表）表：
键：table_id ↔ 台桌表中的 id
作用：标明券在使用时是在哪张台桌上消费的；
联动：可用于后续把平台券使用时间段与台费流水对齐（仅结构层面）。
与团购套餐定义（团购套餐.json）：
键：group_package_id ↔ 团购套餐表中的 id
现状：
目前全部为 0，说明这批平台券尚未映射到内部团购套餐；
结构设计：
一旦做了“平台券 ↔ 自有团购套餐”的映射，这个字段就是关键外键。
与员工 / 账号表：
键：operator_id ↔ 员工/账号表中的 id
作用：按员工维度审计平台券核销情况；
配合 operator_name 做展示。
与外部平台：
键：
coupon_code：对顾客和平台双方都看得见的券码。
certificate_id：平台内部凭证 ID。
verify_id：平台核销 ID（存在时）。
channel_deal_id / deal_id：平台和系统对团购产品的双重映射。
作用：在系统与第三方平台之间做对账、同步状态的基础字段。
3. 索引设计上的自然倾向（从字段看）
纯看字段设计，在数据库里比较合理的索引组合是：
主键：id
唯一索引（候选）：coupon_code
一般索引：
coupon_channel（按平台分流查询）；
use_status（查询未使用或已撤销的券）；
consume_time（时间区间查询，比如一天内所有核销）；
site_order_id（按订单维度查是否用了平台券）；
table_id（按球台查平台券使用情况）；
operator_id（按收银员查）。
这些都属于结构层面可以直接读出的信息，无关任何金额统计。
四、结构层面的额外线索与观察
最后总结一些从结构和字段组合上能看出的“额外信息”，仍然只停留在结构与属性层面：
券产品定义的冗余与稳健性
对同一种团购产品，系统同时存了：
coupon_name
sale_price
coupon_money
deal_id
channel_deal_id
任意一个 ID 字段缺失时（如部分记录 deal_id=0），仍然可以通过其他字段（coupon_name + sale_price + coupon_money + channel_deal_id）唯一识别该产品。
这种多字段冗余，结构上提升了抗“配置缺失”的能力。
多层 ID 设计（内部 ↔ 渠道 ↔ 平台）
对同一个概念（“团购商品”）同时存在：
渠道侧：channel_deal_id；
平台/系统侧：deal_id；
内部套餐侧：group_package_id（虽暂为 0）。
对同一张券同时存在：
顾客看到的 coupon_code；
平台内部的 certificate_id、verify_id；
系统内部的 id。
结构上体现出：系统刻意把“外部 ID”和“内部 ID”分层保存，而不是只保留其中一个。
时间字段区分“记录生成”与“业务发生”
create_time 与 consume_time 同时存在，多数记录仅相差 1 秒；
结构上明确：系统把“核销动作被记录的时间”和“券被认为实际使用的时间”分开存储，为后续审计、对账预留了空间（例如出现延迟写入或补录时）。
使用状态与逻辑删除的双维度
use_status 负责描述“业务意义上的状态”（已用/已撤销等）；
is_delete 负责描述“这条记录在系统里是否被逻辑删除”；
从结构设计看，可以同时存在 use_status=2 且 is_delete=0 的记录，说明“业务状态异常但仍然需要保留记录”。
与订单、台桌结合后可形成的“结构视图”
仅从字段关系看，一次平台券核销在全系统里的“链路”大致是：
平台券产品（deal_id / channel_deal_id）
→ 券实例（coupon_code / certificate_id）
→ 平台验券记录（本文件 id）
→ 门店订单（site_order_id）
→ 具体台桌（table_id，对应台桌列表）
→ 台费流水 / 其他订单明细（通过同一订单号在其他 JSON 里衔接）
即使不看任何金额，从 ID 设计也能看出：系统是希望把“外部平台 → 券 → 订单 → 台桌”串成一条完整链路的。
字段值域的稳定性
多个字段采用了典型“0/1/2”小枚举：
coupon_channel：1/2 两个平台；
use_status：1/2 两种状态；
groupon_type：目前只有 1；
is_delete：0/1；
说明系统在这部分采用的是固定枚举编码，而不是随意字符串，这一点利于后续联表和性能优化。

874
docs/api-reference/endpoints/recharge_settlements.md Normal file
View File

@@ -0,0 +1,874 @@
# 充值结算记录（GetRechargeSettleList）
> 自动生成于 2026-02-13 | 数据来源：实时 API
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Site/GetRechargeSettleList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/Site/GetRechargeSettleList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `recharge_settlements` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（rangeStartTime / rangeEndTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `settleType` | int | `0` | 结算类型（0=全部） |
| `paymentMethod` | int | `0` | 支付方式（0=全部） |
| `rangeStartTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `rangeEndTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `isFirst` | int | `0` | 是否首充（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 92 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `id` | int | 3087072625102533 |
| 2 | `tenantId` | int | 2790683160709957 |
| 3 | `siteId` | int | 2790685415443269 |
| 4 | `siteName` | string | '' |
| 5 | `balanceAmount` | float | 0.0 |
| 6 | `cardAmount` | float | 0.0 |
| 7 | `cashAmount` | float | 0.0 |
| 8 | `couponAmount` | float | 0.0 |
| 9 | `createTime` | string | '2026-02-09 05:12:42' |
| 10 | `memberId` | int | 2799207363643141 |
| 11 | `memberName` | string | '葛先生' |
| 12 | `tenantMemberCardId` | int | 2799216572794629 |
| 13 | `memberCardTypeName` | string | '储值卡' |
| 14 | `memberPhone` | string | '13811638071' |
| 15 | `tableId` | int | 0 |
| 16 | `consumeMoney` | float | 10000.0 |
| 17 | `onlineAmount` | float | 0.0 |
| 18 | `operatorId` | int | 2790687322443013 |
| 19 | `operatorName` | string | '收银员:郑丽珊' |
| 20 | `revokeOrderId` | int | 0 |
| 21 | `revokeOrderName` | string | '' |
| 22 | `revokeTime` | string | '0001-01-01 00:00:00' |
| 23 | `payAmount` | float | 10000.0 |
| 24 | `pointAmount` | float | 10000.0 |
| 25 | `refundAmount` | float | 0.0 |
| 26 | `settleName` | string | '充值订单' |
| 27 | `settleRelateId` | int | 3087072624987845 |
| 28 | `settleStatus` | int | 2 |
| 29 | `settleType` | int | 5 |
| 30 | `payTime` | string | '2026-02-09 05:12:42' |
| 31 | `roundingAmount` | float | 0.0 |
| 32 | `paymentMethod` | int | 4 |
| 33 | `adjustAmount` | float | 0.0 |
| 34 | `assistantCxMoney` | float | 0.0 |
| 35 | `assistantPdMoney` | float | 0.0 |
| 36 | `couponSaleAmount` | float | 0.0 |
| 37 | `plCouponSaleAmount` | float | 0.0 |
| 38 | `merVouSalesAmount` | float | 0.0 |
| 39 | `memberDiscountAmount` | float | 0.0 |
| 40 | `tableChargeMoney` | float | 0.0 |
| 41 | `goodsMoney` | float | 0.0 |
| 42 | `realGoodsMoney` | float | 0.0 |
| 43 | `serviceMoney` | float | 0.0 |
| 44 | `prepayMoney` | float | 0.0 |
| 45 | `salesManName` | string | '' |
| 46 | `orderRemark` | string | '' |
| 47 | `salesManUserId` | int | 0 |
| 48 | `canBeRevoked` | bool | False |
| 49 | `pointDiscountPrice` | float | 0.0 |
| 50 | `pointDiscountCost` | float | 0.0 |
| 51 | `activityDiscount` | float | 0.0 |
| 52 | `serialNumber` | int | 0 |
| 53 | `assistantManualDiscount` | float | 0.0 |
| 54 | `allCouponDiscount` | float | 0.0 |
| 55 | `goodsPromotionMoney` | float | 0.0 |
| 56 | `assistantPromotionMoney` | float | 0.0 |
| 57 | `isUseCoupon` | bool | False |
| 58 | `isUseDiscount` | bool | False |
| 59 | `isActivity` | bool | False |
| 60 | `isBindMember` | bool | False |
| 61 | `isFirst` | int | 2 |
| 62 | `rechargeCardAmount` | int | 0 |
| 63 | `giftCardAmount` | int | 0 |
| 64 | `electricityMoney` | float | 0.0 |
| 65 | `realElectricityMoney` | float | 0.0 |
| 66 | `electricityAdjustMoney` | float | 0.0 |
| 67 | `siteProfile.id` | int | 2790685415443269 |
| 68 | `siteProfile.org_id` | int | 2790684179467077 |
| 69 | `siteProfile.shop_name` | string | '朗朗桌球' |
| 70 | `siteProfile.avatar` | string | 'https://oss.ficoo.vip/admin/hXcE4E_1752495052016.jpg' |
| 71 | `siteProfile.business_tel` | string | '13316068642' |
| 72 | `siteProfile.full_address` | string | '广东省广州市天河区丽阳街12号' |
| 73 | `siteProfile.address` | string | '广东省广州市天河区天园街道朗朗桌球' |
| 74 | `siteProfile.longitude` | float | 113.360321 |
| 75 | `siteProfile.latitude` | float | 23.133629 |
| 76 | `siteProfile.tenant_site_region_id` | int | 156440100 |
| 77 | `siteProfile.tenant_id` | int | 2790683160709957 |
| 78 | `siteProfile.auto_light` | int | 1 |
| 79 | `siteProfile.attendance_distance` | int | 0 |
| 80 | `siteProfile.wifi_name` | string | '' |
| 81 | `siteProfile.wifi_password` | string | '' |
| 82 | `siteProfile.customer_service_qrcode` | string | '' |
| 83 | `siteProfile.customer_service_wechat` | string | '' |
| 84 | `siteProfile.fixed_pay_qrCode` | string | '' |
| 85 | `siteProfile.prod_env` | int | 1 |
| 86 | `siteProfile.light_status` | int | 1 |
| 87 | `siteProfile.light_type` | int | 0 |
| 88 | `siteProfile.site_type` | int | 1 |
| 89 | `siteProfile.light_token` | string | '' |
| 90 | `siteProfile.site_label` | string | 'A' |
| 91 | `siteProfile.attendance_enabled` | int | 1 |
| 92 | `siteProfile.shop_status` | int | 1 |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `electricityAdjustMoney` | float |
| `electricityMoney` | float |
| `merVouSalesAmount` | float |
| `plCouponSaleAmount` | float |
| `realElectricityMoney` | float |
## 详细字段分析
> 以下内容迁移自旧版 `recharge_settlements-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
二、siteProfile（门店维度快照）
每条记录都带一个相同的 siteProfile，表示当前门店信息。字段含义与之前文件中的 siteProfile 一致：
id
类型：int
含义：门店 ID。
与各 JSON 中的 site_id 一致。
org_id
类型：int
含义：门店所属组织 ID（类似“门店所在公司/组织”）。
shop_name
类型：string
示例："朗朗桌球"
含义：门店名称。
avatar
类型：string
含义：门店头像图片 URL。
business_tel
类型：string
含义：门店电话。
full_address
类型：string
含义：完整门店地址。
address
类型：string
含义：精简地址/展示用地址。
longitude / latitude
类型：float
含义：门店经纬度。
tenant_site_region_id
类型：int
含义：门店所属行政区域编码（内部编码）。
tenant_id
类型：int
含义：租户/品牌 ID，对应所有表里的 tenantId 或 tenant_id。
auto_light / light_status / light_type / light_token
类型：int / string
含义：门店灯控相关配置（是否智能控灯、灯控类型、对接凭证等）。
attendance_distance / attendance_enabled
类型：int / int
含义：考勤打卡相关配置（打卡有效范围、是否启用考勤）。
wifi_name / wifi_password
类型：string
含义：门店 WiFi 信息（当前为空）。
customer_service_qrcode / customer_service_wechat
类型：string
含义：客服二维码 / 客服微信。
fixed_pay_qrCode
类型：string
含义：固定收款码图片 URL。
prod_env
类型：int
含义：环境标志（1=线上环境，非测试）。
site_type
类型：int
含义：门店类型（枚举，当前为 1）。
site_label
类型：string
示例："A"
含义：门店标签/分组标签。
shop_status
类型：int
含义：门店营业状态（枚举，当前为 1=营业中）。
以上字段在本文件中值基本固定，仅起到“门店快照”作用。
三、内层 settleList（单条充值结算记录）字段说明
以下所有字段均来自内层 settleList（即每条充值记录）。
为便于阅读，按“主键与关联”、“会员与卡”、“金额相关”、“优惠相关”、“状态与类型”、“时间字段”、“操作人与渠道”等分组说明。
1. 主键与关联维度字段
id
类型：int
含义：本条充值结算记录的主键 ID（唯一标识一条充值/撤销记录）。
唯一性：74 条记录全部不同。
tenantId
类型：int
当前值：同一租户 ID。
含义：租户/品牌 ID，和 siteProfile.tenant_id 一致。
siteId
类型：int
当前值：同一门店 ID。
含义：门店 ID，和 siteProfile.id 一致。
siteName
类型：string
当前值："朗朗桌球"
含义：门店名称，与 siteProfile.shop_name 一致。
tableId
类型：int
当前值：全部为 0。
含义（从命名看）：原本用于关联台桌 ID。
在充值场景中未使用（全部为 0），可理解为“充值记录不依附具体球台”。
serialNumber
类型：int
当前值：全部为 0。
含义（推测）：流水号/小票序号字段；本门店当前未启用或未写入。
settleRelateId
类型：int
唯一值：74 条记录全部不同。
含义（推测）：关联的“结算单/业务单”ID。
根据命名，极可能等于“充值订单主表”的主键，或与支付记录里的 relate_id 相呼应，用于跨表追踪。
settleType
类型：int（枚举）
取值及含义（由数据反推）：
5：settleName = "充值订单"（正常充值）
7：settleName = "充值撤销"（充值撤销记录）
说明：这一枚举区分了充值 vs 撤销两类业务动作。
settleName
类型：string
枚举值：
"充值订单"：对应 settleType = 5
"充值撤销"：对应 settleType = 7
含义：业务类型名称，用于前端展示。
settleStatus
类型：int（枚举）
当前值：全部为 2
含义（推测）：
2：已完成/已结算。
说明：本次导出只保留了完成状态的充值/撤销记录，未包含未完成或待支付状态。
revokeOrderId
类型：int
值分布：
对多数正常充值记录：为对应的撤销单 ID 组成的某种映射（部分为 0，部分为某 ID）。
对撤销记录本身，一般也会有对应关系，用来指向被撤销的原始订单。
含义（推测）：与撤销相关的订单 ID（原订单或撤销单的指针）。
revokeOrderName
类型：string
当前值：全部为空字符串。
含义：撤销单名称/说明，当前未使用。
revokeTime
类型：string（时间）
当前值：全部为 ""（空字符串）。
含义：撤销发生时间。
实际撤销信息现在通过 “充值订单 + 退款金额 + 充值撤销记录” 来体现，该字段未真正使用。
从结构看，这个“充值记录”表沿用了通用“结算单”的模型，预留了多种业务场景字段（包括撤销相关的信息），但本门店实际使用方式是：
原始充值记录 settleType = 5, settleName = "充值订单"，payAmount > 0。
对应的退款信息通过 refundAmount 或单独的 settleType = 7 记录（负数金额）体现，revoke* 字段目前保持空/0。
2. 会员与会员卡相关字段
memberId
类型：int
含义：会员档案的主键 ID。
关联：
对应“会员档案.json”中 tenantMemberInfos 的 id 字段（部分成员能直接匹配）。
用途：标识给哪位会员充值。
memberName
类型：string
值示例："轩哥", "羊", "夏", 以及一些手机号字符串。
含义：会员名称/昵称快照。
说明：此处记录的是当时会员名字，后续会员改名时，本记录不变（快照字段）。
memberPhone
类型：string
含义：会员手机号快照，用于查找和展示。
memberCardTypeName
类型：string（枚举）
当前值：
"储值卡" 占绝大多数
"月卡" 仅 1 条（对应一次月卡充值）
含义：本次充值针对的会员卡类型名称。
tenantMemberCardId
类型：int
含义：会员卡实例 ID（某张具体卡）。
说明：
多个充值记录可能对应同一张卡（同一个 ID 多次出现）。
这类 ID 通常对应“会员卡表”的主键（本次导出中该表未单独出现）。
isBindMember
类型：bool
当前值：全部为 False
含义（结合命名推测）：是否绑定为会员（或是否有绑定的推荐人/员工等）。
但由于本数据中所有充值都有 memberId，而 isBindMember 全为 False，实际业务含义可能已经变化或未使用，需以系统配置为准。
isFirst
类型：int（枚举）
当前值：1 或 2
1 出现 11 次
2 出现 63 次
命名上很明显是“是否首次”的含义，但从现有数据看，同一会员有时只有 2，说明缺失了更早的记录或编码含义稍有偏差。
建议：业务解释上视为“是否首单/首充”的标志，但具体 1/2 对应什么角色需要系统字典确认。
3. 金额相关字段（充值金额结构，不做盈利分析）
这一部分是本表的核心。
所有金额类型统一为 float，单位为“元”。
3.1 充值总额与退款
payAmount
含义：本次记录对应的充值金额（含正负）。
特点：
正数：实际充值金额（1000, 3000, 5000, 10000, 44000 等）。
负数：撤销或冲销金额（-3000, -5000, -10000, -44000 等）。
与 settleType 的关系：
"充值订单"（settleType=5）：绝大多数为正值；少数被退款的记录仍为正值，但 refundAmount>0。
"充值撤销"（settleType=7）：金额为负值。
refundAmount
含义：针对本条充值订单所做的退款金额（通常为正数）。
分布：
大部分记录为 0。
少数记录为 10000、5000、44000、3000 等，与对应的 payAmount 完全相等。
配合观察：
有一条 "充值订单" 记录 payAmount=10000，同时 refundAmount=10000。
对应存在一条 "充值撤销" 记录，payAmount=-10000，refundAmount=0。
结构含义：
原始充值单通过 refundAmount 标记“已被退款”，
同时生成对应的 "充值撤销" 负值记录作为记账流水。
3.2 资金来源 / 支付渠道拆分（本数据中未细分）
balanceAmount
当前值：全部为 0。
命名含义：从“账户余额”支付的金额（在充值场景中不适用，因此为 0）。
cardAmount
当前值：全部为 0。
命名含义：从某种“储值卡 / 会员卡余额”为消费来源的金额（本表为充值，不是消费，暂未使用）。
cashAmount
当前值：极少数记录为 3000、5000，其余为 0。
含义：现金收款金额。
onlineAmount
当前值：全部为 0。
命名含义：线上支付金额（微信/支付宝等），当前门店这段时间的充值可能按统一支付方式计入 payAmount，而没有拆渠道。
couponAmount
当前值：全部为 0。
含义：用券直接支付的金额（例如储值券），在本充值场景中未使用。
3.3 积分、到账金额类
pointAmount
含义（结合取值关系推断）：计入会员账户的“储值金额”或“积分型金额”。
特征：
多数情况下等于 payAmount 的绝对值。
对于被完全撤销的场景：
"充值订单"：payAmount>0，pointAmount 仍为正值；
"充值撤销"：相应记录 pointAmount=0。
因此 pointAmount 更像是“本条生效后，卡上增加的金额”，而撤销记录不再增加金额。
rechargeCardAmount
当前值：全部为 0。
命名含义：充值到卡上的金额（可能用于区分“余额型卡充值额”和“赠送/积分”等），当前没有单独拆出。
giftCardAmount
当前值：全部为 0。
含义（推测）：赠送卡金额（如买 1000 送 100 的 100 部分）。
prepayMoney
当前值：全部为 0。
命名含义：预付款金额（如订金）。本门店充值没有使用该维度。
3.4 消费相关金额（在充值场景中为 0）
以下字段在通用结算模型中用于“商品/台费/服务”消费金额，本表为纯充值场景，因此全部为 0，仅列明用途：
consumeMoney
当前值：0
含义：总消费金额（消费类订单使用）。
goodsMoney
当前值：0
含义：商品消费金额。
realGoodsMoney
当前值：0
含义：实际商品应计金额（可能扣除折扣后的商品金额）。
tableChargeMoney
当前值：0
含义：台费金额。
serviceMoney
当前值：0
含义：服务类项目金额（例如助教、其他服务）。
4. 优惠、折扣、活动相关字段（当前数据几乎全 0）
这些字段是通用结算模型中用于记录活动优惠、商品促销、助教促销等的金额，在本充值场景下本店未用到，全部为 0.0：
activityDiscount
含义：营销活动折扣金额。
allCouponDiscount
含义：各类优惠券、团购券综合折扣金额。
goodsPromotionMoney
含义：商品促销优惠金额。
assistantPromotionMoney
含义：助教相关促销优惠金额。
assistantPdMoney
含义：助教配单金额/相关费用。
assistantCxMoney
含义：助教促销或冲销相关金额。
assistantManualDiscount
含义：助教手动减免金额。
couponSaleAmount
含义：出售券/套餐的金额（与消费类订单相关）。
memberDiscountAmount
含义：因会员折扣产生的优惠金额。
pointDiscountPrice / pointDiscountCost
含义：积分抵扣产生的价差/成本。
adjustAmount
含义：结算时手工调整金额（四舍五入以外的修正）。
roundingAmount
含义：抹零金额（尾数四舍五入处理产生的差额）。
以上字段设计说明：
充值记录数据结构复用了“结算单”的全量字段，实际场景仅使用了“充值金额、退款金额、积分/储值增加等”少数字段，其余优惠/活动相关字段在当前时间段为全 0。
5. 状态与标志字段
isActivity
类型：bool
当前值：全部为 False
含义：是否关联某个营销活动（如充值满送活动）。
当前为 False，说明这段时间的充值没有绑定系统内的“活动对象”。
isUseCoupon
类型：bool
当前值：全部为 False
含义：本次结算是否使用优惠券。充值未用券。
isUseDiscount
类型：bool
当前值：全部为 False
含义：是否使用了折扣（例如会员打折）。
充值一般是面值入账，因此为 False。
canBeRevoked
类型：bool
当前值：全部为 False
含义：是否仍可进行撤销操作。
当前导出时，这 74 条记录均不可再撤销（可能是时间窗已过）。
settleStatus
已在上文说明，全部为 2（已完成）。
6. 时间字段
createTime
类型：string（时间）
含义：充值记录创建时间，一般即收银完成时间。
用途：作为时间轴排序和统计依据。
payTime
类型：string（时间）
含义：支付完成时间。
特点：在当前数据中，createTime 与 payTime 通常非常接近或相同。
revokeTime
类型：string
当前值：全部为空。
含义：撤销生效时间，当前未使用。
7. 操作员 / 营业员 / 支付方式字段
operatorId
类型：int
含义：操作该笔充值的收银员/员工 ID。
operatorName
类型：string
含义：操作员姓名，与 operatorId 对应，便于直接阅读。
salesManName
类型：string
当前值：全部为空字符串。
含义：营业员/销售员姓名（与提成相关的角色）。充值记录未单独指定销售员。
salesManUserId
类型：int
当前值：全部为 0。
含义：营业员用户 ID。
paymentMethod
类型：int（枚举）
取值：1, 2, 4 三种。
含义：支付方式编码。
具体编码→支付渠道的映射（如现金/微信/支付宝/银行卡等）需要参考系统内部“支付方式字典”；
从数据分布看：
大部分充值记录使用 4，少数是 1、2，实际渠道应为某几种常用支付方式。
8. 备注字段
orderRemark
类型：string
当前值：全部为空字符串。
含义：充值单备注，例如手工说明，当前未使用。
四、结构关系与设计线索（不做金额/盈利分析）
从字段结构角度，可以看出以下几点重要信息：
通用“结算单模型”的复用
大量字段（商品金额、台费金额、助教金额、活动优惠、积分抵扣等）在本表都为 0，仅充值相关字段有值。
说明“充值记录”不是单独设计的表，而是基于统一的“结算单/收银单结构”，通过 settleType 区分不同业务类型（台费、商品、助教、充值等）。
这也意味着：
在同一套系统中，“台费结算”“商品销售”“助教结算”“充值记录”等 JSON，很可能都是同一张逻辑表不同类型的切片。
充值与撤销通过两种机制共同表达
settleType + settleName 用于区分“充值订单”与“充值撤销”。
退款信息通过两种方式表现：
原始充值单上 refundAmount > 0；
单独的 "充值撤销" 记录，payAmount 为负数。
这说明系统在设计上既保留了原始订单的“退款标签”，又通过负数流水记录真实冲销过程，方便对账和追溯。
会员 ID 与会员卡 ID 的关系
memberId 对应“会员档案.json”中 tenantMemberInfos.id（即某个会员主体）。
tenantMemberCardId 对应的是具体某一张卡的 ID（你这批数据没有单独的“会员卡表”，但是从命名与取值分布可以看出来，它比 memberId 更细一层）。
memberCardTypeName 给出了卡类型（储值卡、月卡等），说明充值记录同时向“会员主体”和“卡实例”两层维度挂钩。
表内未使用但预留的业务扩展点
activityDiscount、isActivity、isUseCoupon、allCouponDiscount 等字段在当前数据中全部为 0/False，但结构上已经为“充值参与活动”“充值优惠券”“充值满送”等预留了入口。
goodsMoney、serviceMoney、tableChargeMoney 全为 0，说明这张结算结构可以在别的业务场景被复用为综合结算（充值 + 消费），本门店当前的充值使用方式非常简单。
门店维度的一致性
siteId / siteName 与 siteProfile.id / siteProfile.shop_name 完全一致，且所有记录都属于同一个门店。
说明该文件仅包含这一家门店的充值流水，和你给的信息“所有数据均来自同一门店”一致。
与其他 JSON 的关联线索（仅从字段命名角度）
与会员档案的关联：
memberId ↔ “会员档案.json” tenantMemberInfos.id
memberName / memberPhone 则是当时的快照。
与支付记录的潜在关联：
settleRelateId 加上 paymentMethod，典型用法是在“支付记录”表中通过 relate_type=充值 + relate_id=settleRelateId 进行关联。
与其他结算类 JSON 的一致性：
字段命名和结构（goodsMoney, tableChargeMoney, serviceMoney, 折扣类字段）的完整复用，说明“台费结算”“商品销售”“助教流水”“充值记录”几类 JSON，是同一个结算域模型的不同“视图”或筛选条件。

711
docs/api-reference/endpoints/refund_transactions.md Normal file
View File

@@ -0,0 +1,711 @@
# 退款流水（GetRefundPayLogList）
> 自动生成于 2026-02-13 | 数据来源：实时 API
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Order/GetRefundPayLogList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/Order/GetRefundPayLogList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `refund_transactions` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 32 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `tenantName` | string | '朗朗桌球' |
| 2 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
| 3 | `id` | int | 3089577798995141 |
| 4 | `site_id` | int | 2790685415443269 |
| 5 | `tenant_id` | int | 2790683160709957 |
| 6 | `pay_sn` | int | 0 |
| 7 | `pay_amount` | float | -8.0 |
| 8 | `pay_status` | int | 2 |
| 9 | `pay_time` | string | '2026-02-10 23:41:06' |
| 10 | `create_time` | string | '2026-02-10 23:41:06' |
| 11 | `relate_type` | int | 1 |
| 12 | `relate_id` | int | 3089548319804869 |
| 13 | `is_revoke` | int | 0 |
| 14 | `is_delete` | int | 0 |
| 15 | `online_pay_channel` | int | 0 |
| 16 | `payment_method` | int | 4 |
| 17 | `balance_frozen_amount` | float | 0.0 |
| 18 | `card_frozen_amount` | float | 0.0 |
| 19 | `member_id` | int | 0 |
| 20 | `member_card_id` | int | 0 |
| 21 | `round_amount` | float | 0.0 |
| 22 | `online_pay_type` | int | 0 |
| 23 | `action_type` | int | 2 |
| 24 | `refund_amount` | float | 0.0 |
| 25 | `cashier_point_id` | int | 0 |
| 26 | `operator_id` | int | 0 |
| 27 | `pay_terminal` | int | 1 |
| 28 | `pay_config_id` | int | 0 |
| 29 | `channel_payer_id` | string | '' |
| 30 | `channel_pay_no` | string | '' |
| 31 | `check_status` | int | 1 |
| 32 | `channel_fee` | float | 0.0 |
## 详细字段分析
> 以下内容迁移自旧版 `refund_transactions-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
2. 记录内容类型（这份 JSON 实际记录的是什么）
从字段组合和数值特征看，每条记录代表：
“一笔已发生的退款支付流水（资金层面的退款交易）”
特点：
pay_amount 全为负数（例如 -12.0, -44000.0, -3000.0），很明显是“钱从店里流出”的方向。
pay_status 全为 2，结合支付记录推测是“退款/完成状态”（至少表示“已处理完成”）。
action_type 全为 2，极大概率是“退款动作类型”的枚举。
relate_type 只出现 2 与 5，对应两类不同业务：一种是“消费类”，一种是“充值/储值类”（具体含义依赖系统配置，但肯定是区分不同业务来源）。
这份“退款记录”是 资金维度 的退款流水，不是“业务维度”的退款单（比如没记录退款原因、操作备注等）。业务上的退款原因应从对应的订单、充值记录或其他业务表中去追踪。
二、字段逐一说明（含数据类型 & 枚举推断）
下面按功能分组，对每个字段说明其含义、类型，是否枚举，以及这些记录中实际出现的取值。
1. 门店 / 租户维度字段
tenantName
类型：string
示例："朗朗桌球"
含义：租户（商户）名称。
特点：本文件中固定为“朗朗桌球”，完全冗余于 siteProfile.shop_name。
作用：方便直接在流水中看到店名，无需再查门店档案。
tenant_id
类型：int
示例：2790683160709957
含义：租户/品牌 ID，全系统维度标识该商户。
特点：本文件中所有记录相同。
作用：
作为所有门店数据的“租户分区键”；
与其他 JSON 中同名字段一致，用来确认“同一商户”。
site_id
类型：int
示例：2790685415443269
含义：门店 ID。
特点：本文件中所有记录相同（单门店）。
作用：
关联其他数据表中同一门店的数据；
与 siteProfile.id 一致，是 siteProfile 的主键。
siteProfile
类型：object
含义：门店信息快照，结构与其他 JSON 中的 siteProfile 完全一致。包含字段包括但不限于：
id：门店 ID（= site_id）；
shop_name：店名；
full_address / address：地址；
longitude / latitude：经纬度；
business_tel：电话；
一系列门店配置项（灯控、考勤、营业状态等）。
作用：
为每条退款记录附带一份当时的门店元信息；
提供冗余信息，避免联表查询门店档案。
2. 退款流水主键与关联业务字段
id
类型：int
示例：2955202296416389
含义：本条 退款流水 的唯一 ID。
特点：
每条记录一个不同的长整型 ID，疑似雪花 ID 或类似分布式 ID。
作用：作为退款记录表主键，内部检索用。
relate_type
类型：int（枚举）
当前取值：{2, 5}
含义：本退款对应的“业务类型”。
结合支付记录的 relate_type 推测：
1（在支付记录中存在）：某类订单支付（可能是结账单支付）。
2：另一类业务，比如“台费/商品类消费单”或“综合订单”；在退款记录中有多条。
5：通常用来标记“储值/充值类业务”，这里的几条金额很大，形态上很像“退充值款”。
结构作用：
不直接指向某张表，而是先告知“这是哪种业务”，再配合 relate_id 确定具体业务记录。
relate_id
类型：int
示例：2948246513454661
含义：本次退款关联的业务 ID。
对于 relate_type = 2：应该对应某个订单/结算的主键；
对于 relate_type = 5：应该对应某条充值记录或储值业务记录的主键。
特点：
同一个 relate_id 可能对应多条退款流水（例如先退 88.33，又退 0.67，对应两个不同撤销动作，都关联到同一 relate_id）。
与其他 JSON 的关系：
在“支付记录”中也有 relate_type + relate_id 组合，含义一致：指向业务实体；
本文件里的退款流水和“支付记录”是通过“共同指向同一业务实体”来间接关联，而不是直接指向支付记录。
3. 时间字段
create_time
类型：string，格式为 "YYYY-MM-DD HH:MM:SS"
示例："2025-11-03 15:36:19"
含义：本条退款流水在系统内创建时间。
特点：
当前数据中，create_time 与 pay_time 完全相同，说明系统在退款发生时立刻生成流水记录。
如果未来有“申请退款-审核-执行”流程，create_time 有可能偏早。
pay_time
类型：string，格式同上
示例："2025-11-03 15:36:19"
含义：退款在支付渠道层面实际发生的时间。
特点：
当前数据中与 create_time 一致，可以视为“退款完成时间”。
结构提示：
保留 create_time 和 pay_time 两个字段，说明系统设计上区分“记录生成时间”与“渠道交易时间”。如果引入异步处理，二者可能就会出现差异。
4. 金额相关字段
pay_amount
类型：float
示例：-12.0, -44000.0, -3000.0, -0.67 等
含义：本次退款的 资金变动金额。
特征很重要：
全部为负数，绝对值就是退款金额。
表示“从门店账户流出的金额”（相对于支付记录中的正数进账）。
结构意义：
这份“退款记录.json”在设计上没有专门用 refund_amount 存实际退款额，而是直接用 pay_amount < 0 表示退款金额大小。
这点对之后做数据抽取/ETL 很重要：判断退款金额只看 pay_amount 的负数；refund_amount 字段在当前实现中并未使用。
refund_amount
类型：float
当前全部为：0.0
含义（推测）：
设计上本应显示“实际退款金额”（正数），与 pay_amount 配合使用；
但在目前实现里，系统只用了 pay_amount 表示金额，并没有填充这个字段。
在当前数据中的状态：
可以视为“保留字段/未启用”。
balance_frozen_amount
类型：float
当前：全部 0.0
含义（推测）：
涉及会员储值卡退款时，暂时冻结的余额金额；
用于一些“先冻结后解冻/退款”的逻辑。
当前数据状态：
所有退款记录的 member_id / member_card_id 都是 0，对应的冻结金额自然也是 0；
说明这 11 笔退款都不是“退到会员卡余额”，而是对普通支付渠道（例如刷卡）的退款。
card_frozen_amount
类型：float
当前：全部 0.0
含义：与上一个类似，偏向“某张卡的被冻结金额”，也与会员卡/储值账户相关。
状态同上：本数据中未发生“卡冻结退款”。
round_amount
类型：float
当前：全部 0.0
含义（推测）：
舍入金额/抹零金额；
在某些场景下，如果退款金额存在四舍五入等调整，会单独记录到这个字段。
当前未使用。
channel_fee
类型：float
当前：全部 0.0
含义（推测）：
第三方支付渠道对本次退款收取的手续费；
正常应该在“通道成本核算”里用到。
当前数据中没有任何通道手续费记录（可能通道不收手续费，或者手续费隐藏在其他费用内）。
5. 支付方式 / 渠道相关字段
结合“支付记录.json”一起看，更容易理解这些字段的结构设计。
payment_method
类型：int（枚举）
当前取值：仅 4
在“支付记录.json”中出现的取值有：2、4。
含义（推测）：
支付/退款的 方式类型：
2：某种线上支付渠道（很可能是微信）；
4：另一种支付方式（很可能是银行卡 POS 或现金），当前这批退款全是 4，说明都是同一支付方式的退款。
具体枚举值定义要以“非球科技”系统文档为准，但可以确定是“支付方式枚举”。
online_pay_channel
类型：int（枚举）
当前：全部 0
在“支付记录.json”里同样全部为 0。
含义（推测）：
线上支付的 渠道编号，例如：
0：线下/默认渠道；
其他值（如 1,2）可能分别代表微信、支付宝等。
当前门店的退款记录全部为 0，说明这 11 笔退款要么是线下渠道，要么系统没有区分线上子渠道。
online_pay_type
类型：int（枚举）
当前：全部 0
含义（推测）：
在线退款的类型：
0：原路退回；
其他值（如果存在）可能代表“退到余额”、“退到其他银行卡”等。
当前数据中未出现其他值，说明门店的退款都是默认策略（很可能就是原路退回）。
pay_terminal
类型：int（枚举）
当前：全部 1
含义（推测）：
退款所使用的 终端类型：
1：前台收银端；
其他值可能为：小程序、自助机、后台管理系统等。
本文件中所有退款都来自同一种终端类型。
pay_config_id
类型：int
当前：全部 0
含义（推测）：
支付配置 ID，例如商户在“非球科技”内配置的某一条支付通道（某个微信商户号、银联通道）的主键。
当前数据未填（可能全部走默认配置），因此都是 0。
channel_payer_id
类型：string
当前：全部为空字符串 ""
含义（推测）：
支付渠道侧的 payer ID，例如微信 openid、银行卡号掩码等。
当前数据未使用（可能系统没回写或导出时屏蔽了）。
channel_pay_no
类型：string
当前：全部为空字符串 ""
含义（推测）：
第三方支付平台的交易号（如微信支付单号、支付宝交易号等）。
当前为空：要么是通道未返回，要么导出接口没带出这部分数据。
6. 会员关联字段
member_id
类型：int
当前：全部 0
含义：
租户内部的会员 ID（对应会员档案中的某个主键）。
当前状态：
这 11 笔退款中没有任何一笔标记了会员 ID，说明是“非会员退款”或退款没绑定到会员档案。
member_card_id
类型：int
当前：全部 0
含义：
关联的会员卡账户 ID（对应“储值卡列表”或“会员档案”中的某一张卡）。
当前状态：
没有记录任何“退到某张会员卡”的情况；
结合 balance_frozen_amount = 0、card_frozen_amount = 0，可以确定当前导出时间范围的退款全部是对外部支付渠道的退款，没有会员卡内部余额的退款。
7. 状态标志字段
pay_status
类型：int（枚举）
当前：全部 2
在“支付记录.json”中同样只有值 2。
含义（推测）：
支付/退款状态枚举：
1 可能为“待支付/处理中”；
2 为“已完成”（支付成功 / 退款完成）。
鉴于所有支付、退款记录导出时都已经完成，因此本文件中只有 2。
is_revoke
类型：int（枚举）
当前：全部 0
含义（推测）：
是否撤销型退款/撤销原支付：
0：正常退款；
1：撤销类型操作。
当前为 0，说明所有记录按“正常退款”处理，而不是“支付撤销”这类特殊类型。
is_delete
类型：int（枚举）
当前：全部 0
含义：逻辑删除标志。
0：未删除；
1：已删除（逻辑上标记删除，但记录仍存在）。
当前数据中所有退款记录都处于“未删除”状态。
check_status
类型：int（枚举）
当前：全部 1
含义（推测）：
审核状态：
1：已审核/通过；
其他值可能表示“待审核/审核拒绝”等。
结构意义：
说明系统设计上支持“退款需审核”的流程，但当前导出时这些记录已经审过。
action_type
类型：int（枚举）
当前：全部 2
含义（推测）：
行为类型：
1：支付；
2：退款；
或类似的“资金动作类型”。
结合：
支付记录并没有此字段，退款记录有 action_type=2；
再加上 pay_amount<0，基本可以确定这是“退款动作”的枚举标识。
8. 其他操作相关字段
cashier_point_id
类型：int
当前：全部 0
含义（推测）：
收银点 ID，例如前台 1、前台 2、自助机等。
当前数据中未区分具体收银点，统一为 0。
operator_id
类型：int
当前：全部 0
含义：
执行该退款操作的操作员 ID。
当前全部为 0，说明：
要么系统没有记录具体操作员；
要么导出接口未把这个信息带出（但字段已预留）。
三、与其它 JSON 文件的关联关系（结构层面）
从字段角度，退款记录.json 与其它数据之间主要有以下关联：
与门店/租户：
tenant_id ↔ 所有 JSON 中的 tenant_id；
site_id ↔ 所有 JSON 中的 site_id；
siteProfile 内部的 id、tenant_id 与上述字段一致。
→ 说明：退款记录明确挂在“朗朗桌球”这个门店下，与其它消费、库存、助教等记录在同一数据域。
与支付记录（支付记录.json）：
两者都拥有：
relate_type + relate_id：指向同一个业务实体（订单、充值等）；
payment_method、online_pay_channel：同一套支付方式枚举；
pay_amount、pay_status、pay_time：结构一致。
差异：
支付记录的 pay_amount 为正数（进账），退款记录的 pay_amount 为负数（出账）；
退款记录多了一些退款专用字段：refund_amount、balance_frozen_amount、card_frozen_amount、is_revoke、online_pay_type、channel_fee 等。
结构性结论：
支付记录 = 资金正向流入流水；
退款记录 = 资金反向流出流水；
通过 同一个 relate_type + relate_id 指向同一业务主单，从而把“支付”和“退款”绑定在同一个订单/充值实体之上。
与订单/充值等业务表：
relate_type 通知你“这是哪种业务”，relate_id 是那种业务表里的主键。
在已导出的 JSON 中，对应的业务表大致为：
relate_type = 2 → 多数对应“订单类业务”（例如结账记录、小票详情、消费明细）；
relate_type = 5 → 多数对应“充值类业务”（对照余额变更记录、充值记录）。
虽然我们在当前导出中没拿到完整的充值记录明细，但这两字段的存在，已经把退款挂在“业务主单”的坐标上了。
与会员体系：
通过 member_id、member_card_id 理论上可以关联到：
会员档案（会员档案.json）；
储值卡列表（储值卡列表.json）；
余额变更记录（余额变更记录.json）。
当前这批数据里二者均为 0，说明这 11 笔退款完全与会员卡无关，是纯支付渠道层面的退款。
结构意义：
一旦未来有“退到储值卡”的场景，member_id/member_card_id 会出现非 0 值，进而通过上述表串联起“资金退款 → 会员余额变更 → 卡账户状态”。
四、结构层面的额外重要线索（不涉及金额分析）
正/负号决定资金方向：
退款记录并没有用一个单独的“类型字段 + 正数金额”来描述退款，而是直接用 pay_amount 为负，配合 action_type=2 表示“退款”。
对后续数据对接/迁移很关键：判断“是支付还是退款”，不能只看 pay_status，而是要同时看 action_type + pay_amount 的符号。
业务实体与资金流水是一对多关系：
两条记录中 relate_id 相同但 id 不同的情况，意味着同一业务单可以产生多笔退款（例如分批退）。
这也解释了为什么系统用 relate_type + relate_id 来指业务，而“支付 record ID / 退款 record ID”本身只是在资金流水表内唯一。
退款文件是资金维，不含任何“原因类字段”：
没有“退款原因”、“备注”、“操作人姓名”等文本字段；
“是否审核通过”、“是否撤销”等只通过状态位表示；
说明系统将“业务解释”留给业务表（订单/充值），这里只关心钱动了多少、从哪儿来、到哪儿去。
会员退款与普通退款在结构上是统一模型：
即使当前数据里没有会员退款记录，字段已经预留了：
member_id / member_card_id；
balance_frozen_amount / card_frozen_amount；
online_pay_type 等。
一旦发生“退到余额/退到会员卡”的场景，这份结构可以无缝承载，不需要变更表结构。
审核流程是结构预留但未复杂使用：
有 check_status 字段，也有 is_revoke，表明系统支持“审核 + 撤销”这类管理流程。
当前导出数据中全部为 check_status=1、is_revoke=0，说明：
要么店内流程简单，退款都直接通过；
要么导出只包含“已审核通过的记录”。
与支付记录共用枚举体系：
payment_method、online_pay_channel、pay_terminal、relate_type 等枚举字段，与支付记录完全共用。
这一点对于你后续构建统一的资金流水视图很关键：可以把支付记录和退款记录 union 在一起，通过这些枚举和正负金额，就能得到一张统一的资金流水大表。

28
docs/api-reference/endpoints/role_area_association.md Normal file
View File

@@ -0,0 +1,28 @@
# 角色区域关联（QueryRoleAreaAssociation）
> 自动生成于 2026-02-13 | 数据来源：实时 API
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `User/QueryRoleAreaAssociation` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/User/QueryRoleAreaAssociation` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `无（新 API，尚未建表）` |
| 分页方式 | 无分页 |
| 时间范围 | 不需要 |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `roleId` | int | `12` | 角色 ID |
## 响应字段（共 1 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `roleAreaRelations` | array | [{'id': 2790684101675845, 'pid': 0, 'name': '广东', 'deptCo... |

919
docs/api-reference/endpoints/settlement_records.md Normal file
View File

@@ -0,0 +1,919 @@
# 结账记录（GetAllOrderSettleList）
> 自动生成于 2026-02-13 | 数据来源：实时 API
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Site/GetAllOrderSettleList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/Site/GetAllOrderSettleList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `settlement_records` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（rangeStartTime / rangeEndTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `settleType` | int | `0` | 结算类型（0=全部） |
| `rangeStartTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `rangeEndTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `siteTableAreaIdList` | array | `[]` | 台桌区域 ID 列表（空=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 92 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `id` | int | 3092711340902597 |
| 2 | `tenantId` | int | 2790683160709957 |
| 3 | `siteId` | int | 2790685415443269 |
| 4 | `siteName` | string | '朗朗桌球' |
| 5 | `balanceAmount` | float | 4285.55 |
| 6 | `cardAmount` | float | 0.0 |
| 7 | `cashAmount` | float | 0.0 |
| 8 | `couponAmount` | float | 0.0 |
| 9 | `createTime` | string | '2026-02-13 04:48:42' |
| 10 | `memberId` | int | 2799207522600709 |
| 11 | `memberName` | string | '' |
| 12 | `tenantMemberCardId` | int | 0 |
| 13 | `memberCardTypeName` | string | '' |
| 14 | `memberPhone` | string | '' |
| 15 | `tableId` | int | 2956248279567557 |
| 16 | `consumeMoney` | float | 5567.77 |
| 17 | `onlineAmount` | float | 0.0 |
| 18 | `operatorId` | int | 2790687322443013 |
| 19 | `operatorName` | string | '收银员:郑丽珊' |
| 20 | `revokeOrderId` | int | 0 |
| 21 | `revokeOrderName` | string | '' |
| 22 | `revokeTime` | string | '0001-01-01 00:00:00' |
| 23 | `payAmount` | float | 0.0 |
| 24 | `pointAmount` | float | 0.0 |
| 25 | `refundAmount` | float | 0.0 |
| 26 | `settleName` | string | '发财 发财' |
| 27 | `settleRelateId` | int | 3092230766020741 |
| 28 | `settleStatus` | int | 2 |
| 29 | `settleType` | int | 1 |
| 30 | `payTime` | string | '2026-02-13 04:49:48' |
| 31 | `roundingAmount` | float | 0.0 |
| 32 | `paymentMethod` | int | 0 |
| 33 | `adjustAmount` | float | 1282.22 |
| 34 | `assistantCxMoney` | float | 0.0 |
| 35 | `assistantPdMoney` | float | 646.32 |
| 36 | `couponSaleAmount` | float | 0.0 |
| 37 | `plCouponSaleAmount` | float | 0.0 |
| 38 | `merVouSalesAmount` | float | 0.0 |
| 39 | `memberDiscountAmount` | float | 0.0 |
| 40 | `tableChargeMoney` | float | 2564.45 |
| 41 | `goodsMoney` | float | 2357.0 |
| 42 | `realGoodsMoney` | float | 2357.0 |
| 43 | `serviceMoney` | float | 0.0 |
| 44 | `prepayMoney` | float | 0.0 |
| 45 | `salesManName` | string | '' |
| 46 | `orderRemark` | string | '' |
| 47 | `salesManUserId` | int | 0 |
| 48 | `canBeRevoked` | bool | False |
| 49 | `pointDiscountPrice` | float | 0.0 |
| 50 | `pointDiscountCost` | float | 0.0 |
| 51 | `activityDiscount` | float | 0.0 |
| 52 | `serialNumber` | int | 0 |
| 53 | `assistantManualDiscount` | float | 0.0 |
| 54 | `allCouponDiscount` | float | 0.0 |
| 55 | `goodsPromotionMoney` | float | 0.0 |
| 56 | `assistantPromotionMoney` | float | 0.0 |
| 57 | `isUseCoupon` | bool | False |
| 58 | `isUseDiscount` | bool | False |
| 59 | `isActivity` | bool | False |
| 60 | `isBindMember` | bool | False |
| 61 | `isFirst` | int | 0 |
| 62 | `rechargeCardAmount` | float | 4285.55 |
| 63 | `giftCardAmount` | int | 0 |
| 64 | `electricityMoney` | float | 0.0 |
| 65 | `realElectricityMoney` | float | 0.0 |
| 66 | `electricityAdjustMoney` | float | 0.0 |
| 67 | `siteProfile.id` | int | 0 |
| 68 | `siteProfile.org_id` | int | 0 |
| 69 | `siteProfile.shop_name` | string | '' |
| 70 | `siteProfile.avatar` | string | '' |
| 71 | `siteProfile.business_tel` | string | '' |
| 72 | `siteProfile.full_address` | string | '' |
| 73 | `siteProfile.address` | string | '' |
| 74 | `siteProfile.longitude` | float | 0.0 |
| 75 | `siteProfile.latitude` | float | 0.0 |
| 76 | `siteProfile.tenant_site_region_id` | int | 0 |
| 77 | `siteProfile.tenant_id` | int | 0 |
| 78 | `siteProfile.auto_light` | int | 1 |
| 79 | `siteProfile.attendance_distance` | int | 0 |
| 80 | `siteProfile.wifi_name` | string | '' |
| 81 | `siteProfile.wifi_password` | string | '' |
| 82 | `siteProfile.customer_service_qrcode` | string | '' |
| 83 | `siteProfile.customer_service_wechat` | string | '' |
| 84 | `siteProfile.fixed_pay_qrCode` | string | '' |
| 85 | `siteProfile.prod_env` | int | 1 |
| 86 | `siteProfile.light_status` | int | 1 |
| 87 | `siteProfile.light_type` | int | 0 |
| 88 | `siteProfile.site_type` | int | 1 |
| 89 | `siteProfile.light_token` | string | '' |
| 90 | `siteProfile.site_label` | string | '' |
| 91 | `siteProfile.attendance_enabled` | int | 1 |
| 92 | `siteProfile.shop_status` | int | 1 |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `electricityAdjustMoney` | float |
| `electricityMoney` | float |
| `merVouSalesAmount` | float |
| `plCouponSaleAmount` | float |
| `realElectricityMoney` | float |
## 详细字段分析
> 以下内容迁移自旧版 `settlement_records-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
data.total
类型：int
含义：本次查询命中的结账记录总数，这里是 4739。
注意：每页只返回最多 100 条记录，total 是全量总数。
data.settleList
类型：数组
含义：当前页的结账记录列表。
每个元素结构为：
{
"siteProfile": { ... },
"settleList": { ...结账明细... }
}
即“门店快照 + 单条结账记录”组合。
2. 外层记录结构
每个 data.settleList 元素包含两个字段：
siteProfile
settleList（内层真正的结账明细对象）
2.1 siteProfile
类型：object
本文件中 siteProfile 字段结构与其他 JSON 一致，但内容多为 0 或空字符串：
id：门店 ID（这里为 0，说明该接口没有填充真实门店快照）。
org_id：组织 ID。
shop_name：店名，这里为空。
avatar：门店头像 URL。
business_tel：门店电话。
full_address / address：门店详细地址 / 简要地址。
longitude / latitude：经纬度。
tenant_site_region_id：地区编码。
tenant_id：租户 ID。
auto_light / light_status / light_type / light_token：灯控相关配置。
site_type：门店类型枚举。
site_label：门店标签。
attendance_enabled / attendance_distance：考勤开关及距离。
customer_service_qrcode / customer_service_wechat：客服信息。
fixed_pay_qrCode：固定收款码。
prod_env：环境标记。
shop_status：门店状态。
结构用途：
字段设计上与其它文件相同，用作“门店维度快照”；但当前导出中几乎是空壳，真正的门店信息在结账记录的内层字段 siteId / siteName 以及其他 JSON 的门店档案里。
2.2 settleList（内层结算对象）
类型：object
含义：本次结账的一条汇总记录（整单维度），真正的业务字段都在这个对象里。
下文所有字段说明，都是针对这个内层 settleList。
二、内层结账记录字段逐个说明（共 61 个）
为便于理解，按维度分组说明。
1. 主键与关联 ID / 桌台信息
id
类型：int
示例：2957922914357125
含义：结账记录主键 ID（订单结算 ID）。
结构关联：
与台费流水（siteTableUseDetailsList）中的 order_settle_id 一致。
与小票详情（orderSettleId）一致。
即：这是全系统统一的“结账单号”。
tenantId
类型：int
示例：2790683160709957（全表固定）
含义：租户/商户 ID（品牌维度）。
siteId
类型：int
示例：2790685415443269（朗朗桌球）
含义：门店 ID。
关联：
与其他所有 JSON 中的 site_id 对应。
与门店档案中的 id 对应。
siteName
类型：string
示例："朗朗桌球"
含义：门店名称，冗余展示字段。
tableId
类型：int
示例：2793003705192517
含义：本次结账对应的桌台 ID。
关联：
对应台桌维表或台费流水中的 site_table_id。
用于定位具体是哪张桌。
settleName
类型：string
示例："A区 A17", "A区 A4"
含义：结账对象名称，一般是“区域 + 桌号”的组合。
结构关系：
与台费流水中的 site_table_area_name + ledger_name 一致（如 A区 + A17）。
便于报表和前端展示。
settleRelateId
类型：int
示例：2957858167230149
含义：关联订单的“交易号”（order_trade_no）。
结构关联：
与台费流水（order_trade_no）、助教流水（order_trade_no）中的该字段完全一致。
这一字段将“结账记录”与“各类明细表（台费、助教、商品等）”逻辑上串起来。
serialNumber
类型：int
示例：0（当前样本均为 0）
含义（推测）：结账序列号 / 打印序号，用于内部排序或冲正追踪。
2. 时间与状态字段
createTime
类型：string（时间字符串）
格式："YYYY-MM-DD HH:MM:SS"
示例："2025-11-09 23:34:49"
含义：结账记录创建时间，一般对应收银端点“确认结账”的时间。
payTime
类型：string
示例："2025-11-09 23:35:57"
含义：实际支付完成时间。通常晚于 createTime（比如多支付场景）。
settleStatus
类型：int（枚举）
当前样本：全部为 2
含义（推测）：结账状态枚举。
2 很可能表示“已结算/已完成”。
其它枚举值（未出现在本数据中）可能为“待支付”、“已撤销”等。
settleType
类型：int（枚举）
当前样本值：1、3
含义（结构层面）：
代表结账类型，比如：
1：正常结账；
3：特殊类型（例如挂账、补单、某类调整单）。
具体含义依赖系统配置，但可以确定这是“结账类型”的枚举字段。
canBeRevoked
类型：bool
当前样本：全部为 False
含义：是否允许被撤销/冲正。
True：当前结账记录仍可做撤销或冲正操作；
False：不能再撤销（例如已过撤销时限、已经被冲正）。
revokeOrderId
类型：int
当前样本：全为 0
含义：若当前记录是“被撤销的单”，则记录对应的“撤销单 ID”；或反过来记录“原单 ID”。
结构上：作为撤销关系的外键使用，目前样本中未出现实际撤销记录。
revokeOrderName
类型：string
当前样本：全为空字符串
含义：撤销单名称/标识，用于辅助说明撤销关系。
revokeTime
类型：string（时间）
当前样本：全为 "0001-01-01 00:00:00"（无效时间）
含义：撤销时间。当记录发生撤销时将写入真实时间，当前数据尚未出现此场景。
3. 会员维度字段
memberId
类型：int
示例：0 或 2799207363643141 等
含义：会员主键 ID。
结构关联：
与“会员卡列表（tenantMemberCards）”中的 tenant_member_id 一致。
即：这是“租户维度的会员卡 ID”。
memberName
类型：string
当前样本：均为空字符串
含义：会员姓名快照。
说明：当前导出中未填充，但结构上就是成员名称。
memberPhone
类型：string
当前样本：均为空
含义：会员手机号快照。
tenantMemberCardId
类型：int
当前样本：均为 0
含义（推测）：会员卡账户 ID（与 memberId、会员卡表的 id 之间存在映射）。
当前导出未实际使用，但结构上预留了“结账记录 → 会员卡账户表”的外键。
memberCardTypeName
类型：string
当前样本：空
含义：会员卡类型名称，如“储值卡”“次卡”“活动抵用券”等。
对应会员卡表中的 member_card_type_name 字段。
isBindMember
类型：bool
当前样本：全部为 False
含义：本次结账是否绑定了会员。
True：本单关联会员（即 memberId > 0）；
False：散客。
isFirst
类型：int（0/1 枚举的可能性较大）
当前样本：全部为 0
含义（推测）：是否首单（新客首单）。
0：否；
1：是。
当前导出中未出现首单记录，值全部为 0。
memberDiscountAmount
类型：float
当前样本：全部为 0.0
含义：会员折扣产生的优惠金额（元）。
虽然值全为 0，但结构上这是“会员折扣”维度的金额字段，后续可与其他优惠字段一起分层统计。
4. 消费构成（台费/商品/助教/服务）
这些字段是在“消费侧”拆解每一笔结账的构成（不涉及付款方式）。
consumeMoney
类型：float
示例：58.0, 96.0, 362.82 等
含义：本次结账消费总额（不考虑支付方式/优惠结构的前后顺序，单纯汇总项目金额）。
结构关系（从金额结构角度）：
近似可表示为：
consumeMoney ≈ tableChargeMoney + goodsMoney + assistantPdMoney + assistantCxMoney + serviceMoney ± 各类调价/抹零
这里不展开计算，只指出这是综合金额。
tableChargeMoney
类型：float
示例：48.0, 96.0, 85.72 等
含义：台费（桌台计费部分）的金额。
goodsMoney
类型：float
示例：10.0, 0.0, 8.0 等
含义：商品销售金额（原始商品金额）。
realGoodsMoney
类型：float
示例：10.0, 0.0, 6.0 等
含义：商品实际计入金额（可能已扣除某些折扣、促销）。
结构上：realGoodsMoney 通常是 goodsMoney 调整后的结果。
assistantPdMoney
类型：float
示例：0.0, 206.67, 194.99 等
含义：助教“排钟/上课”应计金额（原价）。
结构关联：
与 助教流水.json 中对应订单的 ledger_amount 一致（应收金额）。
与该订单下所有助教明细合计后对齐。
assistantCxMoney
类型：float
示例：0.0, 1330.0, 2280.0
含义（推测）：助教“次课/套餐/持续课”等另一类助教项目的金额。
从结构看，这是对助教收入的另一种拆分维度，和 assistantPdMoney 一起将助教项目区分为不同类型。
serviceMoney
类型：float
示例：当前样本全为 0.0
含义：服务费/其他服务类收费金额，结构上单独列出一个维度，便于区分台费、商品、助教之外的服务收入。
5. 支付与资金构成（按渠道拆分）
这些字段描述“钱从哪来/怎么付”的分配，不是消费项目构成。
payAmount
类型：float
示例：10.0, 58.0, 0.0 等
含义：本次结账“实付金额”（顾客实际支付的总金额），不包括券面值、积分等非现金部分。
cashAmount
类型：float
示例：0.0, 8.0 等
含义：现金支付部分金额。
cardAmount
类型：float
示例：0.0, 8.0, 14.0 等（样本中主要为 0）
含义（推测）：非储值卡类的刷卡金额（例如信用卡/银行卡）。也可能是“会员卡支付”的一种编码方式，视系统定义而定。
balanceAmount
类型：float
示例：0.0, 120.0, 144.0 等
含义：从会员余额账户扣除的金额（储值卡余额消费）。
onlineAmount
类型：float
示例：0.0, 8.0, 352.0 等
含义：线上支付金额汇总（微信/支付宝/云闪付等通道的总和），具体通道细分不在本表中体现。
rechargeCardAmount
类型：float / int（大部分 0，少数为 float）
示例：0, 120.0, 114.61, 1194.0
含义（推测）：与“充值卡”相关的支付额，可能表示本次使用充值卡抵扣的金额。
giftCardAmount
类型：float / int
示例：0, 41.0, 18.0, 500.0, 100.0
含义：礼品卡/代金卡的支付金额。
refundAmount
类型：float
示例：目前样本中多为 0.0
含义：本次结账中涉及的退款金额（如果是退款单或部分退单，则为正数）。
prepayMoney
类型：float
示例：0.0
含义：预付金（定金）部分金额。用于记录提前预付在本单中使用的金额。
6. 优惠 / 折扣 / 活动等金额字段
couponAmount
类型：float
示例：48.0, 96.0, 0.0 等
含义：本单实际由优惠券（代金券/团购券等）抵扣的金额。
couponSaleAmount
类型：float
示例：当前样本为 0.0
含义（推测）：优惠券本身的售卖金额/成本金额（比如顾客为购券支付的金额）。
allCouponDiscount
类型：float
示例：0.0
含义：归集所有券类优惠折扣的金额，作为汇总字段，便于统计“总券优惠”。
goodsPromotionMoney
类型：float
示例：当前样本为 0.0
含义：商品促销产生的优惠金额（如买赠、满减分摊到商品部分）。
assistantPromotionMoney
类型：float
示例：0.0
含义：助教项目参与活动或促销产生的优惠金额。
activityDiscount
类型：float
示例：0.0
含义：活动折扣金额（如整单打折、满减等归集）。
memberDiscountAmount
前文已提（会员维度），本质也是优惠金额字段，只是专属于会员折扣。
roundingAmount
类型：float
示例：0.0, 0.33, 0.01 等
含义：抹零金额/舍入差值。如四舍五入或按角、分抹零产生的调整。
adjustAmount
类型：float
示例：0.0, 148.15, 120.0, 38.34, 18.0 等
含义：人工调价金额（总和），包括整单减免、特殊调整等。
在某些记录中，该值较大，说明存在明显的人工改价行为，但这里不做业务解释，仅说明字段角色是“可调整浮动金额”。
assistantManualDiscount
类型：float
示例：当前样本为 0.0
含义：专门针对助教服务进行的人工减免金额（区别于普通商品/台费的折扣）。
7. 积分相关字段
pointAmount
类型：float
示例：10.0, 215.0 等
含义（结构层面）：
代表与积分相关的一个金额或数量指标。结合字段命名，可能有两种用途：
本单“获得的积分数量”；
本单“用积分抵扣了多少金额”。
具体业务含义需要结合系统配置，不在本次结构分析范围内。
pointDiscountPrice
类型：float
示例：当前样本为 0.0
含义：积分抵扣对应的金额（售价侧）。
pointDiscountCost
类型：float
示例：0.0
含义：积分抵扣对应的成本金额（成本侧）。
8. 布尔标志位（优惠/活动使用情况）
isUseCoupon
类型：bool
当前样本：全部 False
含义：本次结账是否使用了优惠券。
True：使用；
False：未使用。
isUseDiscount
类型：bool
当前样本：False
含义：是否使用了折扣（比如会员折扣、整单打折等）。
isActivity
类型：bool
当前样本：False
含义：是否参与了营销活动（活动价、满减活动等）。
9. 员工 / 操作相关字段
operatorId
类型：int
示例：2790687322443013
含义：结账操作员的用户 ID。
关联：可与员工/账号表中的 id 对应。
operatorName
类型：string
示例："收银员:郑丽珊"
含义：结账操作员名称，包含角色前缀（如“收银员:”）。
salesManName
类型：string
当前样本：为空字符串
含义：营业员/业务员名称（用于提成或业绩归属）。
说明：样本中未单独设置营业员，字段留空。
salesManUserId
类型：int
当前样本：0
含义：营业员对应的用户 ID。
orderRemark
类型：string
当前样本：为空字符串
含义：订单备注，由收银员手工输入，记录特殊说明（例如“客人反映XX”、“活动赠送”等）。
三、字段级结构关系与重要线索（只谈结构，不做业务结论）
从字段结构和跨表关系来看，结账记录.json 在整个系统中的定位非常清晰，主要有以下关键点：
1. 结账记录是多张明细表的“汇总头”
关键外键映射关系已经非常明确：
结账.id = 台费流水的 order_settle_id = 助教流水的 order_settle_id = 小票详情的 orderSettleId
→ 结账记录是这些明细表的“结算头表”。
结账.settleRelateId = 台费流水 / 助教流水 / 其他订单明细中的 order_trade_no
→ 表示的是同一笔“交易号”，可跨不同业务明细汇总。
结论（结构层面）：
结账记录.json 是所有消费行为（台费、助教、商品、服务）在“订单维度”上的整合节点。
2. 桌台维度的绑定
tableId ↔ 台费流水的 site_table_id ↔ 台桌列表的 id
settleName 与台费流水中的 site_table_area_name + ledger_name 一致。
结构上表明：“结账”是针对于具体某张桌和某个区域的。
3. 与助教流水的金额映射
对于含助教的结账记录：
assistantPdMoney = 对应订单下助教流水的 ledger_amount 汇总（原价侧金额）。
助教流水中的 projected_income 则是助教部分在核算侧的实际计入金额。
在本表中不出现 projected_income，而是用一系列折扣、调价、券金额等字段从其他角度拆分。
结构层面：
本表承担“按项目类型（台费/商品/助教/服务）+ 按优惠来源（券、活动、会员、抹零、调价…）”两个维度的汇总拆分。
4. 与会员卡 / 积分体系的连接点
memberId ↔ 会员卡 JSON (tenantMemberCards) 中的 tenant_member_id。
多个金额字段专门为会员卡和积分预留：
balanceAmount、rechargeCardAmount、giftCardAmount → 不同卡/余额类型的资金来源。
memberDiscountAmount、pointAmount、pointDiscountPrice、pointDiscountCost → 会员折扣与积分收益/抵扣的金额维度。
结构上，这说明：
结账记录不仅仅是“收了多少钱”，而是同时承载了“会员体系如何参与本单”的信息，且与会员卡与积分的专门表有外键可以联动。
5. 小票详情与结账记录的一对一关系
在“小票详情.json”（你那边是 orderSettleId + data 那个文件）中：
orderSettleId 与本表的 id 完全一致。
小票详情中也存在大量与本表同名字段（couponAmount、giftCardAmount、adjustAmount 等）。
结构层面：
结账记录.json 是一个“汇总视图”，字段较为精简。
“小票详情.json” 是更细粒度的结构（包含 orderItem 列表、配送信息、会员详情等）。
这意味着如果你要做字段级的数据模型，通常会把结账记录作为 fact 表的一部分，小票详情作为明细扩展。
6. 优惠维度设计的全面性
从字段命名可以看出系统在优惠维度上做了非常细的拆分：
按来源：会员折扣、活动折扣、商品促销、助教促销、券优惠、积分优惠、人工调价、抹零。
每一个维度都对应独立的金额字段（多为 float），并非简单的“总折扣”。
从纯结构角度，这个设计为后续做“多维折扣分析 / 审计 / 对账”提供了足够信息，但同时也增加了建模复杂度，需要在模型中清晰标注每个字段代表“折扣来源”还是“支付渠道”。

11
docs/api-reference/endpoints/settlement_ticket_details.md Normal file
View File

@@ -0,0 +1,11 @@
# 结账小票明细（GetOrderSettleTicketNew）
> 该接口当前不可用（HTTP 1400），暂不生成详细文档。
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Order/GetOrderSettleTicketNew` |
| ODS 对应表 | `settlement_ticket_details` |
| 状态 | ⚠️ 暂不可用 |

591
docs/api-reference/endpoints/site_tables_master.md Normal file
View File

@@ -0,0 +1,591 @@
# 台桌主数据（GetSiteTables）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Table/GetSiteTables` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/Table/GetSiteTables` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `site_tables_master` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要 |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `showStatus` | int | `0` | 展示状态（0=全部） |
| `virtualTableType` | int | `-1` | 虚拟桌类型（-1=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 25 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `id` | int | 2791964216463493 |
| 2 | `audit_status` | int | 2 |
| 3 | `charge_free` | int | 0 |
| 4 | `self_table` | int | 1 |
| 5 | `create_time` | string | '2025-07-15 17:52:54' |
| 6 | `is_rest_area` | int | 0 |
| 7 | `light_status` | int | 2 |
| 8 | `show_status` | int | 1 |
| 9 | `site_id` | int | 2790685415443269 |
| 10 | `site_table_area_id` | int | 2791963794329671 |
| 11 | `table_cloth_use_time` | int | 1863727 |
| 12 | `table_cloth_use_Cycle` | int | 0 |
| 13 | `virtual_table` | int | 0 |
| 14 | `table_name` | string | 'A1' |
| 15 | `table_price` | float | 0.0 |
| 16 | `table_status` | int | 1 |
| 17 | `areaName` | string | 'A区' |
| 18 | `siteName` | string | '朗朗桌球' |
| 19 | `tableStatusName` | string | '空闲中' |
| 20 | `appletQrCodeUrl` | string | 'https://pc-we.ficoo.vip/rootwww/prodwx38a48dd2bc3c1642?e... |
| 21 | `only_allow_groupon` | int | 2 |
| 22 | `delay_lights_time` | int | 0 |
| 23 | `order_delay_time` | int | 0 |
| 24 | `temporary_light_second` | int | 0 |
| 25 | `is_online_reservation` | int | 2 |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `order_id` | int |
## 详细字段分析
> 以下内容迁移自旧版 `site_tables_master-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
结论：
台桌列表.json 是典型的 “台桌维表（维度表）”，为后续所有流水（台费、助教、打折等）提供 site_table_id → 台号/区域/配置 的主数据。
二、记录级字段明细（逐字段）
以下字段均针对 siteTables 数组中的单条记录。
1. 主键 / 门店 / 区域基础字段
id
类型：int
唯一性：71 条记录各不相同。
含义：台桌主键 ID。
关联：
与 台费流水.json 中的 site_table_id 一致；
与 助教流水.json 中的 site_table_id 一致；
与 台费打折.json 中 tableProfile.id 一致。
作用：这是“台”的全系统唯一标识，是各类流水表引用的核心外键。
site_id
类型：int
当前值：全部为同一个值（例如 2790685415443269）。
含义：门店 ID。
关联：
与各个流水表、siteProfile.id 一致，本数据全部属于“朗朗桌球”这一家门店。
siteName
类型：string
当前值：全部为 "朗朗桌球"。
含义：门店名称快照，冗余字段，配合 site_id 使用。
site_table_area_id
类型：int
唯一性：14 个不同值。
含义：门店维度的“台桌区域 ID”。
关系：
同一个 site_table_area_id 对应一个唯一的 areaName（1:1）。
在其它 JSON（例如台费流水里的 tableProfile.site_table_area_id）中也存在同样的 ID，用于在门店内统一识别区域。
areaName
类型：string
枚举（本门店实际值）：
"A区"（18 台）
"B区"（15 台）
"补时长"（7 台）
"C区"（6 台）
"麻将房"（5 台）
"VIP包厢"（4 台）
"斯诺克区"（4 台）
"K包"（3 台）
"666", "M7", "k包活动区"（各 2 台）
"TV台", "M8", "发财"（各 1 台）
含义：区域名称，用于前台展示和区域维度管理。
结构特征：
site_table_area_id 与 areaName 一一对应；
有些区域名（如“补时长”“666”）本身就带业务含义（补时专用、特殊台）。
2. 台桌自身属性字段
table_name
类型：string
唯一性：71 条记录 71 个不同值。
示例："A1" ~ "A18", "B1" ~ "B6", "S1" ~ "S4", "VIP1", "VIP2", "VIP3", "VIP5", "TV台", "M7", "M8", "666", "888", "发财", "常乐", "幸会(纯k)", "董事办", "补时长"、"补时长2"…"补时长7"，"大包", "小包" 等。
含义：台号/台名称，用于前台操作界面展示，也出现在小票和各种流水中的 ledger_name 或 tableName 字段。
table_price
类型：float
当前观测：全部为 0.0。
含义（结构角度）：
设计上应为“台的基础单价”字段（例如按小时或按局单价）；
本门店实际上没有在台列表中配置单价，台费单价来自别处（如计费策略、时段价格表），因此这里统一为 0。
结论：这是一个“预留但未在本门店使用”的价格字段，真实计费规则在其他地方。
virtual_table
类型：int，枚举。
当前值：全部为 0。
含义（推测）：
0：物理台（实体存在的桌）；
1：虚拟台（组合计费或逻辑台，如合台、补钟虚拟台等）。
说明：尽管存在“补时长*”这类功能性台，但字段上仍标记为 0，说明系统是通过“特殊命名 + 台费计费逻辑”来实现补时，而没有使用 virtual_table=1。
self_table
类型：int，枚举。
当前值：全部为 1。
含义（推测）：
1：“本门店自有台”，非共享或外部配置；
0：可能预留用于联营/非自有台等场景，本门店未出现。
结构意义：标记台桌归属类型，未来可用于区分自营台与其他来源台。
is_rest_area
类型：int，枚举。
当前值：全部为 0。
含义（推测）：
0：正常计费区域；
1：休息区，可能不参与计费或有不同计费逻辑。
本门店未使用此区分。
3. 状态与展示控制相关字段
table_status
类型：int，枚举。
当前分布：
1：64 条，对应 tableStatusName = "空闲中"
2：2 条，对应 tableStatusName = "使用中"
3：5 条，对应 tableStatusName = "暂停中"
明确映射关系：
1 → 空闲中
2 → 使用中
3 → 暂停中
含义：台当前运行状态，真实反映某一时刻台的占用/暂停情况。
tableStatusName
类型：string，枚举。
当前值：
"空闲中"
"使用中"
"暂停中"
含义：table_status 的中文名称，仅为展示用途。
light_status
类型：int，枚举。
当前分布：
2：70 条
1：1 条
含义（结合命名推断）：
该字段是台灯/灯光状态开关位：
1：开灯/可控；
2：关灯/关闭状态。
当前导出时刻大部分台灯处于关闭状态（2），只有一张台为 1。
该字段与智能硬件（开关台灯）联动使用。
delay_lights_time
类型：int
当前值：全部为 0。
含义（推测）：台灯熄灭延迟时间（单位多半是秒或分钟），用于结账后延时关灯。
本门店未启用延迟关灯功能（全部为 0）。
temporary_light_second
类型：int
当前值：全部为 0。
含义（推测）：临时点灯时长（秒），例如手动临时开灯一段时间。
本门店未使用。
show_status
类型：int，枚举。
当前分布：
1：68 条，台名例如 "A1"..."A18", "B1"...，普通台以及多数补时长台；
2：3 条，台名为 "大包", "大包麻将房", "小包"。
含义（推测）：
1：正常在前台“开台列表”中展示；
2：不在常规开台列表展示，仅用于特殊用途（比如线上预约专用、单独套餐房间等）。
与 is_online_reservation 有明显配合（见下）。
audit_status
类型：int，枚举。
当前值：全部为 2。
含义（结合命名惯例）：
2：已审核/已启用；
其他值（未出现）可能用于“待审核/驳回”等状态。
当前门店所有台桌配置均处于已审核状态。
charge_free
类型：int，枚举。
当前值：全部为 0。
含义（推测）：
0：正常计费；
1：免单/常免台（不计费或特殊场景）。
本门店没有配置免单台。
show_status 已说明，不再赘述。
order_delay_time
类型：int
当前值：全部为 0。
含义（推测）：订单层面允许的“自动延时时长”（例如到点后自动延长多少时间继续计费）。
本门店未使用此功能。
4. 线上预约 / 团购限制字段
is_online_reservation
类型：int，枚举。
当前分布：
2：69 条
1：2 条（台名为 "大包", "小包"）
含义（结合值分布推断）：
1：允许线上预约（可在小程序/线上平台预约这张台）；
2：不允许线上预约。
结构特征：
只有“大包”“小包”被标记为可线上预约，且它们的 show_status = 2，说明这两张台可能主要通过线上预约，而非普通前台开台列表。
only_allow_groupon
类型：int，枚举。
当前值：全部为 2。
含义（结合命名推断）：
1：仅允许团购/券预约使用（团购专用台）；
2：不限制，只要满足其他条件即可使用。
当前门店没有设置“仅限团购使用”的台桌，所有台都标记为 2。
appletQrCodeUrl
类型：string
特征：
每张台一个独立的 URL，结构类似：
https://pc-we.ficoo.vip/rootwww/prodwx38a48dd2bc3c1642?env=prod&type=1&id=<table_id>&siteId=<site_id>
id 参数就是当前台的 id，siteId 为门店 ID。
含义：小程序二维码 URL。
一般用于：
打印二维码贴在台上，顾客扫码可呼叫服务、查看账单或发起线上预约；
员工也可通过小程序快捷开台。
5. 台呢使用相关字段
table_cloth_use_time
类型：int
当前分布：
共有 69 个不同值；
范围：0 ~ 2137840。
含义（结合命名和数值特征）：
台呢使用累计时长，单位极大概率为“秒”：
例如 1863727 秒 ≈ 517 小时，符合“台呢累计使用时长”的量级。
用于提醒更换/保养台呢。
结构上：这是一个不断累加的计数器，每次开台会增长对应秒数。
table_cloth_use_Cycle
类型：int
当前值：全部为 0。
含义（推测）：
台呢使用周期阈值，例如达到某个秒数后提醒更换；
0 表示未配置该阈值。
本门店尚未设置自动提醒周期，只记录使用时长。
6. 其他通用字段
create_time
类型：string，格式 YYYY-MM-DD HH:MM:SS
当前数据：
71 条记录，有 44 个不同的时间点；
多数台在 2025-07-16 这一时段集中创建，少数在 2025-07-15/2025-10-31。
含义：台桌配置的创建时间或最近一次创建/复制时间。
三、与其它 JSON 的字段级关联关系（结构视角）
仅从字段结构和命名角度说明，不做数值层面的比对。
1. 与《台费流水.json》（台费使用记录）
关键关联字段：
台桌列表.id ↔ 台费流水中的 site_table_id
台桌列表.table_name ↔ 台费流水中的 ledger_name（或 tableName）
台桌列表.site_table_area_id ↔ 台费流水里的 tableProfile.site_table_area_id
台桌列表.areaName ↔ 台费流水里的 tableProfile.site_table_area_name
site_id、tenant_id 在两表保持一致。
结构关系：
台桌列表 提供静态的“台属性/区域属性/可用性配置”；
台费流水 提供动态的“台使用时段 + 台费金额拆分”；
两者通过 site_table_id 构成事实表–维度表关系。
2. 与《台费打折.json》（台费调账/打折记录）
关键关联字段：
台桌列表.id ↔ 台费打折中的 site_table_id（或 tableProfile.id）
table_name ↔ tableProfile.table_name
site_table_area_id / areaName ↔ tableProfile.site_table_area_id / site_table_area_name
结构关系：
台费打折记录中的 tableProfile 实际上就是对“台桌列表”中某一行台的快照；
所有与台相关的打折，都可以回溯到 id 对应的台配置记录。
3. 与《助教流水.json》
关键关联字段：
台桌列表.id ↔ 助教流水中的 site_table_id
table_name ↔ 助教流水中的 tableName
site_id、tenant_id 保持一致。
结构关系：
助教服务是附着在具体台或包厢上的；
助教流水 中记录“某助教在某张台上服务的时段和金额”，通过 site_table_id 与台桌配置联动；
可以从结构上做到“按台/按区域统计助教服务情况”。
4. 与其它门店维度类 JSON（如门店信息等）
site_id、siteName 与各个 JSON 中的 siteProfile.id、shop_name一致；
台桌列表 是门店维度下的子实体表，与“门店档案”存在 1:N 关系（一个门店多张台）。
四、从结构关系角度额外能看出的重要线索
台桌列表在整个模型中是核心“维度表”
所有与“台”相关的流水（台费、助教、台费打折等）都通过 site_table_id 引用这里；
字段设计同时覆盖了：基础属性（name/area）、运营状态（table_status）、显示控制（show_status）、线上能力（is_online_reservation、only_allow_groupon）、硬件联动（light_status 与灯控系统）、耗材寿命管理（table_cloth_use_time）。
补时长相关的台是通过“命名 + 区域 + 计费规则”实现的，不是通过 virtual_table 字段
有一组台名字直接叫“补时长*（补时长、补时长2...补时长7）”，区域名也叫“补时长”；
但 virtual_table=0、charge_free=0、self_table=1，说明系统把它们当成普通台，只是在业务逻辑层面赋予“补时台”含义（结构上可注意这一点，用于后续建模时区分）。
线上预约房间与普通台桌在结构上的差异由 show_status + is_online_reservation 组合表达
普通台：show_status=1、is_online_reservation=2；
大/小包：show_status=2、is_online_reservation=1；
结构上的含义是：
普通台：主要由现场前台打开使用，不对外提供线上预约；
大/小包：主要通过线上预约入口使用，不在常规“开台列表”出现。
这在后续做结构分析或建模时，可以用两个字段组合出“台的业务角色”。
所有台处于 audit_status=2，说明当前配置已经“生效”
若未来有台处于 audit_status≠2 的情况，这将意味着该台尚未投入使用；
台费流水中不会引用未审核的台，这点从结构上可以推断出系统的约束逻辑。
台呢使用字段为“维护维度”提供结构钩子
table_cloth_use_time（累计秒数）+ table_cloth_use_Cycle（阈值）构成一个完整的“耗材寿命管理”结构；
本门店仅记录累积使用时长，还未设置“提醒更换周期”，但结构已经预留完备。
价格字段在台列表中未启用，说明计费策略是“另起表管理”
table_price=0 且台费实际单价在 台费流水.json 的 ledger_unit_price 中体现；
这说明系统采用：
“台的物理属性 + 区域属性”在本表；
“实时价格/活动价/时段价”在独立计费策略表；
台费流水则记录计费策略的执行结果（ledger_unit_price、ledger_amount）。
这一点在结构设计上非常明确，对后续做模型时需要把“台列表”和“计价策略”分开看。
综上，20251110_043250_台桌列表.json 从结构上完整刻画了门店所有台桌的静态属性和部分实时状态，并通过 id 字段在全系统范围内作为“台”的唯一主键，被台费、助教、打折等多类流水反复引用。它是整个非球科技门店模型中的核心基础维表之一。

426
docs/api-reference/endpoints/stock_goods_category_tree.md Normal file
View File

@@ -0,0 +1,426 @@
# 商品分类树（QueryPrimarySecondaryCategory）
> 自动生成于 2026-02-13 | 数据来源：实时 API
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoodsCategory/QueryPrimarySecondaryCategory` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/TenantGoodsCategory/QueryPrimarySecondaryCategory` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `stock_goods_category_tree` |
| 分页方式 | 无分页 |
| 时间范围 | 不需要 |
## 请求参数
无（`body: null`）
## 响应字段（共 2 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `total` | int | 0 |
| 2 | `goodsCategoryList` | array | [{'id': 2790683528350533, 'tenant_id': 2790683160709957, ... |
## 详细字段分析
> 以下内容迁移自旧版 `stock_goods_category_tree-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
一、文件内容类型与整体结构
实际内容类型判断
从文件内部结构看，这个 JSON 并不是“库存变化明细流水”，而是：
一个用于库存模块的 “商品分类（含业务大类）树形配置”。
顶层对象是商品分类列表 goodsCategoryList。
每条记录表示一个“商品分类节点”，支持父子层级（大类 / 子类）。
所有分类都标记了 is_warehousing = 1，说明这些分类下的商品会进入库存管理。
结合文件名可以推断：
库存变化界面的筛选条件中需要“按商品分类过滤”，这个文件就是该页面请求返回的“分类维度数据”。
二、分类节点结构与字段说明
分类节点字段集合（父子完全一致，共 11 个字段）：
id
tenant_id
category_name
alias_name
pid
business_name
tenant_goods_business_id
open_salesman
categoryBoxes
sort
is_warehousing
1. 标识与层级关系字段
1.1 id
类型：int
含义：分类节点主键 ID（在商品分类维度中的唯一标识）。
特征：
父子节点各有独立的 id，互不重复。
全表总共有 26 个不同的 id（9 个根节点 + 17 个子节点）。
1.2 pid
类型：int
含义：父级分类 ID。
取值规则：
对于根节点：pid = 0。
对于子节点：pid = 对应父节点的 id。
树结构示例（部分）：
根：器材（id=2790683528350535, pid=0）
子：皮头（pid=2790683528350535）
子：球杆（pid=2790683528350535）
子：其他（pid=2790683528350535）
根：酒水（id=2790683528350539, pid=0）
子：饮料、酒水、茶水、咖啡、加料、洋酒（pid 都等于根节点 id）
结构结论：id + pid 组成了标准的父子树关系，可以不依赖 categoryBoxes，直接自下而上追溯父级。
1.3 categoryBoxes
类型：list
含义：子分类数组。
特征：
根节点 categoryBoxes 为非空，包含若干子节点。
子节点的 categoryBoxes 一律为空数组 []，树深度为 2 层。
作用：
是对 id/pid 关系的树形展开，方便前端直接渲染树，无需自己拼接层级。
从结构角度看，同一层级关系既可以通过 pid 还原，也可以直接通过 categoryBoxes 读取，属于冗余表示。
总结：
树结构的 核心外键关系 为 pid 指向父节点的 id；categoryBoxes 为“展开后的子节点列表”，两者信息完全一致，只是展现形式不同。
2. 租户维度字段
2.1 tenant_id
类型：int
含义：租户 ID（品牌/商户 ID）。
取值：
所有节点（父子合计 26 条）的 tenant_id 完全相同。
说明：
因为本次导出只有一个门店，tenant_id 在所有 JSON 中都是同一个值，用来标识“朗朗桌球”所在的商户。
没有 site_id 字段，说明商品分类是在“租户层级”共享的，而非每个门店单独一套分类（本店只有一个门店，这一点在结果上体现为统一）。
3. 分类名称类字段
3.1 category_name
类型：string
含义：分类名称（实际业务分类名称）。
观测到的不同值（共 18 个）：
一级大类：槟榔、器材、酒水、水果、零食、雪糕、香烟、其他、小吃
二级子类：槟榔、皮头、球杆、其他、饮料、酒水、茶水、咖啡、加料、洋酒、果盘、零食、面、雪糕、香烟、其他2、小吃
说明：
分类名称用于商品档案、销售记录等的分类显示，是前台展示的主要维度之一。
二级分类丰富了同一业务线下的细分类型（例如“酒水”下面拆成“饮料/酒水/茶水/咖啡/加料/洋酒”）。
3.2 alias_name
类型：string
观测值：全部为 ""（空字符串）。
含义：
预留的“别名”字段，可用于：
分类别名；
简称（如“热饮”→“热”）。
当前门店未使用此功能。
4. 业务大类维度字段
这是本文件中很重要的一组结构信息，用于把多个细分类归入同一业务线。
4.1 business_name
类型：string
含义：业务大类名称。
观测值（共 9 个，与根节点的类别一致）：
槟榔、器材、酒水、水果、零食、雪糕、香烟、其他、小吃
特征：
根节点的 business_name 等于自身的 category_name；
子节点的 business_name 等于其所在的根节点的 category_name：
例：饮料、茶水、咖啡、加料、洋酒等的 business_name 都是 "酒水"；
皮头、球杆、器材-其他的 business_name 都是 "器材"；
面、果盘、零食 的 business_name 都是 "水果" 或 "零食" 等（根据挂载位置）。
结构结论：
business_name 明确了业务线/业务大类，即便子分类名称不同，仍属于同一业务线。
4.2 tenant_goods_business_id
类型：int
含义：业务大类 ID。
分组情况（按 business_name 聚合）：
槟榔 → 1 个 ID
器材 → 1 个 ID
酒水 → 1 个 ID
水果 → 1 个 ID
零食 → 1 个 ID
雪糕 → 1 个 ID
香烟 → 1 个 ID
其他 → 1 个 ID
小吃 → 1 个 ID
（即每个 business_name 对应唯一一个 tenant_goods_business_id）
特征：
根节点和子节点共享同一个 tenant_goods_business_id（按业务线划分）。
例如：
“酒水”根节点和其所有子节点“饮料/酒水/茶水/咖啡/加料/洋酒”都有同一个 tenant_goods_business_id。
结构意义：
构成三层结构：
租户 → tenant_id
业务线 → tenant_goods_business_id + business_name
具体分类 → id + category_name（含父子层级）
库存变化明细、销售明细可以：
按 id 统计（细分类别）；
按 tenant_goods_business_id 聚合（业务大类视角）。
5. 营业员与库存开关字段
5.1 open_salesman
类型：int，枚举。
观测值：全部为 2（共 26 条记录）。
含义（结合命名推断）：
是否启用“营业员”或“导购提成”相关的功能开关。
通常设计上会是类似：
1：开启；
2：关闭；
也可能是反过来，具体以系统配置为准。
数据特征：
全部为同一个值，说明当前门店所有这些分类在“库存变化”模块中采用统一的营业员开关策略，并无针对分类的差异化策略。
结构结论：
这是一个未来可以按分类差异化配置营业员/提成逻辑的预留字段；当前没有分类级别的差异。
5.2 is_warehousing
类型：int，枚举。
观测值：全部为 1。
含义（结合命名）：
是否“走库存 / 参与仓储管理”：
1：参与库存管理；
其他值（推测有 0）：不参与库存（如服务类商品、手工费用、补差价等）。
结构含义：
本文件可视为“所有参与库存管理的商品分类清单”，因此均为 1。
不走库存的分类要么不在本列表，要么在其他配置中 is_warehousing = 0。
6. 排序字段
6.1 sort
类型：int
根节点：
观测值：0 或 1。
子节点：
观测值：0 或 1。
含义：
分类的排序序号，用于前端展示顺序的控制。
数值越小可能越靠前（具体排序规则由前端或服务端设定）。
数据特征：
多数为 0，只有极少数为 1，说明基本上未对分类做精细排序，仅对个别分类做了简单调整。
三、结构关系与与其它数据的潜在关联
虽然这个文件本身不包含“库存变动明细”，但从字段设计可以看出它在整个系统里的位置。
1. 与“库存变化记录1（明细）”的关系（结构推断）
真正的库存变动流水（商品加减库存）记录中，一般会有：
goods_id / sku_id
category_id 或 category_name
tenant_goods_business_id 或 business_name
这里的分类树提供了“类别维度”，用于：
在库存变化列表界面按分类过滤；
在报表中按大类/小类统计库存变化。
结构链接（推断）：
库存变化记录表中的 category_id ↔ 本表的 id。
或者通过 tenant_goods_business_id 进行业务大类聚合。
2. 与“商品档案/门店商品”数据的关系（结构推断）
商品档案（某一 JSON 文件中）常见字段会有：
category_id（商品分类 ID，外键指向这里的 id）；
tenant_goods_business_id（商品所属的业务线，外键指向这里的业务大类）。
结构作用：
确保商品 → 分类树 → 库存统计 之间能通过统一的分类维表联动。
3. 与“门店销售记录 / 出入库记录”的关系（结构推断）
销售记录、出库记录、退货记录等，往往只记录 goods_id，通过商品档案再关联到分类：
销售流水 → 商品档案（goods_id） → 分类 ID（category_id） → 本文件分类树。
本文件在整个数据体系中，是一个标准的维表（分类维度），并不是事实流水表。
四、结构层面的关键信息与线索（不涉及任何盈利或数据指标分析）
树形分类深度为 2 层
根节点 9 个，每个根节点下 0~数个子节点。
没有更深层级（所有子节点的 categoryBoxes 均为空）。
这表明当前门店的分类设计比较扁平：业务大类 + 一层子类 已满足日常库存管理需求。
业务线与分类层级分离设计
通过 business_name + tenant_goods_business_id 定义业务大类；
通过 category_name + id + pid 定义分类树；
子分类的 business_name 固定继承根业务大类，不随子分类名称改变。
这种设计的好处：
可以在报表中按业务线分析（例如“酒水线整体的库存变化”）；
在操作界面可按细分类（如“洋酒”“饮料”）细分过滤。
库存参与与业务开关统一配置
所有分类 is_warehousing = 1，说明“库存变化记录”页面只关心走库存的商品；
所有分类 open_salesman = 2 表示在这一模块中对营业员相关逻辑采用统一开关，不做细分类别区分。
若未来启用无需库存的分类（如服务、台费），很可能不会出现在本文件或会有 is_warehousing = 0 的节点。
租户级共享分类，无门店级差异字段
分类结构中没有 site_id，只有 tenant_id；
对于多门店场景，意味着：同一租户下所有门店共享同一套商品分类结构。
对你当前这个“单店”来说，结果等价于“门店唯一分类配置”，但结构上已经为多店共用做了准备。
冗余字段为前端展示和扩展留空间
alias_name：可用来做别名/简称，本店未用。
table_area_id、card_type_ids 等类似字段在其他文件中已有类似设计模式；这里的 open_salesman、is_warehousing 也是这一类开关/扩展型字段。
这些字段使系统在不改动核心数据结构的情况下，可以增加更多维度的控制（如按分类控制提成、按分类控制是否走库存）。

747
docs/api-reference/endpoints/store_goods_master.md Normal file
View File

@@ -0,0 +1,747 @@
# 门店商品库存主数据（GetGoodsInventoryList）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/GetGoodsInventoryList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/TenantGoods/GetGoodsInventoryList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `store_goods_master` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要 |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `goodsSecondCategoryId` | array | `[]` | 二级分类 ID 列表（空=全部） |
| `goodsState` | int | `0` | 商品状态（0=全部） |
| `enableStatus` | int | `0` | 启用状态（0=全部） |
| `siteId` | array | `[2790685415443269]` | 门店 ID |
| `existsGoodsStock` | int | `0` | 是否有库存（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 45 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `siteName` | string | '朗朗桌球' |
| 2 | `oneCategoryName` | string | '零食' |
| 3 | `twoCategoryName` | string | '面' |
| 4 | `id` | int | 2793025851560005 |
| 5 | `tenant_goods_id` | int | 2792178593255301 |
| 6 | `site_id` | int | 2790685415443269 |
| 7 | `tenant_id` | int | 2790683160709957 |
| 8 | `goods_name` | string | '合味道泡面' |
| 9 | `goods_cover` | string | 'https://oss.ficoo.vip/admin/8M1WM7_1753204221337.jpg' |
| 10 | `goods_state` | int | 1 |
| 11 | `goods_category_id` | int | 2791941988405125 |
| 12 | `unit` | string | '桶' |
| 13 | `sale_num` | int | 104 |
| 14 | `cost_price` | float | 0.0 |
| 15 | `provisional_total_cost` | float | 0.0 |
| 16 | `total_purchase_cost` | float | 0.0 |
| 17 | `batch_stock_quantity` | int | 43 |
| 18 | `sale_price` | float | 12.0 |
| 19 | `stock_A` | int | 0 |
| 20 | `stock` | int | 18 |
| 21 | `create_time` | string | '2025-07-16 11:52:51' |
| 22 | `is_delete` | int | 0 |
| 23 | `custom_label_type` | int | 2 |
| 24 | `goods_second_category_id` | int | 2793236829620037 |
| 25 | `total_sales` | int | 104 |
| 26 | `remark` | string | '' |
| 27 | `audit_status` | int | 2 |
| 28 | `update_time` | string | '2025-11-09 07:23:47' |
| 29 | `pinyin_initial` | string | 'HWDPM,GWDPM' |
| 30 | `goods_bar_code` | string | '' |
| 31 | `able_discount` | int | 1 |
| 32 | `min_discount_price` | float | 7.0 |
| 33 | `sort` | int | 100 |
| 34 | `freeze` | int | 0 |
| 35 | `days_available` | int | 13 |
| 36 | `average_monthly_sales` | float | 1.32 |
| 37 | `safe_stock` | int | 0 |
| 38 | `send_state` | int | 1 |
| 39 | `enable_status` | int | 1 |
| 40 | `sale_channel` | int | 1 |
| 41 | `able_site_transfer` | int | 2 |
| 42 | `cost_price_type` | int | 1 |
| 43 | `forbid_sell_status` | int | 1 |
| 44 | `is_warehousing` | int | 1 |
| 45 | `option_required` | int | 1 |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `commodity_code` | string |
| `goodsStockWarningInfo` | object |
| `not_sale` | int |
| `time_slot_sale` | int |
## 详细字段分析
> 以下内容迁移自旧版 `store_goods_master-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
二、记录级字段详解（45 个字段逐一说明）
我按“维度分类”来拆，确保每个字段都覆盖到。
1. 门店/租户维度
tenant_id
类型：int
含义：租户/品牌 ID。同一品牌下多个门店共享一个 tenant_id。
枚举情况：本文件中为单一固定值（同一品牌）。
site_id
类型：int
含义：门店 ID。
枚举情况：本文件中为单一固定值（同一家门店“朗朗桌球”），和其它 JSON 中的 site_id 一致。
siteName
类型：string
观察值：全为 "朗朗桌球"
含义：门店名称，是对 site_id 的冗余展示，方便直接阅读，无需再去关联门店档案。
2. 商品标识和分类维度
id
类型：int
含义：门店商品 ID，门店维度的商品主键。
用途：在其它文件中经常以 site_goods_id 的名字出现，与这里的 id 一致，用来关联库存记录、销售记录等。
tenant_goods_id
类型：int
含义：租户/品牌维度的商品 ID，相当于“全局商品 ID”。
用途：用于跨门店或与“商品档案（商品档案.json）”对齐时使用。
goods_name
类型：string
含义：商品名称，例如“合味道泡面”“地道肠”“麻将房茶位费”等。
用途：业务展示字段，历史流水里也会冗余存一份商品名。
goods_category_id
类型：int
含义：商品一级分类 ID。
用途：
对应“分类表”（在库存变化记录 2 等文件里）中的主键。
与 oneCategoryName 搭配使用。
goods_second_category_id
类型：int
含义：商品二级分类 ID。
用途：
同样对应分类表中的某个分类 id，其 pid 为一级分类。
与 twoCategoryName 搭配使用。
oneCategoryName
类型：string
含义：一级分类名称，如“零食”“酒水”“服务费”等。
说明：与 goods_category_id 一一对应，是易读文本字段。
twoCategoryName
类型：string
含义：二级分类名称，如“面”“洋酒”“纸巾”等。
说明：与 goods_second_category_id 对应。
unit
类型：string
观察值示例："包", "瓶", "个", "份", "根", "杯", "盒", "桶", "盘", "支" 等。
含义：商品计量单位（销售单位）。
goods_bar_code
类型：string
观察值：当前导出中全部为空字符串。
含义：商品条形码（如 EAN-13 编码），用于扫码销售。此字段设计为可填，但此店目前未配置。
goods_cover
类型：string
含义：商品图片 URL（如 OSS 对象存储地址），用于前端展示商品图片。
pinyin_initial
类型：string
观察值示例："HWDPM,GWDPM", "HJM", "DDC", "QJF150", "15YHGBL" 等。
含义：商品名称的拼音首字母缩写，有时多个别名用逗号分隔。
作用：
用于前端按拼音检索、排序，加快模糊搜索（输入字母即可搜到商品）。
3. 库存与数量相关字段
stock
类型：int
含义：当前可用库存数量（以 unit 为单位）。
特征：可以是 0（库存卖完），也可以非常大（例如纸巾、茶位费这种按“份”计的虚拟库存设定）。
stock_A
类型：int
观察值：本文件全部为 0。
含义（系统设计）：副单位库存数量。如果商品存在双单位（例如箱/瓶），stock_A 通常用于记录副单位库存。当前门店没有启用副单位库存管理，因此为 0。
batch_stock_quantity
类型：int
含义：当前“批次”的库存数量（主单位）。
典型特征：
与 stock 和历史销量有强相关：
对于长期在售商品，batch_stock_quantity 通常大于等于 stock，两者差额可理解为：本批次进货数量减去该批次已消耗数量。
对于刚建档但未真正建立采购记录的商品，可能只是 1 等占位值。
结构性结论：
在有成本价的商品上，batch_stock_quantity × cost_price ≈ provisional_total_cost，说明它是“当前成本批次”的数量基数。
sale_num
类型：int
含义：在当前统计口径下的销售数量（总销量，单位同 unit）。
特征：和 total_sales 完全一致（当前导出时的统计口径下），说明两者是同一统计周期。
total_sales
类型：int
含义（从命名看）：累计销售数量。
实际：当前数据中 total_sales == sale_num，说明此接口的统计区间 = “截至当前的全部历史”，因此数量一致。
结构意义：如果将来系统只查询一段时间，则 sale_num 可能是区间销量，total_sales 可能是历史总销量；字段保留了扩展空间。
safe_stock
类型：int
观察值：全部为 0。
含义：安全库存量（阈值），低于该值时系统可以提示补货。
当前门店尚未设置安全库存，所以全部为 0，仅起到结构占位作用。
4. 价格、成本与金额相关字段
sale_price
类型：float
含义：商品标准销售价（挂牌价），单位为元。
说明：实际结算时可能会打折或用券抵扣，但这个字段表示“定价”。
cost_price
类型：float
含义：商品成本价（单件成本）。
观察：
部分商品为 0（未录入或通过其它方式结转成本），
部分商品为正数，比如“地道肠” cost_price=1.788。
cost_price_type
类型：int，枚举
观察值：
1：154 条
2：7 条
含义（结合成本字段推测）：
1 代表使用“固定成本价”（手工维护的 cost_price），provisional_total_cost 按“数量 × cost_price”算。
2 代表使用“动态成本价”（例如按采购单平均价结转），当前导出中这部分商品 provisional_total_cost 多为 0，说明成本尚未按采购单结转。
provisional_total_cost
类型：float
含义：暂估总成本，单位为元。
观测规律：
对于有成本价的商品，provisional_total_cost ≈ batch_stock_quantity × cost_price（四舍五入差 0.00X 级别）。
结构上的作用：
用于在不逐条展开采购明细的前提下，快速给出当前库存价值的估算。
total_purchase_cost
类型：float
含义：总采购成本，单位为元。
当前数据：与 provisional_total_cost 完全相等。
解释：
从名字看，“total_purchase_cost” 更偏向“已确认采购成本”，而“provisional_total_cost” 更偏向“暂估成本”；在你这份导出中两者还没有区分开来，但字段为后续做结算/重算成本保留了结构空间。
min_discount_price
类型：float
观察值：有的为 0，有的明显小于等于 sale_price（如 sale_price=12, min_discount_price=7）。
含义：最低允许成交价（限价）。
用法逻辑（推测）：
收银/后台手动改价时，系统会校验最终成交价是否 ≥ min_discount_price，低于此价格则不允许成交或需要额外权限。
为 0 时，可能表示“不设置限价/由其它规则控制”。
able_discount
类型：int，枚举
观察值：全部为 1。
含义（结合命名）：
是否允许参与折扣。当前全部为 1，说明所有商品都允许打折。
若系统开启限制，可能会出现 0=不参与任何折扣策略的商品。
5. 时间与销售表现相关字段
create_time
类型：string，格式 YYYY-MM-DD HH:MM:SS
含义：门店商品档案创建时间（商品在门店建立档案的时间点）。
update_time
类型：string
含义：最后一次修改该商品档案的时间（包括价格调整、状态变更等）。
days_available
类型：int
观察值示例：0、1、2、3、12、13、56、100、400、500、2875 等，大范围分布。
含义（结构推断很明确）：
商品“在架天数”或“可售天数”，大致等于当前时间减去首次上架时间。
为 0 的多数是刚建档/刚启用不久的商品。
average_monthly_sales
类型：float
观察值：如 1.32、0.42、13.06、0.16 等。
含义：平均月销量（件/月），根据某个统计周期内的销售数据折算而来。
结构特征：
实际计算公式系统内部掌握即可，你这边只需知道该字段是“历史行为汇总指标”，不参与账务，只是帮助做补货/品类管理的辅助指标。
6. 状态与开关类字段
这类字段很多都是“0/1/2 枚举标志”，需要集中看清。
goods_state
类型：int，枚举
观察值：
1：152 条
2：9 条
结构性判断：
1：正常状态（主流值）。
2：特殊状态（例如“新建未完全启用”、“停售但未下架”等）——这 9 条商品特点是：stock=0、batch_stock_quantity=1、days_available=0，说明它们处于一种“建档但未形成完整库存/销售”的边缘状态。
和 enable_status、send_state 叠加使用，共同确定对外是否可售。
audit_status
类型：int，枚举
观察值：全部为 2。
含义（典型业务语义）：
2：审核通过。
其他值（未在本数据中出现）可能是 0=待提交，1=待审核，3=审核不通过等。
说明：代表这批商品档案已经通过审核，才允许参与业务。
enable_status
类型：int，枚举
观察值：全部为 1。
含义（结合名称与常见编码）：
1：启用。
可能存在 2：停用（未在本数据中出现，但可以推断）。
作用：控制商品档案是否参与任何业务（库存、销售等）。
send_state
类型：int，枚举
观察值：全部为 1。
含义（命名趋近“上架状态/可售状态”）：
1：可销售/可下单。
其它值可能表示“停售”“仅内部使用”等，本数据暂未出现。
备注：和 enable_status、goods_state 一起使用，表达商品对外可售的综合状态。
sale_channel
类型：int，枚举
观察值：全部为 1。
含义：销售渠道类型。
常见模式：
1 可能代表“门店堂食/线下”；
其他值（未出现）可能代表“外卖/线上商城/第三方平台”等。
is_warehousing
类型：int，枚举
观察值：全部为 1。
含义：是否纳入库存管理。
1：启用库存管理（会有出入库流水）。
其他值（0/2）在你其它文件中出现过，一般代表“不计库存”或“历史遗留编码”。
当前门店所有商品都启用了库存管理。
is_delete
类型：int，枚举
观察值：全部为 0。
含义：逻辑删除标志。
0：未删除（有效档案）；
1：已删除（逻辑上删除，不再参与业务，但历史流水保留）。
freeze
类型：int，枚举
观察值：全部为 0。
含义：冻结状态。
0：未冻结；
非 0（未出现在当前数据中）可能表示“锁库存”“禁止出库”等特殊状态。
forbid_sell_status
类型：int，枚举
观察值：全部为 1。
命名上是“禁止销售状态”，结合常见模式：
1：未禁止（允许销售）；
2：被禁止销售（即使上架也不能卖）。
当前门店没有被单独禁售的商品。
able_site_transfer
类型：int，枚举
观察值：
2：160 条
0：1 条
含义（结合命名与值分布）：
表示是否允许跨门店调拨或跨站点共享库存。
2 多半表示“不允许跨店调拨”；0 可能是“未配置/默认值”。
当前门店商品基本都不允许做跨店调拨。
custom_label_type
类型：int，枚举
观察值：全部为 2。
含义（推测）：自定义标签类型。
1：使用系统默认标签（未出现）；
2：使用自定义标签/分类（当前所有商品都为 2）。
从字段名看，和一二级分类、标签打印等功能有关。
option_required
类型：int，枚举
观察值：全部为 1。
含义（推测）：是否需要在销售时选择规格/选项。
1：不要求额外选项（单规格商品）；
若出现其他值，可能代表“必须选择配料/口味/规格”等。
当前门店把所有商品都当作“单规格”处理，未开启复杂选项体系。
able_discount（前面已分析）
类型：int，枚举
观察值：全部为 1，表示所有商品允许参与折扣。
**send_state / enable_status / goods_state 综合说明：
这三个字段都与商品状态相关，但侧重点不同：
goods_state：商品基本状态（建档层面的状态）。
enable_status：是否启用这条商品档案。
send_state：是否在销售端可下单。
当前数据看：绝大多数商品是完全“正常可售”的状态（1/1/1），有少数 goods_state = 2 的边缘状态商品，其他两个字段依然是启用和可售，说明 goods_state 主要用于后台管理上的状态区分。
7. 其它辅助字段
remark
类型：string
观察值：全部为空字符串。
含义：商品备注（可以写口味说明、供应商、注意事项等）。当前尚未使用。
sort
类型：int
观察值：如 100、120 等。
含义：排序权重，用于前端商品列表展示时的排版顺序，数值越小/越大哪个优先，具体规则看系统设定（一般是数值越小排序越靠前）。
batch_stock_quantity / total_purchase_cost / provisional_total_cost 关系补充
对于成本价非 0 的商品，大致满足：
total_purchase_cost ≈ batch_stock_quantity × cost_price
provisional_total_cost ≈ total_purchase_cost
说明：
这套字段主要服务于库存价值估算，和盈利分析无关，是为后续进销存对账、成本核算准备的结构。
三、字段枚举与可能取值小结
为方便后续开发或建模使用，枚举字段集中整理如下（仅基于当前导出数据推断）：
goods_state：
1：正常状态（主流值）
2：特殊状态（新建/停售/未完整启用，配合 stock=0、days_available=0）
audit_status：
2：审核通过（当前唯一值）
enable_status：
1：启用（当前唯一值；停用值未出现在数据中）
send_state：
1：可销售（当前唯一值）
sale_channel：
1：线下门店渠道（当前唯一值）
is_warehousing：
1：参与库存管理（当前唯一值）
is_delete：
0：未删除（当前唯一值）
freeze：
0：未冻结（当前唯一值）
forbid_sell_status：
1：未被禁止销售（当前唯一值）
able_site_transfer：
2：不允许跨店/跨站点调拨（绝大多数记录）
0：未配置（个别记录）
cost_price_type：
1：固定成本价
2：动态成本价（暂未生成实际成本）
custom_label_type：
2：自定义标签（当前唯一值）
option_required：
1：不要求额外选项（单规格商品）
able_discount：
1：允许参与折扣（当前唯一值）
四、从结构角度看，这个文件在整体数据体系中的位置
虽然你目前只要求这个文件本身的字段分析，但结合之前已看过的其它 JSON，可以从字段结构看出以下几条重要关系（纯结构角度，不做任何金额/盈利分析）：
与“商品档案（全局）”的关系
tenant_goods_id 对应全局商品档案中的 id，表示“品牌维度”的商品。
id 则是“门店维度”的商品 ID，对应其它文件中的 site_goods_id。
这说明：
一个全局商品可以在多个门店下产生多个 id（门店商品），各自维护自己的库存、定价、状态。
与库存类文件的关系
在“库存变化记录”“库存汇总”等文件中，字段 siteGoodsId 就是这里的 id，goodsCategoryId/goodsSecondCategoryId 就是这里的 goods_category_id/goods_second_category_id。
也就是说：
门店商品档案 = 商品“主档”；
库存变化记录 = 商品“流水”；
库存汇总 = 商品“统计汇总”。
本文件提供的 stock、batch_stock_quantity、成本相关字段是某一时刻的快照，而库存变动表是全量出入库记录，两者在结构上互相补充。
与销售类文件的关系
“门店销售记录.json” 中的 site_goods_id 与本文件的 id 对应，tenant_goods_id 也一致。
销售记录只记录每一笔销售的数量和金额；而“门店商品档案”提供了商品的基础信息和聚合信息（如 sale_num、average_monthly_sales等）。
从结构角度看，商品档案是维表，销售记录是事实表。
与分类结构的关系
goods_category_id、goods_second_category_id + oneCategoryName、twoCategoryName 在库存分类文件中也有完全对应的 ID 和名称。
整个系统的分类树（父子关系）由分类表维护，这里只是把“已经归类好”的结果冗余在商品档案里，便于业务侧直接使用。

716
docs/api-reference/endpoints/store_goods_sales_records.md Normal file
View File

@@ -0,0 +1,716 @@
# 门店商品销售记录（GetGoodsSalesList）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/GetGoodsSalesList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/TenantGoods/GetGoodsSalesList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `store_goods_sales_records` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `isSalesBind` | int | `0` | 是否绑定销售（0=全部） |
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `goodsSalesType` | int | `0` | 销售类型（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 50 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `siteId` | int | 0 |
| 2 | `siteName` | string | '朗朗桌球' |
| 3 | `orderGoodsId` | int | 0 |
| 4 | `openSalesman` | int | 2 |
| 5 | `id` | int | 2957924029550406 |
| 6 | `order_trade_no` | int | 2957858167230149 |
| 7 | `site_id` | int | 2790685415443269 |
| 8 | `tenant_id` | int | 2790683160709957 |
| 9 | `operator_id` | int | 2790687322443013 |
| 10 | `operator_name` | string | '收银员:郑丽珊' |
| 11 | `order_settle_id` | int | 2957922914357125 |
| 12 | `ledger_name` | string | '哇哈哈矿泉水' |
| 13 | `ledger_group_name` | string | '酒水' |
| 14 | `ledger_unit_price` | float | 5.0 |
| 15 | `ledger_count` | int | 1 |
| 16 | `ledger_amount` | float | 5.0 |
| 17 | `order_pay_id` | int | 0 |
| 18 | `create_time` | string | '2025-11-09 23:35:57' |
| 19 | `is_delete` | int | 0 |
| 20 | `tenant_goods_category_id` | int | 2790683528350540 |
| 21 | `tenant_goods_business_id` | int | 2790683528317768 |
| 22 | `is_single_order` | int | 1 |
| 23 | `site_goods_id` | int | 2793026176012357 |
| 24 | `cost_money` | float | 0.01 |
| 25 | `ledger_status` | int | 1 |
| 26 | `site_table_id` | int | 2793003705192517 |
| 27 | `discount_money` | float | 0.0 |
| 28 | `salesman_user_id` | int | 0 |
| 29 | `salesman_name` | string | '' |
| 30 | `salesman_role_id` | int | 0 |
| 31 | `tenant_goods_id` | int | 2792115932417925 |
| 32 | `discount_price` | float | 5.0 |
| 33 | `real_goods_money` | float | 5.0 |
| 34 | `sales_type` | int | 1 |
| 35 | `package_coupon_id` | int | 0 |
| 36 | `order_coupon_id` | int | 0 |
| 37 | `goods_remark` | string | '哇哈哈矿泉水' |
| 38 | `returns_number` | int | 0 |
| 39 | `member_discount_amount` | float | 0.0 |
| 40 | `point_discount_money` | float | 0.0 |
| 41 | `point_discount_money_cost` | float | 0.0 |
| 42 | `push_money` | float | 0.0 |
| 43 | `sales_man_org_id` | int | 0 |
| 44 | `coupon_deduct_money` | float | 0.0 |
| 45 | `option_value_name` | string | '' |
| 46 | `option_price` | float | 0.0 |
| 47 | `option_member_discount_money` | float | 0.0 |
| 48 | `option_coupon_deduct_money` | float | 0.0 |
| 49 | `member_coupon_id` | int | 0 |
| 50 | `order_goods_id` | int | 2957858456391557 |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `coupon_share_money` | float |
## 详细字段分析
> 以下内容迁移自旧版 `store_goods_sales_records-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
二、单条销售记录字段逐项说明（共 50 个）
我按“业务维度”来分组说明，并标出类型、是否枚举以及与其他表的关系。
2.1 订单 / 商品 / 关联 ID 类字段
id
类型：int
唯一性：200 条记录全部不重复。
含义：本条「门店销售流水」记录的主键 ID。
用途：在系统内部唯一标识这一条销售明细。
order_trade_no
类型：int
唯一值个数：93
含义：订单交易号（业务单号）。
关系：
与台费流水、团购套餐流水、助教流水等表中的 order_trade_no 一致，用于把同一订单下的不同消费项目串联起来（台费、商品、助教、套餐等）。
order_settle_id
类型：int
唯一值个数：88
含义：订单结算 ID（结账单主键）。
关系：
与「小票详情」里的 orderSettleId 对应。
正常情况下，对应结账记录表中的结算主键（本次导出结账记录为空，但字段设计就是为此）。
order_pay_id
类型：int
唯一值个数：89
含义：关联支付记录的 ID。
关系：
对应「支付记录」中的主键或 relate_id，指向本条销售所属的那笔支付流水。
order_goods_id
类型：int
唯一值个数：200（每条都不同）
含义：订单商品明细 ID（订单内部的商品行主键）。
关系：
在其它明细表或小票详情中，如果需要区分订单里的多行商品，通常会用这个 ID 做关联。
orderGoodsId
类型：int
唯一值个数：1，全部为 0
含义：老版本字段 / 兼容字段，理论上也是订单内商品明细 ID。
说明：
当前接口已经统一使用 order_goods_id，orderGoodsId 处于「保留但未使用」状态，因此全部为 0。
site_goods_id
类型：int
唯一值个数：61
含义：门店商品 ID。
关系：
对应 门店商品档案1.json 中的 id 字段。
所有库存与销售明细针对的商品，在门店维度都是用这个 ID 做主键。
tenant_goods_id
类型：int
唯一值个数：61
含义：租户（品牌）级商品 ID（全局商品 ID）。
关系：
对应「商品档案（全局）」中的 id 或同名字段。
一个全局商品在多个门店可以生成多个 site_goods_id，但共享同一个 tenant_goods_id。
tenant_goods_category_id
类型：int
唯一值个数：9
含义：租户级商品一级分类 ID。
关系：
对应分类表中的一级分类主键，用于品牌维度的商品分类。
tenant_goods_business_id
类型：int
唯一值个数：7
含义：租户级商品「业务大类」ID（例如“零食类”“酒水类”等更高维度）。
2.2 门店 / 球台维度字段
tenant_id
类型：int
含义：租户/品牌 ID。
特征：所有记录为同一个值，对应「非球科技系统中你的商户」。
site_id
类型：int
含义：门店 ID（系统主键）。
关系：
与其它 JSON（台费流水、助教流水、库存类等）中的 site_id 一致，都指向同一家门店。
siteName
类型：string
观测值：全部为 "朗朗桌球"
含义：门店名称，是对 site_id 的冗余文本。
siteId
类型：int
观测值：全部为 0
含义：历史兼容字段，当前接口中不再使用。真正的门店 ID 已经统一用 site_id 表示。
site_table_id
类型：int
唯一值个数：31
观测值：既有非零长整型，也有为 0 的情况。
含义：球台 ID。
非 0：销售记录关联到具体某张桌台（例如顾客在台上点饮料）。
0：该商品销售未关联桌台（例如纯前台售卖或库存调整类销售）。
关系：
对应「台桌列表」中的 id 字段。
2.3 商品名称 / 分组 / 备注类字段
ledger_name
类型：string
含义：销售项目名称（商品名称），例如 “哇哈哈矿泉水”“地道肠”“东方树叶”等。
说明：业务展示用字段，历史流水即使商品改名，这里会保留当时的名字。
ledger_group_name
类型：string
观测值示例："酒水", "零食", "小吃", "服务费" 等。
含义：销售项目所属的「门店内部分组名称」，类似前台菜单分组或大类标签。
关系：
与 tenant_goods_category_id / 分类表是两套维度：
一套是品牌统一分类（tenant_goods_category_id），
一套是门店前台展示的分组（ledger_group_name）。
goods_remark
类型：string
观测：
部分记录为空；
部分与商品名相同，例如 ledger_name="哇哈哈矿泉水"，goods_remark="哇哈哈矿泉水"。
含义：商品备注/口味说明/特殊说明。
用途：点单时如果需要额外说明，可以写在这里。
option_value_name
类型：string
观测值：本批数据全部为空字符串。
含义：商品选项名称（如规格、口味：大杯/小杯，不加冰等）。
结构用途：
为将来支持“多规格/多口味商品”留的位；当前门店未启用，所有销售都视为单规格。
2.4 金额 / 单价 / 数量相关字段
ledger_unit_price
类型：float
含义：商品在该次销售中的「结算单价」（元/单位）。
观测值示例：5.0, 8.0, 2.0, 10.0, 72.0 等。
ledger_count
类型：int
含义：销售数量（以 unit 为单位，unit 字段在门店商品档案中）。
观测值：如 1, 2, 3, 6, 36 等。
ledger_amount
类型：float
含义：原始应收金额，公式上接近 ledger_unit_price × ledger_count。
说明：这是未考虑优惠前的金额基础，用于后续计算折扣和抵扣。
discount_price
类型：float
含义：折后单价（元/单位）。
观测：
对于无折扣商品，discount_price = ledger_unit_price；
对于有折扣商品，discount_price < ledger_unit_price，例如单价 8 元，折后单价 6 元。
discount_money
类型：float
含义：本条销售明细的「价格优惠金额」，即原价部分被减免掉的金额。
典型关系：
在简单场景下：ledger_amount - discount_money = real_goods_money（再加上积分/券抵扣后才是最终收入）。
观测示例：0.0, 1.0, 2.0, 4.0, 540.0 等。
real_goods_money
类型：float
含义：商品实际入账金额（考虑折扣、可能还会考虑其它抵扣后的实际销售金额）。
观测值：5.0, 10.0, 8.0, 6.0, 4.0 等。
结构地看：real_goods_money ≤ ledger_amount，差额由各类优惠字段解释（折扣、优惠券、积分等）。
cost_money
类型：float
含义：本条销售对应的成本金额（以元计）。
观测示例：0.01, 0.00, 3.58, 1.79, 0.64 等。
关系：
透视结构时，cost_money 对应该销售的成本摊销结果，来源于门店商品档案中 cost_price 与成本核算逻辑。
returns_number
类型：int
观测值：全部为 0
含义：退货数量（如果这条明细做了退货，会记录退货数量）。
当前导出时间段内，没发生退货，因此都是 0。
2.5 积分 / 优惠券 / 抵扣类字段
coupon_deduct_money
类型：float
观测值：全部为 0.0
含义：被优惠券 / 团购券直接抵扣到这条商品明细上的金额。
说明：
当前样本中没有券直接作用于单个商品，因此为 0；
如果有券只在订单级抵扣，这部分优惠就不会写到商品层的 coupon_deduct_money。
member_discount_amount
类型：float
观测值：全部为 0.0
含义：由会员身份（会员折扣）针对这一行商品产生的优惠金额。
说明：尽管字段存在，但当前实际折扣可能合并反映在 discount_money 中，这个字段没有拆开体现。
point_discount_money
类型：float
观测值：全部为 0.0
含义：由积分抵扣的金额（顾客兑换积分抵现金额）。
point_discount_money_cost
类型：float
观测值：全部为 0.0
含义：积分抵扣对应的“成本金额”（后台核算用），例如按积分成本来计提费用。
package_coupon_id
类型：int
观测值：全部为 0
含义：套餐券 ID。
关系：
若某商品是从套餐拆分出来的，可能会记录这个字段，用于追溯到「团购套餐流水」或相关套餐定义。当前样本中没有使用这个结构。
order_coupon_id
类型：int
观测值：全部为 0
含义：订单级优惠券 ID。
关系：
当整个订单使用某张优惠券（而非单个商品），会在订单主表 /订单层记录 order_coupon_id；
商品层的这个字段可能用于记录“订单级券对本行分摊的关系”。目前样本未使用。
member_coupon_id
类型：int
观测值：全部为 0
含义：会员券 ID（比如会员专享优惠券）。
当前数据未使用，属于为会员权益预留的字段。
option_price
类型：float
观测值：全部为 0.0
含义：商品选项（规格/加料）的附加价格。
说明：如加冰、加料、升级大杯等产生附加费用时，理论上应该体现到这里。当前门店未使用此功能。
option_member_discount_money
类型：float
观测值：全部为 0.0
含义：由会员折扣作用在“选项价格”上的优惠金额。
option_coupon_deduct_money
类型：float
观测值：全部为 0.0
含义：由优惠券抵扣“选项价格”的金额。
上面这三个 option_* 字段，是为“主商品 + 选项”的更复杂计价方式预留的，本店当前所有记录都是单规格，选项体系未启用。
2.6 操作员 / 销售员相关字段
operator_id
类型：int
唯一值个数：1
含义：操作员 ID（录入这笔销售的员工）。
关系：
与其它流水中的 operator_id 相同，可以跨台费/助教/商品销售统一看到是谁操作。
operator_name
类型：string
观测示例："收银员:郑丽珊" 等。
含义：操作员姓名，文字冗余。
openSalesman
类型：int，枚举
观测值：全部为 2
含义（结合系统其它文件推断）：
1：启用“营业员/销售员”机制（要指定 salesman）；
2：未启用营业员机制，本条记录不单独计算某销售员提成。
当前门店配置中显然未启用营业员分成功能，对全部商品都统一为 2。
salesman_name
类型：string
观测值：全部为空字符串
含义：营业员姓名（如果有为具体销售员记业绩，则在此填姓名）。
salesman_user_id
类型：int
观测值：全部为 0
含义：营业员用户 ID（系统账号 ID）。
salesman_role_id
类型：int
观测值：全部为 0
含义：营业员的系统角色 ID（例如某个角色代码表示“销售员”）。
sales_man_org_id
类型：int
观测值：全部为 0
含义：营业员所属组织/部门 ID。
当前门店全部为 0，说明未启用这套销售员分组织的体系。
push_money
类型：float
观测值：全部为 0.0
含义：本条销售对应的提成金额（给营业员/促销员的提成）。
在启用营业员体系时，这里才会出现正数。
2.7 记录状态 / 控制类字段
ledger_status
类型：int，枚举
观测值：全部为 1
含义：销售流水状态。
1：正常有效。
其他数值（未在本数据中出现）一般表示“待结算”“作废”等。
is_single_order
类型：int，枚举
观测值：全部为 1
含义：是否单独订单标识。
1：作为独立明细参与某个订单结算；
0：可能在某些特殊业务中合并为打包项目。
当前门店所有商品销售都按照常规方式参与订单，所以全部为 1。
sales_type
类型：int，枚举
观测值：全部为 1
含义：销售类型。
1：正常销售；
其他数值常见用法（数据中未出现）可能是：2 = 赠品；3 = 内部消耗；4 = 盘点调整等。
结构上，sales_type 决定这条记录在统计时属于哪类业务。
is_delete
类型：int，枚举
观测值：全部为 0
含义：逻辑删除标志。
0：正常有效；
1：已删除（仅保留历史，不再参与前端展示及统计）。
2.8 时间字段
create_time
类型：string（格式 YYYY-MM-DD HH:MM:SS）
含义：销售记录创建时间，通常就是结账时间或录入时间。
用途：用于按时间维度查询销售流水，与订单层的时间字段对齐。
三、从字段看「门店销售记录」在整体数据结构中的位置（纯结构关系）
只从字段结构出发，不做任何金额/盈利计算，可以看到这份销售记录在整个系统中的“连接点”：
订单维度
order_trade_no / order_settle_id
与台费、助教、团购套餐流水等表共享，形成「订单主表（结算）– 多种明细表」的结构。
如果结账记录表有数据，order_settle_id 对应那里的主键，create_time 与订单结束时间基本一致。
支付维度
order_pay_id
连接到「支付记录」中的一条支付流水，再通过支付的 relate_type/relate_id 把支付和订单、充值等业务区分开。
对于退款，则通过退款记录里的 relate_type/relate_id 反向关联到原来的订单或支付。
商品维度
site_goods_id ↔ 门店商品档案1.json.id
tenant_goods_id ↔ 全局商品档案 ID
tenant_goods_category_id / tenant_goods_business_id ↔ 分类与业务大类表
→ 这一层关系把「商品定义」与「销售明细」连接起来，方便做结构上的货品分析（类别、品牌维度等），而不是金额分析。
库存维度
在「库存变化记录1.json」中，siteGoodsId 就等于这里的 site_goods_id。
每一次商品销售理论上应对应一次库存的出库记录（stockType=出库），虽然那个表没有直接再写订单号，但通过商品 ID 和时间可以在结构上对应得上。
「库存汇总.json」则在商品维度上汇总了进出库数量，与 sale_num 等聚合指标对齐。
球台维度
site_table_id ↔ 「台桌列表.json」的 id
当 site_table_id 非 0 时，说明这条商品销售与具体球台关联（例如在某桌消费时点单）；
为 0 时则是与台桌无关的前台销售/其它业务。
人员维度
operator_id / operator_name 与其它流水（台费、助教等）的同名字段一致，形成一个统一的「操作员」维度。
openSalesman、salesman_* 一组字段则是预留的「营业员/提成」体系，目前处于关闭状态（全部 2 / 0）。
优惠 / 券 / 积分维度
本文件中的 coupon_deduct_money、order_coupon_id、member_coupon_id 等字段目前值都为 0，说明在当前时间段样本内：
优惠券/团购券更多是在订单级别处理，而非按商品行拆分；
但是结构已经支持将来按商品拆分优惠。
与「平台验券记录」「团购套餐流水」这类券相关表，理论上可以通过订单号或券 ID 去对应（当前样本内此方向的结构信息在订单级别更多）。
整体上，「门店销售记录.json」可以视为商品维度的核心事实表，它挂在订单主键下面，通过 site_goods_id 与商品档案、库存表相连，通过 site_table_id 与球台表相连，再通过 tenant_id/site_id 统一到门店维度，通过 operator_id 连接到操作员维度。

516
docs/api-reference/endpoints/table_fee_discount_records.md Normal file
View File

@@ -0,0 +1,516 @@
# 台费优惠记录（GetTaiFeeAdjustList）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Site/GetTaiFeeAdjustList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/Site/GetTaiFeeAdjustList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `table_fee_discount_records` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 20 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `tableProfile` | object | {'id': 2793020259897413, 'tenant_id': 2790683160709957, '... |
| 2 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
| 3 | `id` | int | 2957913441881989 |
| 4 | `adjust_type` | int | 1 |
| 5 | `applicant_id` | int | 2790687322443013 |
| 6 | `applicant_name` | string | '收银员:郑丽珊' |
| 7 | `create_time` | string | '2025-11-09 23:25:11' |
| 8 | `is_delete` | int | 0 |
| 9 | `ledger_amount` | float | 148.15 |
| 10 | `ledger_count` | int | 1 |
| 11 | `ledger_name` | string | '' |
| 12 | `ledger_status` | int | 1 |
| 13 | `operator_id` | int | 2790687322443013 |
| 14 | `operator_name` | string | '收银员:郑丽珊' |
| 15 | `order_settle_id` | int | 2957913171693253 |
| 16 | `order_trade_no` | int | 2957784612605829 |
| 17 | `site_id` | int | 2790685415443269 |
| 18 | `site_table_id` | int | 2793020259897413 |
| 19 | `tenant_id` | int | 2790683160709957 |
| 20 | `tenant_table_area_id` | int | 2791961347968901 |
## 详细字段分析
> 以下内容迁移自旧版 `table_fee_discount_records-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
这个 JSON 是“台费打折 / 台费调整流水表”。每条记录不是“台的使用记录”，而是 在台费基础上追加的一条“金额调整记录”，用来记录某个订单、某张台在台费上的手工打折/减免金额。
二、记录级字段拆解与说明
以下字段说明全部针对 taiFeeAdjustInfos 里的单条记录。
为方便理解，先给出字段列表：
关联与主键类：id, order_trade_no, order_settle_id, tenant_id, site_id, site_table_id, tenant_table_area_id
台桌 / 门店快照：tableProfile, siteProfile, ledger_name
金额与数量：ledger_amount, ledger_count
申请 / 操作信息：adjust_type, applicant_id, applicant_name, operator_id, operator_name, create_time
状态标记：ledger_status, is_delete
1. 主键与订单关联字段
id
类型：int
唯一性：每条记录一个独立值。
含义：台费打折 / 调整流水主键 ID。
作用：在“台费调账表”中唯一标识一条折扣/调账操作。
order_trade_no
类型：int
唯一性：本文件中 200 条记录出现 195 个不同的值（有少数订单有多条调整记录）。
含义：订单交易号。
关联：
与 台费流水.json、助教流水.json、小票详情.json 中的同名字段一致，用于把这一条“台费调整”挂接到某笔订单上。
order_settle_id
类型：int
唯一性：本页记录中每条都有自己的 order_settle_id。
含义：结算单/小票 ID。
关联：
与“小票详情.json”中的 orderSettleId 对应；
与其他消费流水（台费、助教、商品）中 order_settle_id 一致，作为同一次结账的统一主键。
tenant_id
类型：int
当前值：全部为同一个 ID（例如 2790683160709957）。
含义：租户/品牌 ID。
作用：标识记录属于哪一个商户（同一个“非球科技”租户）。
site_id
类型：int
当前值：全部为同一值（例如 2790685415443269）。
含义：门店 ID，本批数据全部为同一家门店（朗朗桌球）。
关联：
与 siteProfile.id 一致；
与其它 JSON 中的 site_id 一致，用于保证门店维度对齐。
site_table_id
类型：int
当前有约 50 个不同值。
含义：台桌 ID。
关联：
与 台费流水.json 中的 site_table_id 一致；
与“台桌列表”/台桌配置表中的 id 对应，表明是哪一张台发生了打折/调账。
tenant_table_area_id
类型：int
当前有约 13 个不同值。
含义：租户维度的“台桌区域 ID”。
关联：
与台桌区域配置表对应，帮助从区域维度分析打折分布（结构上可用）。
2. 台桌与门店快照字段
tableProfile
类型：object（字典）
键包括：
id：台桌 ID（与 site_table_id 对应）
tenant_id：租户 ID
tenant_name：租户名称（当前为空字符串）
siteName：站点/门店名（当前为空字符串，门店名在 siteProfile.shop_name 中）
table_name：台号（如 "S1", "VIP1", "A10" 等）
site_table_area_id：门店内区域 ID
site_table_area_name：区域名（如 "斯诺克区", "VIP包厢", "A区" 等）
area_type_id：区域类型 ID（当前为 0，未使用）
table_price：台的基础单价（当前为 0.0，不在这里维护）
ewelink_client_id：智能硬件 ID（当前为空）
charge_free：是否免单标识（当前为 0）
含义：折扣发生时，对应台桌的配置信息快照。
siteProfile
类型：object
内容与其他文件保持一致，包括：
门店 ID、组织 ID、门店名称、门店头像、电话、地址、经纬度、营业状态、标签等。
含义：门店信息快照，用于报表时直接读取，无需再联门店档案。
ledger_name
类型：string
当前观测：全部为空字符串（200 条记录所有值均为 ''）。
含义（推测）：
设计上应该用于记录“调账项目名称”或“打折原因描述”（例如某种优惠规则名称），但当前门店并未使用该字段。
结论：结构上是预留字段，目前这家门店的台费打折没有填写名称，信息集中在金额层面。
3. 金额与数量字段
ledger_amount
类型：float
当前记录：共有 182 个不同的数值，典型值如：
96.0（5 条）
120.0（4 条）
75.33、144.0、8.18、35.51、69.0、100.0 等
含义（关键点）：
通过与 台费流水.json 做对比，可以明确：
对于某个 order_trade_no，在台费流水中有：
ledger_amount = 原始应收台费金额；
adjust_amount = 台费调账金额；
在台费打折表中：
对应同一个 order_trade_no 的 ledger_amount = 台费流水中的 adjust_amount。
例如（真实数据）：
某订单：
台费流水：ledger_amount = 203.44, adjust_amount = 101.72, real_table_charge_money = 101.72
台费打折：ledger_amount = 101.72
说明：这一条台费打折记录的金额，正是该订单在台费上被减免/调账的金额。
结论：
在本表中，ledger_amount 表示 “台费调账/减免金额”，不是使用时长对应的原价，而是“被调整掉”的那一部分金额。
ledger_count
类型：int
当前观测：全部为 1（200 条所有记录）。
含义：
这里不是“秒数”，而是“调整次数/条数”的量化，目前固定为 1，表示“一次调账事件”。
即：本表中的“计数”是按条计，不是按时间计。
与台费流水中的 ledger_count（计费秒数）完全不同含义。
4. 申请与操作相关字段
adjust_type
类型：int，枚举字段。
当前观测：全部为 1。
含义（根据文件含义 + 命名 + 数据）：
文件名是“台费打折”，字段名为“调整类型”，当前所有记录都是 1，即“台费打折/台费减免”这一种调整类型。
推测枚举含义可能类似：
1：台费打折/减免；
其他值（未出现）：可能用于“台费转移”、“误操作恢复”等其它调整类型。
结论：
当前门店仅使用了 adjust_type = 1 这一种类型，对应台费打折/减免；其他类型未在本数据出现。
applicant_id
类型：int
当前观测：全部为同一个 ID，例如 2790687322443013。
含义：打折/调账申请人 ID。
作用：记录谁发起了这次台费调整。
本时段内所有调整均由同一位员工发起。
applicant_name
类型：string
当前观测：全部为同一个字符串，如："收银员:郑丽珊"。
含义：申请人姓名（带角色描述），为 applicant_id 的冗余显示字段。
operator_id
类型：int
当前观测：全部与 applicant_id 相同。
含义：实际执行调账操作的操作员 ID。
说明：这段时间内，“申请人”和“操作员”是同一个人。
operator_name
类型：string
当前观测：全部与 applicant_name 相同。
含义：操作员姓名。
create_time
类型：string，格式 YYYY-MM-DD HH:MM:SS
唯一性：200 条记录中有 171 个不同时间点，有些时间点有多条记录（比如同一时刻对不同台/订单进行多次调整）。
含义：台费调整记录的创建时间，即打折操作被执行的时间戳。
说明：与台费流水中的 create_time（结算时间）相互配合，可以还原调整发生于结账之前还是之后。
5. 状态与删除标记
ledger_status
类型：int，枚举字段。
当前观测：
值为 1 的记录：195 条
值为 0 的记录：5 条
结合数据特征：
某些订单有多条打折记录，其中：
旧记录 ledger_status = 0
最新一条 ledger_status = 1
同一 order_trade_no 下，ledger_status = 0 的记录在台费流水的 adjust_amount 中不再生效，只保留 ledger_status = 1 对应的金额。
推测枚举含义：
1：生效调整（当前有效的台费打折 / 调账记录）；
0：已失效/被覆盖的调整记录（历史记录、已撤销或被后续调账覆盖）。
结论：
ledger_status 是“调整记录自身的状态”，用于区分历史打折记录和当前有效的那条。
is_delete
类型：int，枚举字段。
当前观测：全部为 0。
含义：逻辑删除标志：
0：未删除（有效记录）；
1：已逻辑删除（后台标记删除）。
当前时间段没有逻辑删除的调整记录，但表结构已经预留这个标志。
三、与其它 JSON 的关联关系（从结构与字段角度）
1. 与台费流水（20251110_035011_台费流水.json）
关联字段：
order_trade_no：两表共有
order_settle_id：两表共有
site_id、tenant_id：门店与租户维度一致
site_table_id：指向同一张台
结构关系：
对于某个订单 order_trade_no = X：
台费流水表（siteTableUseDetailsList）里有一条记录：
ledger_amount：原始应收台费金额；
adjust_amount：在这条台费上调账/减免的金额；
real_table_charge_money：顾客实际付的台费（不含券承担部分）。
台费打折表（taiFeeAdjustInfos）里有一条或多条记录：
ledger_amount = 对应台费流水中的 adjust_amount（生效那条折扣）。
ledger_status = 1 的记录是“当前有效”的调账金额；0 的记录是旧的、不再生效的历史打折记录。
用法（结构角度）：
台费流水给出 时长 + 原始台费 + 各种金额拆分（含 adjust_amount）；
台费打折表给出 是谁、何时、以哪种类型（adjust_type）发起了这笔调账，调了多少金额；
两表通过 order_trade_no（或 order_settle_id + site_table_id）做一对一 / 一对多关系，从而完整还原“这笔台费折扣从哪来”的结构链条。
2. 与台桌配置 / 区域配置
site_table_id ↔ 台桌配置表的 id；
tableProfile.table_name ↔ 台桌配置表中的 table_name；
tableProfile.site_table_area_id、tableProfile.site_table_area_name ↔ 门店台桌区域维表；
tenant_table_area_id ↔ 租户层面的区域维表。
结构线索：
台费打折可以按“区域”和“台号”两个维度归集（结构上可行），例如统计“斯诺克区”发生过多少次台费调整操作，这里先停留在结构层面，不做数值统计。
3. 与门店信息（siteProfile）
siteProfile.id ↔ site_id
内含门店名称、地址、经纬度等，与其它 JSON 里的 siteProfile 一致。
结构线索：
若多门店数据放在一起，siteProfile 冗余在每条记录中，可以直接按门店维度进行分组，而无需再去门店档案表查名称。
4. 与员工/账号体系
applicant_id / operator_id 与账号体系中的用户 ID 对应（与助教账号 user_id 属于同一 ID 空间）。
applicant_name / operator_name 为相应的姓名快照。
结构线索：
后续可以按员工维度统计“某收银员进行了多少次台费打折、调整金额是多少”，这是结构上天然支持的（本门店当前全部折扣都由同一人发起）。
四、本表在整体数据模型中的结构角色（从字段设计的角度）
从字段设计可以看出：
taiFeeAdjustInfos 是专门用于“台费调账/打折”的事实表
它不记录时长，只记录金额和操作人；
与台费流水表形成一对一/一对多的“主表+子操作表”关系；
通过 order_trade_no + site_table_id 等字段和台费流水紧密联动。
金额语义与台费流水的“adjust_amount”强绑定
台费流水中 adjust_amount 字段本身只是一个“结果值”；
台费打折表里，用 ledger_amount 再详细记录每一次调整，且补充了操作人、操作时间、状态（ledger_status）、类型（adjust_type）等信息。
也就是说：台费流水里的 adjust_amount 实际上是台费打折表中 ledger_amount 的汇总结果（在结构上是一致的）。
状态字段把“历史折扣记录”和“当前有效折扣”分离
通过 ledger_status 区分有效和失效的调整记录，允许同一订单多次修改折扣；
表明系统设计上支持“反悔/覆盖折扣”的业务流程。
adjust_type 为将来扩展预留空间
虽然当前所有记录都是 1（台费打折），但从命名看，可以扩展到其它类型调整，如台费转移、误操作修正等。
结构上已经清晰区分“调整类型”，便于将来拆分不同业务路径。
ledger_count 固定为 1，清晰地把“台费使用时长”和“台费调整次数”分离
台费使用时长在台费流水表中、单位是秒；
台费打折只管“第几次调整”，不和时间绑定，避免混淆。
五、小结（本文件的结构重点）
20251110_035908_台费打折.json 记录的是 台费层面的“打折 / 调账”流水，不是台的使用流水。
每条记录核心信息包括：
调账金额：ledger_amount（即台费流水中的 adjust_amount）
订单关联：order_trade_no、order_settle_id
台桌定位：site_table_id + tableProfile.table_name
区域维度：tenant_table_area_id + tableProfile.site_table_area_name
操作人维度：applicant_id/applicant_name、operator_id/operator_name
时间维度：create_time
状态与类型：ledger_status（有效/失效）、adjust_type（当前仅为台费打折）
从结构关系来看，它与 台费流水 做的是金额层面的一一校对，通过 adjust_amount ↔ ledger_amount 的关系，把“原始台费金额”和“实际负担方（顾客/券/内部调账）”这条链路闭合起来；同时也为后续从“员工/时间/区域”维度审计台费打折行为提供了完整的结构基础，而不涉及任何盈利或经营分析。

739
docs/api-reference/endpoints/table_fee_transactions.md Normal file
View File

@@ -0,0 +1,739 @@
# 台费流水（GetSiteTableOrderDetails）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Site/GetSiteTableOrderDetails` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/Site/GetSiteTableOrderDetails` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `table_fee_transactions` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `isSaleManUser` | int | `0` | 是否销售员用户（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 39 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
| 2 | `id` | int | 2957924029058885 |
| 3 | `order_trade_no` | int | 2957858167230149 |
| 4 | `site_id` | int | 2790685415443269 |
| 5 | `tenant_id` | int | 2790683160709957 |
| 6 | `member_id` | int | 0 |
| 7 | `operator_id` | int | 2790687322443013 |
| 8 | `operator_name` | string | '收银员:郑丽珊' |
| 9 | `order_settle_id` | int | 2957922914357125 |
| 10 | `ledger_unit_price` | float | 48.0 |
| 11 | `ledger_name` | string | 'A17' |
| 12 | `ledger_count` | int | 3600 |
| 13 | `ledger_amount` | float | 48.0 |
| 14 | `order_pay_id` | int | 0 |
| 15 | `create_time` | string | '2025-11-09 23:35:57' |
| 16 | `is_delete` | int | 0 |
| 17 | `site_table_id` | int | 2793003705192517 |
| 18 | `site_table_area_id` | int | 2791963794329671 |
| 19 | `tenant_table_area_id` | int | 2791960001957765 |
| 20 | `is_single_order` | int | 1 |
| 21 | `ledger_start_time` | string | '2025-11-09 22:28:57' |
| 22 | `ledger_end_time` | string | '2025-11-09 23:28:57' |
| 23 | `ledger_status` | int | 1 |
| 24 | `site_table_area_name` | string | 'A区' |
| 25 | `real_table_charge_money` | float | 0.0 |
| 26 | `used_card_amount` | float | 0.0 |
| 27 | `adjust_amount` | float | 0.0 |
| 28 | `real_table_use_seconds` | int | 3600 |
| 29 | `coupon_promotion_amount` | float | 48.0 |
| 30 | `service_money` | float | 0.0 |
| 31 | `member_discount_amount` | float | 0.0 |
| 32 | `last_use_time` | string | '2025-11-09 23:28:57' |
| 33 | `salesman_name` | string | '' |
| 34 | `salesman_user_id` | int | 0 |
| 35 | `salesman_org_id` | int | 0 |
| 36 | `mgmt_fee` | float | 0.0 |
| 37 | `fee_total` | float | 0.0 |
| 38 | `start_use_time` | string | '2025-11-09 22:28:57' |
| 39 | `add_clock_seconds` | int | 0 |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `activity_discount_amount` | float |
| `order_consumption_type` | int |
| `real_service_money` | float |
## 详细字段分析
> 以下内容迁移自旧版 `table_fee_transactions-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
二、记录级字段拆解与说明
1. 顶层 / 分页相关
code（在数组元素上）
类型：int
枚举：当前仅出现 0。
含义：接口调用状态，0 表示成功。
data.total
类型：int
含义：本次查询条件下台费流水总条数（3813），用于分页计算。
data.siteTableUseDetailsList
类型：array
含义：台费流水记录列表，每个元素即一次台费使用记录。
2. 主键 / 订单维度字段
这些字段用来把台费流水和订单、小票、支付等其他表关联在一起。
id
类型：int
唯一性：每条记录一个独立值。
含义：台费流水记录主键（事实表主键）。
order_trade_no
类型：int
唯一性：本文件中每条记录一个值（200 条全不重复）。
含义：订单交易号，是整笔订单的主编号。
关联：
与其它 JSON（如 助教流水、小票详情、门店销售记录）中的同名字段一致，用于把 同一订单下的台费、助教、商品等多条明细串联。
order_settle_id
类型：int
唯一性：每条记录一个值（200 条全不重复）。
含义：结算单号/结账 ID，对应一次结账操作。
关联：
与“小票详情.json”中的 orderSettleId 对应；
与（若存在）结账记录表的主键对应。
order_pay_id
类型：int
含义：订单支付记录 ID。
关联：
对应“支付记录.json”中的 id 或 relate_id（视模型而定），用于追踪这条台费最终对应哪一条支付流水。
tenant_id
类型：int
观测：所有记录值相同（2790683160709957）。
含义：租户/品牌 ID。本文件所有记录都属于同一租户。
关联：与所有其它 JSON 中的 tenant_id 一致，用于跨表做“商户维度”的过滤。
site_id
类型：int
观测：所有记录相同（2790685415443269）。
含义：门店 ID，本次数据全部来自同一门店（朗朗桌球）。
关联：
与 siteProfile.id 一致；
与其它表（助教流水、销售记录等）中的 site_id 对应，保证“门店维度”一致。
3. 台桌维度字段
这些字段描述“哪一张台、在哪个区域”。
site_table_id
类型：int
唯一性：约 45 个不同值。
含义：球台 ID。
关联：
对应“台桌列表”中的 id（当前导出文件中有一类与之对应的台桌配置表）。
用于精确确定具体是哪个台。
ledger_name
类型：string
示例值："A1"、"A2"、"A3"、"A4"、"A5"、"A7"、"A8"、"A9"、"A10"、"S1" 等。
含义：台号名称，实际展示给员工/顾客看的桌台编号。
备注：与 site_table_id 一一对应，是桌台维表中的名称字段冗余到流水里的快照。
site_table_area_id
类型：int
唯一性：10 个左右的不同值。
含义：门店内“台桌区域” ID（站在门店物理布局的角度）。
关联：
对应“门店台桌区域配置表”的主键；
与 site_table_area_name 搭配使用。
tenant_table_area_id
类型：int
唯一性：与 site_table_area_id 数量相同，也是 10 个值。
含义：租户维度的台桌区域 ID（品牌层面的同一类区域）。
关联：
对应租户层面的“区域维表”，支持多门店共享同一套区域配置。
site_table_area_name
类型：string
枚举（本数据中观测值）：
"A区"（144 条）
"B区"（21 条）
"斯诺克区"（17 条）
"麻将房"（6 条）
"C区"（5 条）
"K包", "VIP包厢"（各 2 条）
"666", "TV台", "M8"（各 1 条）
含义：台桌区域的名称，用于门店表现和区域统计。
4. 会员维度与相关字段
member_id
类型：int
观测：
多数为 0（180 条），表示散客/非会员。
少量为非 0 的 10 个不同 ID。
含义：门店/租户内的会员 ID。
关联：
与“会员档案.json（tenantMemberInfos）”内的 id 对应（有部分 ID 完全匹配，部分会员可能不在当前导出页）。
用于将台费流水关联到具体哪位会员。
member_discount_amount
类型：float
观测：
大多数为 0.0；
少量为正值，如 376.87、259.16、151.98、253.02、108.16 等。
含义：由会员权益产生的优惠金额，例如会员折扣、会员价等。
特点：
在部分记录中 ledger_amount = real_table_charge_money = member_discount_amount，说明该台费完全通过会员权益抵扣，记录在此字段，同时仍保留原价。
used_card_amount
类型：float
观测：当前样本全部为 0.0。
含义（推测）：储值卡/次卡直接抵扣到台费的金额。
说明：字段已预留，但在本时间范围内台费未通过“卡余额”支付，或该信息不在此表体现。
5. 时间与时长相关字段
5.1 时间点
create_time
类型：string，格式 YYYY-MM-DD HH:MM:SS
含义：这条台费流水记录的创建时间，通常接近结账时间。
start_use_time
类型：string
含义：台开始使用的时间（实际开台时间）。
特点：在数据中，与 ledger_start_time 完全相同（见下）。
last_use_time
类型：string
含义：最后使用/操作时间。
特点：
大多数情况下与 ledger_end_time 只差 1 秒；
可以理解为“真实最后一次计时上报的时间”。
ledger_start_time
类型：string
含义：台账上的计费起始时间。
关系：
当前数据中 ledger_start_time == start_use_time，说明起算时刻与开台时间一致。
ledger_end_time
类型：string
含义：台账上的计费结束时间。
关系：
和 last_use_time 多数情况下相差 1 秒（last_use_time 比它晚 1 秒），说明计费结束时间经系统截断处理，而 last_use_time 是最后事件时间。
5.2 时长（秒）
ledger_count
类型：int
含义：台账记录的计费秒数，计费用秒数（应收时长）。
特点：
大部分记录中 ledger_count 等于 real_table_use_seconds，少数记录差 1 秒（对齐问题）。
为 0 的少数记录（6 条），对应 real_table_use_seconds 也为 0。
real_table_use_seconds
类型：int
含义：实际使用的总秒数（系统真实统计的使用时长）。
关系：
与 ledger_count 基本一致（只有 +1 秒的偏差），可以认为 ledger_count 是基于它做的计费截断结果。
当两者均为 0 且 is_single_order = 0 时，表示这条记录只是占位/关联记录，并未产生真实使用和收费（例如合单场景或转移）。
add_clock_seconds
类型：int
含义：加钟秒数，在原有使用基础上追加的时长。
观测：
绝大部分记录为 0；
少数为 2400（40 分钟）、4200（70 分钟）等 60 的倍数。
说明：加钟逻辑为分钟级别，字段用于记录累计加钟时长。
6. 金额与优惠拆分字段
这些字段共同描述“台费原价金额”和各类优惠/调整后的分解。
ledger_unit_price
类型：float
示例值：48.0、58.0、68.0、88.0、98.0、116.0 等。
含义：台费结算时设置的 每小时单价/计费单价。
用途：与 ledger_count 共同决定原始应收额。
ledger_amount
类型：float
含义：按单价与计费时长计算出的原始应收台费金额。
近似关系：ledger_amount ≈ ledger_unit_price × ledger_count / 3600，考虑到四舍五入会有小数差。
real_table_charge_money
类型：float
含义：台费中实际向顾客收取的金额（现金/实付维度，未含券方承担或内部调账的那一部分）。
特点：
有的记录值为 0，说明该台费完全由券或内部调账承担，没有直接收取现金；
有的记录 real_table_charge_money = ledger_amount，说明没有外部优惠，顾客按原价买单。
coupon_promotion_amount
类型：float
观测：
常见值：48.0、96.0、116.0、68.0、136.0、144.0... 等；
有大量记录值等于整小时单价或其整数倍。
含义：由优惠券/活动/团购（平台/门店促销）承担的优惠金额，直接抵扣在台费上。
特点：当 real_table_charge_money = 0 且该字段为 ledger_amount 时，说明整笔台费是由券促销全额承担。
member_discount_amount
上文已说明，这里补充与金额的结构关系：
功能：表示由会员折扣或会员权益承担的那部分金额。
特殊场景：
有些记录中 ledger_amount = real_table_charge_money = member_discount_amount，从结构上看，是“原价计费 + 会员承担 + 仍记录为台费收入”的一种设计（系统内部体现为会员权益消耗）。
adjust_amount
类型：float
观测：
多数是 0.0；
少数为正值，如 120.0、148.15、14.16、24.18...。
含义：调整金额/调账金额，用于将台费金额转移或冲减到其它项目，或手工调整。
特点：
部分记录中 ledger_amount 全部通过 adjust_amount 抵消（real_table_charge_money = 0，coupon_promotion_amount = 0，adjust_amount = ledger_amount），说明这笔台费被完全调账到其他地方（例如包厢统一计费，或计入套餐）。
used_card_amount
类型：float
当前样本全为 0.0。
含义：由储值卡、次卡等“卡内余额”抵扣的金额。
说明：字段设计已预留，但本段时间内台费没有通过储值卡扣款，或者卡扣款在其他表体现。
service_money
类型：float
当前样本全为 0.0。
含义（推测）：门店用于记录“服务费/成本/分成金额”的字段，类似助教流水里的 service_money。
说明：当前门店未启用此字段结算台费。
mgmt_fee
类型：float
当前样本全为 0.0。
含义（推测）：管理费字段，用于未来支持“台费附加管理费/服务费”的功能。
当前未启用。
fee_total
类型：float
当前样本全为 0.0。
含义：各种附加费用（如管理费、服务费）合计值。
说明：和 mgmt_fee 一样，目前作为预留字段，没有实际使用。
从结构上看，台费金额被拆成多个维度：
原始应收：ledger_amount
实际收现：real_table_charge_money
券促销承担：coupon_promotion_amount
会员承担：member_discount_amount
调账：adjust_amount
卡扣款：used_card_amount（当前为 0）
各字段合起来，描述一条台费从“原始计费”到“谁来承担”这一系列拆分，非常细颗粒度，但这里不做金额计算和盈利分析，仅从结构上说明。
7. 操作员 / 营业员相关字段
operator_id
类型：int
含义：操作员 ID，负责开台/结账的员工账号 ID。
关联：与员工/账号体系中的用户 ID 对应（与助教账号的 user_id 属于同一种 ID 体系）。
operator_name
类型：string
含义：操作员姓名（冗余字段），便于直接阅读，不必再联表员工档案。
salesman_name
类型：string
当前样本全部为空字符串。
含义：业务员/营业员姓名，如果台费有单独提成员工，这里记录归属人。
当前门店未启用该字段做提成归属。
salesman_user_id
类型：int
当前全为 0。
含义：营业员的用户 ID（与 salesman_name 搭配）。
salesman_org_id
类型：int
当前全为 0。
含义：营业员所属机构/部门 ID。
8. 状态 / 标记类字段
ledger_status
类型：int，枚举。
观测：全部为 1。
含义（推测）：
1：正常已结算台费；
其他值（例如 0 未结算、2 作废）在当前数据未出现，但从命名看属于状态位。
is_single_order
类型：int，枚举。
观测：1（194 条）、0（6 条）。
含义（推测）：
1：该台费记录对应的是一个独立计费单元（单独结算的桌费）；
0：非独立结算条目，可能依附于其他订单（如合并结账、占位记录、转单/转台的中间记录）。
特点：is_single_order = 0 的记录中，ledger_count 和 real_table_use_seconds 为 0，说明没有实际使用与收费，是一种结构性的“占位/关联”记录。
is_delete
类型：int，枚举。
观测：全部为 0。
含义：逻辑删除标志：
0：未删除（有效记录）；
1：已逻辑删除（从界面隐藏，历史保留）。
当前导出时间段没有被标记删除的台费记录。
9. 门店信息快照
siteProfile
类型：object（字典）
观测：所有记录的 siteProfile 内容相同。
内部字段包括（概略）：
id（门店 ID，与 site_id 相同）
org_id（所属组织 ID）
shop_name（门店名称，如“朗朗桌球”）
full_address、address
longitude、latitude
tenant_site_region_id、tenant_id
一些门店级配置（例如自动开灯、WiFi、客服二维码、营业状态等）
含义：当前门店的完整档案快照，冗余到流水表中，便于报表直接读取而无需再联表门店档案。
三、与其它 JSON 的结构关联关系（从字段层面）
只从字段层面梳理，不做数值层面的分析：
与“助教流水.json”
关联键：
order_trade_no、order_settle_id：同一订单下，台费流水与助教流水共享同一交易号和结算号，可以一起还原某次消费包含“台费 + 助教”的组合明细。
site_id、tenant_id：门店与租户维度一致。
结构上：两者都是“事实表”，分别记录“台使用”和“助教服务”，共享同一套订单系统与支付系统。
与“小票详情.json”
关联键：
order_settle_id ↔ 小票详情中的 orderSettleId；
order_trade_no ↔ 小票中的订单号。
结构线索：
小票层面是顾客看到的整笔账单；台费流水是其中“台费项目”的拆解结果（含时长、单价、优惠明细）。
与“会员档案.json（会员信息）”
关联键：
台费流水中的 member_id ↔ 会员档案中的 id（tenant_member_id）。
用途：
可以从台费流水倒推出是哪个会员在该台消费；
再通过会员档案看其手机号、姓名、卡状态等。
与“台桌列表/台桌配置.json”
关联键：
site_table_id ↔ 台桌列表的 id；
site_table_area_id ↔ 门店台桌区域配置表；
tenant_table_area_id ↔ 租户层面区域配置表。
用途：
支持按台、按区域统计使用时长与台费占用情况；
结合 ledger_name 和 site_table_area_name 做场地运营维度分析（结构上可行，这里不做数值分析）。
与“支付记录.json”
关联键：
order_pay_id ↔ 支付记录中的 ID/关联 ID。
结构线索：
可从支付记录看付款方式（现金/二维码/微信/支付宝/卡扣等），与本表的 real_table_charge_money、used_card_amount 等金额字段拼接成完整支付结构。
与“门店销售记录/库存变动.json”
虽然台费不是库存商品，但在整体订单结构中，台费与商品销售在“订单主表”上共享 order_trade_no 和 order_settle_id，结构上处于同一个“结账事件”下。
四、本表在整体模型中的结构角色（从字段设计角度的线索）
从字段设计和关联关系可以看出：
siteTableUseDetailsList 是标准的“台费事实表”
每条记录 = 一段台使用时长结算快照；
通过主键 id 唯一标识；
通过 site_table_id/site_table_area_id 关联台桌维度；
通过 order_trade_no、order_settle_id 关联订单与小票；
通过 member_id 关联会员；
通过 operator_id 关联操作员。
金额拆分字段非常细：
ledger_amount（原始应收），real_table_charge_money（实收现金），coupon_promotion_amount（券促销承担），member_discount_amount（会员承担），adjust_amount（调账），used_card_amount（卡扣），mgmt_fee/fee_total（预留管理费）。
说明在“台费”这一单类目上，系统已经设计为支持按承担主体拆分金额，用于对接多种优惠渠道与内部对账，但当前门店部分字段尚未启用（如 mgmt_fee、used_card_amount、service_money）。
时间与时长字段区分了“计费时间”和“真实时间”：
real_table_use_seconds 与 ledger_count 基本一致，但仍保留两个字段，说明系统刻意区分“真实使用时长”和“计费时长”；
last_use_time 与 ledger_end_time 相差 1 秒左右，说明系统既保留了事件时间，也保留了计费截断时间。
状态/标志字段为后续扩展留了空间：
ledger_status、is_single_order、is_delete 在当前数据中值单一或高度偏向某个值，说明系统支持更多状态，但当前门店只是处于相对简单的使用方式（几乎全部是正常未删除的台费记录，少量非独立订单占位记录）。
区域与桌台配置两级 ID（site_table_area_id / tenant_table_area_id）说明：
区域体系既有门店维度 ID，又有租户维度 ID，这为将来多门店统一配置区域，或者跨门店统计同类型区域的运营情况做了结构铺垫。
总的来说，台费流水.json 在结构上已经非常“规范化”：它作为台费的事实表，通过一系列 ID 字段与会员、门店、台桌、订单及支付等多张表关联，并在单条记录层面拆分了时长与金额的各个组成部分。这些都是后续做联表分析、建模和数据对齐时非常关键的结构信息。

591
docs/api-reference/endpoints/tenant_goods_master.md Normal file
View File

@@ -0,0 +1,591 @@
# 租户商品主数据（QueryTenantGoods）
> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/QueryTenantGoods` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/TenantGoods/QueryTenantGoods` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `tenant_goods_master` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要 |
## 请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `costPriceType` | int | `0` | 成本价类型（0=全部） |
| `ableDiscount` | int | `-1` | 是否可折扣（-1=全部） |
| `tenantGoodsStatus` | int | `0` | 商品状态（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |
## 响应字段（共 31 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `categoryName` | string | '饮料' |
| 2 | `isInSite` | bool | False |
| 3 | `commodityCode` | array | ['10000028'] |
| 4 | `id` | int | 2791925230096261 |
| 5 | `tenant_id` | int | 2790683160709957 |
| 6 | `goods_name` | string | '东方树叶' |
| 7 | `goods_cover` | string | 'https://oss.ficoo.vip/admin/ZwS8fj_1753175129443.jpg' |
| 8 | `goods_state` | int | 1 |
| 9 | `goods_category_id` | int | 2790683528350539 |
| 10 | `unit` | string | '瓶' |
| 11 | `supplier_id` | int | 0 |
| 12 | `create_time` | string | '2025-07-15 17:13:15' |
| 13 | `is_delete` | int | 0 |
| 14 | `goods_second_category_id` | int | 2790683528350540 |
| 15 | `cost_price` | float | 0.0 |
| 16 | `market_price` | float | 8.0 |
| 17 | `pinyin_initial` | string | 'DFSY,DFSX' |
| 18 | `goods_bar_code` | string | '' |
| 19 | `able_discount` | int | 1 |
| 20 | `min_discount_price` | float | 0.0 |
| 21 | `commodity_code` | string | '10000028' |
| 22 | `goods_number` | string | '1' |
| 23 | `update_time` | string | '2025-10-29 23:51:38' |
| 24 | `cost_price_type` | int | 1 |
| 25 | `remark_name` | string | '' |
| 26 | `sale_channel` | int | 1 |
| 27 | `able_site_transfer` | int | 2 |
| 28 | `common_sale_royalty` | int | 0 |
| 29 | `point_sale_royalty` | int | 0 |
| 30 | `is_warehousing` | int | 1 |
| 31 | `out_goods_id` | int | 0 |
## 新增字段（相对本地 JSON 样本）
以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
| 字段名 | 类型 |
|--------|------|
| `not_sale` | int |
## 详细字段分析
> 以下内容迁移自旧版 `tenant_goods_master-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
二、单条商品档案记录字段说明（31 个字段）
为便于理解，按逻辑分组说明。
1. 主键与租户维度字段
id
类型：int
含义：商品档案主键 ID，唯一标识一条商品。
作用：作为其他业务表（销售明细、库存流水、门店商品表等）的外键，通常以 tenant_goods_id 或类似字段出现。
tenant_id
类型：int
当前值：全表 156 条记录均为同一个值。
含义：租户/品牌 ID。
作用：和其它 JSON 中的 tenant_id / tenantId 一致，用于区分不同商户（本次数据只包含同一租户）。
2. 分类维度字段
categoryName
类型：string
含义：商品一级分类名称（业务可读）。
取值情况：
共 14 种分类名称，出现频次较高的包括：
零食（43 条）
饮料（34 条）
香烟（16 条）
其他2（16 条）
雪糕（13 条）
酒水、球杆、小吃、面、槟榔 等。
说明：纯展示用名称，真实关联通过下面的 goods_category_id / goods_second_category_id 完成。
goods_category_id
类型：int
含义：商品一级分类 ID。
取值情况：
共 9 个不同 ID，例如：
一个 ID 对应 46 条、一个对应 45 条、其他若干个对应 10 条以内。
特征：
明显是“分类维度”的主键，和某个“分类表”关联（本次导出中未单独给出分类表）。
各 ID 与 categoryName 一一对应（同一 ID 对应的名称相同）。
goods_second_category_id
类型：int
含义：商品二级分类 ID。
取值情况：
共 14 个不同 ID，与一级分类进一步细分。
分布上，一般跟 categoryName 的细分类对应，如“饮料”下的不同子类。
使用场景：
在销售明细/统计报表中，用于按二级分类汇总。
小结：
categoryName 是分类名称展示字段；
goods_category_id / goods_second_category_id 是分类 ID，用于与“商品分类维表”关联；
其它业务 JSON（例如商品销售明细）中也出现这两个字段，用来做分类维度联表。
3. 商品基础信息字段
goods_name
类型：string
含义：商品名称（前台展示名称）。
特征：
156 条记录全唯一，例如“东方树叶”“红烧牛肉面”“百威235毫升”“雪碧”“双中支中华”等。
用途：
POS 前台展示、票据打印等。
remark_name
类型：string
当前值：全部为 ""（空字符串）。
含义（从命名推断）：商品备注名/别名，通常用来配置简写或特殊显示名称。
当前门店尚未使用该字段，字段设计为将来扩展预留。
goods_number
类型：string
含义：商品内部编码（自定义货号/系统货号）。
特征：
所有 156 条记录均不重复，例如 "1", "2", "3", "4", ...，还有 "10", "11" 等。
使用场景：
作为内部手工输入编码、或导入导出时的匹配字段。
pinyin_initial
类型：string
含义：拼音首字母/助记码。
特征：
156 条记录全不同，如 'DFSY,DFSX', 'HSNRM,GSNRM', 'SRC', 'BW235HS', 'SP' 等；
格式有的是拼音首字母组合，有的是字母+数字混合，说明可能用于多关键字检索。
用途：
前台“拼音码搜索”用的检索字段。
unit
类型：string
含义：计量单位。
取值（共 12 种左右）：
常见：包、瓶、个、份、根、盒、杯、桶、盘、支 等。
用途：
决定库存单位、销售单位（例如“按瓶卖”还是“按包卖”）。
goods_cover
类型：string
含义：商品封面图片 URL 地址。
特征：
共 123 个不同 URL，其中部分同一商品系列共享一张图片（例如某个 URL 出现 34 次）。
用途：
用于前端展示商品图片。
goods_bar_code
类型：string
当前值：全部为 ""（空）。
含义：商品条码（EAN 等），目前未维护。
说明：
字段设计上是用来对接扫码枪的，但当前门店商品条码没有录入。
out_goods_id
类型：int
当前值：全部为 0。
含义（推测）：外部系统商品 ID（对接第三方平台使用，如外卖、线上商城等）。
当前未启用外部对接，因此全部为 0。
commodity_code
类型：string
含义：商品编码（通常为对外商品编码或条码）。
特征：
共 35 种取值，其中：
"10000" 出现 85 条；
"100000" 出现 35 条；
还有 "100017", "100026", "0000000", "10000028", "10000002" 等。
说明：
多条不同 id 的商品可以共用同一个 commodity_code，说明它是某种“系列编码”或“外部编码”而非商品主键。
commodityCode
类型：list（列表内只有一个字符串元素）
示例：['10000']，['100000'] 等。
含义：
与 commodity_code 是同一信息的数组形式（冗余存储），便于支持一个商品对应多个编码的场景。
当前实际使用中，一条记录只有一个编码，因此列表长度均为 1。
4. 价格与折扣相关字段
market_price
类型：float
含义：商品标价 / 售价（标准销售单价）。
特征：
共 45 个不同价格，常见价格如 2、5、6、8、10、12、15、18、20、28 等。
用途：
POS 系统默认销售价格，结算时的基础价格。
min_discount_price
类型：float
含义：该商品允许售卖的最低价格（底价）。
特征：
共 41 个不同价格，分布包括 0.0（32 条）、6、4、15、7、8、5、10、3、28 等。
说明：
0.0 可能表示“未设置底价”或“按系统默认规则”。
cost_price
类型：float
含义：成本价格。
特征：
大部分为 0.0（152 条），少数为 2.0, 2.5, 3.0 等。
说明：
当前门店对绝大多数商品未录入成本，仅为少数商品录入了成本价。
该字段用于库存核算、成本统计等场景（本次不做金额分析，仅说明结构）。
cost_price_type
类型：int（枚举）
取值：
1：149 条
2：7 条
含义（推测）：
不同的成本价格来源或计算方式，如：
1：手工录入成本；
2：按最近进货价/加权平均价等自动计算。
具体含义需参考系统字典，但可以确定是“成本类型枚举”。
able_discount
类型：int（枚举）
当前值：全部为 1
含义（推测）：是否允许参与折扣/打折。
1：允许折扣；
其它值（当前未出现）可能代表“禁止打折”。
当前所有商品均标记为可打折。
sale_channel
类型：int（枚举）
当前值：全部为 1
含义（推测）：销售渠道类型，如“门店堂食/线下零售/线上小程序”等的一种编码。
现有数据只有一个值，说明本门店目前仅通过一种渠道销售这些商品。
5. 库存 / 仓储与门店相关字段
is_warehousing
类型：int（枚举）
当前值：全部为 1
含义（推测）：是否启用库存管理。
1：该商品纳入库存管理；
0：不纳入库存管理（例如纯虚拟商品）。
当前所有商品都处于“有库存管理”的状态。
isInSite
类型：bool
当前值：全部为 False
含义（从命名推测）：是否在当前门店启用/上架。
现象：
虽然导出指定了某个门店，但这里全部为 False，说明这个文件更偏向“租户级商品库视角”，而不是“门店已上架商品视角”；
具体含义可能是“是否已同步到某个特定门店”，当前视图可能没启用这个标志。
able_site_transfer
类型：int（枚举）
取值：
2：155 条
0：1 条
含义（推测）：
字面意思是“是否允许门店间调拨/门店级操作”：
2：允许（或默认可调拨）；
0：不允许。
值使用 2 而非 1，说明内部枚举可能是多态（例如 1=未配置、2=允许、0=禁止），具体需结合系统配置才可精准解释。
当前有一条商品配置为 0，与其他商品行为可能存在差异。
goods_state
类型：int（枚举）
当前值：全部为 1
含义（推测）：商品状态（上架/下架等）。
1：正常/上架；
其他值（本数据未出现）可能表示下架、停用等状态。
6. 佣金 / 提成 / 积分相关字段
common_sale_royalty
类型：int
当前值：全部为 0
含义（推测）：普通销售提成比例或提成金额的配置字段。
当前门店未在商品档案上配置员工提成规则，全部为 0。
point_sale_royalty
类型：int
当前值：全部为 0
含义（推测）：积分销售提成/积分赠送规则相关配置。
当前同样未启用。
说明：
这两个字段与促销、积分、提成等高级功能相关，当前仅作为预留字段存在，未实际配置。
7. 供应商相关字段
supplier_id
类型：int
当前值：全部为 0
含义：供应商 ID，用于关联到供应商档案。
当前所有商品都未挂接具体供应商（或门店未使用供应链管理模块）。
8. 时间与删除状态字段
create_time
类型：string（时间）
格式：YYYY-MM-DD HH:MM:SS
含义：商品档案创建时间。
特征：
156 条记录全部有值，全部唯一。
update_time
类型：string 或 null
含义：商品档案最近一次修改时间。
分布：
null（或 None）：28 条，表示自创建以来未被修改；
其余为不同时刻的更新时间。
用途：
用于增量同步、数据对账等（只需要处理 update_time 大于某个时间点的记录）。
is_delete
类型：int（枚举）
当前值：全部为 0
含义：逻辑删除标志。
0：未删除（有效商品）；
1：已删除（逻辑删除，保留档案但前台不再展示）。
当前所有商品均处于“未删除”状态。
三、结构关系与设计线索（从字段/结构角度，不做金额或经营分析）
从 商品档案.json 的字段设计，可以看出以下几点与系统整体结构密切相关的线索：
“租户级商品库”与“门店级商品视图”的区分
tenant_id 存在，但没有 site_id 字段，且 isInSite 全为 False，is_warehousing 全为 1。
说明这一份是 租户维度的商品主档（Brand/集团统一商品列表），而不是某个门店独立维护的商品清单。
门店层的启用/下架、门店特有售价等，很可能在另一张“门店商品表”（比如带 siteId 的 orderGoods 或 siteGoods 表）中维护，这份只是底层档案。
与“商品销售明细/门店销售记录”的关联点
在另一个 JSON 中（门店商品销售明细），出现了 oneCategoryName, twoCategoryName, goods_category_id, goods_second_category_id 等字段。
可以推断：
销售明细中用 tenant_goods_id 或类似字段引用本表的 id；
用 goods_category_id / goods_second_category_id 建立分类维度统计；
goods_name、commodity_code、unit 等在销售明细中会“快照冗余”，方便查询和展示。
与“库存/仓储模块”的接口设计
is_warehousing 全为 1，说明所有商品都被纳入库存管理范围；
cost_price、cost_price_type、supplier_id 等字段，是典型的库存/进销存用途字段；
这意味着：另有库存流水 JSON（如入库单、出库单、盘点记录等），会通过商品 id（或 out_goods_id）与本表关联。
对接外部系统和扫码收银的预留
goods_bar_code 虽然目前为空，但字段设计表明系统支持条码扫描销售；
out_goods_id 预留了外部商品 ID，对接第三方平台（外卖、统一商品库等）时会使用；
commodity_code/commodityCode 强调了一个商品可以有多种编码的可能（当前只有单元素列表）。
可扩展的促销与提成机制
虽然 common_sale_royalty、point_sale_royalty 当前都为 0，但和“助教流水”“销售记录”中的推广/提成字段组合起来，可以构成统一的提成规则体系；
able_discount、min_discount_price、sale_channel 这几个字段一起，构成了商品在不同渠道、不同活动下允许打折的边界控制。
分类维度的稳定主数据角色
categoryName + goods_category_id + goods_second_category_id 说明分类层级已经固化：至少支持“两级分类”；
这些分类 ID 在多张表中反复出现（销售明细、可能的库存统计视图等），构成统一的“商品分类维度表”。

34
docs/api-reference/endpoints/tenant_member_balance_overview.md Normal file
View File

@@ -0,0 +1,34 @@
# 会员余额总览（TenantMemberBalanceOverview）
> 自动生成于 2026-02-13 | 数据来源：实时 API
## 基本信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `MemberProfile/TenantMemberBalanceOverview` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/MemberProfile/TenantMemberBalanceOverview` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `无（新 API，尚未建表）` |
| 分页方式 | 无分页 |
| 时间范围 | 不需要 |
## 请求参数
无（`body: null`）
## 响应字段（共 9 个）
| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `totalPointBalance` | float | 0.0 |
| 2 | `totalCardBalance` | float | 356619.51 |
| 3 | `totalCardPrincipalBalance` | float | 346917.34 |
| 4 | `electronicCardBalance` | float | 356619.51 |
| 5 | `physicsCardBalance` | int | 0 |
| 6 | `rechargeCardBalance` | float | 90055.67 |
| 7 | `rechargeCardList` | array | [{'cardTypeName': '储值卡', 'balance': 86115.67, 'principalB... |
| 8 | `giveCardBalance` | float | 266563.84 |
| 9 | `giveCardList` | array | [{'cardTypeName': '消费卡', 'balance': 0, 'principalBalance'... |

192
docs/api-reference/goods_stock_movements.md Normal file
View File

@@ -0,0 +1,192 @@
# 库存出入库流水 — QueryGoodsOutboundReceipt
> 模块：`GoodsStockManage` · ODS 表：`goods_stock_movements` · 事实表（增量）
---
## 一、接口概述
查询门店商品库存出入库流水明细，每条记录对应一次库存变动事件（销售出库、采购入库、盘点调整等）。包含变动前后库存数量、变动类型、操作员等信息。所有记录严格满足库存平衡公式：`endNum = startNum + changeNum`。支持双计量单位（主/副单位），当前门店仅使用主单位。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /GoodsStockManage/QueryGoodsOutboundReceipt` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（`startTime` / `endTime`） |
---
## 二、请求
### 请求体（JSON）
```json
{
"siteId": 2790685415443269,
"stockType": 0,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `stockType` | int | 是 | 库存变动类型筛选。`0` = 全部，`1` = 出库，`4` = 入库 |
| `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": 100
}
}
```
`data.list` 中每个对象即为一条库存变动记录，共 19 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（19 个字段）
### 4.1 商品与库存标识
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteGoodsStockId` | int | `2957911857581957` | 库存记录主键 ID，每条变动记录唯一。同一商品可在不同批次/仓位产生多条记录 |
| `siteGoodsId` | int | `2793026183532613` | 门店商品 ID。对应门店商品档案（`store_goods_master`）的 `id`，也对应库存汇总的 `siteGoodsId` |
| `siteId` | int | `2790685415443269` | 门店 ID，与其他业务表一致 |
| `tenantId` | int | `2790683160709957` | 租户/品牌 ID，所有记录相同 |
| `goodsCategoryId` | int | `2790683528350539` | 一级分类 ID，对应分类树主键。约 5 个不同值 |
| `goodsSecondCategoryId` | int | `2790683528350540` | 二级分类 ID，对应分类树子节点。约 7 个不同值 |
### 4.2 商品基本信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `goodsName` | string | `"阿萨姆"` | 商品名称（当时的名称快照），与 `siteGoodsId` 一一对应 |
| `unit` | string | `"瓶"` | 库存计量单位。常见值：瓶、包、盒、根、个、桶、份 |
| `price` | float | `8.0` | 商品单价（静态快照），单位：元（人民币）。同一 `siteGoodsId` 的所有记录 `price` 一致，避免价格调整后历史记录无法还原 |
### 4.3 库存数量变动（主单位）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `startNum` | int | `28` | 变动前库存数量 |
| `endNum` | int | `27` | 变动后库存数量。严格满足 `endNum = startNum + changeNum` |
| `changeNum` | int | `-1` | 本次变化量。负数 = 出库/减少，正数 = 入库/增加。`stockType=1` 时全为负数，`stockType=4` 时全为正数 |
### 4.4 库存数量变动（副单位，预留）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `startNumA` | int | `0` | 副单位变动前库存（如箱/瓶双单位场景）。当前门店未启用，全部为 0 |
| `endNumA` | int | `0` | 副单位变动后库存，当前全部为 0 |
| `changeNumA` | int | `0` | 副单位变化量，当前全部为 0 |
### 4.5 变动类型
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `stockType` | int | `1` | 库存变动类型枚举：`1` = 出库（销售出库，`changeNum` 为负数），`4` = 入库/盘盈/调整增加（`changeNum` 为正数）。其他可能值（如报损、盘亏、退货等）当前样本未出现 |
### 4.6 操作与时间
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `createTime` | string | `"2025-11-09 23:23:34"` | 库存变动记录创建时间。可与小票时间、台费时间交叉校验。同一秒内可能有多条记录（同桌多商品一起销售） |
| `operatorName` | string | `"收银员:郑丽珊"` | 操作人。大部分为收银员（前台销售触发），个别为"系统"（自动盘点调整等） |
### 4.7 备注
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `remark` | string | `""` | 备注信息，用于手工记录变更原因（如"盘点差异调整""报损"）。当前全部为空 |
---
## 五、响应样例（单条记录）
```json
{
"siteGoodsStockId": 2957911857581957,
"siteGoodsId": 2793026183532613,
"siteId": 2790685415443269,
"tenantId": 2790683160709957,
"stockType": 1,
"goodsName": "阿萨姆",
"createTime": "2025-11-09 23:23:34",
"startNum": 28,
"endNum": 27,
"changeNum": -1,
"unit": "瓶",
"price": 8.0,
"operatorName": "收银员:郑丽珊",
"changeNumA": 0,
"startNumA": 0,
"endNumA": 0,
"remark": "",
"goodsCategoryId": 2790683528350539,
"goodsSecondCategoryId": 2790683528350540
}
```
---
## 六、跨表关联
### 与门店商品档案（`store_goods_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `siteGoodsId` | `id` | 门店商品 ID，关联商品基础信息、定价、库存快照 |
| `goodsCategoryId` | `goods_category_id` | 一级分类 ID |
| `goodsSecondCategoryId` | `goods_second_category_id` | 二级分类 ID |
### 与库存汇总（`goods_stock_summary`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `siteGoodsId` | `siteGoodsId` | 门店商品 ID。库存变动明细按 `siteGoodsId` + 时间范围聚合后即为库存汇总 |
> 结构关系：库存变动（明细表）→ 按 siteGoodsId + 时间范围聚合 → 库存汇总（汇总表）。
### 与门店销售记录（`store_goods_sales_records`）
- 当 `stockType = 1`（出库）时，对应销售记录中的商品销售行为
- 通过 `siteGoodsId` / `site_goods_id` 和 `createTime` / `create_time` 可在结构上对齐
### 与商品分类树（`stock_goods_category_tree`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `goodsCategoryId` | `id`（一级节点） | 一级分类主键 |
| `goodsSecondCategoryId` | `id`（二级节点） | 二级分类主键 |
### 与操作员维度
- `operatorName` 与其他流水（台费、助教、销售记录）中的 `operator_name` 一致，形成统一的操作员维度
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/goods_stock_movements.md，按逻辑分组详解所有 19 个字段，含库存平衡公式说明和跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

176
docs/api-reference/goods_stock_summary.md Normal file
View File

@@ -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/ 确认字段覆盖完整
-->

216
docs/api-reference/group_buy_packages.md Normal file
View File

@@ -0,0 +1,216 @@
# 团购套餐定义 — QueryPackageCouponList
> 模块：`PackageCoupon` · ODS 表：`group_buy_packages` · 维度表（快照）
---
## 一、接口概述
查询门店下所有团购套餐的配置定义。每条记录对应一种团购套餐的规则定义，包括套餐名称、面值、有效期、每日可用时段、限定台区、状态等。本表是团购业务的核心维度表，被平台券核销记录和团购核销记录通过套餐 ID 引用。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /PackageCoupon/QueryPackageCouponList` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要（全量快照） |
---
## 二、请求
### 请求体（JSON）
```json
{
"areaId": [],
"commonShowStatus": 1,
"offlineCouponChannel": 0,
"systemGroupType": 1,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `areaId` | array | 是 | 区域 ID 列表。空数组 = 全部 |
| `commonShowStatus` | int | 是 | 展示状态筛选。`1` = 展示中 |
| `offlineCouponChannel` | int | 是 | 线下券渠道筛选。`0` = 全部 |
| `systemGroupType` | int | 是 | 系统分组类型。`1` = 默认 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 17
}
}
```
`data.list` 中每个对象即为一条团购套餐定义记录，共 35 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（35 个字段）
### 4.1 基本信息与主键
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2939215004469573` | 门店侧套餐 ID（主键）。平台验券记录中的 `group_package_id` 指向此 ID |
| `package_id` | int | `1814707240811572` | 上层/系统级套餐 ID。多个 `id` 不同的记录可共享同一 `package_id`（同一套餐在不同门店/版本下的本地配置） |
| `package_name` | string | `"早场特惠一小时"` | 团购套餐名称，用于前台展示和核销界面。示例：`"B区桌球一小时"`、`"中八、斯诺克包厢两小时"`、`"KTV欢唱四小时"` |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `site_name` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
| `creator_name` | string | `"店长:郑丽珊"` | 创建人信息（角色:姓名），用于权限追踪 |
| `create_time` | string | `"2025-10-27 18:24:09"` | 套餐创建时间 |
### 4.2 金额与时长
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `selling_price` | float | `0.0` | 团购售卖价（元）。当前全部为 `0.0`，实际售价可能在平台侧维护 |
| `coupon_money` | float | `0.0` | 券面值/内部结算面值（元）。如：早场一小时 = `40.0`，KTV 四小时 = `200.0`。核销时按此金额执行抵扣记账 |
| `duration` | int | `3600` | 套餐包含时长（秒）。`3600` = 1 小时，`7200` = 2 小时，`14400` = 4 小时 |
| `usable_count` | int | `9999999` | 可使用次数上限。`9999999` 为"无限次"哨兵值 |
### 4.3 有效期与日期限制
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `start_time` | string | `"2025-10-27 00:00:00"` | 套餐生效开始日期 |
| `end_time` | string | `"2026-10-28 00:00:00"` | 套餐失效日期。极大日期（如 `9999-12-31`）表示长期有效 |
| `date_type` | int | `1` | 日期限制类型。`1` = 通用（每天可用）。其他值可能表示工作日/周末/指定日期 |
| `date_info` | string | `""` | 细粒度日期信息（如具体日期列表），预留字段，当前基本为空 |
| `usable_range` | string | `""` | 可用日期范围文字描述（如"周一至周五"），当前未使用 |
### 4.4 每日时段限制
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `start_clock` | string | `"00:00:00"` | 每日可用起始时间（第一时段） |
| `end_clock` | string | `"1.00:00:00"` | 每日可用结束时间（第一时段）。`1.00:00:00` 格式为"天.时:分:秒"，表示跨日截止 |
| `add_start_clock` | string | `"00:00:00"` | 附加可用时段起始时间（第二时段），支持不连续时段（如早场+夜场） |
| `add_end_clock` | string | `"1.00:00:00"` | 附加可用时段结束时间。`1.00:00:00` = 跨午夜到次日凌晨 |
### 4.5 区域/台桌限制
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `area_tag_type` | int | `1` | 区域约束模式。`1` = 按台区标签限制 |
| `table_area_name` | string | `"A区"` | 套餐适用台区名称。示例：`"A区中八"`、`"B区中八"`、`"斯诺克"`、`"包厢"`、`"KTV"` |
| `table_area_id` | string | `"0"` | 单一台区 ID（已弃用，全部为 `"0"`） |
| `tenant_table_area_id` | string | `"0"` | 租户级台区 ID（已弃用，全部为 `"0"`） |
| `tenant_table_area_id_list` | string | `"2791960001957765"` | 租户台区配置 ID，实际起约束作用。指向台区分组表 |
| `table_area_id_list` | string | `""` | 具体台区 ID 列表（如 `"1,2,3"`），当前未使用 |
### 4.6 适用卡种
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `card_type_ids` | string | `"0"` | 适用会员卡类型 ID。`"0"` = 不限卡种 |
| `max_selectable_categories` | int | `0` | 最大可选分类数。`0` = 不限制 |
### 4.7 状态与类型
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_enabled` | int | `1` | 启用状态（配置层面）。`1` = 启用/上架，`2` = 停用/下架 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 正常，`1` = 已删除 |
| `effective_status` | int | `1` | 动态有效状态。`1` = 有效（可核销），`3` = 已过期/失效 |
| `type` | int | `2` | 内部业务子类型。`1` 和 `2` 两种值，具体含义需结合系统配置 |
| `group_type` | int | `1` | 团购类型。`1` = 计时类/台费类套餐 |
| `system_group_type` | int | `1` | 系统团购类型。`1` = 券码类团购（需凭码核销） |
---
## 五、响应样例（单条记录）
```json
{
"site_name": "朗朗桌球",
"effective_status": 1,
"id": 2939215004469573,
"site_id": 2790685415443269,
"tenant_id": 2790683160709957,
"package_name": "早场特惠一小时",
"table_area_id": "0",
"table_area_name": "A区",
"selling_price": 0.0,
"duration": 3600,
"start_time": "2025-10-27 00:00:00",
"end_time": "2026-10-28 00:00:00",
"is_enabled": 1,
"is_delete": 0,
"type": 2,
"package_id": 1814707240811572,
"usable_count": 9999999,
"create_time": "2025-10-27 18:24:09",
"creator_name": "店长:郑丽珊",
"tenant_table_area_id": "0",
"table_area_id_list": "",
"tenant_table_area_id_list": "2791960001957765",
"start_clock": "00:00:00",
"end_clock": "1.00:00:00",
"add_start_clock": "00:00:00",
"add_end_clock": "1.00:00:00",
"date_info": "",
"date_type": 1,
"group_type": 1,
"usable_range": "",
"coupon_money": 0.0,
"area_tag_type": 1,
"system_group_type": 1,
"max_selectable_categories": 0,
"card_type_ids": "0"
}
```
---
## 六、跨表关联
### 与平台券核销记录（`platform_coupon_redemption_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `group_package_id` | 套餐 ID → 平台券关联的内部套餐（当前全部为 0，预留） |
### 与团购核销记录（`group_buy_redemption_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `promotion_coupon_id` | 套餐 ID → 核销流水中使用的套餐定义 |
| `duration` | `promotion_seconds` | 套餐标准时长，两表一致 |
> 结构链路：团购套餐定义 → 平台验券记录（券码与套餐 ID） → 团购核销记录（订单明细中的券使用记录）。
### 与台桌/台区配置
- `tenant_table_area_id_list`：与台区配置表中的台区组合 ID 关联
- `table_area_name`：与台区配置中的 `area_name` 含义一致
### 与门店维度
所有业务表的 `tenant_id`、`site_id` 一致，共享门店维度。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/group_buy_packages.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

256
docs/api-reference/group_buy_redemption_records.md Normal file
View File

@@ -0,0 +1,256 @@
# 团购核销记录 — GetSiteTableUseDetails
> 模块：`Site` · ODS 表：`group_buy_redemption_records` · 事实表（增量）
---
## 一、接口概述
查询团购券在门店台费上的使用明细流水。每条记录描述一张团购券被核销到某张球台的台费上，包含券码、套餐配置、抵扣金额与时长、关联订单与球台、促销拆账等信息。本表是"团购套餐定义 + 台费流水 + 平台券核销"之间的桥接事实表，将某张券、某个套餐配置、某个订单、某张桌、某段时间、某个金额绑定在一起。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /Site/GetSiteTableUseDetails` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（`startTime` / `endTime`） |
---
## 二、请求
### 请求体（JSON）
```json
{
"siteId": 2790685415443269,
"offlineCouponChannel": 0,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"page": 1,
"limit": 100,
"queryType": 1
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `offlineCouponChannel` | int | 是 | 线下券渠道筛选。`0` = 全部 |
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
| `queryType` | int | 是 | 查询类型。`1` = 默认 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 200
}
}
```
`data.list` 中每个对象即为一条团购核销流水记录，共 43 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（43 个字段）
### 4.1 台桌与门店维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_id` | int | `2793003705192517` | 球台 ID，对应台桌列表的 `id` |
| `tableName` | string | `"A17"` | 球台名称/台号。示例：`"A7"`、`"B1"`、`"斯1"`、`"麻1"` |
| `tableAreaName` | string | `"A区"` | 球台所属台区名称。枚举：`"A区"`、`"B区"`、`"斯诺克区"`、`"麻将房"` |
| `tenant_table_area_id` | int | `2791960001957765` | 租户级台区分组 ID，用于校验券的适用台区与实际台桌是否匹配 |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `siteName` | string | `"朗朗桌球"` | 门店名称，冗余展示用 |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
### 4.2 订单与关联 ID
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957924029615941` | 团购核销流水记录主键 ID |
| `order_trade_no` | int | `2957858167230149` | 订单交易号，与台费流水、助教流水、小票详情等共用的订单主键 |
| `order_settle_id` | int | `2957922914357125` | 结算单 ID（小票结账主键），对应小票详情的 `orderSettleId` |
| `order_pay_id` | int | `0` | 支付记录 ID。`0` = 未关联具体支付记录 |
| `order_coupon_id` | int | `2957858168229573` | 订单中券使用记录 ID，与平台验券记录主键对应 |
| `coupon_origin_id` | int | `2957858168229573` | 平台/上游系统券记录主键 ID（券来源 ID）。当前与 `order_coupon_id` 完全相等 |
| `promotion_activity_id` | int | `2957858166460101` | 团购/促销活动 ID，对应平台或内部促销活动主键 |
| `promotion_coupon_id` | int | `2798727423528005` | 团购套餐定义 ID，对应 `group_buy_packages` 表的 `id` |
### 4.3 金额字段（核心）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_unit_price` | float | `29.9` | 台费标准单价（元/小时）。已知值：`29.9`、`39.9`、`59.9`、`69.9`、`11.11`、`128.0` |
| `ledger_count` | int | `3600` | 本次券实际核销的计费秒数。大部分等于 `promotion_seconds`，少数略有差异 |
| `ledger_amount` | float | `48.0` | 本次券实际冲抵台费的金额（元）。绝大部分与 `coupon_money` 相等 |
| `coupon_money` | float | `48.0` | 本次核销时券在门店侧的可抵扣金额（元）。已知值：`48.0`、`58.0`、`68.0`、`96.0`、`116.0`、`288.0` |
| `goodsOptionPrice` | float | `0.0` | 商品规格价格，用于商品类促销分摊。当前未使用 |
### 4.4 时长字段
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `promotion_seconds` | int | `3600` | 团购套餐标准时长（秒）。枚举：`3600`（1 小时）、`7200`（2 小时）、`14400`（4 小时）。与套餐定义的 `duration` 一致 |
| `table_charge_seconds` | int | `3600` | 本次结算中球台总计费秒数。当券完全覆盖时等于 `ledger_count`；有多种计费组合时可能更大 |
### 4.5 促销拆账字段
> 按不同业务子模块预留的促销金额分摊字段。当前门店团购券仅用于抵扣台费，以下字段全部为 `0.0`。
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_service_promotion_money` | float | `0.0` | 分摊到台费服务费的促销金额（元） |
| `assistant_promotion_money` | float | `0.0` | 分摊到助教服务的促销金额（元） |
| `assistant_service_promotion_money` | float | `0.0` | 分摊到助教服务费的促销金额（元） |
| `goods_promotion_money` | float | `0.0` | 分摊到商品的促销金额（元） |
| `reward_promotion_money` | float | `0.0` | 奖励金/积分抵扣的促销金额（元） |
| `recharge_promotion_money` | float | `0.0` | 充值类优惠的分摊金额（元） |
### 4.6 券标识与渠道
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `coupon_code` | string | `"0107892475999"` | 团购券券码，核销时扫描/录入。与平台验券记录的 `coupon_code` 一致，串联全链路 |
| `order_coupon_channel` | int | `1` | 券渠道类型。`1` = 渠道 A，`2` = 渠道 B（具体平台需查系统配置） |
| `offer_type` | int | `1` | 优惠类型。`1` = 套餐券（当前唯一值） |
| `ledger_name` | string | `"全天A区中八一小时"` | 团购项目记账名称，通常来源于套餐定义的 `package_name` |
| `ledger_group_name` | string | `""` | 团购项目记账分组名称，当前未使用 |
### 4.7 状态与标志
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 流水状态。`1` = 正常有效 |
| `is_single_order` | int | `1` | 是否独立订单行。`1` = 独立条目结算，`0` = 嵌在组合结算中 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 正常，`1` = 已删除 |
### 4.8 操作员与销售员
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 执行核销/结算操作的员工 ID |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名（带职位前缀） |
| `salesman_user_id` | int | `0` | 营业员用户 ID。当前未启用 |
| `salesman_name` | string | `""` | 营业员姓名。当前未启用 |
| `salesman_role_id` | int | `0` | 营业员角色 ID。当前未启用 |
| `sales_man_org_id` | int | `0` | 营业员所属组织 ID。当前未启用 |
### 4.9 时间
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 23:35:57"` | 流水创建时间（券核销时间，接近结账时间） |
---
## 五、响应样例（单条记录）
```json
{
"tableName": "A17",
"tableAreaName": "A区",
"siteName": "朗朗桌球",
"goodsOptionPrice": 0.0,
"id": 2957924029615941,
"order_trade_no": 2957858167230149,
"table_id": 2793003705192517,
"site_id": 2790685415443269,
"tenant_id": 2790683160709957,
"operator_id": 2790687322443013,
"operator_name": "收银员:郑丽珊",
"order_settle_id": 2957922914357125,
"ledger_name": "全天A区中八一小时",
"ledger_group_name": "",
"ledger_unit_price": 29.9,
"ledger_count": 3600,
"ledger_amount": 48.0,
"order_pay_id": 0,
"create_time": "2025-11-09 23:35:57",
"is_delete": 0,
"promotion_activity_id": 2957858166460101,
"promotion_coupon_id": 2798727423528005,
"is_single_order": 1,
"order_coupon_id": 2957858168229573,
"order_coupon_channel": 1,
"ledger_status": 1,
"promotion_seconds": 3600,
"coupon_origin_id": 2957858168229573,
"table_charge_seconds": 3600,
"offer_type": 1,
"coupon_money": 48.0,
"tenant_table_area_id": 2791960001957765,
"assistant_promotion_money": 0.0,
"assistant_service_promotion_money": 0.0,
"table_service_promotion_money": 0.0,
"goods_promotion_money": 0.0,
"reward_promotion_money": 0.0,
"recharge_promotion_money": 0.0,
"salesman_user_id": 0,
"salesman_name": "",
"salesman_role_id": 0,
"sales_man_org_id": 0,
"coupon_code": "0107892475999"
}
```
---
## 六、跨表关联
### 与团购套餐定义（`group_buy_packages`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `promotion_coupon_id` | `id` | 套餐定义 ID → 使用的是哪种团购套餐 |
> 通过此关联可获取套餐名称、标准时长、适用台区、每日可用时段等配置。`promotion_seconds` 与套餐定义的 `duration` 在结构上一致。
### 与平台券核销记录（`platform_coupon_redemption_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `coupon_code` | `coupon_code` | 券码，串联平台 → 核销 → 台费流水全链路 |
| `coupon_origin_id` / `order_coupon_id` | `id` | 平台券记录主键 |
### 与订单/小票相关表
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_trade_no` | `order_trade_no` | 订单号 → 同一笔结账中的台费、助教、商品等明细 |
| `order_settle_id` | `orderSettleId` | 结算单 ID → 小票详情 |
| `order_pay_id` | 支付记录 `id` | 支付流水 ID（非 0 时） |
### 与台桌维度/台区配置
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `table_id` | 台桌列表 `id` | 具体球台 |
| `tenant_table_area_id` | 套餐定义 `tenant_table_area_id_list` | 实际使用台区 ↔ 套餐允许台区，用于校验 |
### 与门店维度
所有业务表的 `tenant_id`、`site_id` 一致，共享门店维度。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/group_buy_redemption_records.md，43 个字段按 9 个逻辑分组详解，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

Some files were not shown because too many files have changed in this diff Show More