aps-agent/docs/round-69-beihai-shipyard-synthetic-dataset-work-plan.md

Round 69 工作计划：北海造船场景高拟真 SYNTHETIC APS 数据包

日期：2026-08-03

1. 目标与真实性边界

在当前仓库直接实现一个可重复执行的 Python 数据生成器，并生成完整目录 beihai-shipyard-aps-data/。数据用于 APS 开发和验证，严格声明：

• datasetType = SYNTHETIC
• organizationScenario = BEIHAI_SHIPYARD_APS
• timezone = Asia/Shanghai
• generatedFor = APS development and validation
• dataDisclaimer = 模拟数据，不代表北海造船真实业务数据
• 项目、人员、供应商、船东及全部业务参数均为模拟，不得表述为北海造船内部 ERP/MES/PLM/WMS/SRM/QMS 数据。

2. 交付范围

2.1 生成器与 CLI

新增 server/shipyard_synthetic/ 包和 scripts/generate_beihai_shipyard_aps.py，支持：

• 固定随机种子，默认 20260901；
• --scale small|standard|full，默认 full 满足附件最低规模；
• --project-count 1..4；
• --output；
• --incremental：确定性业务 ID 不复用，以内容哈希跳过未变化文件；删除语义使用 tombstone/status，不静默复用旧 ID；
• --scenario baseline|material-delay|crane-failure|dock-delay|design-change|all；
• --validate-only；
• JSON、CSV、统一 world.json、统计和校验报告。

2.2 数据域

完整覆盖：

1. 四个 BH-SYN 船舶合同/项目与 18 类里程碑；
2. 项目→专业→区域→总段→分段→托盘/区域工作包→生产任务→工序 WBS；
3. 图纸与工程发布、EBOM/PBOM/MBOM；
4. 物料、替代料、库存、分配、计划收货、齐套；
5. MAKE/BUY/OUTSOURCE/STOCK 分类和净需求明细；
6. 工艺路线、前后置、工序资源/技能/质量要求；
7. 组织、车间、工作中心、设备、船坞、码头、胎架、堆场、涂装房、起重机、运输、班组、人员、日历与班次；
8. 生产工单、采购建议、委外建议、有限能力排产、资源负荷、瓶颈、冲突、KPI；
9. MES 模拟下发/报工、领料、质量检验、不合格和返工；
10. baseline 与 4 个异常场景、局部重排和方案对比；
11. 20 个船舶 APS Skill manifest 与 schema；
12. 20 类以上 SYNTHETIC RAG 知识资产和 evidenceRefs；
13. expected 结果、完整性/约束/质量报告和数据字典。

2.3 最低 full 规模

• 4 项目、72 里程碑；
• 280 分段、72 总段、1,000 工作包、4,000 WBS 生产任务；
• 12,000 物料、50,000 BOM 行；
• 220 工艺路线；
• 2,400 生产工单、12,000 工序、12,000 排产槽位（4 艘船各 3,000 道工序，解决附件局部/全局规模交集）；
• 150 设备资源、60 班组、40 供应商；
• 550 采购建议、140 委外建议；
• 180 风险/冲突记录；
• 120 RAG 知识条目（20 类各至少 6 条）。

3. 架构与算法

• 生成器完全确定性：稳定 ID、稳定排序、固定基准日 2026-09-01，不使用当前时间进入业务内容。
• world.json/领域 JSON 是规范模型，CSV 为同版本的确定性投影；领域记录以 DatasetBundle 聚合，CSV 表由单一 table registry 导出；
• BOM 展开与净算输出 gross / stock / releasedAllocation / plannedReceipt / substitute / safetyStock / scrap / netRequirement 明细；供应语义拆为 sourcingMode=MAKE|BUY|OUTSOURCE|OWNER_SUPPLIED 与 fulfillmentMode=STOCK|TRANSFER|PLANNED_RECEIPT|NEW_SUPPLY|DESIGN_PENDING；
• MAKE 必须绑定 routing，BUY/OUTSOURCE 必须绑定供应商或进入显式风险；
• baseline 采用滚动时域瓶颈启发式 + RCPSP 风格资源序列：按项目优先级、里程碑、物料可用日、前置工序和资源能力排入唯一资源时间轴；
• 船坞、码头、胎架、涂装房、起重机为独占资源；尺寸/重量、技能、日历、Hold Point 为硬约束；
• 多方案固定为 7 类：交期优先、资源均衡、成本优先、加班最小、船坞优先、风险最小、综合推荐；输出算法、输入摘要、约束数、求解状态、时间、gap、软代价、归一化方法、降级原因和证据；
• 生成 15 类异常事件；附件列出的 4 个 canonical scenario 文件聚合其中关键事件，同时增加 scenarios/events/ 保存每个事件的 input/before/after/diff；采用冻结区保护 + 半冻结影响报告 + 自由区局部修复；不可满足时输出 INFEASIBLE、冲突核心和解除建议，不伪造成功。

4. world.json 接入

统一 world 同时包含：

• 顶层 datasetMetadata 和完整 shipyard* 数据域；
• 现有 APS 兼容投影：flexMaterials、flexOrders、flexRoutings、flexEquipment、flexScheduleVersions、flexWorkOrders、采购/委外/自制建议；
• planningSourceHash、输入版本、scenarioId、algorithmEvidence、explanations；
• 不接触或覆盖 server/data/** 现场文件。

5. 校验与验收

必须生成并验证：

• 外键错误 = 0；
• 未解释排产决策 = 0；
• 未标记资源重叠 = 0；
• baseline 未标记硬约束违反 = 0；
• MAKE 无 routing = 0 或显式数据质量异常；
• BUY/OUTSOURCE 无供应商 = 0 或显式供应风险；
• 采购建议都有净算明细；
• 生产工单都有 routing/resource requirement；
• 委外建议有前后工序和供应商；
• 四项目都有 milestone/baseline/schedule version；
• 固定种子双次生成内容哈希一致；不同种子至少 manifest/sourceHash 不同；
• full 规模满足下限，CSV 行数与 manifest 统计一致；
• JSON Schema 校验通过；
• world.json 可被现有 WorldStore 隔离加载；
• 真实业务文件哈希前后不变。

6. 写边界

• W69-CONTRACT：server/shipyard_synthetic/config.py、models.py、registry.py、__init__.py。
• W69-MASTER：server/shipyard_synthetic/master_data.py、projects.py、engineering.py。
• W69-PLAN：server/shipyard_synthetic/materials.py、planning.py、scheduler.py、scenarios.py。
• W69-OUTPUT：server/shipyard_synthetic/rag_skills.py、schemas.py、validation.py、exporter.py、cli.py、scripts/generate_beihai_shipyard_aps.py。
• W69-TEST：tests/golden/test_shipyard_synthetic_dataset.py。
• 主 agent：集成、生成 full 数据包、运行验证、文档收口、独立审计。

各 worker 写集互斥；共享契约以 W69-CONTRACT 为先，其他 worker 只能导入，不得回写 contract 文件。

7. 验证命令

• .venv\Scripts\python.exe -m ruff check server/shipyard_synthetic scripts/generate_beihai_shipyard_aps.py tests/golden/test_shipyard_synthetic_dataset.py
• .venv\Scripts\python.exe -m compileall -q server/shipyard_synthetic scripts/generate_beihai_shipyard_aps.py
• .venv\Scripts\python.exe -m pytest tests/golden/test_shipyard_synthetic_dataset.py -q
• .venv\Scripts\python.exe scripts/generate_beihai_shipyard_aps.py --scale full --output beihai-shipyard-aps-data --scenario all
• .venv\Scripts\python.exe scripts/generate_beihai_shipyard_aps.py --validate-only --output beihai-shipyard-aps-data
• 关联 golden、全量 tests/golden、Node 60、Web build、8003/5173/browser。

8. 外部边界与停止条件

• 本轮不需要北海造船真实凭据或内部数据；所有参数明确为模拟。
• 真实数据映射、真实船坞/设备/工时/供应商校准只输出待校准参数清单，不冒充完成。
• 不 commit/push/merge/publish；若后续要提交或合并，必须另行向用户报告风险、测试和数据包体量并获得授权。

9. Plan Audit

待并行实施计划完成后执行独立 feasibility audit；只有 PLAN AUDIT: PASS 才进入实现。

10. 首轮 Plan Audit 修订（权威覆盖前文）

10.1 精确规模与基数

full profile 固定为：4 projects / 72 milestones / 72 GRAND_BLOCK / 280 SECTION / 1,000 work packages / 4,000 WBS production tasks / 12,000 materials / 50,000 BOM relations / 220 routing templates / 2,400 production orders / 12,000 operations / 12,000 schedule slots / 150 equipment resources / 60 teams / 40 suppliers / 550 purchase suggestions / 140 outsource suggestions / 180 risks-conflicts / 120 knowledge assets。

关系冻结为：

• project 1:N WBS task；4,000 task 均匀分配到 4 船，每船 1,000；
• task 0..1 production order；2,400 task 产生 production order；
• production order 1:5 operation，恰好 12,000 operations；
• baseline 中每个 active operation 恰好 1 schedule slot；
• GRAND_BLOCK 1:N SECTION，blocks.csv 用 blockType 和 parentBlockId 区分；
• 50,000 BOM relations 是 EBOM/PBOM/MBOM 总和，三者行数分别写入 manifest。

small/standard 按同一公式缩放，project 选择顺序固定 BH-SYN-2601→2604，任何 scale/项目数下业务 ID 稳定。

10.2 完整方案、异常与执行质量闭环

• 7 类方案：DELIVERY_FIRST、RESOURCE_BALANCED、COST_FIRST、MIN_OVERTIME、DOCK_UTILIZATION、MIN_RISK、RECOMMENDED。
• 15 类异常事件必须全部生成 scenarios/events/<eventId>/{input,before,after,diff}.json；附件 4 个 canonical scenario JSON 是事件聚合视图。
• execution 六表必须含数据：MES orders、operation reports、material issues、quality inspections、nonconformities、rework orders。质量状态机为 PLANNED→HOLD→RELEASED；NCR→REWORK→REINSPECTION→CLOSED，返工真实占用 slot/resource/team。

10.3 硬约束矩阵

validator 与 scheduler 必须覆盖并逐项报告：设计释放、FS/SS/FF/SF+lag、MBOM/routing、materialReadyAt、库存守恒、独占资源、dock/berth/fixture/paint booth、设备维护、重量/尺寸/吊装半径、运输路径/车辆/窗口、涂装温湿度/固化、技能/人数/资质/连续工时、供应商月产能/blackout、委外运输加工检验回厂、已开工/MES/frozen 保护、空间干涉、动火-油漆-密闭舱互斥、区域施工密度、Hold Point、船级社/船东见证日历、天气窗口、战略区粗粒度规则。每项有 validator metric 和测试。

10.4 Skill/RAG 可观察验收

• Skill registry 必须逐一包含附件指定的 20 个 exact skillId；每项含 skillId/name/description/inputSchema/outputSchema/requiredData/algorithmCandidates/hardConstraints/softConstraints/fallbackAlgorithm/timeoutSeconds/validationRules/evidenceFields/version。
• 20 份 input/output schema 必须可解析；validator 逐字段校验。
• RAG 固定 20 category × 6 assets = 120；每条具备附件全部字段，sourceType 固定 SYNTHETIC_KNOWLEDGE；所有 schedule/solution evidenceRefs 必须解析到真实 asset/skill/input/version。

10.5 算法证据语义

第一版 baseline 使用确定性 rolling-horizon bottleneck heuristic + RCPSP-style serial schedule generation，不声称 CP-SAT/MILP 最优：

• algorithm=ROLLING_HORIZON_BOTTLENECK_HEURISTIC；
• solveStatus=FEASIBLE|INFEASIBLE|UNKNOWN；
• heuristic 的 optimalityGap=null、gapType=NOT_APPLICABLE；
• solve time 为真实 measured milliseconds，但不进入业务内容摘要/determinism hash；
• fallback/timeout 必须显式，不能把 fallback 结果冒充原算法；
• 只有未来真实 CP-SAT/MILP 返回 bound 时才允许数值 gap。

10.6 WorldStore 语义 smoke

验证必须在临时目录并设置 APS_DB_DISABLED=1：

1. 复制生成的 world 到 temp；
2. 用 WorldStore(tempPath, world_key='bh-syn-test', tenant_uuid='synthetic') 加载；
3. 断言加载前后规范业务摘要不变；
4. 调用现有 flex summary / flex gantt / material/sourcing consumer，确认兼容投影可消费；
5. 不连接或修改现场 DB，不触碰 server/data/**；
6. 现场四文件 SHA-256 前后相同。

10.7 独立 worker 自检与资源上限

每个 worker 的命令见并行计划 §6。full 生成必须使用 sibling temp dir，校验全绿后原子替换；失败清理 temp。验收上限：180 秒、峰值内存 1.5 GiB、输出目录 300 MiB；超限必须显式失败，不以 small 代替 full。

10.8 Pre-merge stop

本轮不提交/合并。未来用户授权前，主 agent 必须独立报告：主要结论、关键洞察、风险与覆盖率、未关闭项、数据包文件数/体量、交付 branch/commit（若存在）、特殊注意事项，并明确询问是否合并目标分支。

11. 完成状态与验收结论

• CONTRACT、MASTER、SUPPLY、SCHEDULE、SCENARIO、OUTPUT、VALIDATION、TEST 九条边界均已完成并汇合。
• Full 规模精确计数全部满足；完整目录 beihai-shipyard-aps-data/ 已生成。
• 独立校验为 PASS/FEASIBLE，全部硬约束、主外键、证据引用、净算、采购/委外追溯、独立返工、真实方案/场景差异和执行闭环错误数为 0。
• 同种子两次 full 输出业务摘要一致、逐文件 SHA-256 不一致数为 0。
• Round 69 focused 49 passed（含 26 个硬约束非法变异）；全量黄金 1120 passed / 2 warnings；Node 60 passed；Web build 通过。
• fresh full 生成、校验、导出并逐文件比对用时 87.238 秒，峰值工作集 1,298.496 MiB，输出 205.206 MiB，哈希差异 0，均低于门槛。
• 8003/5173 HTTP 200，浏览器真实运行 title 与主界面通过、warning/error=0。
• server/data 四个受保护文件哈希未变化。
• 详细证据见 docs/round-69-beihai-shipyard-synthetic-dataset-state.md 与 docs/round-69-beihai-shipyard-synthetic-dataset-runtime.json。
• 最终限定范围只读审计 AUDIT PASS；manifest/world 审计前后哈希不变。
• 未 commit、push、merge 或 publish。