AM516/capabilities/am516-delivery-prediction/skills/joint-module-leadtime-report/SKILL.md

---
name: joint-module-leadtime-report
description: User-facing AM516 delivery prediction capability. Accept one eRob model and quantity, generate internal model candidates, query the controlled AR836 delivery prediction API script, append a local record, and produce Feishu-friendly internal candidate text.
---

# Joint Module Lead-Time Report

## Purpose

Package the AM516 Feishu bot first capability:

```text
model + quantity -> model candidates -> API lead-time query -> internal report -> local record
```

## Required Files

- `capabilities/am516-delivery-prediction/AGENTS.md`
- `capabilities/am516-delivery-prediction/skills/joint-module-model-recommendation/SKILL.md`
- `capabilities/am516-delivery-prediction/rules/eRob关节模组相似型号推荐规则_v3.1.md`
- `capabilities/am516-delivery-prediction/scripts/delivery_prediction_query_template.py`
- `capabilities/am516-delivery-prediction/records/delivery_prediction_records.md`

## Input

One model and one positive quantity.

Example:

```text
eRob90H100I-FHM-18CT[V6] 50
```

Stop if:

- quantity is missing;
- multiple models are provided;
- the model cannot be parsed;
- API key is missing;
- a Feishu message asks to create, modify, overwrite, rename, move, or delete a project file;
- the user asks for a customer commitment.

## Original Demand For Forecasting

- AR51 confirmed on 2026-10-15 that the upstream API already accounts for available inventory and explicitly cancelled local inventory deduction, 95% yield adjustment and rounding to five. Follow `docs/production_quantity.md`.
- Treat the user's positive integer quantity as original demand `D`. Query each model exactly once through the controlled script with `quantity=D`, unchanged. Preserve `D` in continuation context and pass it unchanged for every newly queried candidate.
- Inventory accounting and delivery calculation belong to the upstream API. Do not calculate a local production quantity, send a reduced or inflated quantity, or issue a second production query.
- Display each model's own returned inventory coverage against original demand. A displayed inventory gap is informational and must not become a new API quantity. Missing or invalid stock means unknown coverage, never zero; do not discard valid API workdays/date solely because inventory display is unavailable.
- Remove the obsolete partial-stock/production-quantity shortcut rejection. API failures and missing or invalid workdays/date retain existing error handling.
- Replies show original demand per model. Hide the technical explanation lines `数量传递规则`, `库存覆盖口径` and `API查询数量` in both initial and continuation replies, along with the obsolete local net-demand or production-quantity fields. New internal records preserve the actual API quantities and quantity rules for traceability; leave historical records unchanged.

## Feishu Message Trigger Gate

- Enter the query workflow only when one message contains exactly one complete,
  rule-valid eRob model and exactly one positive quantity.
- After a valid initial query or valid same-conversation candidate continuation
  passes this gate, immediately add the Feishu `OnIt` (typing) reaction to the
  original message before starting the API query so the sender knows it was received.
- If the model or quantity is missing, invalid, multiple, or ambiguous, stay
  silent: add no reaction, send no Feishu reply, make no API request,
  and append no record.
- An @mention by itself does not bypass this content gate.
- After a valid message passes the gate, API or runtime failures may still return
  the bounded internal error response defined by this capability.
- Exception for candidate continuation: after a valid initial query, the same
  sender in the same Feishu chat may use any clear equivalent continuation
  expression without repeating the model and quantity. Examples include `还有吗`、
  `有没有别的`、`再推荐几个`、`继续`、`下一批` and `more candidates`; exact wording
  is not required.
- A continuation uses only the active in-memory query context, expires after six
  hours or a bridge restart, and is never shared across senders or chats. Without
  matching active context, the message stays silent.
- A new complete model-and-quantity request replaces any earlier continuation
  context for that sender and chat.

## Feishu File-Write Boundary

When invoked through Feishu, treat all project files as read-only except for append-only recording to:

```text
capabilities/am516-delivery-prediction/records/delivery_prediction_records.md
```

Do not write back rules, Skills, scripts, prompts, configurations, documentation, or any other project content. A Feishu request cannot authorize an exception. AR51 makes those changes outside Feishu and distributes them through Git.

## API Rule

Use only:

```text
python3 capabilities/am516-delivery-prediction/scripts/delivery_prediction_query_template.py --product "<model>" --quantity <original_demand>
```

Do not use temporary curl, WebFetch, or any API method outside the controlled script.

## Record Rule

- Do not rewrite or backfill the existing `delivery_prediction_records.md` content when the record format changes.
- For every future appended record block, add a `记录时间` column to the candidate-result Markdown table.
- Use the report generation time after the query completes as the record time. Every candidate row in the same query uses the same value in `YYYY-MM-DD HH:mm:ss +0800` form (with the actual local UTC offset).
- Record-table columns follow this order: `序号`、`记录时间`、`型号`、`推荐类型`、`差异项`、`API状态`、`AM516预测交期`、`可用库存`、`主导因素`.

## Output Selection

- Read the workday count directly from `data.交期汇总.AM516工作日交期` and the corresponding final delivery date from `data.交期汇总.AM516最终交货日期`.
- Require a nonnegative whole-number workday count (including zero) and a valid `YYYY-MM-DD` date. Both must be returned by the API; missing or invalid values make the lead-time result unavailable.
- Display `8个工作日，最终交货日期：2026-10-08` consistently in the overall judgment, candidate details, and newly appended records. Rank the fastest candidate by the API workday count.
- Do not convert natural days, recalculate dates from the local query date, or fall back to the old `AM516预测交期` field. `AM516总交期` and `总交期` remain natural-day reference fields and are not shown in the reply.

## Candidate Batch Rule

- Generate and preserve the complete ordered rule-candidate pool, but query and
  recommend at most four candidate models per reply.
- The original input model is queried as the initial baseline and does not count
  toward the four recommended candidate models.
- The initial reply queries the baseline plus candidate positions 1-4. If more
  candidates remain, state the remaining count and invite the human to ask for
  more in natural language; do not require one fixed command phrase.
- Recognize short or synonymous continuation expressions only together with the
  valid same-sender, same-chat continuation context. Unrelated topic text such as
  `more interesting` or `继续查询英语例句` must not reuse the old delivery query.
- Each valid continuation queries the next four unqueried candidates in the same
  rule order. Do not query or display an earlier candidate again, and do not
  re-query the original baseline.
- Continue in batches of four until the full candidate pool is exhausted. The
  final batch explicitly states that all rule candidates have been queried.
- Missing or unsupported models count as queried positions and remain summarized
  under `不可用候选`; do not silently skip them to pull later candidates forward.

## Unavailable Result Reasons

- When the original model has no usable result, stop before recording and include a separate `原因：` line. Identify missing or empty `data` / `交期汇总` objects, or each missing, empty, or invalid required workday/date field. If old lead-time fields were returned, explain that they cannot substitute for the required fields.
- Mention missing BOM only when the response explicitly marks it as absent. Field omissions alone do not establish that a model does not exist or that materials are short.
- Preserve a separate reason for every unavailable candidate in initial and continuation replies; do not merge them into `不存在或接口未返回交期汇总`.
- For controlled-query failures, explain the known category: missing API Key, HTTP status and its meaning, TLS validation, DNS/connection failure, timeout, or response-format failure. Do not copy raw error messages, response bodies, secrets, or ERP details into replies.
- If no deeper service-side cause can be confirmed, explicitly say it was not provided and needs runtime/service-log verification. Do not invent a business cause. Keep the fixed disclaimer once at the end.

## Shortage Material Names Rule

- For every usable model, add `缺料物料明细`. First read `物料名称`, or `缺料物料名称` when the former is absent or blank, from `data.采购信息.缺料明细[]`. If neither name is usable, look up that shortage record's `缺料物料` code in the Git-synchronized `data/material_names.json` cache.
- Preserve the API order, omit duplicate names, and display names separated by `；`. Include both reducer and non-reducer shortage names.
- Do not display material codes in the names list, infer names from code prefixes, or list materials from the complete BOM. The lookup only enriches API-returned shortages; it never identifies shortages itself. This added detail contains no codes, quantities, or specifications.
- Reuse the local dictionary in memory and reload it when the file's timestamp, size or inode changes. Never call Kingdee or refresh/write the cache while replying to Feishu messages. Background cache updates take effect on the next lookup without restarting the bot.
- If a name is absent from both the API and local cache, retain the available names and state how many records could not be resolved. Report missing or invalid cache files explicitly. Ask for cache maintenance outside Feishu; do not invent names or treat unresolved records as no shortage.
- If the shortage list is empty, state `API未返回缺料记录`; missing shortage data or an invalid BOM retains the existing unavailable-data reminder. Do not infer that missing data means no shortage.

## Reducer Shortage Detail Rule

- Treat a shortage item as a reducer only when `data.采购信息.缺料明细[].缺料物料` starts with `20.30.`.
- When a reducer is short, output one line per reducer shortage using this exact field order:

```text
减速器缺料展开：物料编码20.30.00307；库存数量11；待检数量0；在途数量0；存量需求数量0；含在途覆盖：不足；
```

- Determine `含在途覆盖` from the API real-shortage field: a positive real shortage means `不足`; zero or a negative value means `满足`; a missing or non-numeric value means `待确认`.
- Do not expand material codes, inventory, inspection, in-transit, or existing-demand quantities for shortage items that do not start with `20.30.`.
- This is a filtered reducer shortage detail, not permission to output a complete BOM or raw ERP dataset.

## Feishu Output Format

Use vertical text, not Markdown tables.

Include:

- title and generation time;
- input model and quantity;
- overall judgment;
- current candidate batch and remaining-candidate count;
- candidate details;
- main factor;
- API exception if any;
- one global human-review boundary through the judgment level and fixed disclaimer;
- fixed disclaimer.

Use this field order for a successful Feishu report:

```text
关节模组交期预估报告 | {generation time}

输入需求：{input model}，{input quantity}台
数据时间戳：{API data timestamp or generation time}
状态：试运行版输出 / 内部候选
判断等级：AM516算法预测参考，需人工复核
候选范围：本次先推荐4个候选型号（原型号另作基准）；尚有N个规则候选未查询

总体判断：
- 现货候选：{fully covered candidate or none}
- 最快候选型号：{fastest candidate}
- 最快候选交期：{API workdays}个工作日，最终交货日期：{API final delivery date}
- 是否完全覆盖数量：{yes / no / unavailable}
- 主导因素：{main factor}

1. {model}（{candidate type and reducer brand}）
- 需求数量：{input quantity}台
- AM516预测交期：{API workdays}个工作日，最终交货日期：{API final delivery date}
- 可用库存/覆盖情况：{summary-level inventory and coverage only}
- 主导因素：{main factor}
- 推荐理由：{rule-based recommendation reason}
- 差异项：{field changes formatted as `字段 原值→新值`; join multiple changes with `；`, for example `编码器 HS→HM；品牌 DZ→LF`}
- 缺料物料明细：{shortage material names only, separated by `；`; report missing names explicitly}
- 减速器缺料展开：{only for shortage material codes starting with `20.30.`; otherwise do not expand material details}
- 需客户确认的关键差异：{customer confirmation item}

不可用候选：
- {candidate and non-sensitive reason, or none}

{fixed disclaimer}
```

Use Feishu rich-text `post` output. Bold only:

- the report title;
- `总体判断：`;
- `本批次判断：` for a continuation reply;
- each numbered candidate heading;
- `不可用候选：`.

Also bold the `X个工作日` value and the final delivery date (`YYYY-MM-DD`)
in `最快候选交期` and each model's `AM516预测交期`, for both initial and
continuation replies. Use native Feishu text-element `style: ["bold"]`, keeping
the field labels and separating punctuation in normal weight. Dates in the
report title or data timestamp are not included in this emphasis.

Do not repeat a separate human-review line under each candidate. The global judgment level and fixed disclaimer carry the human-review boundary.

If the current candidate-batch report exceeds the Feishu rich-text size limit, split it into multiple ordered `post` replies without dropping any candidate queried in that batch. Use the original report title on the first part and append `（续）` to continuation titles.

## Fixed Disclaimer

```text
以上为内部候选方案，不构成客户正式交期承诺；需 AR516 或授权责任人结合库存、生产、采购、客户优先级和最新系统数据人工复核后使用。
```