DEMO-AGENT/docs/需求分析/1.config模块需求分析.md

Config 模块需求分析

1. 模块定位

config 模块负责整个注册申报资料审核系统的运行底座。它不直接承担业务审核、信息抽取或报告生成，但它决定了系统能否以稳定、可控、可讲解的方式启动、读取资料、装配规则、连接模型、管理上传目录并支撑 Docker 演示。

在当前题目下，config 不应再被理解为一个普通 Django 配置目录，而应被视为“注册资料审核平台的环境装配层”。

2. 模块目标

本模块需要实现以下目标：

1. 让系统能够在本地开发、测试、复试演示和 Docker 演示环境中稳定启动。
2. 为法规资料、上传文件、解析结果、向量库和审计数据提供清晰的路径规范。
3. 将与模型、RAG、规则包、文件解析、导出目录相关的参数统一配置化。
4. 保证测试环境可离线执行，不因为本地真实模型密钥存在而影响回归测试。
5. 为后续从“通用 Demo”切换到“注册申报垂直系统”的配置迁移提供兼容空间。

3. 业务背景下的配置需求

3.1 本题不是单纯的聊天页项目

题面要求系统处理的是“整包注册资料”，这意味着配置层必须面向文件密集型、规则密集型场景设计。与普通问答系统相比，本题配置上至少多出以下关注点：

• 上传目录不仅要按场景分，还要考虑按项目批次、申报轮次、资料章节分层。
• 规则来源不止一个 YAML，可能包括法规目录模板、字段抽取模板、一致性校验规则、风险分级规则，以及公告附件原文所对应的结构化法规包。
• 文档解析链路中可能同时使用 pdfplumber、PyMuPDF、Word 解析库、OCR 预留能力，因此要有可切换的解析策略配置。
• 审计数据不能只保留“问答日志”，还要能关联具体资料批次和审核任务。

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 回填结果与新生成文档导出目录。

• RULESET_DIR 法规目录模板、字段规则、风险规则所在目录。

• REG_SOURCE_DIR 法规原文与公告附件所在目录。

• CHROMA_PATH 向量库目录。

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 直接取页数、Word 按分页符或估算策略。

• DOCX_PARSE_STRATEGY 例如“仅提取文本”“提取文本和表格”“保留章节层级”。

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

  用于支持飞书应用、机器人入口、事件回调和 CLI / MCP 工具接入。

这三个配置很关键，因为题面中的法规条目和样例材料未来可能变化，系统必须能讲清楚“按哪个版本在审”。

新增公告附件包后，这类版本配置的重要性进一步提高，因为系统不仅要说明“按哪个资料目录模板在审”，还要说明“按哪个公告附件包和哪个文件格式要求在审”。

6. 路径与目录结构需求

6.1 建议的目录设计

为贴合真实业务，建议在数据目录下形成类似结构：

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/

这样的结构比“统一丢进某个场景目录”更适合注册资料业务，因为它天然支持：

• 同一产品多轮申报
• 同一项目多批资料
• 原始文件与处理中间结果分离
• 规则版本独立维护
• 注册申报、变更备案、延续注册可分开维护规则包
• 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 页数统计和解析策略提供显式配置位。
5. 增加法规原文目录、法规流程类型和文件格式模板版本配置。
6. 增加 Word 导出目录和飞书应用接入相关配置。

11. 本模块验收标准

本模块需求完成后，应达到以下验收状态：

1. 一套 .env 即可完成本地和 Docker 演示环境启动。
2. 系统目录结构能清楚承载“原始资料、抽取结果、规则、报告、向量库”五类资产。
3. 模型调用、RAG、规则开关、文档处理策略均配置化，不散落在业务代码中。
4. 测试环境在有真实 API Key 的机器上仍能稳定离线跑通。
5. 后续模块在引用路径、规则和模型参数时不再写死常量。