🎉 init: 小龙的工作空间

2026-06-06 10:40:48 +08:00
commit a188ee1426
3201 changed files with 231817 additions and 0 deletions
@@ -0,0 +1,362 @@
+# Software Factory Core Layer
+
+> **PR-36**：Software Factory Core — SF-01 ~ SF-15 全部 Factory 的统一入口。
+
+---
+
+## 目录
+
+1. [架构定位](#架构定位)
+2. [模块架构](#模块架构)
+3. [Factory Contract](#factory-contract)
+4. [Factory Registry](#factory-registry)
+5. [Product Model](#product-model)
+6. [Workflow Engine](#workflow-engine)
+7. [Artifact Graph](#artifact-graph)
+8. [Factory Reporting](#factory-reporting)
+9. [使用示例](#使用示例)
+10. [扩展性设计](#扩展性设计)
+
+---
+
+## 架构定位
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│               AI Software Company Layer (SF-01~SF-15)        │
+│    SF-01 Strategy · SF-02 Requirement · SF-03 Design · ...   │
+└────────────────────────────┬─────────────────────────────────┘
+                             │ 注册并运行于
+┌────────────────────────────▼─────────────────────────────────┐
+│              Software Factory Core Layer (PR-36)              │
+│                                                              │
+│  Factory Contract  →  统一接口规范                             │
+│  Factory Registry  →  SF-01~SF-15 元数据管理                   │
+│  Product Model     →  统一产品模型                             │
+│  Workflow Engine   →  Factory 编排引擎                        │
+│  Artifact Graph    →  产物图谱与追踪                           │
+│  Factory Reporting →  跨 Factory 报告体系                      │
+└────────────────────────────┬─────────────────────────────────┘
+                             │ 构建于
+┌────────────────────────────▼─────────────────────────────────┐
+│               Agent Runtime Layer (PR-35)                    │
+│  Task · Pipeline · State Machine · Adapters · Reporting       │
+└────────────────────────────┬─────────────────────────────────┘
+                             │ 调用
+┌────────────────────────────▼─────────────────────────────────┐
+│          Quality Foundation (PR-01 ~ PR-34)                  │
+│  Checklist · Baseline · Gate · Precompute · Memory · ...      │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 层次关系
+
+| 层次 | PR 编号 | 职责 |
+|------|---------|------|
+| Quality Foundation | PR-01 ~ PR-34 | 质量门禁、基线比较、发布检查、记忆系统 |
+| Runtime Layer | PR-35 | 统一任务执行引擎、状态机、适配器 |
+| **Factory Core Layer** | **PR-36** | **Factory 注册、编排、产品模型、产物追踪、报告** |
+| AI Software Company | SF-01 ~ SF-15 | 具体 Factory 实现（产品战略到公司运营） |
+
+---
+
+## 模块架构
+
+```
+src/software-factory-core/
+├── index.mjs                 # Barrel export（唯一入口）
+├── factory-contract.mjs      # Part B：统一 Factory 接口
+│   ├── FactoryInput          # 进入 Factory 的输入
+│   ├── FactoryOutput         # Factory 产出
+│   ├── FactoryArtifact       # 产物（10 种类型）
+│   ├── FactoryMetric         # 度量指标（8 种类型）
+│   ├── FactoryReport         # 报告（5 种类型）
+│   └── FactoryDependency     # Factory 间依赖（4 种类型）
+├── factory-registry.mjs      # Part A：Factory 注册中心
+│   ├── SF-01 ~ SF-15 元数据定义
+│   ├── 按领域/依赖/状态查询
+│   ├── 拓扑排序 + 并行批次
+│   └── 实现注册与执行
+├── product-model.mjs         # Part C：统一产品模型
+│   ├── 15 种产品组件类型
+│   ├── 生命周期管理（8 阶段）
+│   └── 默认技术栈推荐
+├── workflow-engine.mjs       # Part D：Factory 编排引擎
+│   ├── 4 种执行模式
+│   ├── 4 种失败策略
+│   ├── 标准 Factory 流程
+│   └── 条件执行支持
+├── artifact-graph.mjs        # Part E：产物图谱
+│   ├── 节点 + 边模型
+│   ├── 图遍历（祖先/后代/依赖链）
+│   ├── 完整性校验
+│   └── 按多维度检索
+└── factory-reporting.mjs     # Part F：报告体系
+    ├── Factory Report
+    ├── Project Report
+    ├── Product Report
+    ├── Release Report
+    └── Business Report
+```
+
+---
+
+## Factory Contract
+
+所有 SF-01 ~ SF-15 必须遵守的统一接口：
+
+| 类型 | 作用 | 必填字段 |
+|------|------|----------|
+| `FactoryInput` | Factory 入参 | `factoryId` |
+| `FactoryOutput` | Factory 出参 | `factoryId`, `status` |
+| `FactoryArtifact` | Factory 产物 | `kind`, `name`, `factoryId` |
+| `FactoryMetric` | 度量指标 | `factoryId`, `name`, `value` |
+| `FactoryReport` | 标准化报告 | `type`, `title` |
+| `FactoryDependency` | Factory 间依赖 | `from`, `to` |
+
+### Artifact 种类（10 种）
+
+```
+requirement → prototype → design → architecture → code
+→ test → release → report → operations → marketing
+```
+
+### 依赖种类（4 种）
+
+| Kind | 含义 | 行为 |
+|------|------|------|
+| `hard` | 硬依赖 | 上游失败 → 下游阻断 |
+| `soft` | 软依赖 | 上游失败 → 下游可继续 |
+| `data` | 数据依赖 | 上游产物作为下游输入 |
+| `trigger` | 触发依赖 | 上游完成触发下游启动 |
+
+---
+
+## Factory Registry
+
+注册 SF-01 ~ SF-15 共 15 个 Factory：
+
+| ID | 名称 | 领域 | 核心 input → output |
+|----|------|------|---------------------|
+| SF-01 | 产品战略工厂 | product-strategy | other → requirement, report |
+| SF-02 | 需求工程工厂 | requirement-engineering | requirement → requirement, prototype |
+| SF-03 | 产品设计工厂 | product-design | requirement → design, prototype |
+| SF-04 | 视觉设计工厂 | visual-design | design → design |
+| SF-05 | 技术架构工厂 | architecture | requirement, design → architecture, code |
+| SF-06 | 平台规划工厂 | platform-planning | architecture → architecture, report |
+| SF-07 | 全栈开发工厂 | full-stack-development | architecture, design, requirement → code, test |
+| SF-08 | Agent 协作工厂 | agent-collaboration | requirement, code → code, report |
+| SF-09 | 质量治理工厂 | quality-governance | code, test, architecture → report |
+| SF-10 | 测试工厂 | testing | code, architecture → test, report |
+| SF-11 | 发布工厂 | release | code, test, report → release, report |
+| SF-12 | 运维工厂 | operations | release, report → operations, report |
+| SF-13 | 演进工厂 | evolution | operations, report → requirement, report |
+| SF-14 | 增长工厂 | growth | operations, report → report, marketing |
+| SF-15 | 软件公司工厂 | software-company | report → report |
+
+### Registry API
+
+```javascript
+const registry = createFactoryRegistry();
+
+registry.get("SF-07");                    // → Factory 元数据
+registry.list({ domain: "testing" });      // → 按领域过滤
+registry.getDependencies("SF-07");         // → 上游依赖
+registry.getDependents("SF-05");          // → 下游依赖者
+registry.getTopologicalOrder();           // → 拓扑排序
+registry.getParallelBatches();            // → 并行批次
+
+// 注入实现
+registry.registerImplementation("SF-07", myFullStackFactory);
+registry.execute("SF-07", input);         // → FactoryOutput
+```
+
+---
+
+## Product Model
+
+### 产品组件类型（15 种）
+
+```
+Desktop App / Web App / Official Website / Admin System
+Backend Service / Database / Android App / iOS App
+Mini Program / API Platform / Payment System
+Account System / License System / Download Center
+Update Service
+```
+
+### 生命周期（8 阶段）
+
+```
+concept → planning → development → testing
+→ staging → production → maintenance → sunset
+```
+
+---
+
+## Workflow Engine
+
+### 执行模式（4 种）
+
+| 模式 | 行为 |
+|------|------|
+| `sequential` | 按 stages 顺序逐个执行 |
+| `parallel` | 并行执行所有阶段（忽略依赖） |
+| `dependency` | 按依赖图自动排序，批量并行执行 |
+| `conditional` | 按条件逐个执行 |
+
+### 标准流程（13 阶段）
+
+```
+SF-01 Strategy
+  ↓
+SF-02 Requirement
+  ↓
+SF-03 Design ──→ SF-05 Architecture
+  ↓                    ↓
+SF-04 UI          SF-06 Platform Planning
+  ↓                    ↓
+  └──────→ SF-07 Development ←──────┘
+               ↓
+       SF-09 Quality ──→ SF-10 Testing
+               ↓               ↓
+       └──────→ SF-11 Release ←──────┘
+                    ↓
+               SF-12 Operations
+                    ↓
+       SF-14 Growth ──→ SF-13 Evolution
+```
+
+### 失败策略（4 种）
+
+| 策略 | 行为 |
+|------|------|
+| `stop` | 遇失败立即停止工作流 |
+| `continue` | 记录失败，继续执行 |
+| `retry` | 自动重试（最多 maxRetries 次） |
+| `fallback` | 执行备选路径 |
+
+---
+
+## Artifact Graph
+
+### 图结构
+
+- **节点 (ArtifactNode)**: 产物（代码/文档/测试/报告/…）
+- **边 (ArtifactEdge)**: 关系（依赖/产出/派生/包含/…）
+
+### 关系类型（8 种）
+
+```
+depends_on / produces / parent_of / derived_from
+references / contains / input_to / related_to
+```
+
+### 图操作
+
+```javascript
+const graph = createArtifactGraph();
+graph.addNode(node);
+graph.addEdge(edge);
+
+graph.getAncestors(nodeId);        // 追溯依赖祖先
+graph.getDescendants(nodeId);      // 追溯下游依赖者
+graph.getDependencyChain(nodeId);  // 拓扑排序依赖链
+graph.getDirectDependencies(nodeId);
+graph.getDirectDependents(nodeId);
+graph.validateAll();               // 完整性校验
+```
+
+---
+
+## Factory Reporting
+
+| 报告类型 | 内容 |
+|----------|------|
+| Factory Report | 单 Factory 执行摘要、产物、风险、决策 |
+| Project Report | 多 Factory 聚合、风险总结、建议 |
+| Product Report | 产品状态、组件、生命周期、质量评估 |
+| Release Report | 发布决策、认证、测试结果、制品 |
+| Business Report | 产品组合、Factory 舰队、关键指标 |
+
+---
+
+## 使用示例
+
+### 注册并执行 Factory
+
+```javascript
+import { createFactoryRegistry, createFactoryInput, createFactoryOutput,
+         createFactoryArtifact, createFactoryMetric } from './src/software-factory-core/index.mjs';
+
+const registry = createFactoryRegistry();
+
+// 注入 SF-07 实现
+registry.registerImplementation("SF-07", (input) => {
+  return createFactoryOutput({
+    factoryId: "SF-07",
+    status: "passed",
+    artifacts: [
+      createFactoryArtifact({ kind: "code", name: "auth.ts", factoryId: "SF-07" }),
+    ],
+    metrics: [
+      createFactoryMetric({ factoryId: "SF-07", name: "loc", value: 350, kind: "count", unit: "lines" }),
+    ],
+    nextActions: ["Run tests"],
+  });
+});
+
+// 执行
+const input = createFactoryInput({ factoryId: "SF-07" });
+const output = registry.execute("SF-07", input);
+console.log(output.status); // "passed"
+```
+
+### 编排 Workflow
+
+```javascript
+import { createStandardFactoryWorkflow, executeWorkflow } from './src/software-factory-core/index.mjs';
+
+const wf = createStandardFactoryWorkflow();
+const result = await executeWorkflow(wf, registry, { product });
+console.log(result.status); // "completed"
+```
+
+### 产物追踪
+
+```javascript
+import { createArtifactGraph, createArtifactNode, createArtifactEdge } from './src/software-factory-core/index.mjs';
+
+const graph = createArtifactGraph();
+const prd = createArtifactNode({ kind: "requirement", name: "PRD v1", factoryId: "SF-02" });
+const design = createArtifactNode({ kind: "design", name: "Wireframe", factoryId: "SF-03" });
+
+graph.addNode(prd);
+graph.addNode(design);
+graph.addEdge(createArtifactEdge({ from: design.id, to: prd.id, relation: "depends_on" }));
+
+const chain = graph.getDependencyChain(design.id);
+// → [prd, design] (topological order)
+```
+
+---
+
+## 扩展性设计
+
+### 原则
+
+1. **禁止硬编码 Factory 实现** — Registry 只管理元数据，实现通过 `registerImplementation()` 外部注入
+2. **保持兼容** — 不修改 `src/agent-runtime/` 任何文件，不修改现有测试
+3. **保持可扩展** — `metadata` 字段支持 vendor extensions，自定义 Factory 可在 SF-15 之后添加
+4. **纯函数优先** — 数据模型为不可变创建模式，引擎为纯函数
+
+### 未来扩展点
+
+- 在 SF-01~SF-15 之外注册 `SF-16+`
+- 实现持久化 Artifact Graph（替换内存 Map）
+- 添加 Workflow 可视化（Mermaid/DAG 输出）
+- 集成 CI/CD（自动化 Workflow 触发）
+
+---
+
+*PR-36 — Software Factory Core Layer。SF-01 ~ SF-15 的根基。*