# 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/ / raw/ normalized/ extracted/ / text/ tables/ metadata/ reports/ / 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. 后续模块在引用路径、规则和模型参数时不再写死常量。