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