furniture-3d-system-Wu/furniture-3d-system/docs/workflow/生产部署入口说明.md

生产部署入口说明

适用范围：furniture-3d-system 当前生产部署入口核对。

这份文档只记录非敏感入口与核查口径，不保存密码、密钥、数据库连接串或对象存储密钥。

权威生产目标

• SSH 入口：root@ltai5tdb2ogyj59fquyedh.yydd.ai
• SSH 端口：60022
• 生产部署目录：/opt/furniture-3d-system-prod
• PM2 进程名：furniture-3d-system-prod
• 应用本机端口：3001
• 默认部署来源：origin/main

本仓库部署脚本

• 首选入口：仓库根目录 scripts/deploy-yydd-prod-from-git.ps1
• 底层打包脚本：仓库根目录 scripts/create-yydd-prod-deploy.ps1

执行部署或生产核查前，优先读取上面两个脚本的当前默认参数，并在远端实时确认当前 PM2 进程、current 软链接和健康检查结果。部署入口默认从 origin/main 取代码，发布前必须核对远端 refs/heads/main 和本地 origin/main 是否一致。

底层发布流程会执行依赖安装、prisma generate、迁移、构建、PM2 重启和健康检查。因此生产发布前必须先确认迁移目录、迁移历史和主数据 strict 巡检口径没有分叉。

只做生产/目标库地基核查时，优先在远端应用目录执行 npm run db:foundation:audit:production-readonly。该命令不事务回放治理迁移 SQL，只通过只读迁移状态和质量查询生成 .master-data-audits/foundation-production-readonly-current/manifest.json，适合把脱敏 summary 或 manifest 交回主线收口。拿到 manifest 后，用 npm run db:foundation:verify-production-readonly -- --manifest <manifest.json> 做机器验收；只有 accepted: true 才能把这份证据计入生产级地基收口。

花名册同步

• 花名册同步属于当前 furniture-3d-system 自有能力，不依赖 shujuku2 或旧入口机。
• 项目默认命令：npm run sync:employee-directory 只做 dry-run，不提交同步载荷。
• 真实同步命令：npm run sync:employee-directory:apply，生产 systemd 脚本必须显式使用 --apply。
• 生产定时器安装脚本：furniture-3d-system/scripts/install-employee-directory-sync-timer.sh
• 生产 systemd 名称：furniture-employee-directory-sync.service / furniture-employee-directory-sync.timer
• 定时频率：每天 03:00 和 15:00。
• 源库连接信息只允许放在生产本地 /opt/furniture-3d-system-prod/shared/employee-directory-sync.env，不能写入 Git 或共享文档。
• 生产应用内部接口密钥继续从 /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，两组凭据不能混用。
• 首次部署后需在正式服务器执行该安装脚本，并手动执行一次 npm run sync:dingtalk-directory:apply 完成首次填充；后续由 systemd 每日执行。

BOM 成本参考镜像

• 用户核算请求只读取本地 PostgreSQL 镜像，不在请求中连接上游 rpt.pm_bomBaseInfo。
• 低压只读预检：npm run sync:bom-cost-reference -- --dry-run --max-pages=2；默认单连接、每页 100 行、完整页之间等待 250ms。
• 真实同步必须显式传 --apply、固定确认词、目标 PostgreSQL 身份和来源 SQL Server 身份；上游登录必须是 report_reader，app_writer 会被程序拒绝。
• 生产定时器安装脚本：furniture-3d-system/scripts/install-bom-cost-reference-sync-timer.sh。
• 生产 systemd 名称：furniture-bom-cost-reference-sync.service / furniture-bom-cost-reference-sync.timer。
• 默认调度：每天中国标准时间 02:00，附带最多 10 分钟随机延迟；安装时可通过非敏感环境变量调整。
• 上游连接继续只使用生产共享 .env 中现有的 JST_PLANNING_SQLSERVER_* / report_reader；不在第二个文件中重复保存密码。
• 首次运行安装脚本只会创建权限为 600 的 /opt/furniture-3d-system-prod/shared/bom-cost-reference-sync.env 门禁与限速模板；目标/来源身份未填齐或现有只读配置不完整时拒绝安装定时器。
• 本地参考行只保留最新成功批次，避免每日约 76 万行无限增长；历史场景在自己的明细快照中保留来源行、指纹、单价、规则和原始计算依据，不依赖旧镜像行回查。
• 镜像新鲜度按最新成功批次的完成时间判断。上游当前可见的创建时间只作审计展示，不能用来判断当天同步是否过期。
• 准确度回测：npm run backtest:bom-cost-reference -- --sample-size=30，只读最新成功镜像，不访问上游；样本限制 20 至 50 个，任一可比较 SKU 超过固定 10% 误差门槛即失败。
• 迁移、真实同步、安装/启用定时器和生产回测都必须另行获得生产操作授权；部署代码本身不代表这些动作已经执行。

操作日志保留策略

• 清理脚本：npm run db:cleanup-operation-logs 默认只做 dry-run；只有显式传入 --apply --confirm=cleanup-operation-logs 才会删除数据。
• 自动清理范围严格限定为 OperationLog 中 SYSTEM + SUPPLY_CHAIN_PRODUCT_ARCHIVE + details.kind=UPDATED + SUCCESS 且创建时间早于 30 天的字段变更。
• 用户操作、商品档案导入、失败/重试日志及其他业务范围日志至少保留 365 天；本次策略不自动删除超过 365 天的审计日志。
• 生产安装入口：furniture-3d-system/scripts/install-operation-log-retention-timer.sh。
• 生产 systemd 名称：furniture-operation-log-retention.service / furniture-operation-log-retention.timer，默认每天中国标准时间 04:30 执行，附带最多 10 分钟随机延迟。
• 安装脚本会在 /opt/furniture-3d-system-prod/shared/operation-log-retention.env 保存权限为 600 的数据库身份门禁和非敏感参数；身份未填写或保留天数不是 30 天时拒绝启用。
• 首次启用前必须先在生产执行 dry-run，核对候选数量、数据库身份和 systemd 落点；生产安装、首次 --apply 和后续代码部署均需另行获得授权。

明确排除

• 192.168.58.20 不是当前 furniture-3d-system 的生产部署目标。
• 本机泛别名 prod 不能作为当前项目生产服务器判断依据。
• 旧 gongxiangp2 / youyidian-3d-material 的生产或 FreeNAS 信息不能直接套用到当前项目。

最小核查口径

生产相关动作开始前，至少确认：

1. 目标主机是 ltai5tdb2ogyj59fquyedh.yydd.ai:60022。
2. 远端存在 /opt/furniture-3d-system-prod。
3. PM2 中存在 furniture-3d-system-prod。
4. 应用监听端口是 3001。
5. 部署来源是 origin/main，且远端 main 和本地 origin/main 一致。
6. 生产只读地基核查优先使用 npm run db:foundation:audit:production-readonly。
7. 生产只读 manifest 回传后，使用 npm run db:foundation:verify-production-readonly -- --manifest <manifest.json> 验收，不能人工挑几个字段就宣称生产通过。
8. 不把密码、密钥或连接串写入 Git、文档或长期记忆。

部署后核查

部署后不能只看公网 /api/health。至少补核：

• 远端 REVISION 或当前发布目录 commit。
• pm2 describe furniture-3d-system-prod。
• 应用端口 3001 是否监听。
• 最近错误日志是否有启动失败、数据库失败、对象存储失败。
• https://cp.jiansun.vip/api/health。
• 关键页面：首页、产品资料、仓库质检、非集成详情或本次改动涉及页面。