# Sagacora 业务 Skill 安装与使用文档

版本：20261010（传统进销存流程：按销售、采购、仓库、财务办理，基础选项直接选择，后台与客户端统一单据交接）

## 当前能力概览

- 按销售、采购、仓库、财务的传统单据流程办理，日常不要求维护各种字典；商品类别、单位可直接输入名称。
- 后台入口：[业务工作台](https://sagacora.com/admin/workbench)，完整口径见包内 `references/workflows/traditional-operations.md`。

- **报价到订单直接在 Skill 客户端办理**：准备报价 → 展示价格来源与预填字段 → 用户确认 → 创建报价 → 准备转单 → 用户确认 → 创建订单；任务保存到服务端，可在新会话中查询和继续。

- 订单全流程（录入/更正/确认/取消/结单/采购分发/收发货/开票收款）、库存与经营分析、拜访与客户群待回复；
- 客户层级与商业条款：客户可挂上级（最多 5 层，防环），折扣（`sale_discount_rate`，0-1 小数）与结算方式（`settlement_method`）按层级就近继承；条款按生效窗口接替（未来生效不切断当前约定）；**停用祖先的条款不参与解析**（20260821-r4 起）；确认订单时条款快照落库；
- 商品/品牌主数据维护（需对应 `write.*` 权限）、MCP 专用查询工具 `jidan_customer_effective_terms`。

## 本版兼容与消息说明

- 商品的品牌、类型、单位外键 ID 保留为物理关联；界面隐藏，不删除。商品四项调价字段和重复供应商 ID、供应商部门/税号/银行信息、开票资料客户 ID 退出新增/修改/导入，物理列和历史值保留。历史订单等业务快照不回写。
- 开票资料自身不再绑定客户，客户/供应商引用开票抬头；税率读取按有效开票抬头匹配。供应商结算方式保留历史字段与导入兼容，新的简化表单不强制填写。
- 齐斌部署 `JIDAN_WECOM_WORKING_HOURS_ONLY=true`：北京时间每天（含周末）[08:00,18:30) 发送，窗口外写入持久队列、下次08:00补发，不丢弃、不重算消息；排队不算发送尝试，失败重试与过期租约恢复同样受限。通用代码默认 false，其他部署不自动改变。
- 网页受限账号权限与企业微信管理者身份独立。待办验收只看指定验收人身份，不看创建人；凭据只能私下交付已核实的目标收件人，交付未核实不得标记账号需求完成。

## 安装包下载

当前版本 `20261010`：

```text
https://sagacora.com/downloads/jidan-order-operations-20261010.zip
```

sha256 校验值以服务端 `jidan_skill_version` 返回的 `skill-manifest.json` 为准。

历史版本仍可下载，但建议所有用户升级到最新版：回复口径与工具返回字段在 r9 起以名称为主。

## 安装步骤

本版新增 `jidan_prepare_quotation`、`jidan_prepare_order_from_quotation`、`jidan_confirm_skill_action`、`jidan_get_skill_task`、`jidan_list_skill_tasks`。更新客户端 Skill 后重新连接 MCP；已使用“全部工具”授权的 Token 自动获得其允许范围内的新工具，自定义工具清单需管理员补选。报价写入仍需 `write.quotations` 与原业务角色权限；只读 Token 不能准备或确认写入草稿。

1. 会话内调用 MCP 工具 `jidan_skill_version`，确认服务端当前版本；若服务端版本高于本地 SKILL.md 头部 `version`，先升级再执行业务写入；
2. 下载上方 zip，解压后用包内 `SKILL.md`、`agents/`、`references/`、`scripts/`、`tests/` 覆盖本地 skill 目录；
3. 自动化验收在源码仓库执行：`cd agent-platform && .venv/bin/python -m pytest ../skills/jidan-order-operations/tests/ -q`（497 个用例及 15 个子测试）；安装包不含部署迁移脚本和仓库级发布检查，不能用 `unittest discover` 代替完整 pytest 验收；
4. 业务写入需要管理员在「身份与租户 → 设置权限」为绑定身份勾选对应 `write.*` 权限（默认全部不开放）。

## 版本日志

每次发布的新增与修复（新版本在前；历史版本的详细安装说明见仓库 `skill-package/JIDAN_ORDER_OPERATIONS_INSTALL_*.md`）：

| 版本 | 日期 | 主要内容 |
| --- | --- | --- |
| `20261010` | 10-10 | 传统进销存流程：按销售、采购、仓库、财务办理，基础选项直接选择，后台与客户端统一单据交接；兼容现有受控工具与历史业务数据 |
| `20261006` | 10-06 | Skill 主导报价到订单：结构化草稿、来源核验、确认执行、跨会话任务恢复与重复请求回执恢复；新增 5 个 MCP 工具，报价默认值与取价同源；平台真实业务及 MCP 传输回归覆盖；运营 497 用例及 15 个子测试 |
| `20260922` | 09-22 | 下单口径：结算方式为空（含上级课题组/单位均未维护）的客户禁止新增销售订单与报价转订单，显式指定结算方式可放行，报错文案与网页端一致；schema v75：`customer_visit` 增 `group_customer_id`/`benefit_promise`/`todo_title`/`todo_due_at`，`customer_id`/`visitor_id`/`participant_names` 放宽可空（管理台新表单以创建人为准，机器人写入路径不受影响）；平台 792、skill 497 用例 |
| `20260920` | 09-20 | 采购侧流程一致性修复：取消采购订单与作废票款不得进入结算；采购明细支持按数量分批结算；正常采购入库在同一事务生成库存流水，历史已过账流水自动配对且不回退订单状态；真实关联采购自动替换未确认估算成本；采购建议跨未完成订单统一分配库存；平台 758、skill 496 用例 |
| `20260914` | 09-14 | 系统审查第二批修复：确认订单补齐开票/送货/结算必填校验、待确认订单禁开出库通知（与平台同口径，单一事实源测试锁定）；单号口径文档对齐（YP/XS）；附件上传移出两阶段确认；SQLite 迁移快速通道覆盖 v73+；电话脱敏默认开启（齐斌明文口径由部署覆盖保留）；schema v74；平台 730、skill 496 用例 |
| `20260913-r1` | 09-13 | 协同待办与个人待办拆分；客户产品标签字典及客户资料多选标签；schema v74；平台 724、skill 493 用例 |
| `20260913` | 09-13 | 系统审查 8 项修复：跨事务幂等稳定键与审批回执重放、审批原子裁决、服务端签名跨回合确认、采购申请可信提交人及历史空提交人拒审、Skill 配置热更新与进程全局锁、镜像内置 Skill 可靠回滚、待确认订单禁止结算；平台 722、skill 493 用例 |
| `20260912-r10` | 09-12 | 出库通知只做岗位间信息传递，不预占、不扣减库存；可用库存与采购建议按现存量计算；平台 718、skill 491 用例 |
| `20260912-r9` | 09-12 | 补齐完整性缺口：管理台确认冻结客户条款；Skill 草稿可确认；出库守卫按明细行；主数据编号锁进写事务；结算单号按最大序号；SKU 前缀剥离跟随开关；XFF 只用真实客户端 IP；平台 718、skill 491 用例 |
| `20260912-r8` | 09-12 | 系统完整性修复：管理台销售订单新增确认入口并统一下游状态门禁；单号发号锁与唯一索引、北京时间业务日期；金额两位四舍五入与分摊订单上限；同 SKU 按订单明细出库及取消冲销；确认/取消行锁、历史价兼容；回滚兼容校验；schema v73；平台 715、skill 489 用例 |
| `20260912-r7` | 09-12 | 管理台需求回查修复：报价转订单单事务与并发锁；跟进扫描按北京时间且取消数量上限；采购申请/出库通知补齐状态、重复行和并发校验，销售订单出库通知入口完整可用；取消出库恢复库存并重算状态；高级筛选逐列入口与 Excel 导出结果一致；schema v72；平台 712、skill 487 用例 |
| `20260912-r6` | 09-12 | 销售出库通知/销售出库单扁平化（freq_606a44b2/freq_c7533060）：出库通知明细新增 无需收货情况/特殊发货安排，累计通知数量不超订单数量，剩余通知数量自动算；「销售订单出库」更名「销售出库单」移入库存管理，出库类型实物扣库存/非实物不扣、出库状态、通知与订单商品信息自动带出，出库单号前缀 SH→XS；schema v71；平台 708、skill 486 用例 |
| `20260912-r5` | 09-12 | 采购申请单扁平化与销售订单行内动作：采购申请单页改扁平明细结构（无需收货情况四枚举/特殊发货安排/商品库存与销售订单信息自动带出），多选批量生成采购订单、行内审批、扁平新建；销售订单操作区两行制，新增 采购申请（库存差异建议量）/出库通知（预留）/结算单（部分数量分批结算，累计不超订单数量，已结算锁价锁量）；schema v70；平台 705、skill 486 用例 |
| `20260912-r4` | 09-12 | 修复云端 PostgreSQL 转单回写失败（freq_e6cecc3e）：转单状态重算聚合列未命名在 PG 下列名重复塌缩，回写段异常回滚而订单已提交，导致可无限重复转单（生产已修复存量台账）；跟进待办口径修正（freq_18b8451c）——报价日期任意早于当天即生成待办、办结时间当天 18:00；平台 700、skill 486 用例 |
| `20260912-r3` | 09-12 | 转订单数量与报价数量解耦（freq_d3aba7a2 bug 提报）：订单数量只要求大于 0、报价 3 也可以下 5——转单本质是确认报价被客户接受，数量不必对齐（客户没说数量时按 1 报、下单 10 个）；转过的报价行二元锁定一行只转一次；Web 向导明细只显示 报价数量/转订单数量，去掉 已转/剩余可转；管理台客户报价单行内预留「生成文档」按钮（freq_38a0422b，按我方报价抬头生成报价单文件的功能后续随文档模块上线）；平台 700、skill 486 用例 |
| `20260912-r2` | 09-12 | 报价单终结与五态转订单状态（freq_b08b72dd）：「客户零星报价」更名「客户报价单」；转订单状态改二元口径五态——未转单（红）/部分转单（蓝）/全部转单（绿）/未转单终结、部分转单终结（灰），判断与数量无关（任一明细行转过即算该行已转），全部转单与终结后不能再转订单；管理台报价单行内新增「终结」按钮（原因必填）；报价日期次日仍未转单/部分转单自动生成业务员跟进待办（办结＝次日 18:00），进入三种终态后待办自动完成并验收；schema v69；平台 700、skill 485 用例 |
| `20260912-r1` | 09-12 | Web 管理台报价转订单向导（freq_0f89371d）：报价单行内「转订单」两步（选产品改数量/删行→补订单信息生成销售订单）；销售订单页顶部新增「新报价单转订单」三步（先按单号/客户搜索选报价单）；转单工具 `items=[{item_id, quantity}]` 行级数量覆盖（不超过剩余可转数量，台账增量累加，行级/主表转单状态实时收敛）；平台 696、skill 482 用例 |
| `20260912` | 09-12 | 修复报价转订单回写丢失：转单执行链缺最终 commit，订单生成后报价单行级台账/主表指针被连接关闭静默回滚，报价单永远停在未转单；管理台「报价转订单」「生成送货单」路由显式带 confirmed，不再被两阶段确认门拦成只读草稿还按成功提示（freq_6dc0f855）；平台 697、skill 477 用例 |
| `20260911-r1` | 09-11 | 品牌显示名称的中英文名直接连接，中间不再添加空格；管理台与 Agent 的查询、关联和商品品牌同步保持一致 |
| `20260911` | 09-11 | 营销支持新增招投标信息（价格明细、常见文档附件）与品牌活动（宣传图仅图片）；会话存档搜索改为群备注/成员/内容；客户群待回复默认隐藏已回复，已回复从系统检测时间起保留 7 天；schema v68 |
| `20260908-r5` | 09-08 | 修复商品品牌显示修复时四位采购折扣被管理台按两位舍入，导致有效折扣被误判为手工指定并保存失败 |
| `20260908-r4` | 09-08 | 修复品牌改名/属地变更后商品管理品牌显示不更新：同步已关联商品品牌文本，并为仅有旧品牌文本的历史商品补齐品牌关联；历史订单等业务快照不回写 |
| `20260908-r3` | 09-08 | 品牌 timestamptz 修改回滚修复；商品属性默认库存商品并确认；非实物出库不扣库存、不进库存查询；MCP `jidan_upload_image`；schema v67 |
| `20260908-r2` | 09-08 | 商品属性必填且不得默认；开票资料按引用抬头独立查询；v66 供应商新增渠道留空、默认开票是；移除写入口但保留物理兼容列，不改历史单据快照；同步网页表单、受限账号权限与工作时段排队补发 |
| `20260908-r1` | 09-08 | 品牌信息规范与英文品牌支持：中英文名至少填写一个，显示名按国产中文在前、进口英文在前组合；品牌新建、修改、导入停用三项兼容字段但保留历史商品继承，授权来源枚举与日期校验统一；schema v65 安全放宽中文名非空约束；平台同步必填模板星号和待办编号中文逗号 |
| `20260908` | 09-08 | 品牌商品数改为按需查询：品牌表新增【商品数】按钮列，普通列表不自动 COUNT；点击单个品牌才按 product.brand_id 实时统计，停用商品计入、改品牌/物理删除后刷新即变化；新增 jidan_brand_product_count MCP 工具，Skill 仅在用户明确询问时调用 |
| `20260907-r4` | 09-07 | 权限与一致性修复：客户条款及旧待办对象授权、财务关联订单取消保护、历史订单精确查询、完整新建确认门禁、协作待办编号及幂等并发保护、合同创建可恢复幂等；schema v64 财务分摊并发约束与日记账增量刷新，平台同步内容安全与登录防护 |
| `20260907-r3` | 09-07 | 公司协作待办不可变 TD-YYYYMMDD-NNNN 编号，按北京时间日期分配；Web、大屏和 MCP 返回编号，支持精确查询及完成、验收、驳回；禁止与旧跟进待办混用 |
| `20260907-r2` | 09-07 | 完成待办必须填写完成情况；验收人限在职人员可搜索选择；大屏到期待办两行省略 |
| `20260907-r1` | 09-07 | 待办事项接入 skill/MCP（freq_6a63cd35 模块后续）：新增 5 个云上工具 `jidan_list_todo_items` / `jidan_create_todo_item` / `jidan_complete_todo_item` / `jidan_accept_todo_item` / `jidan_reject_todo_item`——多责任人（内部人员姓名）、要求办结时间（北京时间）、验收人默认预填创建人可改；新建遵守两阶段确认口径（预填清单先发用户确认）并强制幂等键（聊天重发去重）；验收/驳回服务端硬拦仅验收人本人可操作（管理者豁免，web 端同口径：按钮与接口双层校验）；新增权限位 `read/write.todo_items` 默认对全部角色开放；平台 439、skill 467 用例 |
| `20260907` | 09-07 | 四条需求提报落地：①【内部公司基础信息】四张表（内部公司信息/银行账户/内部部门/内部人员）经 skill/MCP 禁止新增/删除（低频治理走管理台 web 端，修改保留，服务端硬拦）；②客户新增必填收紧——业务员对三种类型一律必填（分级新建的每一级都要带）、单位客户所属单位为强制约束（按客户名称预填、不能清空）、课题组客户的课题组身份即客户名称（列表所属课题组列显示自身名称）；③数据语义顶层规则（硬规则 11）——业务记录引用字段写入时落快照、源头修改不回刷存量只影响新增，数据查询表随源头更改实时展示；平台 429、skill 467 用例 |
| `20260906-r5` | 09-06 | Skill 版本只升不降（freq_1a157255）：新增硬规则——绝对禁止回退/降级旧版本包，也禁止向用户提出或询问这类建议（如「换回 r2 旧包」「旧版本不拦新建」）；两阶段确认等安全约束不因用户嫌繁琐而绕过，版本问题只引导升级到服务端最新版 |
| `20260906-r4` | 09-06 | 客户新增预填二次收紧：常用开票抬头无论客户类型一律默认「所属单位」字段的值（课题组/个人所属单位空缺时先沿上级链继承最近有值者），不再按上级名称另找；预填草稿与写入侧同规则；平台 426、skill 467 用例 |
| `20260906-r3` | 09-06 | 订单总览只读视图（schema v63）：管理台「工作台 → 分析视图」新增订单总览页，以订单为维度聚合 库存状态（已取消/已发齐/缺货/库存满足）/缺货数量/未发与已发数量/出库与通知状态/送货单数与最近发货日期/在采数量/已开票与已收金额/发票张数与收款笔数 共 33 列；口径沿用例外报告与应收提醒（缺货=未发超出可用库存、金额排除作废单据）；平台 424、skill 467 用例 |
| `20260906-r2` | 09-06 | 新建类写操作两阶段确认：所有新建数据的工具首次调用返回预填草稿（客户新增自动按层级继承上级业务默认值、常用开票抬头默认所属单位、单位客户所属单位按名称强制预填、电话/地址空缺问询；报价转订单草稿单列 我方销售抬头/客户开票抬头/送货信息 三处逐项确认），用户确认后带 confirmed=true 才写入；「报价状态」字段删除（转单进度看「转订单状态」）；平台 424、skill 467 用例 |
| `20260906-r1` | 09-06 | 我方报价抬头改真外键（schema v62）：管理台渲染为内部公司下拉选择、列表按简称显示、填简称自动反解；转订单反解析简称写入订单抬头；存量文本按简称回填后删列 |
| `20260906` | 09-06 | 客户零星报价表字段规格落地（schema v61）：单号改 `BJ`+YYYYMMDD+四位流水；主表新增 我方报价抬头（限内部公司简称）/送货信息/结算方式/业务员 随客户继承（可改），有效期默认报价日期次月月底；明细必选商品、单价缺省按取价链、折扣=单价÷目录价四位、金额=数量×单价两位、税率随客户常用开票抬头、是否开票默认是，新增指定批号/单价备注/货期；报价总额=Σ明细金额派生只读；转订单后行级/主表 转订单状态 与 关联销售订单号 自动派生，报价抬头/送货/结算/业务员/行级税率与开票标记随转带入订单；存量行按台账回填；平台 421、skill 465 用例 |
| `20260905-r3` | 09-05 | 采购订单规则表落地：单号自动 `CG`+YYYYMMDD+四位流水（转采购与直接新建均发号，此前转采购不发号）；订单日期必填默认当天、供应商必填；整单发货情况值域 是/否；涉及客户继承申请单；明细新增商品名称/目标价/库存数量（实时）派生列、库存快照列默认隐藏；转采购明细继承申请明细的关联销售订单行、对应销售客户、直发代测、长货期、指定批号；平台 394、skill 461 用例 |
| `20260905-r2` | 09-05 | 采购申请单规则表落地（schema v60）：单号改 `YP`+YYYYMMDD+四位流水；主表新增「订单涉及客户」必填（从销售订单生成时继承客户名称）；明细商品名称/单位按商品档案自动代入、不可手填（单位不一致当场报错）；新增指定批号、是否直发或代发测、长货期/分配发货标注三列（后两者继承销售订单明细、允许调整）；品牌/商品类型/规格/目标价（=目录价）/库存数量/关联销售订单号为派生展示；单行 API 必填口径与导入对齐；平台 393、skill 461 用例 |
| `20260905-r1` | 09-05 | schema v59 出库通知拆分+成本四级匹配+通用待办：出库通知（`outbound-notice-create`，TZ- 编号，内部传递不扣库存、累计通知量≤订单量、订单派生通知状态 未/部分/全部通知）；送货单 `delivery-note-create` 只能引用通知生成、创建即出库扣库存（原子事务，没通知不能出库），取代 delivery-note/-item-add/-execute 三件套，存量送货单按拍板清掉；成本匹配四级规则全自动落账（关联采购→订单日前三个月无关联最高价（个性化 cost_pricing 可关）→订单日前最近无关联→最近一次兜底）；通用待办 `todo-create/-complete/-cancel`（报价未成单转跟进，到期进提醒页）；多订单合并销售结算单开票资料一致硬校验；结算挂款/挂票自动预填明细级分摊；直接新增采购申请单需 confirm_direct 确认、管理台采购申请/订单新增弹确认；平台 391、skill 461 用例 |
| `20260905` | 09-05 | schema v58 单-货-款-票流程图缺口闭环：送货单执行出库（`delivery-note-execute`，订单/送货单出库状态派生+存量回填）；销售结算单挂收款（自动订单分摊+款票齐备自动核销，状态 partially_settled/settled）；现金/支付宝/收票三本账接入认领桥、五本账匹配状态全派生；订单/采购明细引用锁定（商品不可换、数量不得低于已引用量、已结算价格锁定）；销售/采购结算单累计防重；采购入库单超收校验+采购单状态联动；报价单行级部分转化；平台 379、skill 460 用例 |
| `20260904` | 09-04 | schema v57：销售结算单（订单明细→客户确认→发票分摊）、采购结算单（先付后票/先票后付统一工作单，付款/收票/入库挂接并写既有分摊桥）、订单利润（人工审批成本快照：实际采购优先/默认采购价估算/待补成本）；报价单 Web 转订单入口；平台 373、skill 455 用例 |
| `20260903-r3` | 09-03 | 备忘录粘贴登记拜访（SKILL.md 提示词增强，无代码/schema 变更）：把备忘录、工作记录等自由文本粘贴给 WorkBuddy 即可生成拜访记录——解析课题组/时间/参与联系人/内容/地点/结论/后续事项；课题组名经 `jidan_search_customers` 唯一命中（口语简称换全名再搜，多候选/零匹配必须问，系统外客户不自动新建）；联系人直接进 `participant_names`（自由文本）；内容保留原话不丢关键信息；缺拜访时间/后续截止时间必问不默认；登记后回一行「已登记」供核对；同备忘录重发复用幂等键防重复；平台 361、skill 455 用例 |
| `20260903-r2` | 09-03 | 修复 r1 的 v56 迁移自锁（子迁移误加与运行器同名的 advisory lock 导致死等；去锁重切，线上按设计中止未影响数据）。其余同 r1：system_config 三层合并 + 存量冻结 + generic 通用预设 + 管理台系统配置页 + jidan_ops 实时读配置；平台 355、skill 455 用例 |
| `20260903-r1` | 09-03 | 部署级系统配置（三层合并：代码默认←预设包←本地覆盖）：业务库 system_config 表（v56 迁移把存量部署口径自动冻结，行为零变化；新部署应用 config_presets/generic.json 通用档）；jidan_ops 实时读配置——取价执行阶段可停用、编号格式、客户透传过滤、送货拼接模板、自审禁令开关；管理台「系统配置」页（编辑覆盖/恢复默认/应用预设，留审计）；平台 355、skill 455 用例（该版 v56 迁移存在自锁，已被 r2 取代，勿安装） |
| `20260903` | 09-03 | 业务口径单一事实源：新增 business-rules 工具（MCP：jidan_business_rules，返回取价链/客户挂靠/编号/唯一名/显示约定 + 税率等字典实时可选值）；三处提示词副本改由渲染器拼装、税率枚举去写死（修复与字典五档的漂移）；skill 侧镜像常量由跨包一致性测试强制、price_source 类型改读镜像；SKILL.md 不再枚举税率/取价链/编号；平台 343、skill 455 用例 |
| `20260902-r17` | 09-02 | schema v50 内部人员职级改 staff_rank 字典真 FK（job_level → job_level_id，管理台下拉+名称直填解析，线上存量全空无需回填，迁移随部署自动应用）；管理台新建表单必填字段标红 *，必填口径收敛服务端 required_on_create（前端硬编码集合移除，supplier 旧集合已失配）；平台 316、skill 445 用例 |
| `20260902-r20` | 09-02 | schema v53 库存查询：视图扩列（商品类别/规格/单位/是否常备/组装品/可拆分+上下限），可销售数量改 库存+采购未到-销售未发；新增 stock_on_hand_batch 批号视图；页面两开关（显示零库存/区分批号，默认都关），库存数量越界或可销售为负红字预警；平台 319、skill 445 用例 |
| `20260902-r19` | 09-02 | schema v52 内部公司编号：company_no 整型必填、Web 端默认按编号升序（存量回填 1..N 随部署自动迁移）；行操作「一键复制开票信息」按钮（固定格式复制开票四行+收件地址三要素，操作区两行小字）；导入模板必填口径统一读服务端 required_on_create；与 v51 合同挂接追溯（contract_from_order/link/unlink/trace）同包联发；平台 318、skill 445 用例 |
| `20260902-r18` | 09-02 | schema v51 合同挂接与追溯：订单挂合同（客户口径一致）、从订单生成合同（模板+订单信息页）、按合同追溯订单/送货/发票/收付款与差额（不含作废，红冲负数呈现）；平台直连工具 read/write.contracts；平台 318、skill 444 用例 |
| `20260902-r16` | 09-02 | schema v49 采购申请单：提交（SQ 编号）→审批（申请人不能自审）→转采购订单（可部分、累计≤申请量，报价取唯一首选、税率随供应商，回填 requisition_item_id）；撤回/关闭剩余需求；管理台行内审批/转采购同链路；平台 315、skill 445 用例 |
| `20260902` | 09-02 | schema v48 库存调整单：盘点差异/手工调整改走「调整单→审批→不可变流水」，审批人生成 source_type='inventory_adjustment' 流水并刷新常备库存（负库存拒绝并列出商品），制单人不能自审，撤回仅制单人/管理者；v46 直写调整流水口子收回，常备库存表余额列转只读；管理台行内审批/撤回与 skill 工具同链路；平台 313、skill 437 用例 |
| `20260901` | 09-01 | 发布安全收敛：Skill 仅保留 `skills/jidan-order-operations` 一个源码，客户端 zip 直接由它构建；服务端数据库升级统一走迁移器（账本、串行锁、版本防回退、部署前后校验），客户端包不再携带迁移脚本；Skill 用例 428。原 `20260901-r15` 系版本号笔误已作废，内容与本版完全一致。 |
| `20260831-r14` | 08-31 | schema v47：结算方式三处（客户/供应商/订单快照）改 settlement_method_dict 真 FK；存量 现款/现结/立即付款/立即结算→款到发货、月结30天账期→月结30天；层级继承/按单覆写/确认快照/派生显示全链路改存 ID 显名称；线上跑 `scripts/migrate_postgres_v47_settlement_dict_fk.py --apply` |
| `20260831-r13` | 08-31 | schema v46：订单类型以 order_type 字典为准（旧枚举与补结算联动删除）；五处税率字段统一改 tax_rate 字典真 FK（行级税率保持数字）；库存查询视图扩四列口径、库存流水放开 adjustment 调整（原因必填）、采购申请补自动化链路字段与 PO 反向引用；线上跑 `scripts/migrate_postgres_v46_order_type_tax_rate_inventory.py --apply` |
| `20260831-r12` | 08-31 | schema v45：v44 迁移清单遗漏的 `customer.customer_category/customer_tier` 补挂真 FK（`migrate_postgres_v45_customer_dict_fk.py --apply`），修复个人客户新增被拦 |
| `20260831-r11` | 08-31 | schema v44 特定字段规则真 FK 第一批：11 处字典字段改 `*_id` 真 FK（客户分类/分级、纳税人类型、三处发票类型、品牌分级、供应商分类、三本日记账收支类型、商品属性、银行账户补账户类型）——填名称自动解析成 ID、字典外值拒绝、管理台下拉；品牌分级存量按 核心/核心外主推→主推品牌、常用→常见品牌、一般/不常用→普通品牌 归档；供应商分类补「其他」；线上跑 `scripts/migrate_postgres_v44_field_rule_fk.py --apply` |
| `20260831-r10` | 08-31 | schema v43：内部公司银行账户备注改非必填（v41 曾设 NOT NULL）；**特定字段规则字典表对 skill/MCP 只读**——`business_data_row_create/update/delete` 写字典表统一被拒（报错引导去管理台「基础资料 → 特定字段规则」维护），管理台不受影响；线上跑 `scripts/migrate_postgres_v43_bank_note_optional.py --apply` |
| `20260831-r9` | 08-31 | schema v42：删除遗留表 `supplier_invoice_profile`（0 行、与外部开票资料重复）；`customer.customer_category/customer_tier` 改字典软绑定（字典有数据按字典、为空回落内置枚举，CHECK 枚举移除）；线上跑 `scripts/migrate_postgres_v42_drop_supplier_invoice_profile.py --apply` + `ANALYZE` |
| `20260831-r8` | 08-31 | schema v41：特定字段规则新增账户类型字典；内部公司银行账户按截图调整（币种/现金支票/支付限额/启用/创建人、账号全局唯一、备注必填、派生公司简称与日记账最新余额）；字典表统一补创建人；线上跑 `scripts/migrate_postgres_v41_account_type_bank_fields.py --apply` |
| `20260831-r7` | 08-31 | schema v40 菜单重构+特定字段规则字典：目录按 基础资料（含特定字段规则子组）/商品管理/客户与供应商/客户联系/数据查询/不确定用途暂放 重组，改名与下线（供应商开票资料）全落地；新增 10 张统一结构字典表（名称+编码+排序+启用+备注）、内部公司银行账户、采购申请单(+明细)、库存查询/临期/组装/拆分/调整只读视图；线上库跑 `scripts/migrate_postgres_v40_field_rule_dicts.py --apply` |
| `20260831-r6` | 08-31 | 单位客户防重与名称显示口径：单位客户（层级顶点）此前两条防重键全因空值跳过、曾建出第二个「苏州大学」——现按**名称全局防重**，同名单位新增/改名拒绝（个人/课题组仍可重名）；客户名称不再括号拼所属单位/课题组文本（下拉标签与回复同口径，同名靠尾部 ID 区分）；建单位前先按名称查重复用（无 schema 迁移） |
| `20260831-r5` | 08-31 | 版本号对齐重切（内容与 r3 完全一致）：昨天发到 20260830-r4 后今天切到 r3 尾号回退、升级提示观感变差，跳号重切为 r5 恢复递增；变更内容见下方 r3 行（客户类型必填+三层挂靠硬规则） |
| `20260831-r3` | 08-31 | 客户类型必填+三层挂靠硬规则：`customer_kind` 新增必填且**必须由用户明确给出**（个人客户/课题组（科室）/单位），AI 不再自行识别类型；个人客户挂课题组（必须是课题组类型已有客户，且该课题组已挂单位）、课题组挂单位（必须是单位类型已有客户，不能挂课题组）、单位是顶点不能挂上级；挂靠对象必须先建好（建档顺序 单位→课题组→个人）；课题组必填 `organization` 文本的 v31 规则退役；触碰类型/挂靠的修改走全量规则、存量改无关字段不强制补录（无 schema 迁移） |
| `20260831-r2` | 08-31 | schema v39：`business_image.biz_type` 白名单加入 `feature_request`（管理台「需求提报」页附件挂载，记录本体在平台库，业务库只登记图片行）；线上库跑 `scripts/migrate_postgres_v39_feature_request_images.py --apply`；`migrate_schema` 基线升 v39、`business-schema.sql` 同步；用例数 414→418（`test_migration` 断言升 v39，分发副本测试自 v36 起落后已对齐） |
| `20260831` | 08-31 | 外键值按显示名自动解析（平台修复配套，无 schema 迁移）：`business_data` 行级写入外键字段 ID 未命中时按显示名大小写不敏感唯一匹配自动换 ID，多条同名报错列出候选（名称+ID）改传 ID；客户主数据录入口径补齐——新增客户用 `business_data_row_create`（表名 `customer`、客户名称填 `name`）；内部人员表 `name` 存拼音（如 YangXiaoYi）大小写不限，中文姓名匹配不到时先 `business_data_rows` 查内部人员表确认准确名称；unified agent（jidan_run）提示词同口径钉死，`_entry` 报错带实际表名 |
| `20260830-r4` | 08-30 | 内部公司唯一名称硬校验（schema v38）：「公司名称」与「简称」各自全局唯一（含停用记录占名）——新增/改名/Excel 导入三路应用层预检（报错带列名与冲突值）+ 唯一索引 `uq_internal_company_name` / `uq_internal_company_short_name` 兜底；线上库跑 `scripts/migrate_postgres_v38_internal_company_unique.py --apply`（生产表当前 0 行无存量重名） |
| `20260830-r3` | 08-30 | 整体销售折扣接入自动取价（拍板：特殊价格优先、整体折扣兜底）：取价链 7 级扩为 8 级，第 5 级新增客户整体销售折扣（商业条款 `sale_discount_rate` 沿层级就近取，售价=目录价×折扣，不与特殊价格叠加；目录价缺失跳过）——特殊价 95 折的商品按 95 卖，未覆盖商品按整体 9 折卖；`price_source` 新类型 `term_discount`；管理台明细手工填价不受影响 |
| `20260830-r2` | 08-30 | 客户模型收口+订单检索口径（无 schema 迁移）：三层客户中**只有个人客户（person）是对外客户**——`search-customers` 只回 person 且不搜联系人表；`capture_order` 拒绝课题组/单位客户下单；`list-orders` 客户维度三层匹配（人名/挂靠课题组/所属单位，带 `customer_group_name`），新增 `receiver_query` 显式收件检索（仅用户明确说“收件信息包含…”时用）；管理台客户下拉默认只回 person（`customer_kind=all` 取三层，开票资料/条款表例外），客户页默认只显示个人客户；开票资料可挂任意一层、解析沿 person→课题组→单位 就近取 |
| `20260830` | 08-30 | 唯一名称硬校验（schema v37）：外部开票资料「开票名称」（`title`）全局唯一（停用记录也占名）——新增/改名/Excel 导入三路应用层预检（报错带列名与值）+ 唯一索引 `uq_invoice_profile_title` 兜底；供应商名称唯一补齐修改路径——改名撞名从数据库含糊报错改为同一条自然键预检（「修改前整行+补丁」合成、排除自身）；SKILL.md 新增《外部开票资料》维护段（v34 必填口径 + v37 唯一口径）；线上库先跑 `scripts/migrate_postgres_v37_unique_names.py --apply`（存量重名会拒绝应用，先在管理台合并/改名） |
| `20260829-r8` | 08-29 | 核销桥（schema v36）：订单/发票开具日记账/银行存款日记账三方核销——新增 `payment_invoice` 收款↔发票分摊（负数=红冲，方向/上限双校验）；`journal_claim` 把日记账行 1:1 认领内部发票/收付款单或一键生成；两本账 是否匹配订单/是否匹配发票/收款金额 改为系统按分摊派生（`journal-update-match` 对这两类拒绝手工改）；`match-candidates` 给核销候选建议（只查询不落账）；作废/红冲前必须清空核销分摊；管理台同口径（收付款核销发票表、订单/发票已收已开票派生列、状态列只读）；线上库先跑 `scripts/migrate_postgres_v36_writeoff_bridge.py --apply` |
| `20260829-r7` | 08-29 | 销售订单规格表落地（无 schema 迁移）：订单编号改 `S+年年月月日日+四位序号`（S2608290001 起按天计数，旧 XS- 编号不改写）；主表默认随客户继承（客户开票抬头/结算方式沿层级就近继承且按单可手改、确认不覆盖/送货信息按「客户名称，电话，地址」拼接/业务员/订单日期当天）；我方销售抬头只认内部公司简称；补结算订单必带补结算关联原订单号；明细 7 级自动取价（约定单品/品牌折扣四级 > 历史该客户同商品售价 > 商品特殊销售价 > 商品常规销售价）、税率随客户开票抬头继承外部开票资料、折扣=单价÷目录价四位、含税金额=数量×单价两位、是否开票默认是、库存数量快照常备库存；订单总额自动=Σ明细含税金额（未取价留空、存量不回溯）；抓单带 prompts 软提示；correct 扩展 settlement_method/订单类型/开票抬头与明细折扣税率含税金额并联动重算总额；管理台同口径且结算方式快照列放开编辑 |
| `20260829-r6` | 08-29 | 客户信息表规则落地（schema v31）：客户编号留空自动生成（CLA00001 起累加，A 段用完进 B 段，存量客户已按创建时间补号）；默认税率留空默认 1%；个人客户新增必填 常用开票抬头/客户分类/业务员/所属课题组、课题组必填所属单位（软必填，修改只拦清空、存量豁免）；名称+课题组组合唯一；结算方式收进客户表 `settlement_method`（沿层级就近继承，确认订单冻结快照，条款表不再受理 settlement_method）；电话/地址留空保存前确认；课题组所属单位前后不一致提示核对。线上库先跑 `scripts/migrate_postgres_v31_customer_settlement_code.py --apply` （并携带 v32 常备库存重构 `migrate_postgres_v32_regular_stock.py --apply`） |
| `20260829-r5` | 08-29 | 内部公司信息表规则落地（schema v30）：新增必填「收件三列」——收件人（`receiver_name`）/联系电话（`contact_phone`，收件人的电话，与注册电话是两个字段）/收件地址（`receiver_address`）；简称、纳税人类型、发票税率、统一社会信用代码、注册地址、注册电话、开户行及银行账号收紧为必填（空白字符串等同未填，新增/编辑/Excel 导入同口径）；开票限额标签改「开票限额（元）」（单位元，旧表头仍可导入）；SKILL.md/操作契约补内部公司表字段口径（读写走通用 `business_data_*` 工具，与管理台同校验）；线上库用 `scripts/migrate_postgres_v30_internal_company_receiver.py --apply` 升级 |
| `20260829-r4` | 08-29 | 商品表字段更名与补列（schema v29）：「商品类型」更名为「商品类别」（管理台/派生列/提示词/报错措辞同步，Excel 导入旧表头「商品类型」仍兼容）；新增可选文本字段「官网链接」（`website`，非必填、为空不询问、不继承品牌官网、不校验格式），`product-create`/`product-update` 支持录入与修改、空串按清空；线上库用 `scripts/migrate_postgres_v29_product_website.py --apply` 升级 |
| `20260829-r3` | 08-29 | 同步标记切换强制逐次确认：因修改继承字段需要把 `syncs_brand_pricing` 从「是」改为「否」时（含新增商品录入显式价格/手工折扣），必须先向用户说明后果（不再参与品牌折扣级联刷新）并获得明确同意；每次切换、每个商品单独询问，不得沿用此前确认静默切换；用户主动明确要求单独维护时除外 |
| `20260829-r2` | 08-29 | 客户特殊价格自动取价（v28 规格表消费端）：`capture_order` 明细行未显式传 `sale_price` 且已定位真实商品时，服务端自动按 约定单品价格 > 约定品牌折扣 解析——单品行有特殊价格直接用，只有特殊折扣时按 目录价×特殊折扣 计价；「仅客户本人」只覆盖挂靠客户，「本课题组/本单位」沿客户层级链向下覆盖；显式价始终优先、无命中维持留空；命中时返回明细带 `sale_price` 与 `price_source`，回复需转述取价来源。特殊价格约定在管理台「业务数据 → 客户特殊价格」维护 |
| `20260828-r3` | 08-28 | 商品品牌代入字段对齐规范「代入的不可改、未代入的可手动添加」：`product.brand_inherited_fields` 标记代入来源（迁移脚本 `migrate_brand_inherited_fields.py`）；新增时品牌没定义的代入字段可手动填写（`manual_brand_fields` 上报）；修改时锁定字段拒绝、未锁定可手填（折扣支持 `85%` 写法）；换品牌按新品牌重新代入（没值的清空解锁）；目录价/折扣变化自动重算常规价（人工价不动）；价格非负落到脚本层；`brand-discount-recascade` 覆盖折扣后重新锁定；web 管理台同步：品牌下拉、代入预览、锁定禁用、价格黄色高亮、Excel 导入同规则 |
| `20260828-r2` | 08-28 | 品牌创建补齐“为空需询问”口径：`brand-create` 的常规采购折扣、常规销售折扣、限价要求、常规交期、采购渠道（常用供应商）、截单时间、官网 7 个字段缺失时必须先一次性向用户逐项询问（用户答没有/不知道/不填后按空值提交，不反复追问）；属地（`origin_country`）改为必填枚举（进口/国产），服务端拒绝空值与非法值并提示先确认 |
| `20260829` | 08-29 | 销售侧公式对称升级：常规销售价 = 目录价 × 销售折扣率（同步商品销售折扣只继承品牌、显式销售价被拒；不同步商品自由维护但强制公式）；目录价两侧共享——价格+折扣成对反推目录价、两侧冲突拒绝，改目录价两侧价格同源重算；`reinherit_brand_discounts`/切回同步两侧同时刷新；描述性代入字段（默认交期/截单时间/厂家限价/默认供应商）不随品牌同步的商品始终可改，同步商品维持「空值可补、有值锁定」 |
| `20260828-r4` | 08-28 | 商品价格同步与公式：新增 `syncs_brand_pricing`（是否随品牌同步更新，默认是；线上库用 `scripts/migrate_sync_brand_pricing.py` 加列并分级回填，`--verify-only` 可先看同步/公式违例报告）；随品牌同步的商品采购折扣只继承自品牌（`reinherit_brand_discounts=true` 重新继承）、常规采购价恒为 目录价×折扣；不随品牌同步的商品三字段自由维护但必须满足公式（改采购价保留目录价反推 4 位折扣率，回验分位漂移按公式值覆盖）；品牌与商品折扣率统一 4 位小数；`brand-discount-recascade` 只刷同步商品（`non_sync_products_skipped` 单列）；管理台与 Excel 导入同口径 |
| `20260828` | 08-28 | 品牌折扣级联刷新 `brand-discount-recascade`（`write.brand_update` 权限）：修改品牌采购/销售折扣时同步刷新该品牌全部商品的折扣与「目录价×折扣」常规价；默认只读预览（新旧折扣、受影响商品、逐商品价格变化、无目录价与折扣被手工改过的清单），用户确认后 `confirm=true` 单事务执行；特殊采购价/特殊销售价与调整字段不受影响，停用商品默认跳过（`include_inactive=true` 可包含），历史订单价格快照不变 |
| `20260826` | 08-26 | schema v27 行级图片挂载：`upload-image`/`image-query` 的 biz_type 扩展销售出库明细、采购入库明细、发票开具/收到发票日记账（产品图片、发票图片逐行挂载）；管理台列表新增「图片」计数列，点击进查看抽屉上传/预览；线上库用 `scripts/migrate_postgres_v27_image_targets.py --apply` 升级 |
| `20260825-r3` | 08-25 | schema v26 业务图片/附件：私有 OSS 存储 + 1 小时签名 URL；新增 `upload-image`（发票/收付款/商品等对象挂图，图片或 PDF ≤10MB）与 `image-query`（MCP：`jidan_image_query`）；管理台查看抽屉可上传/预览/删除附件，送货单标签打印展示产品图 |
| `20260825-r2` | 08-25 | schema v25 整体补缺上 Skill：预收挂账与追加分摊（payment-allocate/invoice-allocate）、发票与收付款作废红冲、销售/采购退货单、报价单与转订单、费用记录、批次台账查询、组装执行登记、提成月报；单据编号自动生成（XS/RK/SH/SK/XT/CT/BJ/FY/PD）；客户信用额度与账期提示、地址簿带出收货地址 |
| `20260825` | 08-25 | v24 业务记录能力上 Skill：新增外部日记账录入/匹配状态更新/查询（`jidan_journal_query`）、采购入库单登记/查询（`jidan_purchase_receipt_query`）、销售出库明细补录、商品级开票与收付款分摊；`capture_order`/开票/收款/送货单支持规格表新字段（订单类型、开票类型、发票类型、批号、税率、折扣、赠品等）；财务/运营默认可记日记账，采购/仓管默认可登记入库单 |
| `20260824` | 08-24 | schema v24：按《业务管理类与外部来源记录数据字段说明》全量补齐——销售/采购订单及明细、开票、收付款、销售出库补齐规格字段；新建销售出库明细、采购入库（主+明细）、商品级开票/收付款分摊明细与银行存款/现金/支付宝/发票开具/收到发票 5 张外部日记账；管理台列顺序/默认可见列/标签按文档对齐，客户单位、课题组、商品编号/品牌/类型/规格、目录价等由关联带出显示；图片字段本期未建 |
| `20260823-r5` | 08-23 | schema v23：新建内部部门表、内部公司信息表；内部人员（员工档案 21 列）、客户特殊价格（范围/单品/品牌/特殊价格/折扣）、供应商特殊价格（类型/折扣）、常备库存（备注/启用/创建人/创建时间）按规格补齐；商品编号/品牌/类型/规格/单位随商品关联带出显示 |
| `20260823-r4` | 08-23 | schema v22：新建外部开票资料表（开票名称/税号/发票类型/税率/电话/地址/开户行/账号/开票要求等，挂客户），管理台新增“外部开票资料”页 |
| `20260823-r3` | 08-23 | schema v21：供应商表补齐课题组/科室/部门、常用开票抬头 2 列；管理台供应商页按规格排序，标签改为所属单位/供应商分类/主营产品/品牌/创建人等 |
| `20260823-r2` | 08-23 | schema v20：客户表补齐客户编号/常用开票抬头/客户分类/客户分级/地址/是否供应商/默认税率/备注/创建人 9 列，商品表补特殊采购价/特殊销售价 2 列；search-customers 返回编号/分类/分级 |
| `20260823` | 08-23 | 对外展示名称为主：search-customers 返回业务员姓名、status 返回客户/负责人名称、search-offers 返回商品名称、search-brands 返回常用供应商名称；SKILL.md 候选展示与回复准则改为“名称为主、真实 ID 放括号内” |
| `20260821-r8` | 08-21 | db_compat 的 PostgreSQL 参数出口统一把布尔适配为 INTEGER 0/1，修复 is_direct_ship 等布尔字段类型不匹配 |
| `20260821-r7` | 08-21 | schema v19：source_message/sales_order 的 source 约束补入 mcp，修复 MCP 通道建单被数据库拒绝 |
| `20260821-r6` | 08-21 | 管理者角色统一拥有全部业务写能力（含建单/更正/确认/结单/取消），修复企微/实验室通道 manager 建单被拒；审批与审计不变 |
| `20260821-r5` | 08-21 | 包体治理与契约一致性：权限参考补全客户条款能力并修正“唯一可增授权”表述；反伪造规则、状态机改为单一权威源（SKILL.md ↔ 操作契约去重）；“deepseek 模型”措辞改模型无关；zip 剔除 11 个服务器运维脚本（-90KB），包内测试自足验证 195 例全过；安装文档重写并去除本地路径 |
| `20260821-r4` | 08-21 | 客户条款解析新增规则：已停用祖先客户保留在层级链中但条款不再参与解析（跳过并标记 `terms_skipped_inactive`） |
| `20260821-r3` | 08-21 | 商业条款健壮性：条款按生效窗口接替（完全覆盖停用/部分重叠截断/隔断自动接续，未来生效不切断当前约定）；管理台拒绝同类型生效窗口重叠；订单条款快照字段（resolved_*）锁只读；客户名称检索大小写不敏感；客户类型（schema v18） |
| `20260820-r2` | 08-20 | 客户层级与商业条款上线（schema v17）：客户可挂上级（最多 5 层防环），折扣/结算方式按层级就近继承；`customer_effective_terms` 查询与 `customer_set_parent`/`customer_term_upsert`/`customer_term_deactivate` 写命令；`write.customer_terms` 权限；订单确认时条款快照 |
| `20260820` | 08-20 | 品牌主数据新增/停用/启用（`brand-create`/`brand-deactivate`/`brand-activate` + `write.brand_*` 权限），与 web 管理台品牌页对齐 |
| `20260819-r7` | 08-19 | 字段名称显示统一（字段名称列口径一致） |
| `20260819-r6` | 08-19 | 商品编码（SKU）全局唯一（schema v16）；品牌属地补默认值 |
| `20260819-r5` | 08-19 | 商品/品牌字段规范 2026-08-19 全量落地（schema v15） |
| `20260819-r4` | 08-19 | 品牌主数据修改（`jidan_search_brands`）；主数据汇总统计；Token 工具权限可编辑 |
| `20260819-r3` | 08-19 | 默认交付周期改为文本，品牌代入取“常规交期” |
| `20260819-r2` | 08-19 | 商品分类必填、属性默认“库存商品”、目录价自动算价（品牌折扣）、品牌 5 字段代入 |
| `20260819` | 08-19 | 商品新增补齐类字段先问后录；品牌核验与折扣继承 |
| `20260818` | 08-18 | 拜访记录修正/删除；Skill 版本自动校验（`jidan_skill_version` 升级引导机制） |
| `20260817` | 08-17 | 商品价格字段口径修复（目录价/销售价区分） |
| `20260816` | 08-16 | 拜访与客户群待回复任务升级；权限改为角色绑定 |
| `20260809` | 08-09 | 首个发布：订单运营 Skill 基础版（WorkBuddy/OpenClaw 可上传安装，远程 MCP Streamable HTTP 接入） |

> 服务端不随 Skill 包发版的修复（如 MCP 工具注册、企微链路改进）记录在服务端 CURRENT_STATUS.md，不影响客户端版本号。

## 常见问题

- **条款查询用哪个工具**：`jidan_customer_effective_terms`（客户 ID 或名称二选一）；条款设置/停用和层级调整通过 `jidan_run` 自然语言发起；
- **为什么 zip 里没有迁移脚本**：自 r5 起服务器运维脚本（数据库迁移、账号初始化）不再随客户端包分发，由服务端统一管理；
- **测试报缺少模块**：确认使用完整 r5 包，不要把旧包的 `scripts/` 与新包混用。