diff --git a/furniture-3d-system/docs/workflow/生产部署入口说明.md b/furniture-3d-system/docs/workflow/生产部署入口说明.md index 6e1ff52f..24c08ed7 100644 --- a/furniture-3d-system/docs/workflow/生产部署入口说明.md +++ b/furniture-3d-system/docs/workflow/生产部署入口说明.md @@ -36,6 +36,7 @@ - 生产应用内部接口密钥继续从 `/opt/furniture-3d-system-prod/shared/.env` 的 `HR_SYNC_SECRET` 读取。 - 人员信息表的钉钉组织同步使用 `furniture-3d-system/scripts/install-dingtalk-directory-sync-timer.sh`，生产 systemd 名称为 `furniture-dingtalk-directory-sync.service` / `furniture-dingtalk-directory-sync.timer`。 - 钉钉同步每天 `03:00` 执行一次，读取生产共享 `.env` 中的 `DINGTALK_API_CLIENT_ID` 和 `DINGTALK_API_CLIENT_SECRET`，并自动更新人员信息；正式页面仍保持只读。钉钉网页登录使用独立的 `DINGTALK_LOGIN_CLIENT_ID`、`DINGTALK_LOGIN_CLIENT_SECRET`，两组凭据不能混用。 +- 人员信息的每日更新口径：钉钉新人自动新增一行；在职人员按钉钉更新部门/负责人；人工覆盖（manualOverride）的行保持不变；**离职人员不做删除，只在页面把「在职状态」变为离职**（方案 B：先比对上一轮在册且本轮抓取范围内消失的人，再逐个调 `user/get` 确认 60121 用户不存在才标记；抓取人数明显缩水时整轮跳过并写入告警）。 - 首次部署后需在正式服务器执行该安装脚本，并手动执行一次 `npm run sync:dingtalk-directory:apply` 完成首次填充；后续由 systemd 每日执行。 ## BOM 成本参考镜像 @@ -53,6 +54,19 @@ - 准确度回测：`npm run backtest:bom-cost-reference -- --sample-size=30`，只读最新成功镜像，不访问上游；样本限制 20 至 50 个，任一可比较 SKU 超过固定 10% 误差门槛即失败。 - 迁移、真实同步、安装/启用定时器和生产回测都必须另行获得生产操作授权；部署代码本身不代表这些动作已经执行。 +## 商品 SABC 月度核算 + +- 核算命令：`npm run run:product-sabc -- --year=2026 --month=8 --mode=APPLY --confirm=run-product-sabc`；试算（只算不写库）用 `--mode=PREVIEW`，末尾加 `--skip-if-exists` 可跳过已生成月份。 +- 8 月人工表对账命令：`npm run compare:product-sabc-xlsx`，默认读取本机下载的人工工作簿；生产执行前应先完成产品全量档案日销售数据同步。 +- 生产定时器安装脚本：`furniture-3d-system/scripts/install-product-sabc-timer.sh`。 +- 生产 systemd 名称：`furniture-product-sabc-monthly.service` / `furniture-product-sabc-monthly.timer`。 +- 默认调度：每月 3 日中国标准时间 `03:00`，附带最多 10 分钟随机延迟；服务生成上一个自然月的数据，已生成过则跳过（不覆盖管理员的重算结果）。 +- 生成即冻结：每次生成会把整行明细写入 `SupplyChainProductArchiveSabcResult.snapshot`，页面、筛选下拉、导出和经营总览都只读取该快照。生成之后档案的销售状态、人员字段等变化都不会再改变已生成月份的数据。 +- 重新生成（页面「执行核算」）仅限管理员（`ADMIN` / `SUPER_ADMIN`）；其他账号只能查看冻结结果。本地一键刷新 `node scripts/local-sync-archive.mjs` 在每月 3 日前会跳过 SABC 步骤，需要立刻重算时用 `--force-sabc`。 +- SABC 的销售收款总金额、真实业绩、发货件数、商品毛利额和售后金额统一读取 `SupplyChainProductArchiveSalesPerformanceDaily`，与产品全量档案页面保持同一月度口径。 +- 首次安装生成权限为 `600` 的 `/opt/furniture-3d-system-prod/shared/product-sabc-timer.env`，默认 `PRODUCT_SABC_TIMER_MODE=APPLY`；如需先观察可临时改为 `PREVIEW`（只试算不写库、不冻结）。 +- SABC 自动任务只读取现有 `DATABASE_URL`；上游日销售同步任务继续使用 `JST_REPORT_DB_*`，凭据不写入定时器配置。安装、迁移、首次 APPLY 和生产核算都需要单独授权。 + ## 操作日志保留策略 - 清理脚本：`npm run db:cleanup-operation-logs` 默认只做 dry-run；只有显式传入 `--apply --confirm=cleanup-operation-logs` 才会删除数据。