DVC 设计文件需求清单检查工具标准技术文件（Software Specification）
软件名称: dvc_check_require_interface.py
DVC 接口检查工具 程序名：dvc_check_require_interface.py
目标与用途
本程序用于作为接口工具，通过指定设计路径 <phase>/<block>/<stage>/<version>，自动查找相应的 STG_REQ_FILE_LIST 规则文件，并调用 dvc_check_require.py 对当前版本的设计文件进行校验，确认是否符合设计交付要求。
输入参数
| 参数名 | 类型 | 描述 |
|---|---|---|
stage_path | 字符串 | 格式必须为 <phase>/<block>/<stage>/<version>，不可多或少 |
环境变量要求
程序运行前必须设置以下环境变量：
| 环境变量名 | 描述 |
|---|---|
DVC_LOCAL | 本地设计数据库的根路径 |
DVC_HOME | 中央规则数据库的根路径 |
若任一未设定，将输出 fail 并退出。
STG_REQ_FILE_LIST 查找逻辑（优先级）
依下列优先顺序查找存在的规则文件，找到后即停止：
${DVC_LOCAL}/<phase>/<block>/<stage>/<version>/STG_REQ_FILE_LIST${DVC_LOCAL}/<phase>/<block>/<stage>/STG_REQ_FILE_LIST${DVC_HOME}/stage/<stage>/STG_REQ_FILE_LIST
若三处均无文件存在，程序将返回：
fail
STG_REQ_FILE_LIST not found in any candidate path
检查路径定义
程序将始终对以下路径进行检查：
${DVC_LOCAL}/<phase>/<block>/<stage>/<version>
行为流程
- 解析用户传入的
stage_path - 验证并提取
<phase>/<block>/<stage>/<version>四级路径 - 根据查找顺序定位
STG_REQ_FILE_LIST - 调用外部程序
dvc_check_require.py：dvc_check_require.py –check_path <resolved_path> –req_list_path <rules_file> - 捕获其标准输出与返回码并据此决定本程序的输出结果
输出格式
成功
pass
失败示例
- 设计文件缺失：fail
Missing design_file_item: SYMBOL_TABLE
Required patterns: [‘.*\.tbl’] - 格式错误：fail
Invalid stage_path format. Expected <phase>/<block>/<stage>/<version> - 环境变量缺失：fail
Missing DVC_LOCAL or DVC_HOME environment variable
命令行使用方式
export DVC_LOCAL=/path/to/local/dvc
export DVC_HOME=/path/to/global/home
python3 dvc_check_require_interface.py logic/gpu001/syn/GL
外部依赖
- Python 3.6+
- 环境变量：
DVC_LOCAL与DVC_HOME - 可调用的
dvc_check_require.py，需存在于$PATH中
异常处理
| 异常类型 | 输出结果 |
|---|---|
| 参数格式错误 | fail + Invalid stage_path format |
| 环境变量未设置 | fail + Missing DVC_LOCAL or DVC_HOME |
| 查找规则失败 | fail + STG_REQ_FILE_LIST not found |
| 程序执行失败 | fail + Error running dvc_check_require.py |
软件名称: dvc_check_require.py
DVC 文件需求检查工具 程序名：`dvc_check_require.py
目标与用途
本程序用于根据指定规则文件（STG_REQ_FILE_LIST）检查一个设计文件目录下是否包含所需的设计文件。主要应用于设计数据交付前的自动验证流程，确保设计文件目录中包含所有必要文件。
输入说明
1. --check_path
- 类型：路径（string）
- 描述：要检查的设计文件目录路径，程序将递归扫描此目录下所有文件。
2. --req_list_path
- 类型：文件路径（string）
- 描述：规则定义文件路径（STG_REQ_FILE_LIST）。用于描述每类设计文件应满足的正则表达式与要求级别。
STG_REQ_FILE_LIST 文件格式
每一行表示一个设计文件类型的检查规则，格式如下：
<design_file_item> <operator> <expression1> <expression2> ...
规则语法说明
<design_file_item>：逻辑名称，用于标识一类设计文件，如VERILOG_FILE、SYMBOL_TABLE。<operator>：+=：必要项，必须至少存在一个文件符合任一表达式；*=：可选项，目录中可以没有，但若有文件存在，则必须符合任一表达式。
<expression>：使用/.../包裹的正则表达式，用于匹配文件路径。
示例：
# 注释与空行将被忽略
VERILOG_FILE += /.*\.v/ /.*\.gv/
VERILOG_TOP *= /.*_top\.v/
SYMBOL_TABLE += /.*\.tbl/
程序行为说明
- 程序读取并解析规则文件
STG_REQ_FILE_LIST。 - 递归扫描
check_path下所有文件路径。 - 对每一个
design_file_item项目：- 若为
+=，且无任何文件匹配其表达式，记录为失败； - 若为
*=，不强制要求有匹配项，但存在的文件需符合表达式。
- 若为
- 根据是否存在不满足的
+=项目，决定程序整体返回结果。
输出说明
命令行输出：
- 若所有必要项（
+=）都满足条件：
pass
- 若存在未满足的必要项：
fail
Missing design_file_item: SYMBOL_TABLE
Required patterns: ['.*\.tbl']
程序退出码（Exit Code）：
0：检查通过1：检查失败
使用范例
python dvc_check_require.py --check_path ./design_v1 --req_list_path ./STG_REQ_FILE_LIST
依赖环境
- Python 3.6+
- 标准库模块：
argparse,re,pathlib,sys
限制与说明
- 所有表达式需使用
/regex/格式编写，内部为 Python 风格正则表达式。 - 暂不支持多个规则文件合并处理。
- 检查范围仅为文件路径，不解析文件内容。