财务 MRP 分析（fin-mrp-analysis）

安装：SETUP.md · 常见问题 / 反模式：FAQ.md

文档导航

阅读路径：Quick Start 跑通 → 业务查 SKILL 对应章节 → 出问题先查 FAQ，勿全文搜索。

Quick Start

本 skill 复用财务中台登录与组织查询能力。

SkillHub / zip 分发包：不含 bin/；所有命令使用 python3 cli/fin_mrp_cli.py（下文 monorepo 场景可写 fin-mrp-cli）。

cd fin-mrp-analysis          # zip 解压目录；monorepo 内为 skills/fin-mrp-analysis
cp .env.example .env
python3 -m pip install -r requirements.txt
# 首次：二选一登录（账号密码 或 手机验证码）
# 方式 A：账号密码
python3 cli/fin_mrp_cli.py --base-url https://<财务中台地址> login --username <账号> --password <密码>
# 方式 B：手机验证码
python3 cli/fin_mrp_cli.py --base-url https://<财务中台地址> sms-send --phone 138xxxxxxxx
python3 cli/fin_mrp_cli.py login --phone 138xxxxxxxx --code <短信验证码>
python3 cli/fin_mrp_cli.py session
python3 cli/fin_mrp_cli.py org-info

SkillHub / 首次安装（Agent 必做）：若用户尚未配置 .env，在对话中按顺序执行（禁止跳过第 1、2 步；禁止默认某一种登录方式；禁止假设域名）：

1. 财务中台域名 / 网址（FINANCE_BASE_URL，必配）
   - 对用户说：「请提供财务中台的访问地址（域名或完整网址，例如 https://finance.example.com）。」
   - 收到后通过 --base-url 写入 .env；禁止使用内置回退地址充当生产配置、禁止跳过不问。
2. 先提示用户选择登录方式（必须开口询问，等用户明确选择后再往下收集凭据）：
   - 对用户说：「登录财务中台有两种方式：① 账号密码登录；② 手机号短信验证码登录。请选一种。」
   - 用户选 ① 账号密码 → 再收集账号 + 原始密码 → login --username ... --password ...
   - 用户选 ② 短信验证码 → 再收集 11 位手机号 → sms-send → 请用户发来验证码 → login --phone --code

收集后由 Agent 执行（禁止要求用户手工编辑 .env）：

# 用户选账号密码时：
fin-mrp-cli --base-url https://<用户提供的地址> login --username <账号> --password <密码>
# 用户选短信验证码时：
fin-mrp-cli --base-url https://<用户提供的地址> sms-send --phone <手机号>
fin-mrp-cli login --phone <手机号> --code <验证码>
fin-mrp-cli session

显式 --base-url 写入 FINANCE_BASE_URL；显式 --username/--password 成功后可写入 FINANCE_USERNAME/FINANCE_PASSWORD；显式 --phone 成功后可写入 FINANCE_PHONE；验证码不会写入 .env。appid/appkey 已内置，一般无需配置。

登录过期（reloginRequired）：若 .env 已有账号密码 → 直接 fin-mrp-cli login（勿再索要密码）；若仅短信登录 → 须重新收验证码（禁止对短信模式静默 login）。已配置的域名一般无需再问。

• monorepo 根目录 npm install 后自动注册全局 fin-mrp-cli；亦可 npm run link-cli。
• command not found 时：根目录 npm run link-cli，或 ./bin/fin-mrp-cli、npm run fin-mrp-cli -- <子命令>。
• SkillHub / zip 分发包：不含 bin/；执行命令时用 python3 cli/fin_mrp_cli.py 代替 fin-mrp-cli（见 SETUP.md）。
• 登录态：.fin-mrp/cookies.json（JWT authMeta.token）。

完整上手：SETUP.md · 报错排查：FAQ.md

工作流

SkillHub 首次：【先收集域名/网址】→ 【再问用户选登录方式】→ 按所选收集凭据并 login → session → org-info → 业务命令
已配置账号密码 .env：session → 失效 → 直接 login（读 .env）→ 业务命令
仅短信登录：session → 失效（reloginRequired）→ 须重新收验证码登录 → 业务命令

对用户开口示例（规范）

CLI 命令

> 别名说明：下列 *-detail 与短名（如 ss-saleout / ss-saleout-detail）为同一实现的两条入口，不是重复命令。完整对照见 FAQ.md — 命令关系。

组织列表 org-info

GET {FINANCE_BASE_URL}/api/fin/org_info/

fin-mrp-cli org-info
fin-mrp-cli org-info --format markdown

管理报表 mrp-report-balance

GET {FINANCE_BASE_URL}/api/fin/mrp_report_balance/

• 单月查询：period[0] 与 period[1] 均等于 --period（如 2026-04），禁止跨月。
• 多组织：--provider-id 可多次指定或逗号分隔；传参形如 provider_id[0]=3364&provider_id[1]=3418。
• 默认 page=1，limit=1000；单次通常返回约 70+ 行（含 KPI 衍生行）。
• CLI 在每行附加 row_type（kpi/section/detail）与 cur_amount_unit（yuan/ratio）。

# 1. 查组织
fin-mrp-cli org-info

# 2. 查单月管报（JSON，供 Agent 解析）
fin-mrp-cli mrp-report-balance --provider-id 3373 --period 2026-04

# 3. 人类可读表格
fin-mrp-cli mrp-report-balance --provider-id 3373 --period 2026-04 --format markdown

# 4. 附带项目目录（归因用）
fin-mrp-cli mrp-report-balance --provider-id 3373 --period 2026-04 --with-catalog

# 5. 仅输出固定项目目录（不请求接口）
fin-mrp-cli mrp-report-catalog

数据模型（item_name / item_level）

item_name 是固定字典（与绩效利润项目表一致），分析时必须按名称精确匹配，勿自行改写。item_level 区分三类行：

父子关系示例（某子公司 2026-04）：

• JXLR-01 线上收入（含税）item_level=1，item_id=62734238
• JXLR-01-020 普药 item_level=2，parent_id=62734238
• JXLR-01-030 摇钱树、JXLR-01-021 集采 等同属该 section
• 展示顺序以 main_seq 为准（同 section 下 seq 可能重复）

金额与比率字段

> 金额单位：cur_amount、ytd_amount、qoq_diff_amount、month_01～month_12、ly_*、ys_*、l_cur_amount 等绝大多数为人民币元，不是万元。向用户汇报时可 ÷10,000 并注明口径。

Agent：分析时每次只查一个月份；多组织可同次请求。先 org-info 取 provider_id，再查管报；按 item_name 精确取行，下钻时结合 parent_id；禁止编造金额与比率；KPI 行勿与 section 明细相加重复计入。JSON 顶层含 itemLevelGuide 与 fields 说明。

管报与三表数据的关系（重要）

管理报表（mrp-report-balance）以销售出库、返利实收、成本调整等明细为基础，但在写入管报表时还会做额外的数据调整（如品类归集、补贴/摇钱树、成本口径换算、费用分摊等）。因此：

• 管报各项目金额不一定等于直接对 ss-saleout / ss-sale-rebate-received / ss-angle-cost-adjust 三表 grandTotal 按实收口径公式合并的结果。
• 收入在部分场景可与销售出库 total_amount 对齐；毛利、净利润等利润类指标与三表综合公式差异更常见，属正常现象，不代表查询错误。

出现不一致时，Agent 须主动提示使用者：

1. 说明管报会在三表基础上再做调整，与直接汇总三表可能不一致，这是预期行为。
2. 若用户对差异有疑问，建议先查看是否存在相应管报调整项（品类、补贴、费用等），再决定是否下钻明细，以免产生困扰。
3. 禁止强行将三表实收口径综合毛利与管报「总体毛利额」「线上毛利」等 KPI 直接对标并断言一方有误。

管报项目目录

完整结构见 config/mrp_report_items.yaml（与绩效利润项目表顺序一致）；fin-mrp-cli mrp-report-catalog 输出 JSON。

行类型：section（一级汇总/蓝底）→ detail（明细）→ kpi（衍生指标/灰底）

线上品类（收入/毛利共用）：普药、摇钱树、集采、首推、控销、线上-总代及其他

费用四级结构（归因须按此顺序下钻）：

利润瀑布（KPI 灰底行，顺序）：

考核口径可控费用 → 线上边际利润 → 线上净利润 → 扣除平台费和补贴的线上净利润 →（线下段）→ 线下净利润 → 总体毛利额 → 总体净利润 → 奖金前总体净利润 → 考核口径净利润 →（补贴段）→ 总补贴占比

归因顺序建议：考核口径净利润 / 总体净利润 → 线上毛利六品类 → 费用四级（变动→半变动→固定→其他）→ 补贴 → 线下。

常用 KPI 行（item_level=0，按 main_seq 穿插在表中）：

> 报表界面可能标注「万元」展示；接口返回金额为元（总补贴占比 除外）。

资产负债表 rp-balance（RP；数据源 ts_fin_rp_balance，不同于绩效利润管报 mrp-report-balance）

对应 Django FinAnalRpBalanceViewSet（db_fin_report.ts_fin_rp_balance，report_id=57667258）。行结构对齐 report_fp_to_excel「资产负债表」sheet；JSON 宽表分页形态与 mrp-report-balance 类似，但业务数据源不同。

与管报区别：

必填（查询）：--kd-orgid 或 --provider-id + --period。

行类型 row_type：

关键字段：cur_amount 期末数；rpe_amount 上期数；diff / diff_pct 环比；reclassify_amount / reclassified_amount 重分类；check_result_cur 校验（含未分配利润 vs 净利润勾稽）；month_01～month_12、ytd_amount 为本年各月/累计。

# 1. 查有 RP 数据的组织（含 kd_orgid）
fin-mrp-cli rp-balance-org-info

# 2. 查可选期间
fin-mrp-cli rp-balance-period-info

# 3. 按 provider_id 查资产负债表（期间 YYYYMM）
fin-mrp-cli rp-balance --provider-id 3373 --period 202605

# 4. 人类可读表格
fin-mrp-cli rp-balance --provider-id 3373 --period 2026-05 --format markdown

# 5. 仅明细与小计
fin-mrp-cli rp-balance --kd-orgid 100001 --period 202605 \
  --row-type detail --row-type subtotal --row-type total

Agent：

• 查资产负债结构、流动/非流动占比、环比变动用 rp-balance；查利润表/考核净利润仍用 mrp-report-balance，二者不可混用。
• 先 rp-balance-org-info 或 org-info 取 kd_orgid；期间用 rp-balance-period-info 或用户指定 --period（YYYYMM）。
• 金额字段为元；向用户汇报可 ÷10,000 并注明「资产负债表期末数」。
• 接口成功码 code=2000；禁止编造金额与校验结果。
• check_result_cur=请检查 时提示用户关注未分配利润与利润表勾稽（接口已做校验），以及其他往来科目校验项。

与管报 / 三表联合（杜邦等）

杜邦（简化）：净利率（管报）× 总资产周转率（管报收入 ÷ BS 资产合计）× 权益乘数（BS 资产 ÷ 权益）。所有者权益 ≤ 0 时 ROE/权益乘数无意义，改报 ROA 或说明资不抵债状态；总资产宜用平均数，单月期末数为近似。

Agent：用户提「杜邦」「ROE」「杠杆」「偿债」「流动比率」时，在管报之外须查 rp-balance；先 rp-balance-period-info 确认有数据再查，禁止编造 BS 科目金额。

期末库存明细 ss-angle-end-detail / 聚合 ss-angle-end-aggregate

对应 Django FinAnalSklSsAngleEndViewSet（期末库存）。

必填：--provider-id、--account-month（YYYYMM，如 202605）。

明细可选筛选：--angle-id、--sp-zt-code、--biz-type、--manufacturer（生产企业模糊匹配）、--only-near-expiry、--near-expiry-threshold（默认 180 天）、--page、--limit（默认 1000，最大 1000）。

聚合必填：--dimension（1-3 个：sp_zt_code / biz_type / gys_zt_code / goods_type / warehouse_id / manufacturer）；可选 --gys-zt-code（供应商筛选）、--manufacturer（生产企业模糊筛选）、--min-ending-qty。

字段口径（与 Django 3.5.1 一致）：
- 明细关联 ob_fin_basic_goodsdoc_info（sp_zt_code = zt_code），返回 goods_name、goods_spec、manufacturer
- 明细 ending_cost = 期末不含税成本（实收口径），非销售金额
- 明细 biz_type：0普品/1首推/2实销实结/3摇钱树/4控销/5集采/6首推plus/7特推
- 聚合 total_amount / near_expiry_amount = 期末不含税成本合计（实收口径）
- 聚合分组行含 p1_amount、paid_amount；已废弃 pending_rebate_amount（CLI 输出中已剔除）
- 明细含 settlement_type、pay_type、shelf_life_months 等

# 1. 查组织
fin-mrp-cli org-info

# 2. 期末库存明细（JSON）
fin-mrp-cli ss-angle-end-detail --provider-id 3373 --account-month 202605

# 3. 近效期批次 + 表格
fin-mrp-cli ss-angle-end-detail --provider-id 3373 --account-month 202605 \
  --only-near-expiry true --format markdown

# 4. POST 明细（数组筛选）
fin-mrp-cli ss-angle-end-detail --provider-id 3373 --account-month 202605 \
  --method post --sp-zt-code SP10001,SP10002

# 5. 按业务类型 + 供应商聚合
fin-mrp-cli ss-angle-end-aggregate --provider-id 3373 --account-month 202605 \
  --dimension biz_type --dimension gys_zt_code

# 6. 按生产企业聚合
fin-mrp-cli ss-angle-end-aggregate --provider-id 3373 --account-month 202605 \
  --dimension manufacturer

# 7. 按生产企业模糊筛选后查明细
fin-mrp-cli ss-angle-end-detail --provider-id 3373 --account-month 202605 \
  --manufacturer 阿斯利康 --limit 10

期末库存 vs 实时库存（选型）

实时库存 ss-realtime-inventory-detail / ss-realtime-inventory-aggregate

对应 Django FinAnalSklSsRealtimeAngleInventoryViewSet（OceanBase 实时批次库存）。

必填：--provider-id、--account-month（YYYYMM；扣减当月 sale_out_summary_once 已销，通常填当前月）。

明细额外必填：--angle-id / --sp-zt-code / --gys-zt-code 至少一项（防全表扫描）。

聚合必填：--dimension（1-3 个：sp_zt_code / angle_id / biz_type / gys_zt_code / supplier_name / goods_type / warehouse_id / manufacturer）。

可选筛选（明细/聚合共用）：--biz-type、--goods-type、--manufacturer、--only-near-expiry、--near-expiry-threshold（默认 180）、--min-remaining-qty（聚合）。

字段口径：
- stock_num 账面库存；sold_num 当月已销；remaining_num 实时剩余（仅返回 <> 0）
- cost_p4 / cost_p1 = 实时剩余 × 单价；book_cost_p4 / book_cost_p1 为扣减前账面成本
- 聚合 total_qty / total_cost_p4 / total_cost_p1；含 near_expiry_qty、expired_qty、over_180_days_qty
- 明细 --limit 最大 500；聚合最多 5000 行

# 1. 按商品编码查实时库存
fin-mrp-cli ss-realtime-inventory-detail --provider-id 3373 --account-month 202605 \
  --sp-zt-code SP10001

# 2. 按供应商 + 近效期
fin-mrp-cli ss-realtime-inventory --provider-id 3373 --account-month 202605 \
  --gys-zt-code GYS001 --only-near-expiry true --format markdown

# 3. 按业务类型 + 供应商聚合
fin-mrp-cli ss-realtime-inventory-aggregate --provider-id 3373 --account-month 202605 \
  --dimension biz_type --dimension gys_zt_code

Agent：查「现在还有多少库存」用实时库存；查「5 月末库存结构/库龄」用期末库存 + aging/expiry。禁止将实时 remaining_num 与期末 ending_num 直接对标。

库龄 / 效期区间 ss-angle-end-aging / ss-angle-end-expiry

分页拉取明细后在 CLI 侧分桶汇总（非独立后端接口）。

必填：--provider-id、--account-month。

接口筛选（传给明细 API）：--angle-id、--sp-zt-code、--biz-type、--manufacturer（模糊）、--only-near-expiry、--near-expiry-threshold。

CLI 侧筛选：--min-ending-qty、--min-ending-cost、--exclude-zero-qty。

其他：--bucket-months（默认 6，按 30 天/月换算）、--page-size（默认 1000）、--method get|post、--format json|markdown。

# 库龄分布
fin-mrp-cli ss-angle-end-aging --provider-id 498 --account-month 202605

# 效期分布 + 生产企业筛选
fin-mrp-cli ss-angle-end-expiry --provider-id 498 --account-month 202605 \
  --manufacturer 晖致 --format markdown

# 排除零数量批次，自定义 3 个月区间
fin-mrp-cli ss-angle-end-aging --provider-id 498 --account-month 202605 \
  --bucket-months 3 --exclude-zero-qty

Agent（库龄 / 效期）：

• 金额口径：ending_cost（实收口径不含税成本）；每桶输出 interval、costAmount、costRatio、endingQty、qtyRatio、batchCount、batchRatio；顶层含 summary 汇总。
• 分桶规则：默认每 6 个月（--bucket-months 6，内部按 30 天/月）；效期 days_to_expiry < 0 → 已过期。
• 大数据量组织会分页拉取全量明细再汇总，耗时与批次数成正比；优先用 --manufacturer / --sp-zt-code / --only-near-expiry 缩小范围。
• 给用户看表格时用 --format markdown；Agent 解析用默认 JSON（含 buckets、fields）。

Agent（期末库存通用）：先 org-info 取 provider_id；明细成功码 code=2000，聚合成功码 code=0；禁止编造库存数量与金额。

商品主数据 basic-goodsdoc

对应 Django FinAnalBasicGoodsdocViewSet（ob_fin_basic_goodsdoc_info，仅 status=1）。

查询模式（二选一或组合）：

> CLI 与 API 差异：CLI 要求 --goods-name 或 --zt-code 至少一项（防全表扫描）；API 允许两者皆空时分页查全量 status=1 商品。

返回字段：zt_code、goods_name、goods_spec、meas、units、place、manufacturer；批量模式另含 missingZtCodes（未命中编码）。

# 按名称查商品
fin-mrp-cli basic-goodsdoc --goods-name 阿莫西林
fin-mrp-cli basic-goodsdoc --goods-name 晖致 --limit 20 --format markdown

# 按编码批量查品名/规格（TOP 品种分析推荐）
fin-mrp-cli basic-goodsdoc --zt-code SP0212638 --zt-code SP0237888
fin-mrp-cli basic-goodsdoc --sp-zt-code SP0212638,SP0237888 --format markdown

Agent：查 SKU / 厂家用 basic-goodsdoc；凡按销售统计的 TOP/BOTTOM 排名见下文「销售 TOP / BOTTOM 分析」（ss-saleout-aggregate，禁止 ss-saleout-detail 排名或批量查明细）；成功码 code=2000。

销售 TOP / BOTTOM 分析（必须用聚合；禁止明细）

凡用户问 按销售统计的 TOP 或 BOTTOM（TOP/BOTTOM 品、品种、客户、供应商、区域、厂家；销售贡献排名、销售最差/垫底、销量末位等），一律只用 ss-saleout-aggregate；一定不能用 ss-saleout-detail（或其别名 ss-saleout）。

明细接口红线（Agent 必遵）：

1. ss-saleout-detail 禁止批量调用（禁止对 TOP/BOTTOM 列表里的多个 sp_zt_code 循环查明细；禁止一次传多个编码指望明细做排名）。
2. 仅当用户明确查询指定品种（已点名某个品名或单个中台编码）的销售流水/明细时，才允许调用 ss-saleout-detail，且每次只查一个 --sp-zt-code（或单个 --angle-id）。
3. 排名、贡献对比、跨月环比排名变动 → 只走聚合；需要品名时用聚合自带的主数据补全，或事后用 basic-goodsdoc --zt-code 批量补名称（不是明细接口）。

维度选型（ss-saleout-aggregate 支持的 --dimension，TOP 分析按场景选用）：

其他可用维度（结构分析多于 TOP）：relation_type。

# TOP 20 品种（线上）
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension sp_zt_code --top 20 --sale-bill-type 1

# TOP 20 客户
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension kh_zt_code --top 20 --sale-bill-type 1

# TOP 20 供应商
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension gys_zt_code --top 20

# TOP 省份；某省 TOP 城市（二维）
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension province_name --top 20
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension province_name --dimension city_name --top 20

# TOP 20 厂家
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension manufacturer --top 20 --sale-bill-type 1

# 集采业务下 TOP 20 品种（筛选 + 品种维）
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension sp_zt_code --biz-type 5 --top 20

# BOTTOM 20 品种：同一聚合，取 JSON list 末尾 20 条（禁止 ss-saleout-detail）
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension sp_zt_code --sale-bill-type 1

Agent：
- TOP：读 topList 制表；BOTTOM：读 list 末尾 N 条制表；完整列出 N 条，禁止截断。
- 品种 / 供应商 / 客户 TOP/BOTTOM：表格首列必须是中台编码；区域 / 厂家可用名称列。
- 跨月对比：各月同维度、同筛选各查一次聚合，再算环比/同比与排名变动；禁止为对比去批量查明细。
- ss-saleout-detail 红线：禁止用于 TOP/BOTTOM；禁止批量/循环调用；仅用户明确点名单个品种（或单个批次）销售情况时才用。

销售出库明细 / 聚合 ss-saleout-detail / ss-saleout-aggregate

对应 Django FinAnalSklSsSaleoutViewSet（ob_fin_anal_saleoutdt）。

必填：--provider-id、--account-month（YYYYMM）。

明细额外必填：--angle-id 或 --sp-zt-code 至少一项（防全表扫描；接口 OR 条件）。

聚合：不要求 --angle-id / --sp-zt-code；二者均为可选 IN 过滤，不传则按组织+账期全量聚合。

可选筛选（明细/聚合共用）：--kh-zt-code、--biz-type、--sale-bill-type（1线上/2线下）、--business-type、--io-type（1销售出库/2销退入库/3销售退补价）、--only-actual（仅实销 io_type=1）、--manufacturer（生产企业/厂家模糊匹配，关联 ob_fin_basic_goodsdoc_info.t4.manufacturer）。

分页/聚合上限：明细 --limit 默认 100、最大 500；聚合结果最多 5000 行，按 total_amount 降序。

聚合必填：--dimension（1-3 个，不要求含 sp_zt_code/angle_id）。完整可选维度见上文「销售 TOP / BOTTOM 分析」维度表；含 sp_zt_code、kh_zt_code、gys_zt_code、supplier_name、manufacturer、biz_type、sale_bill_type、business_type、goods_type、io_type、relation_type、angle_id 及区域维 province_name / city_name / area_name / street_name。

字段口径（与接口 fin_anal_skl_ss_saleout 一致）：
- 明细关联 ob_fin_anal_ss_angle_basic、供应商/商品/客户/区域等维表；见 JSON fields；商品维表含 manufacturer（生产企业/厂家）
- 收入：amount / total_amount = 真实不含税销售收入；tax_amount / total_tax_amount = 真实含税销售收入
- 非收入：actual_pay_amount / total_actual_pay_amount = 客户实付（勿当作收入）
- 实收口径成本：cost_ss_amount_p4 / total_cost_p4
- 实收口径销售毛利：gross_profit_p4 = 不含税收入 − 实收口径成本；gross_margin_p4 = 毛利 ÷ total_amount；成功码 code=0
- 综合毛利（默认）：ss-saleout-aggregate 默认 --with-composite-profit，自动合并同筛选条件下的返利实收与成本调整，输出 composite_gross_profit_p4（= 销售毛利 + 返利影响 − 成本调整影响）；仅要销售段毛利时传 --no-with-composite-profit
- 与返利实收、成本调整合并公式见下文「当月实收口径收入/成本/利润」

# 1. 查商品编码
fin-mrp-cli basic-goodsdoc --goods-name 阿莫西林 --limit 5

# 2. 查某指定 SKU 销售明细（仅用户明确点名单品时；禁止批量循环）
fin-mrp-cli ss-saleout-detail --provider-id 498 --account-month 202605 --sp-zt-code SP0305101

# 3. 表格输出
fin-mrp-cli ss-saleout-detail --provider-id 498 --account-month 202605 \
  --sp-zt-code SP0305101 --format markdown

# 4. 全组织按业务类型+销售方式聚合（无需 sp_zt_code）
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension biz_type --dimension sale_bill_type

# 5. 按省份+城市聚合（区域维度）
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension province_name --dimension city_name

# 6. 按供应商聚合
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension supplier_name --sale-bill-type 1

# 7. 按生产企业/厂家聚合（TOP 厂家，默认 TOP 30，可 --top 20）
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension manufacturer --sale-bill-type 1 --top 20

# 8. 指定单品明细 + 厂家筛选（仍须单个 sp_zt_code；非排名场景）
fin-mrp-cli ss-saleout-detail --provider-id 498 --account-month 202605 \
  --sp-zt-code SP0305101 --manufacturer 晖致 --limit 10

# 9. 按商品中台编码聚合（TOP/BOTTOM 品种必须用本命令，禁止明细）
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension sp_zt_code --top 20 --sale-bill-type 1

Agent：
- 全组织销售结构 / 任意销售 TOP 或 BOTTOM 用 ss-saleout-aggregate（选型见「销售 TOP / BOTTOM 分析」）；禁止用 ss-saleout-detail 做排名或批量拉取。
- 统一流程：聚合 → TOP 读 topList / BOTTOM 读 list 末尾 N 条 → 跨月对比与下钻仍只用聚合。默认 JSON 含 list（全量降序）与 topList（TOP N）；禁止编造销售数量与金额。
- ss-saleout-detail 何时可用：仅用户明确查询指定单个品种（或单个批次）销售流水时；须带单个 --sp-zt-code 或 --angle-id。禁止对多个编码批量/循环调用明细接口。
- 展示条数：向用户汇报 TOP/BOTTOM N 时，必须完整列出全部 N 条；禁止为省篇幅只展示前 10 条或自行截断。不足 N 条时如实说明。
- 中台编码首列（品种/供应商/客户 TOP/BOTTOM 必读）：
| 分析对象 | 首列（中台编码） | 随后列 |
|----------|------------------|--------|
| 品种 | 商品中台编码（如 SP0240599） | 品名、规格、金额/毛利 |
| 供应商 | 供应商中台编码（如 GYS001234） | 供应商名称、金额 |
| 客户 | 客户中台编码（如 KH000567） | 客户名称、金额 |
- 聚合维度优先用 sp_zt_code / gys_zt_code / kh_zt_code；勿仅用 supplier_name / customer_name 做排名。
- JSON 已统一补充中台编码字段；向用户制表时禁止只写名称而省略编码。
- 品种：--dimension sp_zt_code；CLI 对 topList 自动批量查主数据补品名/规格；BOTTOM 行可用 basic-goodsdoc 补名称。
- 供应商 / 客户 / 区域 / 厂家：分别用 gys_zt_code、kh_zt_code、province_name（可叠市/区/街道）、manufacturer；厂家 dim_1 即名称，无需查主数据。
- 毛利汇报：默认 composite_gross_profit_p4（综合毛利）；禁止仅报 gross_profit_p4 并称「实收口径毛利/利润」。
- 跨月对比：各 account_month 同维度、同筛选各查一次聚合，再算环比/同比；禁止为对比批量查明细。

销售型返利实收分摊 ss-sale-rebate-received-detail / ss-sale-rebate-received-aggregate

对应 Django FinAnalSklSsSaleRebateReceivedViewSet（ob_fin_zt_rebate_sale_received）。

必填：--provider-id、--account-month（YYYYMM，按 dates 业务日期匹配）。

明细额外必填：--angle-id / --sp-zt-code / --kh-zt-code / --received-gys-code 至少一项（防全表扫描；接口 OR 条件）。

聚合：不要求上述范围参数；均为可选 IN 过滤，不传则按组织+账期全量聚合。

可选筛选（明细/聚合共用）：--biz-type、--bus-type、--io-type、--sale-bill-type（1线上/2线下）、--only-actual（仅实销 io_type=1）、--manufacturer（生产企业/厂家模糊匹配，关联 ob_fin_basic_goodsdoc_info.t4.manufacturer）。

聚合必填：--dimension（1-3 个）：sp_zt_code、angle_id、kh_zt_code、received_gys_code、supplier_name、manufacturer（生产企业/厂家）、biz_type、bus_type、io_type、relation_type、sale_bill_type、receive_bill_code、received_bill_code 及区域维度 street_name / area_name / city_name / province_name。

字段口径：
- sale_rebate_amount / total_rebate_amount：正数=调减当期成本（增厚利润），负数=调增当期成本（侵蚀利润）
- 明细关联 ob_fin_anal_ss_angle_basic、ob_fin_basic_goodsdoc_info（含 manufacturer）、ob_fin_basic_supplier_info、ob_fin_basic_customer_info、ob_fin_basic_areas（省市区街道）
- 聚合：total_rebate_amount、total_rebate_tax_amount、record_count；成功码 code=0
- 分页/聚合上限：明细 --limit 最大 500；聚合最多 5000 行，按 total_rebate_amount 降序

# 1. 按实收返利单位查明细
fin-mrp-cli ss-sale-rebate-received-detail --provider-id 498 --account-month 202605 \
  --received-gys-code GYS001

# 2. 按省份+城市聚合（线上实销）
fin-mrp-cli ss-sale-rebate-received-aggregate --provider-id 498 --account-month 202605 \
  --dimension province_name --dimension city_name --sale-bill-type 1 --only-actual

# 3. 按实收返利单位聚合
fin-mrp-cli ss-sale-rebate-received-aggregate --provider-id 498 --account-month 202605 \
  --dimension supplier_name --format markdown

# 4. 按生产企业/厂家聚合
fin-mrp-cli ss-sale-rebate-received-aggregate --provider-id 498 --account-month 202605 \
  --dimension manufacturer --sale-bill-type 1

Agent：全组织返利结构用 ss-sale-rebate-received-aggregate；查明细须 --angle-id / --sp-zt-code / --kh-zt-code / --received-gys-code 至少一项；默认 JSON 含 rows/list 与 fields；禁止编造返利金额。

返利余额 rebate-balance / 返利凭证 rebate-voucher-report

财务中台协议层返利报表（非 fin_anal 三表），与上节「销售型返利实收分摊」互补：

必填：--provider-id、--period（YYYY-MM，与管报 mrp-report-balance 一致，不同于三表 --account-month 的 YYYYMM）。

全量拉取：默认自动合并全部分页（服务端单页上限约 5000）；JSON 含 fetchAll: true、pagesFetched、count/total。无需传 --page/--limit。

rebate-balance 可选筛选：--rebate-unit、--rebate-type（采购型/销售型）、--agreement-method（公对公转账/票折/实物兑付等）、--agreement-status（在用/停用/作废）、--receive-bill-code。

rebate-voucher-report 可选筛选：--voucher-flow-code、--invoice-num（模糊）、--voucher-flow-kind（invoice / bank）。

关键字段（余额）：total_receivable_tax_amount_after_init（协议累计应收）、total_received_tax_amount_after_init（协议累计实收）、book_receivable_uncollected（账面应收未收）、book_received_unallocated（账面实收未摊）。

关键字段（凭证）：total_head_amount（凭证金额）、write_off_amount / un_write_off_amount（已核销/未核销）。

与管报归因的关系：

• ss-sale-rebate-received-*：当月已分摊进成本的销售型返利（影响实收口径综合毛利）。
• rebate-balance / rebate-voucher-report：协议全生命周期应收实收与凭证核销（解释「为什么管报补贴/返利行与实收分摊不一致」「集采/采购型返利是否到账」）。
• 三者不可直接相加对标；管报还可能含额外补贴归集。

# 1. 查组织某月返利余额（可按返利单位、类型筛选）
fin-mrp-cli rebate-balance --provider-id 3373 --period 2026-05 --rebate-type 销售型

# 2. 查返利凭证（发票流水）
fin-mrp-cli rebate-voucher-report --provider-id 3373 --period 2026-05 --voucher-flow-kind invoice

# 3. 人类可读表格
fin-mrp-cli rebate-balance --provider-id 3373 --period 2026-05 --format markdown

Agent：管报归因中涉及「返利未收、票折未核销、采购型返利到账」时下钻本组命令；向用户表述用「返利协议余额」「返利凭证核销」，勿暴露 CLI/API 名。

成本调整单 ss-angle-cost-adjust-detail / ss-angle-cost-adjust-aggregate

对应 Django FinAnalSklSsAngleCostAdjustViewSet（ob_fin_anal_ss_angle_cost_adjust）。

必填：--provider-id、--account-month（YYYYMM）。

明细额外必填：--angle-id / --sp-zt-code / --gys-zt-code / --customer-code 至少一项（防全表扫描；接口 OR 条件）。

聚合：不要求上述四项；均为可选 IN 过滤，不传则按组织+账期全量聚合。

数据范围：接口固定 bill_type IN (1返利, 2调价, 3税差, 4异常余额)。

业务边界：可按品种、供应商、客户（customer_code / customer_name / business_type）、批次、调整单类型等聚合；不支持按区域聚合（与销售出库/返利实收不同）。

可选筛选（明细/聚合共用）：--bill-type（仅限 1–4）、--biz-type、--business-type（客户类别）、--goods-type、--supplier-type、--status（0未对冲/1已对冲）、--manufacturer（生产企业/厂家模糊匹配）。

聚合必填：--dimension（1-3 个）：品种侧 sp_zt_code、goods_type、biz_type、manufacturer；供应商侧 gys_zt_code、supplier_name；客户侧 customer_code / customer_name / business_type；angle_id、bill_type、supplier_type、rebate_type、rebate_method、status、bill_code、rebate_code。

字段口径：
- adjust_pre_amt / total_adjust_pre_amt：负数=调减成本（增厚利润），正数=调增成本（侵蚀利润）（符号与返利实收相反）
- 明细关联 ob_fin_anal_ss_angle_basic、ob_fin_basic_goodsdoc_info（含 manufacturer）、ob_fin_basic_supplier_info
- 聚合：total_adjust_pre_amt、total_adjust_pre_tax_amt、total_adjust_pre_tax、record_count；成功码 code=0
- 分页/聚合上限：明细 --limit 最大 500；聚合最多 5000 行，按 total_adjust_pre_amt 降序

# 1. 按供应商查明细
fin-mrp-cli ss-angle-cost-adjust-detail --provider-id 498 --account-month 202605 \
  --gys-zt-code GYS001

# 2. 按供应商+调整单类型聚合
fin-mrp-cli ss-angle-cost-adjust-aggregate --provider-id 498 --account-month 202605 \
  --dimension gys_zt_code --dimension bill_type

# 3. 按品种（商品编码）+ 业务类型聚合
fin-mrp-cli ss-angle-cost-adjust-aggregate --provider-id 498 --account-month 202605 \
  --dimension sp_zt_code --dimension biz_type

# 4. 按生产企业/厂家聚合
fin-mrp-cli ss-angle-cost-adjust-aggregate --provider-id 498 --account-month 202605 \
  --dimension manufacturer

# 5. 按单 SKU 缩小范围后按品种聚合
fin-mrp-cli ss-angle-cost-adjust-aggregate --provider-id 498 --account-month 202605 \
  --dimension sp_zt_code --sp-zt-code SP0248340 --format markdown

Agent：成本调整用 ss-angle-cost-adjust-aggregate 可按品种/厂家/供应商/客户/批次/调整单类型下钻，禁止按区域聚合；查明细须 --angle-id / --sp-zt-code / --gys-zt-code / --customer-code 四选一；禁止编造调整金额。

采购入库 purinfo-detail / purinfo-aggregate

对应 Django FinAnalPurinfoViewSet（ob_fin_zt_purindt + ob_fin_zt_purinmt，stat_code 关联）。

必填：--provider-id、--account-month（YYYYMM，按主表 dates 业务日期匹配）。

明细额外必填：--angle-id / --sp-zt-code / --gys-zt-code / --stat-code 至少一项（防全表扫描；接口 OR 条件）。

聚合：不要求上述范围参数；均为可选 IN 过滤，不传则按组织+账期全量聚合。

数据范围：仅含主表 bill_type IN (0采购入库, 1采退)，不含退补价(2)。

可选筛选（明细/聚合共用）：--bus-type、--bill-type（仅限 0/1）、--manufacturer（生产企业模糊匹配）。

聚合必填：--dimension（1-3 个）：sp_zt_code、gys_zt_code、supplier_name、bus_type、manufacturer、angle_id、bill_type。

字段口径：
- 明细 amount / tax_amount / tax = 明细不含税/含税金额与税额
- 聚合 total_amount / total_tax_amount / total_tax = 合计金额；avg_price / avg_tax_price = 平均单价
- 成功码 code=0；明细 --limit 最大 500；聚合最多 5000 行，按 total_amount 降序

# 1. 按供应商查采购明细
fin-mrp-cli purinfo-detail --provider-id 3373 --account-month 202605 --gys-zt-code GYS001

# 2. 按供应商聚合（TOP 20）
fin-mrp-cli purinfo-aggregate --provider-id 3373 --account-month 202605 \
  --dimension supplier_name --top 20

# 3. 按生产企业/厂家聚合
fin-mrp-cli purinfo-aggregate --provider-id 3373 --account-month 202605 \
  --dimension manufacturer

# 4. 按商品+业务类型聚合
fin-mrp-cli purinfo-aggregate --provider-id 3373 --account-month 202605 \
  --dimension sp_zt_code --dimension bus_type

Agent：
- 采购结构/TOP 供应商或厂家用 purinfo-aggregate；默认 JSON 含 list（全量排序）与 topList（默认 --top 30）；禁止编造采购数量与金额。
- 查明细须 --angle-id / --sp-zt-code / --gys-zt-code / --stat-code 至少一项；汇报 TOP N 时完整列出 topList 全部 N 条。

金蝶采购付款 kd-payment-detail / kd-payment-aggregate

对应 Django FinAnalKdPaymentinfoViewSet（ob_fin_kd_payment_info，含付款单/退款单）。

必填：--provider-id、--account-month（YYYYMM）。

明细额外必填：--supplier-code / --kd-bill-code / --purchase-bill-code / --batch-no / --rf-bill-code 至少一项（防全表扫描；接口 OR 条件）。

聚合：不要求上述范围参数；均为可选 IN 过滤，不传则按组织+账期全量聚合。

可选筛选（明细/聚合共用）：--bill-type、--supplier-type、--pay-type、--biz-type、--pay-status、--settle-type、--only-approved。

聚合必填：--dimension（1-3 个）：supplier_code、supplier_name、supplier_type、pay_type、biz_type、bill_type、pay_status、settle_type、settle_type_name。

字段口径：
- 明细 pre_pay_amount = 计划/预付金额；pay_amount = 实际付款金额（退款为负）
- 聚合 total_pre_pay_amount / total_pay_amount = 合计金额；结果按 total_pay_amount 降序
- 成功码 code=0；明细 --limit 最大 500；聚合最多 5000 行

# 1. 按供应商查付款明细
fin-mrp-cli kd-payment-detail --provider-id 3373 --account-month 202605 --supplier-code GYS001

# 2. 按结算方式聚合（TOP 20，仅已审核）
fin-mrp-cli kd-payment-aggregate --provider-id 3373 --account-month 202605 \
  --dimension settle_type --top 20 --only-approved

# 3. 按供应商+付款用途聚合
fin-mrp-cli kd-payment-aggregate --provider-id 3373 --account-month 202605 \
  --dimension supplier_code --dimension pay_type

Agent：
- 付款结构/TOP 供应商或结算方式用 kd-payment-aggregate；默认 JSON 含 list（全量排序）与 topList（默认 --top 30）；禁止编造付款金额。
- 查明细须五类范围参数至少一项；汇报 TOP N 时完整列出 topList 全部 N 条。

当月实收口径收入 / 成本 / 利润（三表合并）

三个聚合接口的 grandTotal（全组织同账期、同筛选条件下）可拼出当月整体损益。金额单位均为元。

> 实收口径：接口字段后缀 _p4（如 total_cost_p4、gross_profit_p4）表示实收口径成本/毛利；向用户说明时称「实收口径」，勿称 P4。
>
> 收入 vs 实付：total_amount = 真实不含税销售收入（与管报「线上/线下收入（不含税）」对齐）；total_tax_amount = 真实含税销售收入；total_actual_pay_amount = 客户实付，非收入口径。
>
> 实收口径毛利：gross_profit_p4 = total_amount − total_cost_p4；毛利率 = 毛利 ÷ total_amount。

符号约定（务必区分）：

综合公式（S=销售出库，R=返利实收，A=成本调整；均为实收口径合并）：

不含税销售收入             = S.total_amount
含税销售收入               = S.total_tax_amount
实收口径销售成本           = S.total_cost_p4
实收口径销售毛利           = S.total_amount − S.total_cost_p4
                            （= S.gross_profit_p4）

实收口径综合成本           = S.total_cost_p4 − R.total_rebate_amount + A.total_adjust_pre_amt
实收口径综合毛利           = 实收口径销售毛利 + R.total_rebate_amount − A.total_adjust_pre_amt

聚合须指定 --dimension（任选 1 个即可，如 sale_bill_type / bill_type）；grandTotal 为全量合计，与维度分组无关。三次查询须使用相同 --provider-id、--account-month 及可比筛选（如均限线上 --sale-bill-type 1）。

# 1. 销售段（收入 / 实收口径成本 / 实收口径毛利）
fin-mrp-cli ss-saleout-aggregate --provider-id 498 --account-month 202605 \
  --dimension sale_bill_type

# 2. 返利实收（读 grandTotal.total_rebate_amount，作用于实收口径成本）
fin-mrp-cli ss-sale-rebate-received-aggregate --provider-id 498 --account-month 202605 \
  --dimension sale_bill_type

# 3. 成本调整（读 grandTotal.total_adjust_pre_amt，作用于实收口径成本）
fin-mrp-cli ss-angle-cost-adjust-aggregate --provider-id 498 --account-month 202605 \
  --dimension bill_type

Agent：
1. 分别取三接口 JSON 的 grandTotal，按上表公式计算实收口径综合成本/综合毛利；禁止编造金额。
2. 向用户汇报时注明：实收口径销售毛利率 = gross_profit_p4 ÷ total_amount；勿将 total_actual_pay_amount（客户实付）当作收入。
3. 下钻维度时三表筛选条件须一致；成本调整不可按区域与销售段对齐下钻（可按客户维度）。
4. 明细验证用各 *-detail 子命令；全月汇总用 *-aggregate 的 grandTotal 即可。
5. 与管报对比时见上文「管报与三表数据的关系」：禁止将实收口径综合毛利与管报 KPI 直接对标；若用户同时持有管报与三表结果且存在差异，须主动说明管报会在三表基础上再做调整，建议先查是否存在相应调整项。

登录接口

支持两种登录方式，均调用 POST {FINANCE_BASE_URL}/api/login/。

方式一：账号密码

{
  "type": "account_with_appid",
  "username": "<账号>",
  "password": "<密码 MD5>",
  "appid": "<内置或覆盖>",
  "appkey": "<内置或覆盖>"
}

CLI：fin-mrp-cli login --username <账号> --password <原始密码>（密码自动 MD5；appid/appkey 已内置）。

方式二：手机号 + 短信验证码

发码：POST {FINANCE_BASE_URL}/api/ysbVerifyCode/

{ "phoneNo": "<11 位手机号>" }

短信登录：

{
  "type": "mobile",
  "username": "<11 位手机号>",
  "password": "<短信验证码>"
}

登录过期时 CLI 返回 reloginRequired: true：若 .env 已有账号密码可直接 login；若使用短信登录须重新收验证码（禁止对短信模式静默 login，禁止再向用户索要已在 .env 的账号密码）。

环境变量

sms-send 参数

--phone

login 参数

--username、--password、--password-md5、--appid、--appkey、--type、--phone、--code、--token、--cookie-header、--cookie-file、--show-response

Agent 注意

> 登录失败、无权限、0 行、组织 ID 传错等报错场景优先查 FAQ.md；本节侧重对外表述与业务分析禁令。

面向用户的表述（必读）

Skill 使用者通常不懂代码、命令行或接口字段。Agent 自行完成登录、查数、下钻；向用户交付的内容须业务化，与内部执行方式分离。

对用户说（推荐）

• 用组织名、年月、管报项目名称（如「考核口径净利润」「线上毛利—集采」「变动费用—平台费」）。
• 金额用万元并注明口径（如「不含税收入」「实收口径毛利」）。
• 归因用瀑布/表格：结论 → 主要拖累项 → 对冲项 → 建议下一步。
• 品种/供应商/客户表格：首列必须是中台编码（商品 SP…、供应商 GYS…、客户 KH…），第二列起才是名称与金额；禁止只写名称不写编码。
• 下一步用自然语言任务，例如：「需要的话，我可以继续查 5 月集采里毛利下滑最大的前 20 个品种，并与 4 月对比。」

对用户不说（禁止，除非用户明确要技术细节）

• 命令行、fin-mrp-cli、子命令名、--provider-id 等参数。
• JSON 字段名（如 grandTotal、gross_profit_p4、item_name、code=0）。
• API 路径、表名、维度英文名（如 biz_type、sp_zt_code）。
• 「Agent 解析 JSON」「CLI 默认输出」等实现描述。

术语对照（对内查数 → 对外说法）

示例：错误 vs 正确

• ❌ 「执行 fin-mrp-cli mrp-report-balance --provider-id 3373 --period 2026-05」

• ✅ 「已调取某子公司 2026 年 5 月管理报表，并与 4 月环比对比。」

• ❌ 「gross_profit_p4 环比 -56.9 万，与管报 线上毛利（不含税） 差 50 万因口径不同」

• ✅ 「销售明细汇总的毛利比管报线上毛利略高，因管报还做了品类归集和费用分摊等调整，属正常现象。」

首次使用引导（对用户）

• 若尚未配置财务中台，初始化须依次收集两项配置：
  1. 财务中台域名/网址（FINANCE_BASE_URL，必问，经 --base-url 写入；禁止跳过或用默认回退地址冒充已配置）
  2. 登录方式——必须先问「① 账号密码登录」还是「② 手机号短信验证码登录」；用户选定后再收集对应凭据。禁止未询问就默认某一种方式，也禁止同时索要账号密码和手机号
• 选定登录方式后：账号密码方式收集账号+密码；短信方式收集手机号并发码，请用户把验证码发过来。
• 禁止要求用户打开或手工编辑 .env；Agent 通过 --base-url 与 login（账号或短信）自动写入。
• 业务接口仅需 JWT 登录态；不再使用财务分析 accessToken（FIN_ANAL_ACCESS_TOKEN 已废弃，勿再收集或配置）。
• 之后登录过期：若已有账号密码 → 直接重登，勿再要密码；若仅短信登录 → 白话说明「需要再收一次验证码」再走 SMS。已配置的域名一般无需再问。
• 用户只需提供：哪家子公司、哪个月份、想弄清什么问题（首次除外，须先完成域名与登录配置）。

登录与会话

• 任何业务命令前先 fin-mrp-cli session；失效时按上表重登，不要编造响应。
• 登录成功响应可含 credentialsPersisted（键名如 FINANCE_USERNAME/FINANCE_PHONE 等，不含验证码明文；账号密码虽可写入 .env，响应里只列键名）。

输出格式

• 对内：默认 stdout 为 JSON，供 Agent 解析与计算；需要表格时可使用 markdown 格式分支。
• 对外：见上文「面向用户的表述」——结论、表格、归因说明均用业务语言；禁止把 CLI 用法、JSON 结构当作用户操作指南。
• 接口字段 *_p4 表示实收口径；向用户统一称「实收口径」，勿称 P4。

管报分析

• 每次只查一个月份；多组织可同次 --provider-id。
• 按 item_name 精确匹配取行；KPI 行（item_level=0）勿与 section 明细重复相加。
• 接口金额为元（总补贴占比 为小数）；禁止编造组织或管报数据。
• 管报在销售、返利、成本调整基础上会做额外数据调整；与三表直接汇总不一致属正常。用户对比两类数据且有疑问时，须提示可能存在管报调整项，建议先查相应调整（见「管报与三表数据的关系」）。

资产负债表分析

• 命令：rp-balance / rp-balance-period-info / rp-balance-org-info；详见上文「资产负债表 rp-balance」。
• 组织：--kd-orgid 或 --provider-id（CLI 经 org-info 解析 kd_orgid）；期间 YYYYMM 或 YYYY-MM。
• 与管报 --period YYYY-MM 对应：管报 2026-05 → 资产负债表 202605。
• 查结构、环比（cur_amount / rpe_amount / diff_pct）、校验项（check_result_cur）；默认 JSON 输出 rows，含 rowTypeGuide。
• 禁止将 BS 存货与 MRP 期末库存直接等同；禁止在无 rp-balance 数据时编造资产/负债金额。
• 杜邦 / ROE / 杠杆分析：管报 + rp-balance 联合；权益为负时勿机械输出 ROE（见上文「与管报 / 三表联合」）。

销售 / 利润分析（实收口径）

• 凡按销售统计的 TOP 或 BOTTOM（品、客户、供应商、区域、厂家等）：必须 ss-saleout-aggregate；TOP 读 topList，BOTTOM 读 list 末尾 N 条；详见「销售 TOP / BOTTOM 分析」。
• ss-saleout-detail 红线：禁止用于排名；禁止批量/循环调用；仅用户明确查询指定单个品种（或单个批次）销售情况时才用。
• 销售出库结构汇总用 ss-saleout-aggregate；单 SKU 流水用 ss-saleout-detail 且只带一个 --sp-zt-code 或 --angle-id。
• 收入：amount / total_amount（不含税）、tax_amount / total_tax_amount（含税）；actual_pay_amount 为客户实付，非收入。
• 实收口径：JSON 中 gross_profit_p4 为销售段毛利；默认聚合另含 composite_gross_profit_p4（综合毛利，已合并返利实收与成本调整）。与管报毛利口径不同，勿直接对标。
• 当月实收口径综合利润：ss-saleout-aggregate 默认已合并三表行级/总计综合毛利；亦可分别调用三接口取 grandTotal 手算（见 SKILL「当月实收口径收入/成本/利润」）；注意返利实收与成本调整的符号约定相反。
• 禁止编造销售数量、金额或毛利。与管报对比时遵循「管报与三表数据的关系」：存在差异时主动说明管报含额外调整，勿断言查询有误。

期末库存分析

• 必填：--provider-id + --account-month（YYYYMM）；账期与管报 --period（YYYY-MM）对应，如管报 2026-05 → 库存 202605。
• 命令选型见上文「库龄 / 效期」Agent 表；结构汇总用 ss-angle-end-aggregate，批次明细用 ss-angle-end-detail。
• 库存金额均为 实收口径不含税成本（ending_cost / 聚合 total_amount），非销售金额。
• 禁止编造库存数量、库龄占比、效期分布；数字以 CLI 输出的 buckets / rows 为准。