kanfu-panda 旧项目接入 PDLC
扫描现有项目结构，逆向生成基线文档，并进行健康检查发现潜在问题。让旧项目平滑接入 PDLC 流程。
核心原则
- 只生文档，不动代码：不修改任何现有代码，仅生成基线文档
- 增量接入：旧代码标记为"已接入基线"，只有新功能走完整 PDLC
- 守卫畅通：生成的基线文档满足守卫检查，后续命令不再被阻断
子命令解析
从 $ARGUMENTS 中解析子命令：
| 子命令 | 说明 |
|---|---|
scan |
扫描项目，输出接入报告 + 健康检查报告（不写任何文件，只读分析） |
init |
根据扫描结果，逆向生成基线文档到 docs/ 目录 |
如果未提供子命令或无法识别，输出以上帮助信息后停止。
scan 子命令
全程只读，不创建/修改任何文件，只在终端输出报告。
第一步：项目结构识别
技术栈检测
- 检查特征文件：
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 依赖推断）
- 检查特征文件：
服务/应用识别
- 微服务：扫描
backend/services/或具有独立启动入口的子目录 - 单体服务：根目录即为服务
- 前端应用：扫描
frontend/、web/、app/或具有前端框架特征的目录 - 记录每个服务/应用的名称、技术栈、入口文件
- 微服务：扫描
数据库识别
- 从配置文件推断数据库类型（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 生成文档。
执行流程
- 执行与
scan相同的扫描逻辑（收集项目信息） - 检查
docs/下是否已有同名基线文档，已存在则跳过（避免覆盖） - 创建 PDLC 标准目录结构（如不存在）：
docs/ ├── 00_standards/ ├── 01_requirements/prd/ ├── 02_design/ │ ├── api/ │ ├── architecture/ │ └── database/ ├── 03_development/ ├── 04_testing/ ├── 05_deployment/ └── 07_reviews/ - 逆向生成基线文档（详见下方）
- 生成接入状态文件
- 输出生成结果摘要
基线文档生成规则
所有基线文档以 ADOPTED- 前缀命名，与正常 PDLC 文档区分。
所有文档头部包含接入标记：
<!-- 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 接入状态：
# 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`）
要求
- scan 子命令严格只读，不创建/修改任何文件
- init 子命令不修改任何现有代码文件，只在
docs/目录下创建文档 - 已存在的文档不覆盖，跳过并提示
- 基线文档中需人工补充的部分用
> ⚠️引用块明确标注 - 健康检查问题必须给出具体的文件路径和行号
- 读取
.claude/templates/pdlc/adopt-report-template.md模板作为格式参考
接入操作: $ARGUMENTS
本命令的 handoff 输出：
✅ PDLC 接入基线文档 完成
📦 产出：docs/**（基线文档集）
👉 下一步：（本次流程结束，无后续）