# 软件项目总控 -- 通用软件项目从需求到交付的总控流程

面向 API 服务、后台模块、插件、CLI 工具、数据处理脚本、自动化任务、中小型后端应用和非网站类功能项目。目标是在进入任务拆解前，先定义项目边界、架构方案、数据/API/集成、实现路径、验证、发布和沉淀，避免复杂需求直接落入零散代码生成。

> 本 Skill 不替代 `task-decomposition-and-execution`，而是在拆解前定义通用软件项目必须覆盖的阶段和验收项；随后调用 `task-decomposition-and-execution` 将阶段转为 Wave 任务。

## 输入要求

1. **项目类型**（必填）：API服务/后台模块/插件/CLI工具/数据脚本/自动化任务/服务端应用
2. **业务目标**（必填）：解决什么问题，交付后谁使用
3. **运行环境**（必填）：语言、框架、CMS/平台、数据库、服务器、定时任务或队列
4. **输入输出**（必填）：外部输入、数据来源、输出结果、调用方式
5. **交付要求**（可选）：上线方式、回滚要求、性能目标、安全要求、监控告警、巡检要求、验收人

## 执行流程

### 第一步：项目启动与边界确认

- **填充项目启动模板**：按主 SKILL.md「项目启动模板」章节填写项目启动信息（含终极功能、循环轮次、改动点数），作为后续 Wave 拆解和轮次控制基准
- 明确项目类型、业务目标、成功标准和交付边界
- 判断是否属于网站项目；若是，转入 `website-project`
- 明确 In scope / Out of scope，避免需求漂移
- 确认运行入口：HTTP API、后台菜单、命令行、定时任务、队列消费、插件钩子

### 第二步：需求规格与行为契约

调用 `spec-driven-development` 输出需求规格，并补充：

- 业务对象和状态流转
- 输入参数、输出结果、错误码或异常类型
- 权限、幂等、重试、审计和日志要求
- 运行观测要求：关键指标、日志字段、告警阈值、巡检频率
- 兼容性要求：PHP版本、CMS版本、MySQL版本、浏览器或系统环境

### 第三步：架构与技术方案

按项目类型调用对应子技能：

- API/服务：调用 `api-design`
- 数据库/SQL：调用 `mysql-database`
- CMS/PHP二开：调用 `cms-development`
- 前端/后台页面：调用 `frontend-design`
- 技术不确定：调用 `tech-selection`

必须明确：

- 模块边界和文件组织
- 数据模型、接口契约、依赖服务
- 错误处理、日志、配置和权限
- 可观测性方案：日志路径、指标口径、异常上报、告警接收人
- 长任务是否需要 `Init → Step → Poll`
- **架构权衡留痕（复杂度门槛）**：仅当本方案存在**多候选方案 / 跨模块影响 / 高影响决策**时必填——每项须附「候选方案 → 各自 trade-off → 选择理由 + 反选理由 + 撤销条件」（见 `spec-driven-development` 第四步 Design / `tech-selection` 第四步）。单一合理实现、低复杂度改动（如单文件小功能）**不强制**反选论证，避免违反"澄清过度"反模式；模糊 / 高影响决策仍须显式标注并交用户拍板。

### 第三步点五：模块边界审查

在进入 Wave 拆解前，对架构方案中涉及的模块边界进行合规审查，防止跨模块改动失控。

**审查维度**：

| 维度       | 检查项                              | 违规信号                                      |
| ---------- | ----------------------------------- | --------------------------------------------- |
| 依赖方向   | 模块间依赖是否单向无环              | 循环依赖 / 底层模块反向依赖上层               |
| 接口契约   | 跨模块调用是否通过明确接口          | 跨模块直接访问内部实现 / 绕过接口调用私有方法 |
| 数据持有   | 每个数据实体是否有唯一归属模块      | 同一张表被多个模块直接写入 / 缓存键冲突       |
| 变更半径   | 单次改动是否需要同步修改 ≥ 3 个模块 | 一处业务规则变更需要同时改多个模块            |
| 术语一致性 | 跨模块是否对同一概念使用同一名称    | 同一概念在不同模块有不同命名                  |

> 上表为**工程边界**维度。复杂业务系统（多子域/术语多义/跨上下文协作）应先加载 `domain-driven-design` 提供**限界上下文语义边界**（同一术语在不同上下文可有不同模型），与工程边界互补——审查时先语义后工程。CRUD 为主的项目跳过语义边界，避免过度设计。

**审查输出**：

- 绘制模块依赖图（文本箭头图即可）
- 违规项标注严重度（阻塞/警告/建议）和修复方向
- 循环依赖或数据归属冲突为阻塞级，必须在进入 Wave 拆解前解决
- 审查结果写入「架构决策」章节，随第八步沉淀到项目记忆

**轻量模式**（模块数 ≤ 3 时适用）：仅检查依赖方向和接口契约两项，其余跳过。

### 第四步：实现计划与 Wave 拆解

调用 `task-decomposition-and-execution`，按依赖拆成可验证 Wave：

| Wave   | 内容                               | 验证                  |
| ------ | ---------------------------------- | --------------------- |
| Wave 1 | 环境、配置、入口、基础结构         | 能运行入口            |
| Wave 2 | 数据模型、接口契约、核心服务       | 数据读写/接口返回正确 |
| Wave 3 | 业务流程、权限、异常处理           | 主路径和异常路径通过  |
| Wave 4 | 测试、安全、性能、兼容             | 检查清单通过          |
| Wave 5 | 文档、部署、回滚、监控、巡检、交付 | 可交接可回滚可观测    |

**轮次控制承接**（引用主 SKILL.md「项目启动模板」和「轮次与收敛」章节）：

- 第一步填充的项目启动模板中「循环轮次」和「每轮改动点数」字段，在本步 Wave 拆解时落地执行
- 默认轮次 3 轮，安全最大轮次 6 轮，每轮改动点不超过 3 处
- 每轮结束时按主 SKILL.md「收敛判定逻辑」判断是否结束（终极功能完成/默认轮次到达/安全最大轮次/连续2轮P2微调）
- 超过安全最大轮次必须强制结束并输出未完成清单，不得无限循环

### 第五步：代码实现与自检

- 调用 `code-generation` 实现每个 Wave 的最小可验证切片
- 遵循 `karpathy-coding-guidelines`：先推演、少抽象、避免模板化膨胀
- 涉及 SQL 时遵循 `mysql-database`
- 涉及 CMS 时遵循 `cms-development`
- 每个改动必须给出验证方法

### 第六步：审查、测试与安全验证

- 调用 `code-review` 检查安全、性能、可维护性、规范符合性
- 调用 `test-generation` 覆盖正常路径、异常路径、边界条件和回归路径
- 检查 SQL 注入、XSS、CSRF、权限绕过、文件上传、反序列化等风险
- 长任务必须验证 Init 创建、Step 分批、Poll 查询、Cancel 取消、失败重试和僵尸检测

**证据格式（必填，对齐主流程 Step 4）**：

| 验证项        | 证据类型  | 最小字段                                                                                                                                             |
| ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| 代码审查      | 命令+输出 | 审查命令 + 问题分级清单（阻塞/严重/一般/建议）                                                                                                       |
| 单元/集成测试 | 测试报告  | 测试用例数、通过数、失败用例清单                                                                                                                     |
| 安全验证      | 命令+输出 | 扫描命令 + 扫描结果 + 阻塞级问题清单                                                                                                                 |
| 长任务验证    | API 响应  | Init 创建响应 + Step 进度响应 + Poll 最终状态 + Cancel 响应 + 失败重试响应 + 僵尸检测扫描结果（Poll 检测 `running` 超阈值 → 标记 `failed`/`resume`） |

未声明证据类型的验证视为未完成。

### 第七步：发布、回滚、监控与交付

- 明确发布方式：文件覆盖、插件启用、命令部署、数据库迁移、计划任务
- 输出上线前检查：配置、权限、依赖、缓存、日志、备份
- 数据库变更必须有备份和回滚 SQL
- 输出监控方案：核心可用性、错误率、慢查询、队列积压、任务失败数、磁盘/内存等运行指标
- 输出告警方案：触发阈值、通知渠道、值班/负责人、升级路径、误报处理
- 输出巡检方案：日/周巡检项、日志检查点、数据一致性检查、备份可恢复性检查
- 输出交付材料：使用说明、部署说明、回滚说明、已知限制

### 第八步：项目记忆沉淀

调用 `project-memory-management` 记录：

- 项目类型、入口、运行环境和部署方式
- 架构决策、数据结构、接口契约和权限规则
- 验证证据、发布记录、回滚方案、监控告警、巡检方案和已知限制
- 后续维护注意事项

## 构建与发布流水线（CI/CD）

> 本节定义通用软件项目必须覆盖的构建、发布和回滚流水线要点，作为第七步的工程化落地。

### 流水线阶段

| 阶段     | 输入                       | 输出                           | 验证                          |
| -------- | -------------------------- | ------------------------------ | ----------------------------- |
| 构建     | 源码、依赖锁文件、构建配置 | 可部署产物（包/镜像/静态文件） | 构建成功且产物校验通过        |
| 测试     | 产物 + 测试套件            | 测试报告（通过率/覆盖率）      | 单元+集成测试通过，无阻塞失败 |
| 静态检查 | 源码                       | lint/类型检查/安全扫描报告     | 无阻塞级问题                  |
| 部署     | 产物 + 环境配置            | 线上版本                       | 健康检查通过，旧版本可回退    |
| 验证     | 线上环境                   | 烟雾测试结果                   | 关键路径可达，错误率低于阈值  |
| 回滚     | 上一稳定版本               | 线上版本回退                   | 健康检查通过                  |

### 强制要求

- **依赖锁定**：构建必须基于 `composer.lock` / `package-lock.json` / `pnpm-lock.yaml` 等锁文件，禁止使用 `latest` / `*` / `dev-main`
- **环境隔离**：构建、测试、生产环境配置必须分离，敏感配置通过环境变量注入，不写入代码库
- **产物可追溯**：每次构建产物必须关联 commit、构建时间、构建号、依赖版本
- **发布可回滚**：每次发布必须保留前一稳定版本，并能在 5 分钟内回退
- **健康检查**：部署后必须执行烟雾测试，验证关键接口和页面可达
- **变更窗口**：业务高峰期禁止发布，DDL/数据库迁移单独走审核流程

### 失败回退

| 失败场景           | 回退动作                                 |
| ------------------ | ---------------------------------------- |
| 构建失败           | 不进入测试；修复依赖或构建配置后重试     |
| 测试失败           | 不进入部署；标注失败用例并修复           |
| 部署后健康检查失败 | 立即触发自动回滚到上一稳定版本           |
| 回滚后仍失败       | 切换到应急流程，通知负责人，保留现场日志 |

## 输出格式

```markdown
## 软件项目交付方案

### 1. 项目启动

- 项目类型:
- 业务目标:
- 成功标准:
- In scope:
- Out of scope:

### 2. 行为契约

| 场景 | 输入 | 输出 | 异常/错误 | 验收标准 |
| ---- | ---- | ---- | --------- | -------- |

### 3. 技术方案

| 层级 | 方案                  | 说明   |
| ---- | --------------------- | ------ |
| 入口 | [API/CLI/插件/任务]   | [说明] |
| 数据 | [MySQL/文件/外部服务] | [说明] |
| 集成 | [依赖服务]            | [说明] |

### 4. Wave执行计划

| Wave | 任务 | 依赖 | 验证 |
| ---- | ---- | ---- | ---- |

### 5. 验证与发布

- 测试:
- 安全:
- 性能:
- 发布:
- 回滚:
- 监控:
- 告警:
- 巡检:

### 6. 交付材料

- 使用说明:
- 部署说明:
- 回滚说明:
- 运维说明:
- 已知限制:
```

## 质量标准

- 必须先定义项目类型、入口、业务目标和成功标准
- 必须明确输入、输出、错误处理和验收标准
- 必须说明架构边界、数据/API/集成方案
- 涉及数据库必须调用 `mysql-database`
- 涉及 CMS/PHP 二开必须调用 `cms-development`
- 涉及长任务必须采用 Init → Step → Poll
- 每个 Wave 必须有验证方法
- 发布前必须有备份、回滚、监控告警、巡检方案和已知限制
- 发布交付必须说明日志位置、关键指标、告警阈值、巡检频率和负责人
- 无验证证据不得标记为完成

## 失败回退机制

| 步骤                           | 失败条件                         | 回退目标                       | 最大重试 | 不可恢复时升级路径             |
| ------------------------------ | -------------------------------- | ------------------------------ | -------- | ------------------------------ |
| 第一步：项目启动与边界确认     | 类型或边界不清                   | 输出澄清清单和默认假设         | 1        | 等待用户确认                   |
| 第二步：需求规格与行为契约     | 输入输出不完整                   | 生成最小行为契约草案           | 1        | 标注待确认字段                 |
| 第三步：架构与技术方案         | 技术栈不确定                     | 调用技术选型输出候选矩阵       | 1        | 由用户决策                     |
| 第四步：实现计划与 Wave 拆解   | 依赖复杂或任务过大               | 重新按模块/入口/数据域拆分     | 2        | 输出依赖图                     |
| 第五步：代码实现与自检         | 验证失败                         | 缩小到最小可复现切片修复       | 2        | 标记阻塞                       |
| 第六步：审查、测试与安全验证   | 环境不可用                       | 输出手动验证清单               | 1        | 标注未实测项                   |
| 第七步：发布、回滚、监控与交付 | 无发布权限、环境信息或监控接收人 | 输出部署包、回滚步骤和运维清单 | 1        | 由有权限人员执行并确认监控告警 |
| 第八步：项目记忆沉淀           | 项目记忆不可用                   | 输出本地交付记录               | 1        | 标注未沉淀                     |

## 关联 reference

- **website-project**（网站项目总控）— 若项目属于网站、CMS站点、企业官网或营销页，转入网站总控
- **spec-driven-development**（Spec驱动开发）— 生成需求规格、行为契约和验收标准
- **task-decomposition-and-execution**（任务拆解与执行）— 将项目阶段拆成 Wave 并逐步验证
- **tech-selection**（技术选型）— 技术栈、框架、数据库、队列、缓存和部署方案选型
- **api-design**（API设计）— HTTP API、错误码、认证、分页和接口契约
- **mysql-database**（MySQL数据库）— 表结构、索引、SQL安全、事务、慢查询和迁移回滚
- **cms-development**（CMS二次开发）— PHP/CMS 插件、模板、后台模块和数据访问层
- **frontend-design**（前端设计）— 后台页面、交互状态、响应式和浏览器验证
- **code-generation**（代码生成）— 生成入口、服务、接口、脚本和业务代码
- **code-review**（代码审查）— 审查安全、性能、可维护性和规范符合性
- **test-generation**（测试用例生成）— 生成单元、集成、回归和边界测试
- **doc-generation**（文档生成）— 生成 README、部署说明、使用说明、回滚说明和运维巡检文档
- **project-memory-management**（项目记忆管理）— 沉淀项目配置、架构决策、发布记录和维护规范