开发提示词：NX 按需生成服务（A 版：轻量自建队列 + run_journal）

交付对象：Claude Code。实现前请先通读本提示词 + 项目根 项目总览.md + docs\维护手册.md + 开发提示词-参数化选型引擎.md（一期，本服务的前置依赖）。实施命令以用户说"开工"为准；本文档只定义"做什么、边界在哪、怎么验收"。部署红线：本服务属于云部署范畴，服务器上线动作需用户另行明确指令，开发与本地联调不在此列。

1. 背景与目标

一期（参数化选型引擎）上线后，选型面板可生成非标准档位组合（型号编码+参数行），但无对应 STEP。用户已决策：不做批量预生成；生成按需触发，输出留存到服务器输出目录、不删除，同组合再次请求直接复用（磁盘增长 = 实际请求过的唯一组合数，天然有界）。

目标（A 版）：搭建按需生成服务——用户在网页/桌面对非标组合点击【在线生成数模】，服务器现场用 NX 无界面模式生成，输出到服务器输出目录并留存复用。请求支持单个与批量两种形态，导出支持多格式：

标准档位：继续走纯静态文件路径，不经过服务（现有架构不动）
非标档位：下载按钮从"置灰"升级为【在线生成数模】→ 请求 → 队列 → NX 生成 → 输出目录 → 下载
单个生成：结果行单组合 → 一个任务 → 一个型号的全格式文件
批量生成：购物车打包时清单含非标条目 → 一次性提交全部非标组合 → 一个批量任务（单 worker 单会话顺序处理）→ 全部完成后打包下载
输出目录：output\<系列>\<型号编码>\，每次生成写入全部格式文件；已存在则该组合直接命中复用，不重复生成、不删除
多格式导出（每型号一套）：STEP(AP214) + Parasolid(.x_t) + IGES + STL；JT / 3D PDF 列为可选升级
不做：Teamcenter Dispatcher（B 版，跑顺后再评估）、主动预生成入库、账号体系

2. 前置依赖与边界

前置依赖 = 一期参数化选型引擎已上线（本服务消费一期产出）：

meta.json 规则包（参数域/规则/型号编码模板）→ 服务端二次校验请求参数的依据
非标组合的概念与 UI 徽标、统一文案基础
注意衔接：一期验收标准里"非标下载置灰"是过渡态，本服务上线后按钮升级为【在线生成数模】，两端一致

做：GenServer（HttpListener 轻量后端）+ 文件队列 + 常驻 NX worker（循环 journal）+ 两端接入 + 输出目录留存复用 + 限流/日志 + 母模工作目录规范 不做（v1 明确排除）：TC 检出与版本追溯（升级项）、Part Families 标准化（升级项）、Dispatcher（B 版）、主动预生成入库、用户账号/支付；标准档位多格式化（升级项：维护端批量导出时顺手出多格式） 购物车联动（v1 含）：清单含非标条目时，打包流程先走批量生成、成功后正常打包（不再跳过）；非标型号打包为型号子文件夹多格式结构

3. 系统架构

网页/桌面  ──HTTP──▶ GenServer(HttpListener, net48)
   非标组合+签名            │
                    参数二次校验(同一份规则JSON)
                            │
             检索输出目录(命中即返回, 不生成)──▶ output\<系列>\<型号>\
                            │ 未命中
                     文件任务队列(jobs\ 目录, 容量上限)
                            │
        ┌───────────────────┼──────────────┐
   NX worker 1      NX worker 2   ...  NX worker N   ← 常驻进程, 每进程1席位
   认领前再检索 → 拷母模副本 → 设表达式 → 更新 → 导多格式 → 写输出目录
                            │
                    结果轮询API(任务号) ──▶ 下载(全格式zip / 批量打包)

检索先行（每次生成前必做）：GenServer 入队前按 output\<系列>\<型号编码>\ 检索输出目录——命中（目录存在且 exports 配置的全格式文件齐全）则直接返回已输出文件，不生成、不进队列；worker 认领任务后再查一次（防并发窗口重复生成）；未命中才真正触发 NX。

组件规格：

GenServer：csc 编译的 net48 控制台程序，HttpListener 自托管（与桌面端 LocalViewerServer 同技术路线，无新运行时依赖）。接口：
- POST /gen — 入参 {series, params, code} → 校验 → 检索输出目录（命中直接返回） → 写队列 → 返回 {jobId}
- POST /gen-batch — 批量：入参 {items: [{series, params, code}...]}（上限如 50 项）→ 逐项校验（任一非法整单拒绝）→ 逐项检索输出目录（命中项免生成） → 未命中项写一个批量任务 → 返回 {jobId}；状态接口附带逐项进度 {done, total, failedItems}
- GET /status?job=<id> — 返回 {state: queued|running|done|failed|timeout, filesUrl?, error?}
- GET /file?job=<id>&token=<一次性token> — 下载该型号全格式 zip
- GET /health — 存活探测
文件任务队列：jobs\ 目录，每任务一个 job_<id>.json（单个任务或批量任务，含参数、母模路径、表达式映射快照）。容量上限按任务计（如 200），超限返回"队列繁忙"文案。任务状态持久在 job 文件里（崩溃可查）。
NX worker（常驻，推荐）：每个席位一个进程，run_journal.exe worker_journal.vb <worker号> 循环：轮询 jobs\ → 认领前对该任务逐项检索输出目录（命中项跳过） → 认领（原子改名/标记）→ 处理 → 写结果文件 → 继续。进程守护：GenServer 或计划任务检测 worker 心跳文件，死了自动重启。
- 批量任务 = 单会话顺序处理：同一 worker 会话内逐项"打开副本→设参→导出→关闭"，复用会话避免每项冷启动；同一系列的项共用一份母模副本（副本从不保存，只导多格式，可安全复用）；跨系列则各拷一份
- v0 备选（更简单）：每任务直接 spawn run_journal 单发 journal——注意 NX 会话启动 ~30-60 秒/次，用户体验差，仅用于联调
生成 journal 要点：
- 打开母模前必须先拷贝母模到任务私有目录再打开（NX 文件锁会排他，多 worker 并发打开同一 .prt 必冲突）
- 按 masters.json 的表达式映射逐项设置表达式；任一设置失败 → 任务失败并写明原因，禁止静默跳过
- 按 masters.json 的 exports 配置逐格式导出：STEP(AP214)/Parasolid(.x_t)/IGES/STL（NX 均有对应导出 API），全部写入该型号输出子文件夹
- 写入状态文件（journal 内 try-catch，不要只依赖 exit code）
输出目录与残留清理：生成结果写入 output\<系列>\<型号编码>\ 留存不删除；清理仅针对任务私有工作副本（母模拷贝等中间物，任务完成后删除，兜底 TTL 2 小时）；jobs 日志按天滚动。输出目录磁盘增长 = 实际请求过的唯一组合数，容量监控/归档属部署决策。
安全：API Key 校验（请求头）+ 每 Key 限流（如 10 次/分钟，超限返回统一文案）+ 参数全量规则校验（不信任客户端）+ 请求日志。v1 不需要账号体系。
两端接入：
- 网页：静态站配置 GEN_API 基址（config.js，默认空 → 按钮维持一期置灰态，优雅降级）。非标组合显示【在线生成数模】→ 提交 → 轮询（间隔 3 秒，断线重连）→ 完成自动下载全格式 zip
- 购物车批量打包联动：打包时清单含非标条目 → 先提示"清单含 {n} 个非标档位"→【生成后打包】提交 /gen-batch → 逐项进度（{done}/{total}）→ 全部成功按原 zip 逻辑打包（非标为型号子文件夹多格式）；部分失败 → 成功项打包 + 失败清单提示可重试
- 桌面：同按钮同文案同流程（联网探测：服务不可达按断网处理）；断网 → 置灰 + "需联网生成"提示。GenServer 地址由维护入口配置、随 .opc 发布
母模工作目录（v1 文件型）：服务器上 catalog-masters\<系列>\<母模>.prt，由维护人员从 Teamcenter 导出"已发布"母模同步至此（人工/robocopy）。TC 自动检出+版本写入 STEP 属性为升级项。

4. masters.json（服务器侧新文件，不进客户包）

{
  "KC": {
    "masterPart": "KC_master.prt",
    "expressionMap": { "bore": "BORE", "stroke": "STROKE", "mount": "MOUNT_TYPE" },
    "exports": { "step": "214", "parasolid": true, "iges": true, "stl": true },
    "timeoutSec": 300
  }
}

exports 支持全局默认 + 按系列覆盖；STL 精度沿用网格管线经验（0.5mm 量级，可配）
命中判定：output\<系列>\<型号编码>\ 目录存在且 exports 配置的全部格式文件齐全
表达式名由用户按 NX 母模实际命名确认；生成服务只认这张表
缺映射的参数（如影响不到几何的选项）可不列，生成照常

5. 验收标准（11 条，全部通过才可部署）

端到端正确性（单个）：网页非标组合（如 KC 系列 stroke=87）点【在线生成数模】→ 下载 zip → 在 NX 中打开 STEP 核对缸径/行程与请求一致（用户侧确认）
批量生成端到端：购物车含 3 个非标条目（跨系列）→ 一次提交 → 逐项进度 → 全部成功后打包 zip（标准档位 STEP + 非标型号子文件夹多格式）且各文件与请求参数一致；含 1 个非法项时整单拒绝
部分失败可重试：批量中 1 项生成失败 → 成功项正常打包、失败项明确列出并可单独重试
检索先行与留存复用：生成结果写入 output\<系列>\<型号编码>\ 且不删除；同一组合第二次请求不触发 NX（观察无进程活动）直接返回已输出文件
多格式完整：每型号输出 STEP/Parasolid/IGES/STL 四格式，文件可各自打开验证
双端一致：桌面联网时与网页同按钮同文案同行为；断网置灰+提示（红线：两端 UI 无差异）
服务端校验：非法组合（越界/违背规则/不存在的系列）被拒绝，不进入队列，不触达 NX
限流：高频请求触发限流文案；日志可查
并发与排队：worker 数 = 席位上限，超出排队；队列满返回"队列繁忙"统一文案（按任务计）
失败与重试：生成失败/超时返回统一文案+可重试；worker 崩溃自动重启，任务不丢（重入队列）
回归零影响：标准档位全部不经服务、行为不变；一期验收项（对拍门禁/组合爆炸保护/31 项 selftest）全过

6. 陷阱清单（12 条）

NX 母模文件锁：多 worker 并发打开同一 .prt 会排他冲突——必须"拷贝副本再打开"（§3 组件 4）
run_journal 启动开销：每任务 spawn 一个 NX 会话 30~60 秒——v1 用常驻轮询 worker，别走每任务冷启动
journal 错误捕获：状态文件必须在 journal 内 try-catch 写入，exit code 不可靠
表达式设置静默失败：设参失败必须判失败并写明，否则交付错误几何
中文路径：服务器工作目录全部英文路径（NX 对中文路径敏感，项目已有教训）
编码：编辑含中文的 .cs/.vb/.ps1 后跑 sample-data\tools\fix-bom.ps1；journal 文件 BOM 手工恢复（fix-bom 不覆盖 .vb 的坑）
任务幂等：认领/完成必须原子操作（文件改名），防止双 worker 抢同一任务
队列有界：jobs 目录容量上限 + 状态表有界，防止磁盘/内存被刷爆
下载 token 一次性：/file 用一次性 token，防止链接外传；下载完成才清理
网页轮询健壮性：轮询断线重连、页面关闭不报错；生成中按钮防重复提交
桌面联网探测："服务不可达"与"断网"同文案处理，不弹错误框
与一期验收衔接：一期"非标置灰"验收项在本服务上线后升级——发布门禁脚本同步更新，别两头打架
批量会话复用脏副本：同系列共用的母模副本绝不能保存（journal 禁 Save）——误存一次，后续所有项都基于脏几何导出
批量部分失败处理：单项失败不得中止整批，记录 failedItems 继续；失败项可单独重试，状态文案一致
输出目录并发写冲突：同型号并发请求（两个用户同时生成同一组合）——按型号原子写（写临时名再改名落位），半成品文件绝不可被下载接口看到

7. 两端统一文案表（zh / en 同源，走 _lang.T/t 双语文案）

场景	中文	English
生成按钮	在线生成数模	Generate 3D model online
生成中	正在生成数模，预计 10–60 秒…	Generating — typically 10–60 s…
排队中	生成队列繁忙，前面还有 {n} 个任务	Queue busy — {n} task(s) ahead
生成失败	生成失败，请重试或联系销售	Generation failed — retry or contact sales
生成超时	生成超时，请重试	Generation timed out — retry
断网/不可达	需联网生成，请连接网络后重试	Internet required for generation
参数无效	请求参数无效	Invalid parameters
限流	请求过于频繁，请稍后再试	Too many requests — try again later
多格式下载	下载全格式压缩包（STEP/Parasolid/IGES/STL）	Download all-format zip (STEP/Parasolid/IGES/STL)
批量提示	清单含 {n} 个非标档位，将在线生成后打包	{n} non-standard item(s) — will be generated before packaging
批量生成按钮	生成后打包	Generate & download zip
批量进度	正在生成 {done}/{total}…	Generating {done}/{total}…
批量部分失败	{n} 项生成失败，其余已打包；失败项可重试	{n} item(s) failed — the rest are packaged. Failed items can be retried.

8. 成本与部署（决策要点，仅分析）

大头 = NX 授权席位：每并发 worker 1 席位，公司现有 NX 可复用；席位少 → 队列深
服务器：Windows Server 一台（CPU/RAM 按席位数量配，每 NX 进程数 GB 内存）
部署位置（内网/公网反代）与公网域名/证书属上线决策，需用户另行指令
开发量：中小型功能（GenServer + journal + 两端接入），约购物车功能量级

9. 交付物

GenServer 源码与编译脚本（tools\build.ps1 增项）+ 启动/守护脚本
worker_journal.vb（常驻轮询生成）+ 单发 journal（联调用）
masters.json 模板 + KC 系列示例（表达式名由用户确认后填）
网页端接入（config.js 基址 + 非标按钮/轮询/多格式 zip 下载 + 购物车批量生成打包联动，style.css 样式）+ 桌面端接入（联网探测/按钮/轮询/购物车联动，MainWindow）
本地联调说明（docs\维护手册.md 增补章节）+ 项目总览.md 回写进展
升级路线备注：TC 检出与版本追溯、Part Families、Dispatcher（B 版）评估、JT/3D PDF 导出、标准档位多格式化

15 KiB Raw Blame History Unescape Escape