pdlc-adopt git:20260507.ba956b7A

Immutable. This exact content is served forever at /api/v1/blob/e6ffa531c5d0a26f.

---
name: pdlc-adopt
description: 旧项目接入 PDLC
argument-hint: [项目目录]
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
layer: 3
stage: lifecycle
produces:
  - docs/**
requires: []
next_step: null
terminal_state: null
---

# 旧项目接入 PDLC

<!-- @include templates/prompts/iron-law.md -->

扫描现有项目结构，逆向生成基线文档，并进行健康检查发现潜在问题。让旧项目平滑接入 PDLC 流程。

## 核心原则

- **只生文档，不动代码**：不修改任何现有代码，仅生成基线文档
- **增量接入**：旧代码标记为"已接入基线"，只有新功能走完整 PDLC
- **守卫畅通**：生成的基线文档满足守卫检查，后续命令不再被阻断

## 子命令解析

从 `$ARGUMENTS` 中解析子命令：

| 子命令 | 说明 |
|--------|------|
| `scan` | 扫描项目，输出接入报告 + 健康检查报告（不写任何文件，只读分析） |
| `init` | 根据扫描结果，逆向生成基线文档到 docs/ 目录 |

如果未提供子命令或无法识别，输出以上帮助信息后停止。

---

## scan 子命令

**全程只读，不创建/修改任何文件，只在终端输出报告。**

### 第一步：项目结构识别

1. **技术栈检测**
   - 检查特征文件：`package.json`、`pom.xml`、`build.gradle`、`go.mod`、`requirements.txt`、`Pipfile`、`Cargo.toml`、`mix.exs` 等
   - 识别框架：Spring Boot、Express、NestJS、FastAPI、Gin、Echo、Django、Rails 等
   - 检查前端框架：`react`、`vue`、`next`、`angular`（从 package.json 依赖推断）

2. **服务/应用识别**
   - 微服务：扫描 `backend/services/` 或具有独立启动入口的子目录
   - 单体服务：根目录即为服务
   - 前端应用：扫描 `frontend/`、`web/`、`app/` 或具有前端框架特征的目录
   - 记录每个服务/应用的名称、技术栈、入口文件

3. **数据库识别**
   - 从配置文件推断数据库类型（MySQL/PostgreSQL/MongoDB/Redis 等）
   - 扫描 ORM 配置（TypeORM/Sequelize/GORM/SQLAlchemy/MyBatis/JPA 等）
   - 检查已有 migration 目录

### 第二步：API 接口提取

按技术栈扫描路由定义：

| 技术栈 | 扫描目标 |
|--------|---------|
| Spring Boot | `@RequestMapping`、`@GetMapping`、`@PostMapping` 等注解 |
| Express/NestJS | `router.get/post/put/delete`、`@Get/@Post` 装饰器 |
| FastAPI | `@app.get/post/put/delete`、`@router.get/post` |
| Go (Gin/Echo) | `r.GET/POST/PUT/DELETE`、`e.GET/POST` |
| Django | `urlpatterns`、`path()`、`re_path()` |

提取信息：HTTP 方法、路径、处理函数名、参数（如能识别）。

### 第三步：数据库结构提取

| 来源 | 提取方式 |
|------|---------|
| ORM Model | 扫描实体类/模型定义，提取表名、字段名、字段类型、关联关系 |
| Migration 文件 | 扫描 `migrations/`、`db/migrate/` 等目录，提取 DDL 变更历史 |
| SQL 文件 | 扫描 `*.sql` 文件，提取 CREATE TABLE 语句 |

### 第四步：已有文档检测

- 检查 `README.md` 内容丰富度
- 检查 `docs/` 目录及子目录
- 检查是否已有 PDLC 文档（`docs/01_requirements/`、`docs/02_design/` 等）
- 如已有 PDLC 文档，标记为"已存在，跳过生成"

### 第五步：健康检查（潜在问题扫描）

对代码进行静态分析级别的检查，按严重程度分级：

#### 🔴 阻断级（必须修复才能安全上线）

- **安全漏洞**
  - SQL 拼接（字符串拼接构建 SQL 而非参数化查询）
  - 硬编码密钥/密码（代码中直接写死的 secret、password、api_key）
  - 未鉴权的敏感接口（涉及用户数据的接口无鉴权中间件）

#### 🟠 严重级（高风险，建议尽快修复）

- **数据风险**
  - 高频查询字段无索引（WHERE/JOIN 条件中的字段无对应索引）
  - 外键关系逻辑不一致（代码中的关联关系与数据库定义不匹配）
  - 无软删除机制（直接物理删除，无法恢复）
- **API 风险**
  - 接口无参数校验（直接使用用户输入，无 validation）
  - 接口无错误处理（缺少 try-catch 或错误中间件）

#### 🟡 一般级（影响质量，建议改进）

- **一致性问题**
  - 文档与代码不一致（如 README 描述的接口与实际不符）
  - Model 定义与数据库 schema 不一致
  - 命名不规范（混用 camelCase 和 snake_case）
- **代码质量**
  - N+1 查询模式（循环中执行数据库查询）
  - 未使用的依赖包
  - 重复代码块

#### 🔵 建议级（优化项）

- 缺少日志记录
- 缺少监控指标
- 缺少 API 文档注解
- 测试覆盖率不足

### 输出格式

```
📊 项目扫描报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 一、项目结构

| 项目 | 详情 |
|------|------|
| 技术栈 | Java Spring Boot 2.7 + MySQL 8.0 |
| 后端服务 | 3 个（user-service, order-service, product-service） |
| 前端应用 | 1 个（web-admin, React 18） |
| 数据库 | MySQL（12 张表） |
| 已有文档 | README.md（简略）、无 PDLC 文档 |

## 二、可生成的基线文档

| 文档类型 | 是否可生成 | 内容预估 |
|---------|-----------|---------|
| 基线 PRD | ✅ 可生成 | 从 README + 服务结构推断，需人工补充业务目标 |
| API 设计文档 | ✅ 可生成 | 提取到 45 个接口定义 |
| DB 设计文档 | ✅ 可生成 | 提取到 12 张表结构 |
| 架构概要 | ✅ 可生成 | 3 服务 + 1 前端的依赖关系图 |

## 三、健康检查报告

### 🔴 阻断 (2)

| # | 位置 | 问题 | 风险 | 修复建议 |
|---|------|------|------|---------|
| 1 | user-service/src/.../UserDao.java:45 | SQL 字符串拼接 | SQL 注入 | 改用 PreparedStatement 参数化查询 |
| 2 | config/application.yml:12 | 数据库密码明文硬编码 | 凭证泄露 | 使用环境变量或密钥管理服务 |

### 🟠 严重 (3)
...

### 🟡 一般 (5)
...

### 🔵 建议 (4)
...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
统计：🔴 2 | 🟠 3 | 🟡 5 | 🔵 4 | 总计 14 个问题

💡 建议：先修复 🔴 阻断级问题，再运行 /pdlc-adopt init 生成基线文档。
```

---

## init 子命令

**建议先运行 `scan` 查看报告，再运行 `init` 生成文档。**

### 执行流程

1. 执行与 `scan` 相同的扫描逻辑（收集项目信息）
2. 检查 `docs/` 下是否已有同名基线文档，已存在则跳过（避免覆盖）
3. 创建 PDLC 标准目录结构（如不存在）：
   ```
   docs/
   ├── 00_standards/
   ├── 01_requirements/prd/
   ├── 02_design/
   │   ├── api/
   │   ├── architecture/
   │   └── database/
   ├── 03_development/
   ├── 04_testing/
   ├── 05_deployment/
   └── 07_reviews/
   ```
4. 逆向生成基线文档（详见下方）
5. 生成接入状态文件
6. 输出生成结果摘要

### 基线文档生成规则

所有基线文档以 `ADOPTED-` 前缀命名，与正常 PDLC 文档区分。

所有文档头部包含接入标记：
```markdown
<!-- PDLC-TRACE -->
<!-- PDLC-ADOPTED -->
<!-- 项目名称: my-project -->
<!-- 接入日期: YYYY-MM-DD -->
<!-- 阶段: 接入基线 -->
<!-- 说明: 由 /pdlc-adopt init 自动生成，内容基于代码逆向推断，需人工审核补充 -->
```

#### 基线 PRD

- 路径：`docs/01_requirements/prd/ADOPTED-<项目名>-prd.md`
- 内容来源：README + 服务列表 + API 接口分组推断功能模块
- 包含：项目背景（从 README 提取）、功能模块清单（从代码推断）、技术栈说明
- **明确标注**：`> ⚠️ 以下内容由代码逆向推断，业务目标和用户故事需人工补充`

#### 基线 API 设计文档

- 路径：`docs/02_design/api/ADOPTED-<服务名>-api.md`（每个服务一个）
- 内容来源：路由定义扫描结果
- 包含：接口列表表格（方法、路径、描述、参数）、按模块分组
- 使用 `templates/api-design-template.md` 的格式
- **明确标注**：`> ⚠️ 接口描述基于函数名推断，请核对补充`

#### 基线 DB 设计文档

- 路径：`docs/02_design/database/ADOPTED-<服务名>-db.md`（每个服务一个）
- 内容来源：ORM Model / Migration / SQL 文件
- 包含：ER 关系图（文本格式）、表结构定义、索引设计、公共字段约定
- 使用 `templates/db-design-template.md` 的格式
- **明确标注**：`> ⚠️ 表结构从代码提取，请核对与实际数据库是否一致`

#### 基线架构文档

- 路径：`docs/02_design/architecture/ADOPTED-<项目名>-arch.md`
- 内容来源：服务列表 + 依赖关系 + 配置文件
- 包含：系统架构图（文本格式）、服务清单和职责、技术栈说明、服务间通信方式
- **明确标注**：`> ⚠️ 架构描述基于代码结构推断，请核对补充`

#### 接入状态文件

- 路径：`docs/00_standards/adopt-status.md`
- 记录各模块的 PDLC 接入状态：

```markdown
# PDLC 接入状态

> 由 `/pdlc-adopt init` 生成于 YYYY-MM-DD

## 接入概况

| 模块 | 基线 PRD | API 设计 | DB 设计 | 架构文档 | 测试覆盖 | 状态 |
|------|---------|---------|---------|---------|---------|------|
| user-service | ✅ | ✅ | ✅ | ✅ | ⚠️ 待补充 | 基线完成 |
| order-service | ✅ | ✅ | ✅ | ✅ | ⚠️ 待补充 | 基线完成 |

## 健康检查问题跟踪

| # | 级别 | 位置 | 问题 | 状态 |
|---|------|------|------|------|
| 1 | 🔴 | UserDao.java:45 | SQL 拼接 | 待修复 |
| 2 | 🔴 | application.yml:12 | 密码硬编码 | 待修复 |

## 后续建议

1. 人工审核基线文档，补充业务目标和用户故事
2. 修复 🔴 阻断级健康问题
3. 新功能开发使用 `/pdlc-feature` 走完整 PDLC 流程
4. 旧功能改造时从 `/pdlc-design` 开始（基线 PRD 已满足守卫检查）
5. 逐步为核心模块补充单元测试（使用 `/pdlc-tdd`）
```

---

## 要求

<!-- @include templates/prompts/output-language.md -->
- scan 子命令**严格只读**，不创建/修改任何文件
- init 子命令不修改任何现有代码文件，只在 `docs/` 目录下创建文档
- 已存在的文档不覆盖，跳过并提示
- 基线文档中需人工补充的部分用 `> ⚠️` 引用块明确标注
- 健康检查问题必须给出具体的文件路径和行号
- 读取 `.claude/templates/pdlc/adopt-report-template.md` 模板作为格式参考

接入操作: $ARGUMENTS

<!-- @include templates/prompts/handoff.md -->

**本命令的 handoff 输出：**

```
✅ PDLC 接入基线文档 完成
📦 产出：docs/**（基线文档集）
👉 下一步：（本次流程结束，无后续）
```