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。