Project Analyzer - SDD 软件设计文档生成器

Harness Engineering 核心理念：AI 是一匹拥有神力的独角兽，力量强大但难以预测。我们不是去拔掉它的角，而是为它打造黄金缰绳和水晶马车。

⚠️ 关键原则：先读取，后生成（所有文档类型）

┌────────────────────────────────────────────────────────────────────┐
│ 文档生成流程（强制） │
├────────────────────────────────────────────────────────────────────┤
│ │
│ 第1步: 扫描相关文件 │
│ ↓ │
│ 第2步: 【必须】逐个读取文件完整内容 ← 禁止跳过任何文件 │
│ ↓ │
│ 第3步: 整理提取的关键信息 │
│ ↓ │
│ 第4步: 生成文档（基于实际内容） │
│ ↓ │
│ 第5步: 自检：对照原始文件验证文档准确性 │
│ ↓ │
│ 第6步: 输出文档 │
│ │
│ ⚠️ 禁止在未读取文件内容的情况下生成文档 │
│ ⚠️ 禁止假设任何技术细节 │
│ ⚠️ 生成后必须对照原始文件进行自检 │
│ │
└────────────────────────────────────────────────────────────────────┘

---

📋 SDD 文档体系

docs/
├── sdd/
│ ├── 01-srs.md # 软件需求规格说明书
│ ├── 02-sad.md # 软件架构文档
│ ├── 03-sdd.md # 详细设计文档
│ ├── 04-dbd.md # 数据库设计文档
│ ├── 05-apid.md # API 接口文档
│ └── 06-tsd.md # 测试设计文档
└── standards/ # 开发规范

---

🔍 各文档类型的扫描规范

📋 SRS - 软件需求规格说明书

必须读取的文件：

文件类型	扫描目标
README.md	项目简介、功能概述
需求文档

业务需求、功能列表 |
| 接口文档 | API 列表、功能模块 |
| 用户故事 | User Story、验收标准 |

扫描命令：

bash

1. 读取 README

cat /path/to/project/README.md

2. 查找需求文档

find /path/to/project -name .md -path /docs/ -o -name 需求 -o -name requirement*

3. 查找接口定义（用于识别功能模块）

find /path/to/project -path /controller/.java -name *Controller.java

---

🏗️ SAD - 软件架构文档

必须读取的文件：

文件类型	扫描目标
pom.xml / go.mod	技术栈、依赖版本
application.yml

数据库、缓存、消息队列配置 |
| Dockerfile | 部署方式、基础镜像 |
| k8s/*.yaml | Kubernetes 部署配置 |
| README.md | 架构说明 |
| 模块目录结构 | 层级架构 |

扫描命令：

bash

1. 读取构建配置

cat /path/to/project/pom.xml
cat /path/to/project/Dockerfile

2. 读取应用配置

cat /path/to/project/*/src/main/resources/application.yml cat /path/to/project/application.yml

3. 读取 K8s 配置

ls -la /path/to/project/k8s/ cat /path/to/project/k8s/*.yaml

4. 扫描模块结构

find /path/to/project -maxdepth 3 -type d | head -50

技术栈判断依据：

判断依据	技术栈结论
<parent><artifactId>spring-boot-starter-parent</artifactId>	Spring Boot
<artifactId>spring-boot-starter-parent</artifactId><version>3.x</version>

Spring Boot 3.x + Java 17+ |
| spring-boot-starter-parent2.x | Spring Boot 2.x + Java 8/11 |
| 基础镜像 openjdk: | Java |
| FROM node: | Node.js |
| FROM python: | Python |
| mybatis-spring-boot-starter | MyBatis |
| spring-boot-starter-data-jpa | JPA/Hibernate |

---

📝 SDD - 详细设计文档

必须读取的文件：

文件类型	扫描目标
所有 Controller.java	接口列表、请求参数
所有 Service.java

业务逻辑、方法签名 |
| 所有 VO/DTO/BO.java | 数据结构 |
| 所有 Entity.java / DO.java | 数据库实体 |
| Mapper XML | SQL 语句 |
| 枚举类 | 状态码、业务常量 |

扫描命令：

bash

1. 扫描所有 Java 源文件

find /path/to/project -name .java -path /src/main/java/* | wc -l

2. 按层级扫描

find /path/to/project -path /controller/.java -name *.java find /path/to/project -path /service/.java -name *.java find /path/to/project -path /dao/.java -o -path /mapper/.java | grep -i java

3. 读取核心类（不能只读类名，要读完整内容）

cat /path/to/project//service/impl/ServiceImpl.java

4. 扫描枚举和常量

find /path/to/project -name Enum.java -o -name Constant.java -o -name Status.java

SDD 自检清单：

□ 所有 Controller 接口已读取
□ 所有 Service 实现类已读取
□ 类图中的方法签名与实际代码一致
□ 时序图中的调用关系与实际代码一致
□ 枚举值与实际代码一致
□ 没有臆造的方法或类

---

🗄️ DBD - 数据库设计文档

必须读取的文件：

文件类型	扫描目标
所有 *.sql 文件	CREATE TABLE、索引、约束
所有 Entity.java / DO.java

实体映射、字段类型 |
| 所有 Mapper.xml | SQL 语句 |
| 迁移记录 | 版本历史 |

扫描命令：

bash

1. 查找所有 SQL 文件

find /path/to/project -name *.sql -type f

2. 查找迁移脚本目录（常见名称）

ls -la /path/to/project/db-migration/ ls -la /path/to/project/migrations/ ls -la /path/to/project/sql/ ls -la /path/to/project/scripts/

3. 【必须】逐个读取 SQL 文件

cat /path/to/project/db-migration/*.sql

4. 查找 DO/Entity 类

find /path/to/project -name DO.java -o -name Entity.java -o -name *PO.java

【必须】对照验证：

SQL 文件 CREATE TABLE ←→ DO/Entity 类注解

SQL 字段	SQL 类型	DO 字段	DO 类型
id	bigint	@TableId	Long
name

varchar(255) | @TableField | String |
| status | smallint | @TableField | Short |
| create_time | timestamp | @TableField | LocalDateTime |

数据库类型判断：

判断依据	数据库类型
AUTO_INCREMENT, ENGINE=InnoDB, CHARSET=	MySQL
SERIAL, GENERATED ALWAYS AS IDENTITY, ::regclass

PostgreSQL |
| NUMBER GENERATED BY DEFAULT AS IDENTITY, CLOB | Oracle |
| IDENTITY(1,1), nvarchar, GETDATE() | SQL Server |

---

📡 APID - API 接口文档

必须读取的文件：

文件类型	扫描目标
所有 @RestController / @Controller	接口定义
所有 @RequestMapping / @GetMapping / @PostMapping 等

HTTP 方法、路径 |
| 所有 @RequestBody DTO | 请求参数 |
| 所有返回值类型 | 响应结构 |
| @Valid / @