vps-work 1.0.0

package/skills/sale-performance-query/references/vps-sales-account-orders.md

@@ -0,0 +1,48 @@
+# +account-orders
+
+按会计科目反查已过账凭证关联的销售订单行。用于“某收入/应收/税费科目对应哪些销售单”等财务销售穿透场景。
+
+| 项 | 值 |
+|----|-----|
+| CLI | `vps-work sales +account-orders [flags]` |
+| 别名 | `vps-work sales +account-sales-detail` |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `account_sales_detail` |
+| 默认 period | `this_month` |
+| 日期口径 | 会计凭证日期 `account_move.date` |
+| 权限 | `sales.account_orders:read`，并继续按销售数据范围裁剪 |
+| 独立角色 | `vps_finance_sales_viewer`；需与具备 `execute:read` 的基础角色组合授权 |
+
+## 查询条件
+
+`--account-code` 与 `--account-name` 至少传一个；同时传入时按 AND 过滤。
+
+| CLI | execute | 说明 |
+|-----|---------|------|
+| `--account-code <code>` | `account_code` | 科目编码精确匹配 |
+| `--account-name <name>` | `account_name` | 中文/英文科目名称包含匹配 |
+| `--move-no <no>` | `move_no` | 会计凭证号包含匹配 |
+| `--order-no <no>` | `order_no` | 销售单号包含匹配 |
+| `--include-draft` | `include_draft=true` | 包含未过账凭证；默认仅 `posted` |
+
+支持共享的 `--period`、`--start-date`、`--end-date`、部门范围、`--limit` 与 `--page`。
+
+## 关联口径
+
+- `直接关联`：所查科目行本身通过 `sale_order_line_invoice_rel` 关联销售订单行，常见于商品收入行。
+- `同凭证关联`：应收、税费等科目行本身不挂销售行，通过同一会计凭证内的商品发票行回溯销售订单行。
+- `借方/贷方/余额` 来自所查科目行；`销售数量/销售行金额` 来自销售订单行；`开票数量/未税金额/含税金额` 来自关联发票行，不能混作同一金额口径。
+- 退款、红字及负数保留数据库原始符号，不自动冲抵或改写。
+
+## 示例
+
+```bash
+# 按收入科目编码查询本月销售单
+vps-work sales +account-orders --account-code 6001 --period this_month
+
+# 按科目名称和凭证号查询
+vps-work sales +account-orders --account-name 主营业务收入 --move-no INV --period last_month
+
+# 精确到销售单
+vps-work sales +account-orders --account-code 6001 --order-no SO26080001
+```

package/skills/sale-performance-query/references/vps-sales-agent-five-suite.md

@@ -0,0 +1,55 @@
+# 代理商 Sell-in、Sell-out 与五件套
+
+## 契约
+
+| CLI | script_key | 默认时间 | 返回 |
+|---|---|---|---|
+| `sales +agent-sell-in-out` / `+sell-in-out` | `agent_sell_in_out_summary` | `this_month` | 代理商 Sell-in、Sell-out、差额和转化比 |
+| `sales +agent-sell-in-out-details` / `+sell-in-out-details` | `agent_sell_in_out_details` | `this_month` | Sell-in 销售行与 Sell-out 订单明细 |
+| `sales +agent-five-source` / `+agent-wujiantao` | `agent_five_source_metrics` | `this_month` | 五件套目标、真实业绩、占比、完成率 |
+| `sales +agent-five-source-half-year` | `agent_five_source_half_year` | 当前上/下半年 | 五件套 Sell-out 真实业绩 |
+| `sales +agent-walkin` | `agent_walkin_orders` | `this_month` | 自然进店/Walk-in 经销商销售订单 |
+| `sales +agent-list` | `agent_list` | `this_month` | 代理商组织树名单 |
+| `sales +agent-five-source-completion` | `agent_wujiantao_completion_rate` | `this_month` | 五件套总体目标、Sell-in 与完成率 |
+| `sales +agent-top-metrics` | `agent_top_metrics` | `this_month` | 当期、当日、全年达成与时间进度 |
+| `sales +agent-performance` | `agent_performance` | `this_month` | 目标、实际、完成率 |
+| `sales +agent-performance-detail` | `agent_performance_detail` | `this_month` | 定金、当日、环比和同比 |
+| `sales +agent-delivery` | `agent_delivery` | `this_month` | 提货/发货分类、系列和材质汇总 |
+| `sales +agent-product-sales` | `agent_product_sales` | `this_month` | 代理商、系列、材质、SKU 层级 |
+| `sales +agent-product-ranking` / `+agent-sku-ranking` / `+agent-product-material-ranking` | 对应 `agent_*_ranking` | `this_month` | 产品、SKU、材质排名 |
+| `sales +agent-phone-sales-proportion` / `+agent-iot-sales-proportion` | 对应 `agent_*_sales_proportion` | `this_month` | 手机/IOT 系列和材质/颜色占比 |
+| `sales +agent-price-distribution` | `agent_price_distribution` | `this_month` | 手机/IOT 价格区间分布 |
+
+底层 `skill_key` 为 `vps-daily-sales-report`。旧客户端脚本键 `agent_wujiantao_completion_rate`、`agent_wujiantao_five_source_metrics`、`agent_wujiantao_half_year_forecast` 继续可用。
+
+## 参数
+
+- 时间使用共享的 `--period`、`--start-date`、`--end-date`；半年度命令未传日期时可传 `--year`、`--month` 决定 H1/H2。
+- `--agent-name <完整名称>` 标准化中英文括号后精确匹配，同时传给 Sell-in、Sell-out 和目标表。
+- `--dealer <名称>` 是兼容参数。新代理商看板查询应优先使用 `--agent-name`，旧库存、订单、终销查询仍可用 `--dealer` 模糊匹配。
+
+## 口径
+
+- Sell-in：直接查询 `odoo_sale_sale`，范围为国内代理部门 ID `2234` 及其完整子树，按客户名称汇总实际金额和数量；不用会脱敏客户名的公共销售行构造器，否则无法精确筛选代理商。
+- Sell-out：与 `vps-ep` 个性化看板一致，取 `dealer_sale_order` 中 `state=done + dealer_nature=domestic`，不额外限制 `JXSD` 或 `doc_type=so`；汇总金额取订单 `total`。
+- `+dealer-final-sales` 是另一套严格终销口径，仍限制 `JXSD + done + so + 非退货明细`，不要与代理商个性化看板 Sell-out 混用。
+- 五件套真实业绩按经销商订单客户类型映射：自然进店→`walk in`、老客户存量→`存量`、线上渠道:官网+社媒→`原线上`、商场线下:异业销售推荐→`下线`、招聘:新员工自带客户转化→`AI招聘`。
+- 五件套目标比例固定为 `walk in 25%`、`下线 3%`、`原线上 4%`、`存量 60%`、`AI招聘 8%`；目标读取 `线下代理OKR.目标`。
+- Walk-in 只返回国内经销商已完成销售单中客户类型为自然进店/Walk-in 的订单，同样不额外限制 `JXSD` 或 `doc_type=so`。
+- Sell-in/out、明细、Walk-in 和五件套返回保留 CLI 的 snake_case 结果，并同时提供与 `vps-ep` 前端一致的 camelCase 字段。
+- Sell-in/out 明细和 Walk-in 使用数据库侧 `OFFSET/LIMIT`；总条数/总金额来自独立聚合查询，不得以当前页长度代替全量合计。
+- 单代理商的提货及产品销售发货量通过 `report_sale_shipment.source_document_number → sale_order.partner_id → res_partner.name` 精确隔离；同时排除不良品库、样品码 `%-YP`、定金和非正向发货，不能混入整个国内代理部门的发货量。
+- `线下代理OKR` 目标严格按请求日期范围读取；当前期无记录时返回 `0`，不自动沿用最近月份。回答时应说明目标缺失，不把 `0` 表述为已配置的零目标。
+- 普通用户沿用 ERP 经销商记录规则；汇总与目标也必须检查返回的 `filter.access`。
+
+## 示例
+
+```powershell
+vps-work sales +agent-sell-in-out --period this_month
+vps-work sales +agent-list --start-date 2026-08-01 --end-date 2026-08-31
+vps-work sales +agent-sell-in-out-details --agent-name "太原拍得丽机器人科技有限公司" --start-date 2026-08-01 --end-date 2026-08-31 --detail-type sell_in
+vps-work sales +agent-five-source --agent-name "太原拍得丽机器人科技有限公司" --period this_year
+vps-work sales +agent-five-source-half-year --year 2026 --month 8
+vps-work sales +agent-walkin --agent-name "太原拍得丽机器人科技有限公司" --period this_month
+vps-work sales +agent-product-ranking --agent-name "太原拍得丽机器人科技有限公司" --period this_month
+```

package/skills/sale-performance-query/references/vps-sales-customer-mix.md

@@ -0,0 +1,47 @@
+# +customer-mix
+
+查询新客、老客与未分类客户的销售额及占比。
+
+| 项 | 值 |
+|----|-----|
+| CLI | `vps-work sales +customer-mix [flags]` |
+| alias | `vps-work sales +customer-sales-mix [flags]` |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `customer_sales_mix` |
+| 默认 period | `this_month` |
+| 默认定金口径 | 不含定金 |
+
+## 分类与关联口径
+
+- 订单关联：`sale_order.customer_source = customer_source.id`。
+- 分类字段：`customer_source.customer_category`。
+- 值映射：`new=新客`、`old=老客`、NULL/空值=`未分类`。
+- 未知扩展值按原值单独展示，不归入新客或老客。
+- 历史 qinzhe 数据没有该字段，按未分类展示；当前月在线 Odoo 数据可正常分类。
+
+## 占比口径
+
+- `sales_share = 分类销售额 ÷ 同口径总销售额`，分母包含未分类。
+- `classified_sales_share = 分类销售额 ÷ (新客销售额 + 老客销售额)`，仅新客、老客返回该值。
+- `classified_coverage_rate = (新客销售额 + 老客销售额) ÷ 同口径总销售额`。
+- 订单数按分类分别去重；`category_order_count_sum` 是分类订单数之和。
+
+回答必须说明时间窗口、是否含定金、未分类销售额和分类覆盖率。不能把未分类静默剔除后只报新客/老客比例。
+
+## 示例
+
+```bash
+vps-work sales +customer-mix --period this_month
+
+vps-work sales +customer-mix --period this_month --dept-l1 国内渠道
+
+vps-work sales +customer-mix --start-date 2026-07-01 --end-date 2026-07-15 --include-deposit
+
+vps-work sales +customer-mix --period this_month --base-url http://127.0.0.1:3920
+```
+
+也可使用通用拆解命令查看分类销售额，但它不计算占比：
+
+```bash
+vps-work sales +dept-breakdown --period this_month --group-by customer_category
+```

package/skills/sale-performance-query/references/vps-sales-customer-region.md

@@ -0,0 +1,70 @@
+# +customer-region
+
+按订单登记的客户国家/地区汇总全公司订单数和营业额。该能力是独立敏感数据权限，不返回客户或订单明细。
+
+| 项 | 值 |
+|----|-----|
+| CLI | `vps-work sales +customer-region [flags]` |
+| alias | `vps-work sales +customer-region-summary [flags]` |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `customer_region_summary` |
+| 默认 period | `this_month` |
+| 默认定金口径 | 不含定金 |
+| 必需 scope | `sales.customer_region.all:read` |
+| 授权角色 | `vps_sales_region_analyst` |
+
+## 地区口径
+
+- 代理销售按订单的 `private_country_id` 国家归类。
+- 普通销售按订单的 `country_code` 国区号及对应国家归类。
+- 退货的代理销售属性回溯原订单，地区与原订单保持一致。
+- 未填地区单独归入“未填写”，不得并入中国或其他地区。
+
+## 业绩口径
+
+- 营业额复用公司 KPI 的实际业绩金额和分摊口径。
+- 退货和退差价按负数冲减。
+- 默认不含定金；显式传 `--include-deposit` 时才包含。
+- 订单数在每个地区内按销售单号去重。
+- 返回 `filter.data_scope=all` 表示全公司口径；未获得独立 scope 时接口必须返回 403，不得降级为本人/本部门数据。
+
+## 返回
+
+- `summary.regions`：匹配的国家/地区数。
+- `summary.order_count`：去重订单数。
+- `summary.sales_amount`：营业额。
+- `rows[].customer_region`、`country_code`、`order_count`、`sales_amount`、`sales_share_pct`：地区分布。
+
+## 示例
+
+```powershell
+# 本月全部地区分布
+vps-work sales +customer-region --period this_month
+
+# 本月来自马来西亚的订单数和营业额
+vps-work sales +customer-region --period this_month --country "马来西亚"
+
+# 国区号也可查询（前导 + 可省略）
+vps-work sales +customer-region --period this_month --country 60
+```
+
+## Execute API
+
+```http
+POST /v1/execute
+Authorization: Bearer <access_token_or_agent_key>
+Content-Type: application/json
+
+{
+  "skill_key": "vps-daily-sales-report",
+  "script_key": "customer_region_summary",
+  "params": {
+    "period": "this_month",
+    "country": "马来西亚"
+  }
+}
+```
+
+缺少 `execute:read` 或 `sales.customer_region.all:read` 时返回 HTTP 403。
+
+回答时必须说明时间窗口、是否含定金、地区来源以及 `data_scope=all`。结果为空时先区分“无权限”和“当期无匹配订单”。

package/skills/sale-performance-query/references/vps-sales-daily-trend.md

@@ -0,0 +1,44 @@
+# +daily-trend
+
+按日、周或月输出销量/销额/订单走势，可按组织渠道和商品款式交叉拆分，并输出上期值、环比、累计、同比，以及商品折扣口径。
+
+| 项 | 值 |
+|----|-----|
+| CLI | `vps-work sales +daily-trend [flags]`；别名 `vps-work sales +trend` |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `monthly_daily_trend` |
+| 默认 period | `this_month` |
+
+## 独有参数
+
+| CLI | execute | 默认 |
+|-----|---------|------|
+| `--no-include-cumulative` | `include_cumulative=false` | 累计默认开 |
+| `--grain day\|week\|month` | `grain` | `day` |
+| `--group-by <dim>` | `group_by` | 全公司；组织渠道用 `org_channel` |
+| `--breakdown-by <dim>` | `breakdown_by` | 无；款式明细用 `product_style1` |
+| `--no-include-comparison` | `include_comparison=false` | 上期及环比默认开 |
+| `--include-yoy` | `include_yoy=true` | 默认 false |
+
+## 示例
+
+```bash
+vps-work sales +daily-trend --period this_month --include-yoy
+
+vps-work sales +trend --period this_year --grain month \
+  --group-by org_channel --breakdown-by product_style1 \
+  --product-subcategory "VERTU ALPHAFOLD" --product-style 高定 \
+  --product-style-details "黄金3,黄金4,金钻"
+
+vps-work sales +trend --period this_month --grain month \
+  --group-by product_category --product-category IOT配件
+```
+
+`day` 返回 `dod_qty_rate/dod_amount_rate`，`week` 返回 `wow_*`，`month` 返回 `mom_*`；同时保留通用的 `qty_change_rate/amount_change_rate`。
+
+商品字段口径：
+
+- `orders` 是去重销售单数；`product_order_count` 是 vps-ep 商品页兼容的销售/分摊明细行数（`COUNT(*)`）。
+- `discount_standard_amount_* = Σ(标准单价 × COALESCE(分摊比例数量, 数量))`，`discount_actual_amount_* = Σ(实际业绩)`。
+- `discount_rate_*` 为 vps-ep 口径 `实际业绩 / 标准价金额`，`standard_to_actual_ratio_*` 为用户原式的倒数口径。
+- `incl_agent` 含代理；`excl_agent` 排除海外渠道、国内代理和 `渠道=代理`。两套折扣都排除置换行。

package/skills/sale-performance-query/references/vps-sales-dealer-orders.md

@@ -0,0 +1,47 @@
+# +dealer-orders
+
+查询 `dealer.sale.order` 经销商订单。该入口与普通销售订单 `+orders` 分开，只返回订单号以 `JXSD` 开头的数据（当前 ERP 序列格式为 `JXSD-...`）。
+
+## 契约
+
+| 项目 | 值 |
+|---|---|
+| CLI | `vps-work sales +dealer-orders [flags]` |
+| 别名 | `vps-work sales +dealer-order-list` |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `dealer_order_list` |
+| 默认时间 | `this_month` |
+| 数据源 | `dealer_sale_order` × `dealer_sale_order_line` |
+
+## 参数
+
+| CLI | execute 参数 | 说明 |
+|---|---|---|
+| `--period <name>` | `period` | 时间枚举或单日 |
+| `--start-date <date>` / `--end-date <date>` | `start_date` / `end_date` | 销售日期闭区间 |
+| `--order-no <no>` | `order_no` | JXSD 订单号包含匹配 |
+| `--dealer <name>` | `dealer` | 经销商名称包含匹配 |
+| `--salesperson <name>` | `salesperson` | 订单内销售员文本包含匹配 |
+| `--customer <text>` | `customer` | 客户名称或手机号包含匹配 |
+| `--product <text>` | `product` | 商品名称、编码或分类包含匹配 |
+| `--vsn <text>` | `vsn` | VSN / IMEI 包含匹配 |
+| `--doc-type <type>` | `doc_type` | `so` 销售、`rt` 退货、`ex` 换货 |
+| `--state <state>` | `state` | `draft` 草稿、`done` 已完成 |
+| `--nature <nature>` | `nature` | `domestic` 国内、`foreign` 国外 |
+| `--page <n>` / `--limit <n>` | `page` / `limit` | 分页；默认每页 50，最大 500 |
+
+## 返回口径
+
+- `订单金额` 取 `dealer.sale.order.total`，与 ERP 经销商订单列表一致；`数量` 是该订单全部明细行的净数量。
+- 商品过滤用于筛中订单，返回被筛中订单的完整商品、商品码和 VSN/IMEI 摘要。
+- 数据范围复用 ERP 记录规则：普通账号查询 `create_uid` 为本人的订单，国内/国外经销商管理组按 `res.dealer.information.nature` 查询对应区域，系统管理员或具有 `sales.performance.all:read` 的账号可查询全域。
+- 客户手机号仅对订单所属经销商或具有 `sales.pii:read` 的账号显示明文，其余返回掩码。
+- 结果包含 `pagination`；`has_more=true` 时继续传 `--page <next_page>`。
+
+## 示例
+
+```powershell
+vps-work sales +dealer-orders --order-no JXSD-2607 --period this_month
+vps-work sales +dealer-orders --dealer "太原拍得丽" --state done --period this_year
+vps-work sales +dealer-orders --vsn 353 --start-date 2026-07-01 --end-date 2026-07-31
+```

package/skills/sale-performance-query/references/vps-sales-dealer-performance.md

@@ -0,0 +1,49 @@
+# 经销商业绩与库存
+
+面向 `dealer.sale.order` 和经销商默认仓库的三个统计入口。终销只认 `JXSD` 前缀订单。
+
+## 契约
+
+| CLI | script_key | 默认时间 | 返回 |
+|---|---|---|---|
+| `sales +dealer-inventory` | `dealer_inventory_summary` | 当前库存，无时间参数 | 经销商库存数量、库存金额、SKU、未定价库存数量 |
+| `sales +dealer-final-sales` | `dealer_final_sales_summary` | `this_month` | 经销商 × 五件套客户类型的终销数量、含税金额、订单数 |
+| `sales +dealer-customer-portrait` / `+dealer-portrait` | `dealer_customer_portrait` | `this_month` | 经销商 × 背景/年龄/购买原因的数量、金额、订单数、订单占比 |
+
+三个入口的 `skill_key` 均为 `vps-daily-sales-report`，均支持 `--dealer` 和 `--nature domestic|foreign`。两个终销入口支持共享时间参数；库存入口额外支持 `--product`。
+
+## 业务口径
+
+### 库存
+
+- 经销商与仓库通过 `res.users.property_warehouse_id` 的公司依赖属性映射。
+- 与 ERP `dealer.dashboard` 一致，只统计默认仓库内部库位、`quantity > 0`、`tracking=serial` 的商品。
+- 库存金额 = 正库存数量 × 最新有效 CNY 标准单价；优先商品级价目表，回退模板级价目表，再回退 `product.template.list_price`。
+- 标准价仍为 0 的数量单列为 `未定价库存数量`，不能把该部分金额解释为已估值。
+
+### 终销与五件套
+
+- 固定过滤：`name LIKE 'JXSD%'`、`state=done`、`doc_type=so`、`order_line_nature IS NOT TRUE`。
+- 数量取行 `quantity`，金额取行含税金额 `tax_included_price`，订单数按 `dealer_sale_order.id` 去重。
+- `dealer_customer_type.name` 精确映射：自然进店→`walk in`、老客户存量→`存量`、线上渠道:官网+社媒→`原线上`、商场线下:异业销售推荐→`下线`、招聘:新员工自带客户转化→`AI招聘`；其余归入 `其他/未分类`。
+
+### 客户画像
+
+- 同一终销集合分别按 `customer_background`、`customer_age`、`purchase_reason` 统计。
+- 每张订单会分别进入三个画像维度；跨维度的订单数不能相加。
+- `订单占比` 的分母是同一经销商、同一画像维度内订单数。
+- 旧数据库如果尚未迁移三个字段，接口返回 `available=false` 和空行，并明确升级提示；不能据此回答“画像均为 0”。
+
+## 权限
+
+- 普通经销商仅看本人；国内/国外经销商经理按 `res.dealer.information.nature` 看对应区域。
+- 系统管理员、共享服务身份或具备 `sales.performance.all:read` 的用户可看全域。
+- 响应必须核对 `filter.access`、经销商、性质和时间窗口。
+
+## 示例
+
+```powershell
+vps-work sales +dealer-inventory --nature domestic
+vps-work sales +dealer-final-sales --period this_year --dealer "太原拍得丽"
+vps-work sales +dealer-customer-portrait --start-date 2026-07-01 --end-date 2026-07-31
+```

package/skills/sale-performance-query/references/vps-sales-deposit-breakdown.md

@@ -0,0 +1,16 @@
+# +deposit-breakdown
+
+含定金、不含定金、定金金额对照。
+
+| 项 | 值 |
+|----|-----|
+| CLI | `vps-work sales +deposit-breakdown [flags]` |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `with_without_deposit_breakdown` |
+| 默认 period | `this_month` |
+
+## 示例
+
+```bash
+vps-work sales +deposit-breakdown --period this_month
+```

package/skills/sale-performance-query/references/vps-sales-dept-breakdown.md

@@ -0,0 +1,32 @@
+# +dept-breakdown
+
+按部门、销售员、产品线等维度排名。
+
+| 项 | 值 |
+|----|-----|
+| CLI | `vps-work sales +dept-breakdown [flags]` |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `dept_breakdown` |
+| 默认 period | `this_month` |
+
+## 独有参数
+
+| CLI | execute | 说明 |
+|-----|---------|------|
+| `--department-mode <mode>` | `department_mode` | `matched`=匹配部门字段口径；`raw`=原始组织层级口径 |
+| `--group-by <dim>` | `group_by` | `dept_l1`…`dept_l5` / `matched_dept` 或 `match_dept` / `salesperson` / `product_subcategory` / `product_category` / `customer_category` |
+| `--auto-next-level` | `auto_next_level` | 未传 group_by 时按部门深度推断，默认 true |
+
+`department_mode=matched` 会强制按销售行的 `匹配部门` 字段汇总；当前在线 Odoo 脚本没有额外匹配规则，忽略历史特例后该字段等同业绩所属门店。`department_mode=raw` 会强制按 `dept_l1`…`dept_l5` 原始组织层级汇总。
+
+## 示例
+
+```bash
+vps-work sales +dept-breakdown --period this_month --group-by salesperson --limit 10
+
+vps-work sales +dept-breakdown --department-mode matched --period this_month --limit 100
+
+vps-work sales +dept-breakdown --period this_month --group-by customer_category
+
+vps-work sales +dept-breakdown --params '{"start_date":"2026-01-01","end_date":"2026-05-31","department_mode":"raw","group_by":"dept_l3","limit":100}'
+```

package/skills/sale-performance-query/references/vps-sales-dept-comparison.md

@@ -0,0 +1,24 @@
+# +dept-comparison
+
+部门、组织渠道或商品维度环比、同比。所有商品过滤条件会同时应用到当期、上期和去年同期。
+
+| 项 | 值 |
+|----|-----|
+| CLI | `vps-work sales +dept-comparison [flags]` |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `dept_comparison` |
+| 默认 period | `this_month` |
+
+## 产物
+
+当期 / 上期 / 去年同期销量、销额、订单数，以及销量/销额环比和同比。
+
+## 示例
+
+```bash
+vps-work sales +dept-comparison --period this_quarter --dept-l1 线下事业部
+
+vps-work sales +dept-comparison --period this_month --group-by org_channel \
+  --product-subcategory "VERTU ALPHAFOLD" \
+  --product-style-details "黄金3,黄金4,金钻"
+```

package/skills/sale-performance-query/references/vps-sales-entities.md

@@ -0,0 +1,25 @@
+# 销售域业务实体与选型
+
+## 三条能力线（不要混用）
+
+| 场景 | 子 skill | 典型 Shortcut |
+|------|----------|---------------|
+| 公司/全部门总销、环比同比、公司 OKR 达成 | `vps-daily-sales-report` | `+headline-kpi`、`+dept-comparison`、`+target-achievement` |
+| 销售单开票申请状态 | `vps-daily-sales-report` | `+invoice-status` |
+| 销售单财务全景（申请、发票、凭证） | `vps-daily-sales-report` | `+order-finance` |
+| 已对账销售收款及是否存在申请 | `vps-daily-sales-report` | `+reconciled-receipts` |
+| 人效、个人 OKR、PK 榜 | `vps-sale-personnel-efficiency` | `+per-person-kpi`、`+personal-okr`、`+team-pk` |
+
+## 商品分类（商品维度过滤）
+
+| 字段 | 含义 | 示例 |
+|------|------|------|
+| `product_category` | 业务二次分类（产线） | `手机`、`IOT配件` |
+| `product_major_category` | Odoo 商品大类 | `戒指`、`腕表` |
+| `product_subcategory` | 系列/细类 | `VERTU AGENT Q` |
+
+查**手机正式销售**用 `product_category=手机`，不要用 `product_major_category=手机`。`product_category=其他` 常含样机，分析正式销售时需排除。
+
+## 定金口径
+
+业绩类脚本默认 **不含定金**（`mv_product."定金"='是'` 剔除）。对照含/不含/定金金额用 `+deposit-breakdown`。

package/skills/sale-performance-query/references/vps-sales-headline-kpi.md

@@ -0,0 +1,26 @@
+# +headline-kpi
+
+公司/部门核心 KPI：销量、销额、订单。
+
+| 项 | 值 |
+|----|-----|
+| CLI | `vps-work sales +headline-kpi [flags]` |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `headline_kpi` |
+| 默认 period | `today` |
+
+## 独有参数
+
+| CLI | execute | 默认 |
+|-----|---------|------|
+| `--include-today` / 否 | `include_today` | true |
+
+共享参数见 [`vps-sales-shared-params.md`](vps-sales-shared-params.md)。
+
+## 示例
+
+```bash
+vps-work sales +headline-kpi
+vps-work sales +headline-kpi --period this_month --dept-l1 线上事业部
+vps-work sales +headline-kpi --period last_month --include-deposit
+```

package/skills/sale-performance-query/references/vps-sales-invoice-attachments.md

@@ -0,0 +1,37 @@
+# 销售单发票附件
+
+按精确销售单号查询其关联的已过账客户发票或退款单附件。接口返回发票号、日期、附件名和文件类型，不返回对象存储签名 URL。
+
+## 调用
+
+只看附件清单：
+
+```bash
+vps-work sales +invoice-attachments --order-no XSD260812137984
+```
+
+通过 Vertu 服务下载全部附件：
+
+```bash
+vps-work sales +invoice-attachments \
+  --order-no XSD260812137984 \
+  --download-dir ./invoice-files
+```
+
+验证本地服务请求但不联网：
+
+```bash
+vps-work sales +invoice-attachments \
+  --order-no XSD260812137984 \
+  --base-url http://127.0.0.1:3920 \
+  --validate-only
+```
+
+## 口径与限制
+
+- 订单号精确匹配，不按发票号查询。
+- 只包含 `posted` 状态的 `out_invoice` 与 `out_refund`。
+- 同一销售单可能关联多张发票、每张发票可能有多个附件。
+- 权限为 `sales.account_orders:read`，并继续按当前用户销售数据范围裁剪。
+- 下载文件名包含销售单号、发票记录 ID 和附件序号，且不会覆盖已有文件。
+- 未配置 `--download-dir` 时只返回元数据；服务端不会把附件存储 URL返回给 CLI。

package/skills/sale-performance-query/references/vps-sales-invoice-status.md

@@ -0,0 +1,37 @@
+# 销售单开票申请状态
+
+## 接口
+
+| 项目 | 值 |
+|------|----|
+| CLI | `vps-work sales +invoice-status --order-names <单号>`（别名 `+invoice-applications`） |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `sales_invoice_status` |
+| 权限 | `sales.account_orders:read` |
+
+## 查询口径
+
+- `order_names` 必填并精确匹配销售单号；一次最多 100 个，重复值自动去重。
+- 同时覆盖开票申请的 `sales_order` 直接关联和 `joint_order` 联合开票关联。
+- 一个销售单存在多次申请时逐条返回，并用 `是否最新申请=true` 标识按申请日期、申请 ID 排序后的最新一条。
+- 找不到销售单返回 `not_found / 未找到销售单`；销售单存在但没有开票申请返回 `not_applied / 未申请`。
+- Odoo 原始状态完整映射为：`draft / 草稿`、`approval / 审批中`、`done / 已完成`、`cancel / 已取消`。
+- `+reconciled-receipts` 中原有的“已开票”只表示申请数量大于零，不能用于回答真实申请状态。
+
+## 参数
+
+| CLI | execute 参数 | 说明 |
+|-----|--------------|------|
+| `--order-names SO1,SO2` | `order_names` | 必填；销售单号精确匹配，逗号分隔 |
+| `--limit <n>` | `limit` | 1–1000，默认 500 |
+| `--offset <n>` | `offset` | 0–4999，默认 0 |
+
+## 示例
+
+```bash
+vps-work sales +invoice-status \
+  --order-names SO001,SO002 \
+  --limit 100
+```
+
+回答时优先使用 `申请状态`，需要解释或排障时再带 `状态代码`；存在多条申请时不要只凭第一条推断，先查看 `是否最新申请` 和是否存在已取消的历史申请。

package/skills/sale-performance-query/references/vps-sales-order-finance.md

@@ -0,0 +1,29 @@
+# 销售订单财务全景
+
+## 接口
+
+| 项目 | 值 |
+|------|----|
+| CLI | `vps-work sales +order-finance --order-no <单号>`（别名 `+finance-detail`） |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `order_finance` |
+| 权限 | `sales.account_orders:read`，并按当前用户销售数据范围校验订单可见性 |
+
+## 返回内容
+
+- `order`：销售单号、日期、状态、金额、币种、公司及是否完成财务对账。
+- `invoice_applications`：直接或联合开票申请、申请日期、申请金额和真实流程状态。
+- `invoices_and_accounting_moves`：发票/退款单对应的凭证号、发票日期、会计日期、过账状态、付款状态、未税金额、税额、含税金额、待付金额、借贷合计、冲销关系及附件摘要。
+- `accounting_lines`：凭证分录的科目编码、科目名称、摘要、借方、贷方、余额和外币金额；单次最多 1000 条，必须检查 `accounting_lines_pagination.truncated`。
+- 开票申请状态、发票过账状态、付款状态是三套不同状态，回答时禁止混用。
+- 会计凭证范围仅限通过销售订单行与发票行关联到该销售单的凭证；不是任意总账凭证搜索。
+- 附件只返回名称和文件类型；需要文件时继续使用 `+invoice-attachments` 下载。
+
+## 参数与示例
+
+```bash
+vps-work sales +order-finance --order-no SO001
+vps-work sales +order-finance --order-no SO001 --invoice-no INV
+```
+
+`--order-no` 必填且精确匹配；`--invoice-no` 可选，对发票/凭证号做包含匹配。

package/skills/sale-performance-query/references/vps-sales-order-logistics.md

@@ -0,0 +1,50 @@
+# +order-logistics
+
+订单物流精查：按订单号、物流单号或出库单号查询发货商品、客户掩码信息、销售员和收货信息。
+
+常规订单查询优先用 `vps-work sales +orders`；订单列表已返回 `最新发货日期`、`物流单号`、`物流单号数`。只有用户明确要看某个订单/物流单号/出库单号的发货明细时才使用本 Shortcut。
+
+| 项 | 值 |
+|----|-----|
+| CLI | `vps-work sales +order-logistics [flags]` |
+| skill_key | `vps-daily-sales-report` |
+| script_key | `order_logistics` |
+| 默认 period | `this_year` |
+
+## 查询条件
+
+下列条件至少传一个；可组合使用。
+
+| CLI | execute | 说明 |
+|-----|---------|------|
+| `--order-no <no>` | `order_no` | 订单号或出库单号精确匹配；高级参数 `fuzzy=true` 时包含匹配 |
+| `--logistics-no <no>` | `logistics_no` | 物流单号或出库单号精确匹配；高级参数 `fuzzy=true` 时包含匹配 |
+| `--department <name>` | `department` | 兼容旧用法：销售员所在部门名称或完整部门路径包含匹配；一般优先用 `+orders` |
+| `--salesperson <name>` / `--name <name>` | `salesperson` | 兼容旧用法：销售员姓名 / 登录名包含匹配；一般优先用 `+orders` |
+| `--user-id <id>` | `user_id` | 兼容旧用法：销售员 Odoo 用户 ID 精确匹配；一般优先用 `+orders` |
+
+共享时间参数见 [`vps-sales-shared-params.md`](vps-sales-shared-params.md)。本 Shortcut 仍支持 `--period`、`--start-date`、`--end-date`、`--limit`、`--page`。
+
+## 返回字段
+
+默认返回列包含：
+
+`订单号`、`下单时间`、`销售员`、`客户名称`、`客户手机号`、`出库单号`、`发货日期`、`物流单号`、`商品编码`、`商品名称`、`发货数量`、`单位`、`仓库`、`收货部门`、`收件人`、`联系电话`、`收货地址`、`备注`。
+
+客户名称、客户手机号和联系电话默认返回中间掩码，不返回明文。
+
+## 示例
+
+```bash
+# 按订单号
+vps-work sales +order-logistics --order-no SO123
+
+# 按物流单号
+vps-work sales +order-logistics --logistics-no SF123
+
+# 按物流单号反查订单摘要，优先用订单列表
+vps-work sales +orders --logistics-no SF123
+
+# 某部门/销售员订单，优先用订单列表
+vps-work sales +orders --dept-l1 "线下事业部" --salesperson "张三" --period this_month
+```