cdspec 0.1.0

package/templates/design-doc/references//347/224/237/344/272/247/345/267/245/345/215/225/345/237/272/347/272/277/347/244/272/344/276/213.md

@@ -0,0 +1,470 @@
+# 生产工单老代码详细设计（精简版）
+
+> 目标：只保留开发最需要的信息，聚焦数据库设计、关键接口、关键方法伪代码。
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+|---|---|
+| 文档版本 | v1.3.1 |
+| 日期 | 2026-03-06 |
+| 业务范围 | 生产工单主链路（下推、下达、开工、暂停、完工、反完工） |
+
+## 2. 数据库设计
+
+### 2.1 核心表字段
+
+#### `product_work_order`（生产工单主表）
+
+| 字段 | 类型 | 非空 | 默认值 | 字典项key | 说明 |
+|---|---|---|---|---|---|
+| `id` | varchar(36) | Y | - | - | 主键 |
+| `work_order_code` | varchar(64) | Y | - | - | 工单号（租户内唯一） |
+| `work_order_status` | varchar(32) | Y | - | `work_order_status` | 工单状态 |
+| `production_order_id` | varchar(36) | Y | - | - | 所属生产订单ID |
+| `order_number` | varchar(64) | Y | - | - | 订单号 |
+| `source_id` | varchar(36) | N | null | - | 来源工序ID |
+| `process_id` | varchar(36) | Y | - | - | 工序ID |
+| `process_code` | varchar(64) | Y | - | - | 工序编码 |
+| `production_line_code` | varchar(64) | N | null | - | 产线编码 |
+| `classes_code` | varchar(64) | N | null | - | 班次编码 |
+| `work_order_num` | decimal(18,4) | Y | 0 | - | 工单数量 |
+| `product_num` | decimal(18,4) | Y | 0 | - | 已生产数量 |
+| `release_time` | datetime | N | null | - | 下达时间 |
+| `actual_start_time` | datetime | N | null | - | 开工时间 |
+| `actual_end_time` | datetime | N | null | - | 完工时间 |
+| `previous_state` | varchar(16) | N | null | `work_order_previous_state` | 前序状态 |
+| `dependent_process` | varchar(255) | N | null | - | 依赖工序 |
+| `tenant_id` | int | Y | - | - | 租户ID |
+| `del_flag` | tinyint | Y | 0 | `del_flag` | 逻辑删除 |
+| `createBy` | varchar(64) | N | null | - | 创建人 |
+| `createTime` | datetime | N | null | - | 创建时间 |
+| `updateBy` | varchar(64) | N | null | - | 更新人 |
+| `updateTime` | datetime | N | null | - | 更新时间 |
+| `sys_org_code` | varchar(64) | N | null | - | 所属组织编码 |
+
+`product_work_order` 索引与约束
+1. `PRIMARY KEY (id)`。
+2. `UNIQUE uk_work_order_code(work_order_code)`。
+3. `INDEX idx_wo_production_order_id(production_order_id)`。
+4. `INDEX idx_wo_source_id(source_id)`。
+
+#### `product_process`（生产工序）
+
+| 字段 | 类型 | 非空 | 默认值 | 字典项key | 说明 |
+|---|---|---|---|---|---|
+| `id` | varchar(36) | Y | - | - | 工序ID |
+| `production_order_id` | varchar(36) | Y | - | - | 订单ID |
+| `process_id` | varchar(36) | Y | - | - | 工序主数据ID |
+| `process_code` | varchar(64) | Y | - | - | 工序编码 |
+| `un_planned_production_num` | decimal(18,4) | Y | 0 | - | 待排数量 |
+| `planned_production_num` | decimal(18,4) | Y | 0 | - | 已排数量 |
+| `un_release_production_num` | decimal(18,4) | Y | 0 | - | 待下达数量 |
+| `production_line_code` | varchar(64) | N | null | - | 产线编码 |
+| `del_flag` | tinyint | Y | 0 | `del_flag` | 逻辑删除 |
+| `createBy` | varchar(64) | N | null | - | 创建人 |
+| `createTime` | datetime | N | null | - | 创建时间 |
+| `updateBy` | varchar(64) | N | null | - | 更新人 |
+| `updateTime` | datetime | N | null | - | 更新时间 |
+| `sys_org_code` | varchar(64) | N | null | - | 所属组织编码 |
+
+`product_process` 索引与约束
+1. `PRIMARY KEY (id)`。
+2. `INDEX idx_process_production_order_id(production_order_id)`。
+
+#### `product_order`（生产订单）
+
+| 字段 | 类型 | 非空 | 默认值 | 字典项key | 说明 |
+|---|---|---|---|---|---|
+| `id` | varchar(36) | Y | - | - | 订单ID |
+| `order_number` | varchar(64) | Y | - | - | 订单号 |
+| `product_status` | varchar(32) | Y | - | `product_order_status` | 订单状态 |
+| `product_plan_status` | varchar(32) | Y | - | `product_plan_status` | 排产状态 |
+| `priority` | int | N | null | - | 优先级 |
+| `tenant_id` | int | Y | - | - | 租户ID |
+| `del_flag` | tinyint | Y | 0 | `del_flag` | 逻辑删除 |
+| `createBy` | varchar(64) | N | null | - | 创建人 |
+| `createTime` | datetime | N | null | - | 创建时间 |
+| `updateBy` | varchar(64) | N | null | - | 更新人 |
+| `updateTime` | datetime | N | null | - | 更新时间 |
+| `sys_org_code` | varchar(64) | N | null | - | 所属组织编码 |
+
+`product_order` 索引与约束
+1. `PRIMARY KEY (id)`。
+
+### 2.2 字典项说明（集中查看）
+
+| 字典项key | 字典值 |
+|---|---|
+| `work_order_status` | `PLANNED` 已排、`ISSUED` 已下达、`STARTED` 已开工、`PRODUCTING` 生产中、`SUSPEND` 暂停、`FINISHED` 完工 |
+| `work_order_previous_state` | `READY` 前序已就绪、`UNREADY` 前序未就绪 |
+| `product_order_status` | `DRAFT`,`SUBMIT`,`AUDITED`,`PLANNED`,`INPRODUCTION`,`CLOSED`,`FINISH` |
+| `product_plan_status` | `ALL_PLANNED`,`PART_PLANNED`,`ALL_UNPLANNED` |
+| `del_flag` | `0` 未删除、`1` 已删除 |
+
+## 3. 关键前后端接口定义（JSON 示例）
+
+> 控制器前缀：`/product/productWorkOrder`。
+> 返回统一包装：`Result<T>`。
+
+### 3.1 查询待排工序 `GET /queryUnPlanedProcessList`
+
+入参示例（Query）
+
+```jsonc
+{
+  "orderIds": "orderId1,orderId2", // 可选：订单ID串，逗号分隔
+  "productionLineCode": "LINE-01"  // 可选：产线编码
+}
+```
+
+出参示例（`Result<List<UnPlanedProcessVO>>`）
+
+```jsonc
+{
+  "success": true,
+  "result": [
+    {
+      "id": "processRowId",                // 工序记录ID
+      "processId": "processId",            // 工序ID
+      "processCode": "GX-001",             // 工序编码
+      "unPlannedProductionNum": 120.0,      // 待排数量
+      "productionLineCode": "LINE-01",     // 产线编码
+      "productionLineName": "一号线",        // 产线名称
+      "processName": "切割",                // 工序名称
+      "orderNumber": "MO-20260306-001"     // 订单号
+    }
+  ]
+}
+```
+
+### 3.2 下推已排 `POST /pushDown`
+
+入参示例（Body: `ReqBaseSingleVO`）
+
+```jsonc
+{
+  "ids": "processId1,processId2" // 必填：待下推工序ID串
+}
+```
+
+出参示例（`Result<String>`）
+
+```jsonc
+{
+  "success": true,
+  "result": "下推已排成功！"
+}
+```
+
+### 3.3 查询已排/已下达 `GET /queryPlanedProcessList`
+
+入参示例（Query）
+
+```jsonc
+{
+  "orderIds": "orderId1,orderId2",          // 可选：订单ID串
+  "productionLineCode": "LINE-01",          // 可选：产线编码
+  "workOrderStatus": "PLANNED",             // 可选：工单状态
+  "queryStartTime": "2026-03-01 00:00:00",  // 可选：查询开始时间
+  "queryEndTime": "2026-03-31 23:59:59",    // 可选：查询结束时间
+  "pageNo": 1,                                // 可选：默认1
+  "pageSize": 10                              // 可选：默认10
+}
+```
+
+出参示例（`Result<IPage<PlanedProcessVO>>`）
+
+```jsonc
+{
+  "success": true,
+  "result": {
+    "records": [
+      {
+        "id": "workOrderId",               // 工单ID
+        "workOrderCode": "WO-20260306-001", // 工单号
+        "workOrderStatus": "PLANNED",      // 工单状态
+        "workOrderNum": 100.0,               // 工单数量
+        "productionLineCode": "LINE-01",   // 产线编码
+        "classesCode": "SHIFT-A"           // 班次编码
+      }
+    ],
+    "total": 1
+  }
+}
+```
+
+### 3.4 已排产下达 `POST /release`
+
+入参示例（Body: `ReqPlanedProcessQueryVO`）
+
+```jsonc
+{
+  "ids": "workOrderId1,workOrderId2", // 必填：待下达工单ID串
+  "orderIds": "orderId1,orderId2",    // 可选：订单过滤
+  "productionLineCode": "LINE-01"     // 可选：产线过滤
+}
+```
+
+出参示例（`Result<String>`）
+
+```jsonc
+{
+  "success": true,
+  "result": "下达成功！"
+}
+```
+
+### 3.5 工单开工 `POST /beginOrder`
+
+入参示例（Body: `ProductWorkOrder` 关键字段）
+
+```jsonc
+{
+  "id": "workOrderId",           // 必填：工单ID
+  "workGroupPerson": "张三,李四"  // 可选：班组人员
+}
+```
+
+出参示例（`Result<Void>`）
+
+```jsonc
+{
+  "success": true,
+  "result": null
+}
+```
+
+### 3.6 工单暂停 `GET /stopOrder`
+
+入参示例（Query）
+
+```jsonc
+{
+  "id": "workOrderId" // 必填：工单ID
+}
+```
+
+出参示例（`Result<Void>`）
+
+```jsonc
+{
+  "success": true,
+  "result": null
+}
+```
+
+### 3.7 工单完工 `GET /finishProductWorkOrder`
+
+入参示例（Query）
+
+```jsonc
+{
+  "id": "workOrderId" // 必填：工单ID
+}
+```
+
+出参示例（`Result<String>`）
+
+```jsonc
+{
+  "success": true,
+  "result": "完工成功"
+}
+```
+
+### 3.8 工单反完工 `GET /reverseCompletionOrder`
+
+入参示例（Query）
+
+```jsonc
+{
+  "id": "workOrderId" // 必填：工单ID
+}
+```
+
+出参示例（`Result<Void>`）
+
+```jsonc
+{
+  "success": true,
+  "result": null
+}
+```
+
+### 3.9 工单详情 `GET /queryById`
+
+入参示例（Query）
+
+```jsonc
+{
+  "id": "workOrderId" // 必填：工单ID
+}
+```
+
+出参示例（`Result<ProductWorkOrderVO>` 关键字段）
+
+```jsonc
+{
+  "success": true,
+  "result": {
+    "id": "workOrderId",               // 工单ID
+    "workOrderCode": "WO-20260306-001", // 工单号
+    "workOrderStatus": "ISSUED",       // 工单状态
+    "orderNumber": "MO-20260306-001",  // 订单号
+    "workOrderNum": 100.0,               // 工单数量
+    "productionLineCode": "LINE-01",   // 产线编码
+    "classesCode": "SHIFT-A"           // 班次编码
+  }
+}
+```
+
+## 4. 关键方法清单（用于代码对照）
+
+| 中文动作 | 英文方法名（开发使用） | 建议方法签名 |
+|---|---|---|
+| 下推已排 | `pushPlannedProcesses` | `void pushPlannedProcesses(PushPlannedProcessesCmd cmd)` |
+| 工单下达 | `releaseWorkOrders` | `void releaseWorkOrders(ReleaseWorkOrdersCmd cmd)` |
+| 工单开工 | `startWorkOrder` | `void startWorkOrder(StartWorkOrderCmd cmd)` |
+| 工单暂停 | `suspendWorkOrder` | `void suspendWorkOrder(SuspendWorkOrderCmd cmd)` |
+| 工单完工 | `completeWorkOrder` | `void completeWorkOrder(CompleteWorkOrderCmd cmd)` |
+| 反完工 | `reverseWorkOrderCompletion` | `void reverseWorkOrderCompletion(ReverseWorkOrderCompletionCmd cmd)` |
+
+## 5. 关键方法伪代码
+
+### 5.1 `pushPlannedProcesses`（下推已排）
+
+**方法目的**：把待排工序转成工单，并确保“建工单 + 扣待排 + 刷订单排产状态”一致。
+
+```text
+# 1) 遍历待下推工序
+for each processId in cmd.processIds:
+    # 2) 查询工序并校验
+    process = processRepository.getById(processId)
+    assert process 存在
+    assert process.productionLineCode 非空
+    assert process.unPlannedProductionNum > 0
+
+    # 3) 查询订单并创建工单
+    order = orderRepository.getById(process.productionOrderId)
+    workOrder = workOrderFactory.buildFromProcess(process, order)
+    workOrder.status = PLANNED
+    workOrderRepository.save(workOrder)
+
+    # 4) 扣减待排量（原值条件更新，防并发）
+    affected = processRepository.decreaseUnplannedQuantity(
+        process.id,
+        expected = process.unPlannedProductionNum,
+        delta = process.unPlannedProductionNum
+    )
+    if affected == 0:
+        throw BizException("待排数量变化，请刷新重试")
+
+# 5) 刷新订单排产状态
+orderDomainService.refreshPlanStatus(relatedOrderIds)
+```
+
+### 5.2 `releaseWorkOrders`（工单下达）
+
+**方法目的**：按顺序下达工单，状态变更为 ISSUED，并回写待下达数量。
+
+```text
+# 1) 读取可下达有序列表
+ordered = workOrderRepository.listPlannedInOrder(cmd.orderIds)
+
+# 2) 校验请求是否“从第一个开始连续下达”
+assert cmd.workOrderIds == firstN(ordered, size(cmd.workOrderIds)).ids
+
+# 3) 执行下达
+for each workOrderId in cmd.workOrderIds:
+    wo = workOrderRepository.getById(workOrderId)
+    assert wo.status == PLANNED
+    assert wo.classesCode 非空
+
+    wo.status = ISSUED
+    wo.releaseTime = now
+    workOrderRepository.save(wo)
+
+    # 回写工序待下达
+    processRepository.decreaseUnreleasedQuantity(wo.sourceId, wo.workOrderNum)
+
+    # 租户策略扩展
+    policyFactory.getPolicy(wo.tenantId).afterRelease(wo)
+```
+
+### 5.3 `startWorkOrder`（工单开工）
+
+**方法目的**：工单进入生产执行态，并把订单状态联动到生产中。
+
+```text
+# 1) 查询工单
+wo = workOrderRepository.getById(cmd.workOrderId)
+
+# 2) 状态机校验并流转
+if wo.status == ISSUED:
+    wo.status = tenantPolicy.startStatus(wo.tenantId)  # STARTED 或 PRODUCTING
+    wo.actualStartTime = now
+else if wo.status == SUSPEND:
+    wo.status = PRODUCTING
+else:
+    throw BizException("当前状态不允许开工")
+
+# 3) 保存工单
+workOrderRepository.save(wo)
+
+# 4) 订单联动
+order = orderRepository.getByOrderNumber(wo.orderNumber)
+order.status = INPRODUCTION
+orderRepository.save(order)
+```
+
+### 5.4 `completeWorkOrder`（工单完工）
+
+**方法目的**：完工前做质检校验，完工后联动订单状态与后序工单前序状态。
+
+```text
+# 1) 查询工单
+wo = workOrderRepository.getById(cmd.workOrderId)
+assert wo.status != FINISHED
+
+# 2) 质检校验
+process = processRepository.getById(wo.sourceId)
+if process.requiresQualityCheck and wo.tenantId != YHC:
+    hasDetecting = reportRepository.existsDetectingOrNullResult(wo.id)
+    if hasDetecting:
+        throw BizException("需质检合格后才能完工")
+
+# 3) 更新完工
+wo.status = FINISHED
+wo.actualEndTime = now
+workOrderRepository.save(wo)
+
+# 4) 订单与后序联动
+orderDomainService.tryMarkFinished(wo.productionOrderId)
+workOrderDomainService.refreshDependentPreviousState(wo.orderNumber)
+
+# 5) 租户后置动作
+policyFactory.getPolicy(wo.tenantId).afterComplete(wo)
+```
+
+### 5.5 `reverseWorkOrderCompletion`（工单反完工）
+
+**方法目的**：将强制完工后的工单回退到完工前状态。
+
+```text
+# 1) 查询工单
+wo = workOrderRepository.getById(cmd.workOrderId)
+
+# 2) 校验可反完工
+if wo.compulsionFinishStatus is null:
+    throw BizException("当前工单不允许反完工")
+
+# 3) 回退工单状态
+wo.status = wo.compulsionFinishStatus
+workOrderRepository.save(wo)
+
+# 4) 回退订单状态
+order = orderRepository.getByOrderNumber(wo.orderNumber)
+order.status = INPRODUCTION
+orderRepository.save(order)
+```

package/templates/design-doc/scripts/validate_doc_layout.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 用途：校验某业务是否符合 design-doc-lifecycle 的目录硬约束
+# 用法：./scripts/validate_doc_layout.sh 生产订单
+
+if [[ $# -ne 1 ]]; then
+  echo "用法: $0 <业务名>" >&2
+  exit 2
+fi
+
+business="$1"
+business_dir="docs/${business}"
+baseline_file="${business_dir}/baseline-${business}.md"
+feature_dir="${business_dir}/feature"
+archive_file="${business_dir}/archive-log.md"
+
+if [[ ! -d "${business_dir}" ]]; then
+  echo "校验失败: 业务目录不存在 -> ${business_dir}" >&2
+  exit 1
+fi
+
+if [[ ! -f "${baseline_file}" ]]; then
+  echo "校验失败: 缺少基线文件 -> ${baseline_file}" >&2
+  exit 1
+fi
+
+if [[ ! -d "${feature_dir}" ]]; then
+  echo "校验失败: 缺少 feature 目录 -> ${feature_dir}" >&2
+  exit 1
+fi
+
+if [[ ! -f "${archive_file}" ]]; then
+  echo "校验失败: 缺少归档日志 -> ${archive_file}" >&2
+  exit 1
+fi
+
+baseline_count=$(find "${business_dir}" -maxdepth 1 -type f -name 'baseline-*.md' | wc -l | tr -d ' ')
+if [[ "${baseline_count}" != "1" ]]; then
+  echo "校验失败: ${business_dir} 下 baseline 文件数量应为 1，实际为 ${baseline_count}" >&2
+  exit 1
+fi
+
+if find "docs" -mindepth 1 -maxdepth 2 -type f -name "baseline-${business}.md" | grep -v "^${baseline_file}$" >/dev/null 2>&1; then
+  echo "校验失败: 发现同业务 baseline 落在多个目录，请先收敛到单目录" >&2
+  exit 1
+fi
+
+echo "校验通过: ${business} 目录结构符合约束"

package/templates/frontend-develop-standard/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: frontend-standards
+description: 部门级前端开发规范执行技能，覆盖 Vue3 编码规范、工程配置规范、Git 提交规范与前端最佳实践。用于前端需求开发、重构、代码评审、工程初始化与联调前自检；当任务涉及 Vue3/TypeScript 页面与组件实现、样式规范、ESLint/Prettier/Husky/Commitlint 配置时触发。
+---
+
+# 部门前端开发规范技能
+
+## 总体目标
+
+在实现前端需求时，优先保证可维护性、一致性与可扩展性，避免临时方案累积技术债务。先明确需求边界与页面职责，再按规范完成编码、样式、工程配置与提交自检。
+
+## 增量开发优先级
+
+针对系统开发中的增量工作，按以下优先级执行：
+
+1. 业务需求与用户明确指令（最高优先级）。
+2. 项目既有规范与代码风格（默认优先遵循）。
+3. 本技能与通用前端规范（用于补充与兜底）。
+
+冲突处理原则：
+
+- 不冲突时：遵循项目现有风格，本技能作为检查清单。
+- 存在冲突时：以项目既有风格为准，避免在本次需求中做大范围风格迁移。
+- 涉及安全、严重缺陷或团队已达成统一升级决策时，可在说明影响范围后做规范升级。
+
+## 执行流程
+
+1. 识别任务类型与范围。
+
+- 若为页面/组件开发，重点执行 Vue3 组件规范、命名规范、样式作用域规范。
+- 若为工程治理任务，重点执行 EditorConfig、Prettier、ESLint、Husky、Commitlint 配置规范。
+- 若用户已指定现有项目约束，以用户约束优先，在不冲突前提下遵循本技能。
+
+2. 加载参考规范并制定实现方案。
+
+- 始终加载 `references/frontend_develop_standard.md`。
+- 若任务仅涉及局部改动，只应用与改动相关的条目，避免过度改造。
+
+3. 编码与配置时强制执行。
+
+- 命名语义化：组件、变量、常量、类型命名遵循规范。
+- 统一代码风格：模板双引号、脚本单引号、多属性换行。
+- 样式默认使用作用域（`scoped`），穿透样式使用 `:deep()`。
+- 禁止保留 `console.log`、`debugger` 和无效注释代码。
+- 事件与处理函数命名保持一致（如 `on-*`、`handle*`）。
+
+4. 交付前执行自检。
+
+- 检查格式化与 lint 规则是否一致。
+- 检查组件职责是否清晰、是否存在可复用代码未抽离。
+- 检查性能与安全风险（如不必要渲染、`v-html`、输入校验缺失）。
+- 检查提交信息是否符合约定式提交规范。
+
+## 交付要求
+
+1. 明确说明本次改动遵循的前端规范条目（至少包含命名、样式、质量自检中的关键项）。
+2. 若涉及工程配置，列出新增或调整的配置文件与关键配置项。
+3. 若涉及组件开发，说明组件职责、事件约定与样式边界处理方式。
+4. 输出遗留风险与后续建议，避免把隐患留给后续维护者。
+
+## 参考资料
+
+- `references/frontend_develop_standard.md`

package/templates/frontend-develop-standard/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Frontend Develop Standard"
+  short_description: "Generated from templates/frontend_develop_standard.md"
+  default_prompt: "Use $frontend-develop-standard to follow this template skill."