365 lines
12 KiB
Markdown
365 lines
12 KiB
Markdown
# Config 模块需求分析
|
||
|
||
## 1. 模块定位
|
||
|
||
`config` 模块负责整个注册申报资料审核系统的运行底座。它不直接承担业务审核、信息抽取或报告生成，但它决定了系统能否以稳定、可控、可讲解的方式启动、读取资料、装配规则、连接模型、管理上传目录并支撑 Docker 演示。
|
||
|
||
在当前题目下，`config` 不应再被理解为一个普通 Django 配置目录，而应被视为“注册资料审核平台的环境装配层”。
|
||
|
||
## 2. 模块目标
|
||
|
||
本模块需要实现以下目标：
|
||
|
||
1. 让系统能够在本地开发、测试、复试演示和 Docker 演示环境中稳定启动。
|
||
2. 为法规资料、上传文件、解析结果、向量库和审计数据提供清晰的路径规范。
|
||
3. 将与模型、RAG、规则包、文件解析、导出目录相关的参数统一配置化。
|
||
4. 保证测试环境可离线执行，不因为本地真实模型密钥存在而影响回归测试。
|
||
5. 为后续从“通用 Demo”切换到“注册申报垂直系统”的配置迁移提供兼容空间。
|
||
|
||
## 3. 业务背景下的配置需求
|
||
|
||
### 3.1 本题不是单纯的聊天页项目
|
||
|
||
题面要求系统处理的是“整包注册资料”，这意味着配置层必须面向文件密集型、规则密集型场景设计。与普通问答系统相比，本题配置上至少多出以下关注点：
|
||
|
||
- 上传目录不仅要按场景分，还要考虑按项目批次、申报轮次、资料章节分层。
|
||
- 规则来源不止一个 YAML，可能包括法规目录模板、字段抽取模板、一致性校验规则、风险分级规则，以及公告附件原文所对应的结构化法规包。
|
||
- 文档解析链路中可能同时使用 `pdfplumber`、`PyMuPDF`、Word 解析库、OCR 预留能力，因此要有可切换的解析策略配置。
|
||
- 压缩包处理链路需要支持 `zip`、`rar`、`7z`，其中 `rar` 和 `7z` 必须使用纯 Python 依赖实现，不能依赖服务器系统级解压工具。
|
||
- 审计数据不能只保留“问答日志”，还要能关联具体资料批次和审核任务。
|
||
|
||
但与此同时，最新版原型已经明确本系统不是“传统多页面审核后台”，而是“以 Agent 对话为核心、资料包为主要业务对象”的产品形态。因此配置层不仅要支撑资料处理和规则加载，还要支撑以下对象级配置：
|
||
|
||
- 资料包与会话绑定规则
|
||
- 会话标题生成规则
|
||
- 资料包列表默认搜索字段
|
||
- 顶层导航与功能开关
|
||
|
||
### 3.2 Demo 与真实业务之间要有明确边界
|
||
|
||
复试时允许 Demo 版做适度简化，但配置层必须明确什么是“演示默认值”，什么是“未来真实化扩展口”。否则系统很容易出现代码里写死演示路径、文档目录、模型名称、法规版本的情况，后续一改题就要整体返工。
|
||
|
||
## 4. 核心职责
|
||
|
||
`config` 模块建议承担以下职责：
|
||
|
||
### 4.1 系统运行配置
|
||
|
||
负责 Django 基础设置，包括：
|
||
|
||
- 应用注册
|
||
- 模板目录
|
||
- 静态资源目录
|
||
- 数据库连接
|
||
- URL 总入口
|
||
- 中间件
|
||
- 时区与语言
|
||
|
||
在本题中，这些基础配置的重点不是“全不全”，而是“是否足够清楚、便于解释”。
|
||
|
||
### 4.2 业务路径配置
|
||
|
||
需要统一管理以下路径：
|
||
|
||
- 原始上传文件根目录
|
||
- 法规原文资料目录
|
||
- 文本抽取中间结果目录
|
||
- 结构化抽取结果目录
|
||
- 向量库目录
|
||
- 规则文件目录
|
||
- 审核报告导出目录
|
||
- 审计附件目录
|
||
|
||
建议不要仅保留 `UPLOAD_ROOT` 和 `CHROMA_PATH` 两个路径，而是扩展出更贴合本题的目录配置。
|
||
|
||
### 4.3 模型与检索配置
|
||
|
||
负责管理：
|
||
|
||
- LLM 基础地址、模型名、超时、温度等参数
|
||
- Embedding 配置
|
||
- RAG 检索开关
|
||
- 向量库实现选择
|
||
- 本地规则优先 / LLM 辅助优先策略
|
||
|
||
本题的法规完整性核查、一致性检查，很多内容应以规则为主、模型为辅，因此配置层应支持这种策略切换。
|
||
|
||
同时，考虑到新增公告附件包中同时存在“注册申报”“变更备案 / 变更注册”“延续注册”等不同业务类型，配置层还应支持按任务类型切换规则集。
|
||
|
||
### 4.4 环境隔离与安全控制
|
||
|
||
负责确保：
|
||
|
||
- 本地 `.env` 中存在真实密钥时，测试仍默认使用 mock provider。
|
||
- 日志中不输出 API Key。
|
||
- Docker 演示环境能通过 `.env` 或 `env_file` 快速启动。
|
||
- 解析目录、导出目录不存在时能够自动创建。
|
||
|
||
## 5. 需要支撑的业务配置项
|
||
|
||
### 5.1 项目级配置项
|
||
|
||
建议保留或新增以下项目级环境变量：
|
||
|
||
- `PROJECT_MODE`
|
||
用于标识当前运行模式，如 `demo`、`review`、`offline-test`。
|
||
|
||
- `SCENARIO_CONFIG_DIR`
|
||
当前场景配置根目录，但语义上应逐步过渡为“任务配置目录”。
|
||
|
||
- `UPLOAD_ROOT`
|
||
原始上传文件保存目录。
|
||
|
||
- `EXTRACTED_TEXT_ROOT`
|
||
文本抽取结果目录。
|
||
|
||
- `STRUCTURED_OUTPUT_ROOT`
|
||
结构化抽取结果目录。
|
||
|
||
- `REPORT_EXPORT_ROOT`
|
||
审核报告导出目录。
|
||
|
||
- `WORD_EXPORT_ROOT`
|
||
Word 回填结果与新生成文档导出目录。
|
||
|
||
- `WORD_TEMPLATE_ROOT`
|
||
可直接报送级 Word 模板库目录。
|
||
|
||
- `RULE_ADMIN_UPLOAD_ROOT`
|
||
规则包、切片文件和人工校订结果上传目录。
|
||
|
||
- `RULESET_DIR`
|
||
法规目录模板、字段规则、风险规则所在目录。
|
||
|
||
- `REG_SOURCE_DIR`
|
||
法规原文与公告附件所在目录。
|
||
|
||
- `CHROMA_PATH`
|
||
向量库目录。
|
||
|
||
建议增加：
|
||
|
||
- `CONVERSATION_TITLE_SOURCE`
|
||
会话标题来源。V1 默认使用解析后的 `product_name`。
|
||
|
||
- `MATERIAL_SEARCH_FIELDS`
|
||
资料包列表默认搜索字段。V1 默认包含 `product_name,batch_id`。
|
||
|
||
- `TOP_LEVEL_TABS`
|
||
顶层页面开关。V1 默认固定为 `chat,materials,knowledge,history`。
|
||
|
||
### 5.2 模型级配置项
|
||
|
||
- `LLM_PROVIDER`
|
||
- `LLM_API_KEY`
|
||
- `LLM_BASE_URL`
|
||
- `LLM_MODEL`
|
||
- `LLM_TIMEOUT`
|
||
- `LLM_TEMPERATURE`
|
||
- `EMBEDDING_API_KEY`
|
||
- `EMBEDDING_BASE_URL`
|
||
- `EMBEDDING_MODEL`
|
||
|
||
建议增加：
|
||
|
||
- `LLM_ENABLE_FOR_RULE_CHECK`
|
||
用于控制法规完整性校验时是否允许 LLM 参与解释和兜底。
|
||
|
||
- `LLM_ENABLE_FOR_FIELD_EXTRACTION`
|
||
用于区分“规则抽取优先”还是“模型抽取优先”。
|
||
|
||
### 5.3 文档处理配置项
|
||
|
||
- `ALLOWED_UPLOAD_TYPES`
|
||
首版至少应支持 `pdf`、`docx`、`doc`、`md`、`txt`，必要时预留图片。
|
||
|
||
- `MAX_UPLOAD_SIZE_MB`
|
||
控制 Demo 环境下的上传体积。
|
||
|
||
- `ENABLE_OCR`
|
||
是否启用 OCR 兜底。
|
||
|
||
- `PAGE_COUNT_STRATEGY`
|
||
页数统计策略。PDF 和 DOCX 必须精确统计页数；DOC 如无法精确统计，应标记为待人工复核。
|
||
|
||
- `DOCX_PARSE_STRATEGY`
|
||
例如“仅提取文本”“提取文本和表格”“保留章节层级”。
|
||
|
||
- `ARCHIVE_EXTRACT_STRATEGY`
|
||
压缩包解包策略。V1 要求 `zip`、`rar`、`7z` 均通过 Python 依赖实现，并保留原始相对路径。
|
||
|
||
- `ARCHIVE_CHAPTER_SOURCE`
|
||
章节点识别依据。V1 默认使用压缩包内多层目录作为章节点识别依据。
|
||
|
||
### 5.4 规则与版本配置项
|
||
|
||
- `REG_RULESET_VERSION`
|
||
当前启用的法规规则版本。
|
||
|
||
- `REG_TEMPLATE_VERSION`
|
||
当前启用的申报目录模板版本。
|
||
|
||
- `FIELD_SCHEMA_VERSION`
|
||
当前产品关键信息字段定义版本。
|
||
|
||
- `REG_WORKFLOW_TYPE`
|
||
当前审核任务所对应的法规流程类型，如 `registration`、`change`、`renewal`。
|
||
|
||
- `REG_FORMAT_TEMPLATE_VERSION`
|
||
当前启用的批准证明文件格式模板版本。
|
||
|
||
- `FEISHU_APP_ID`
|
||
- `FEISHU_APP_SECRET`
|
||
- `FEISHU_BOT_NAME`
|
||
- `FEISHU_ENABLE_CHANNEL`
|
||
- `FEISHU_CALLBACK_URL`
|
||
- `FEISHU_CLI_ENABLED`
|
||
- `FEISHU_GROUP_BOT_ENABLED`
|
||
- `FEISHU_ACCOUNT_MAPPING_SOURCE`
|
||
|
||
用于支持飞书应用、机器人入口、事件回调和 CLI / MCP 工具接入。
|
||
|
||
这三个配置很关键，因为题面中的法规条目和样例材料未来可能变化，系统必须能讲清楚“按哪个版本在审”。
|
||
|
||
新增公告附件包后，这类版本配置的重要性进一步提高，因为系统不仅要说明“按哪个资料目录模板在审”，还要说明“按哪个公告附件包和哪个文件格式要求在审”。
|
||
|
||
## 6. 路径与目录结构需求
|
||
|
||
### 6.1 建议的目录设计
|
||
|
||
为贴合真实业务，建议在数据目录下形成类似结构：
|
||
|
||
```text
|
||
data/
|
||
uploads/
|
||
<project_id>/
|
||
raw/
|
||
normalized/
|
||
extracted/
|
||
<project_id>/
|
||
text/
|
||
tables/
|
||
metadata/
|
||
reports/
|
||
<project_id>/
|
||
chroma/
|
||
rules/
|
||
registration/
|
||
completeness/
|
||
format/
|
||
essential-principles/
|
||
extraction/
|
||
consistency/
|
||
risk/
|
||
knowledge/
|
||
templates/
|
||
admin/
|
||
rule_updates/
|
||
template_library/
|
||
responsibility_mapping/
|
||
```
|
||
|
||
这样的结构比“统一丢进某个场景目录”更适合注册资料业务，因为它天然支持：
|
||
|
||
- 同一产品多轮申报
|
||
- 同一项目多批资料
|
||
- 原始文件与处理中间结果分离
|
||
- 规则版本独立维护
|
||
- 注册申报、变更备案、延续注册可分开维护规则包
|
||
- Word 输出模板与导出结果独立管理
|
||
- 规则切片、人工校订结果和模板库可独立维护
|
||
|
||
### 6.2 路径命名要求
|
||
|
||
路径命名应尽量避免中文自由命名直接成为目录主键，建议在展示层保留中文，在系统层使用稳定 ID。例如：
|
||
|
||
- `project_id`
|
||
- `submission_batch_id`
|
||
- `document_id`
|
||
- `ruleset_version`
|
||
|
||
这样可以避免 Windows 路径、导出路径和 Docker 挂载时出现兼容问题。
|
||
|
||
## 7. 与其他模块的协作边界
|
||
|
||
### 7.1 与 Documents 模块的边界
|
||
|
||
`config` 只负责定义上传目录、抽取目录、导出目录、搜索字段和允许格式，不负责具体解析逻辑。
|
||
|
||
### 7.2 与 Agent Core 的边界
|
||
|
||
`config` 负责提供模型参数、向量库参数、规则目录、会话标题规则和功能开关，不负责具体提示词、抽取模板和审核规则实现。
|
||
|
||
### 7.3 与 Audit 模块的边界
|
||
|
||
`config` 负责定义审计数据落库所需的全局参数和日志脱敏策略，不负责审计内容写入。
|
||
|
||
## 8. 首版必须满足的功能性要求
|
||
|
||
### 8.1 启动要求
|
||
|
||
1. 本地 `python manage.py runserver` 可直接启动。
|
||
2. `python manage.py check` 无配置错误。
|
||
3. Docker Compose 可根据 `.env` 一键启动。
|
||
|
||
### 8.2 配置回退要求
|
||
|
||
1. 未配置 Embedding 专用地址时，允许复用 LLM 地址。
|
||
2. 未配置某些导出目录时，系统自动创建。
|
||
3. 未配置在线模型时，测试环境默认使用 mock provider。
|
||
|
||
### 8.3 错误提示要求
|
||
|
||
当配置错误时，不能只报 Python 异常栈，应尽量给出面向演示者可理解的提示，例如：
|
||
|
||
- “未配置法规规则目录，无法执行完整性检查”
|
||
- “上传目录不可写，请检查 UPLOAD_ROOT”
|
||
- “当前禁用了 LLM 抽取，系统将仅按规则执行”
|
||
|
||
## 9. 非功能要求
|
||
|
||
### 9.1 可演示性
|
||
|
||
配置项不能过度复杂。即便底层支持很多开关，复试演示时也应能用少量环境变量说明清楚系统如何启动。
|
||
|
||
### 9.2 可迁移性
|
||
|
||
应支持从当前“多场景 Demo”平滑迁移到“注册申报审核专用系统”，因此配置命名和目录规划要尽量中性、可扩展。
|
||
|
||
### 9.3 可测试性
|
||
|
||
配置必须允许测试注入临时目录、临时规则目录和 Mock Provider，确保文档解析、审计、页面测试都不依赖真实外部服务。
|
||
|
||
## 10. 当前代码基线下的重构建议
|
||
|
||
### 10.1 保留项
|
||
|
||
建议保留现有：
|
||
|
||
- Django 配置组织方式
|
||
- `.env` 自动加载方式
|
||
- LLM / Embedding 兼容式配置思路
|
||
- Docker Compose 基本启动方式
|
||
|
||
### 10.2 需要调整项
|
||
|
||
1. 将当前偏“通用 Demo”的命名改造成更贴近注册申报业务的配置语义。
|
||
2. 增加抽取结果目录、报告目录、规则目录等配置。
|
||
3. 增加法规规则版本与字段 schema 版本配置。
|
||
4. 为 `.doc`、`.docx`、PDF 页数统计和解析策略提供显式配置位，其中 DOCX 页数必须精确统计。
|
||
5. 增加法规原文目录、法规流程类型和文件格式模板版本配置。
|
||
6. 增加 Word 导出目录和飞书应用接入相关配置。
|
||
7. 增加模板库目录、规则管理目录和责任人映射配置。
|
||
8. 增加纯 Python 压缩包解包依赖与策略配置，覆盖 `zip`、`rar`、`7z`。
|
||
9. 增加资料包与会话绑定、会话命名和资料包搜索字段相关配置。
|
||
|
||
## 11. 本模块验收标准
|
||
|
||
本模块需求完成后，应达到以下验收状态：
|
||
|
||
1. 一套 `.env` 即可完成本地和 Docker 演示环境启动。
|
||
2. 系统目录结构能清楚承载“原始资料、抽取结果、规则、报告、向量库”五类资产。
|
||
3. 模型调用、RAG、规则开关、文档处理策略均配置化，不散落在业务代码中。
|
||
4. 测试环境在有真实 API Key 的机器上仍能稳定离线跑通。
|
||
5. 后续模块在引用路径、规则和模型参数时不再写死常量。
|