docs: 更新V2项目与agent协作文档

2026-06-11 00:20:40 +08:00
4 changed files with 221 additions and 53 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,65 @@
+# Agent Collaboration Guide
+
+This guide is for Codex or other coding agents working in this repository.
+
+## Project Summary
+
+DEMO-AGENT V2 is a Django application for IVD registration document review. The main app is `review_agent`, with workflow modules for file summaries, regulatory review, application form filling, regulatory information package generation, knowledge-base management, and Feishu notification/question handling.
+
+The current `master` branch is intended to match `V2`.
+
+## Important Paths
+
+| Path | Purpose |
+| --- | --- |
+| `config/settings.py` | Django settings and environment loading |
+| `config/urls.py` | Page routes and included API routes |
+| `review_agent/models.py` | Shared Django models |
+| `review_agent/urls.py` | Review-agent API routes |
+| `review_agent/file_summary/` | Attachment handling, file inventory, page count, exports |
+| `review_agent/regulatory_review/` | NMPA review workflow, rules, RAG, risk and issue review |
+| `review_agent/application_form_fill/` | Application form field extraction and Word filling |
+| `review_agent/regulatory_info_package/` | Chapter 1 regulatory information package generation |
+| `review_agent/notifications/` | Notification dispatch and Feishu adapters |
+| `templates/` | Django templates |
+| `static/` | Frontend CSS and JavaScript |
+| `docs/` | Requirements, designs, plans, source materials |
+| `tests/` | pytest suite |
+
+## Development Rules
+
+- Prefer the existing Django patterns in `review_agent` before introducing new abstractions.
+- Keep workflow modules independent. Do not fold regulatory package, application form fill, or regulatory review logic into unrelated modules.
+- Preserve user data and generated artifacts. Do not delete `media/`, `.tmp/`, `db.sqlite3`, or `.env` unless explicitly asked.
+- Treat `.env` as environment-specific configuration. It is currently tracked because this project needs a complete V2 state, but do not print secret values in logs or docs.
+- For Word/PDF/Excel handling, use structured libraries already in the project instead of ad hoc text parsing when possible.
+- For frontend work, keep the current workbench style: restrained, task-focused, evidence-first, and consistent with existing templates and CSS.
+
+## Common Commands
+
+```bash
+python manage.py check
+python manage.py migrate
+python manage.py runserver
+pytest
+pytest tests -k regulatory_info_package
+pytest tests/test_feishu_*.py
+```
+
+## Verification Notes
+
+Before claiming a code change is complete, run at least the narrow test set for the touched workflow. For broad changes, run `python manage.py check` and `pytest`.
+
+Known current state:
+
+- `python manage.py check` passes.
+- `pytest tests -k regulatory_info_package` passes.
+- Full `pytest` may still include a few historical failures unrelated to the latest regulatory-info-package merge; report exact failures if they remain.
+
+## Git Notes
+
+- Check `git status --short --branch` before editing.
+- Do not reset or revert user changes unless explicitly asked.
+- Keep commits grouped by logical concern: docs, feature behavior, tests, cleanup.
+- When merging `V2` and `master`, remember these histories were unrelated before the merge. Prefer preserving the V2 tree when the goal is to keep `master` as the complete V2 state.
+
--- a/PRODUCT.md
+++ b/PRODUCT.md
@@ -1,32 +1,55 @@
 # Product

-## Register
+## Product Name

-product
+DEMO-AGENT V2

 ## Users

-注册资料准备、法规审核和项目管理人员，在资料整理、法规核查、问题整改和申报文件填表过程中使用。
+注册资料准备人员、法规审核人员、项目管理人员和演示评审人员。用户通常需要在资料量大、文件格式复杂、法规要求多、证据链容易断裂的情况下快速完成资料整理、核查、整改和申报文件准备。

 ## Product Purpose

-DEMO-AGENT 是一个体外诊断试剂注册资料审核工作台。它把上传资料、文件汇总、法规规则核查、RAG 依据检索、风险预警、整改复核和申报表填充组织成可追溯的工作流。
+DEMO-AGENT V2 是一个体外诊断试剂注册资料审核工作台。它把上传资料、文件汇总、法规规则核查、RAG 依据检索、风险预警、整改复核、申报表填充和第 1 章监管信息材料包生成组织成可追溯的工作流。
+
+产品目标不是替代法规负责人作最终判断，而是把机械整理、跨文件检索、字段预填、问题归类和证据追溯做扎实，让负责人把精力放在判断和确认上。
+
+## Core Workflows
+
+| 工作流 | 目标产物 |
+| --- | --- |
+| 文件汇总 | 文件目录、页数、类型、批次状态、Markdown/Excel 导出 |
+| 法规核查 | 缺失项、风险项、一致性问题、整改建议、复核记录 |
+| 知识库管理 | 用户资料索引、内置法规资料检索、引用片段 |
+| 申报表填充 | 预填申报表、字段来源、冲突和缺失提示 |
+| 第 1 章监管信息材料包 | CH1.2、CH1.4、CH1.5、CH1.11 等 docx 文件和 zip |
+| 飞书通知与问答 | 批次完成通知、问题模拟查询、系统入口链接 |

 ## Brand Personality

 克制、可信、清晰。界面应服务审核任务，优先呈现状态、证据和下一步动作。

-## Anti-references
+## Anti-References

-避免营销页式大标题、装饰性卡片堆叠、过度动画、过亮的渐变和不必要的视觉噪声。
+避免营销页式大标题、装饰性卡片堆叠、过度动画、过亮渐变和不必要的视觉噪声。不要把审核工作台做成展示型官网，也不要隐藏关键状态或证据来源。

 ## Design Principles

 - 证据优先：每个结论都应能回到来源文件、规则或检索片段。
 - 状态清楚：批次、节点、风险、异常和导出结果要一眼可辨。
 - 操作克制：页面提供必要动作，不把审核工作做成复杂后台。
+- 人工确认：系统负责预处理和提示，法规负责人保留最终确认权。
+- 可追溯：导出文件、消息、节点事件和问题状态都应能回到批次。
 - 复用现有模式：新增页面沿用当前工作台导航、面板、表格和按钮体系。

 ## Accessibility & Inclusion

 默认按 WCAG AA 方向处理对比度、键盘可访问和清晰标签。动效仅用于状态反馈，并尊重减少动态效果需求。
+
+## Operational Boundaries
+
+- `.env` 可用于本地和演示环境，但包含密钥时应限制分发范围。
+- LLM、飞书、Word COM、7z、RAG 索引等外部能力必须允许 mock 或降级。
+- 生成的申报和监管信息文件是预生成结果，需要人工复核后再用于正式申报。
+- 默认存储使用 SQLite 和本地 `media/`，生产环境应迁移到持久化卷和受控备份。
+
--- a/README.md
+++ b/README.md
@@ -1,6 +1,49 @@
 # DEMO-AGENT V2

-V2 是一个重置后的最小 Django 项目，仅保留基础配置和登录页面。
+DEMO-AGENT V2 是一个面向体外诊断试剂注册资料准备与审核的 Django 工作台。系统把资料上传、文件目录汇总、法规核查、知识库检索、风险提示、整改复核、申报表自动填充和第 1 章监管信息材料包生成组织到同一个可追溯的审核流程中。
+
+当前 `master` 已与 `V2` 内容对齐，是项目主线。
+
+## 核心能力
+
+| 能力 | 说明 |
+| --- | --- |
+| 审核工作台 | 登录后进入首页，查看对话、附件、知识库、批次和处理状态 |
+| 对话式工作流 | 在 `/chat/` 中围绕当前对话上传资料、触发汇总、法规核查和生成任务 |
+| 文件汇总 | 读取 PDF、Word、Excel、PowerPoint、压缩包等资料，生成目录、页数、类型和导出结果 |
+| NMPA 法规核查 | 基于规则、文本抽取、RAG 检索和 LLM 复核生成问题、风险和整改建议 |
+| 知识库管理 | 上传管理资料、重建索引、检索引用片段，并过滤已停用或删除文档 |
+| 申报表填充 | 从说明书和资料中抽取关键字段，生成预填申报表和追溯结果 |
+| 第 1 章监管信息材料包 | 生成 CH1.2、CH1.4、CH1.5、CH1.11 等监管信息文件和 zip 产物 |
+| 飞书通知与问答 | 支持企业自建应用消息通知，并预留飞书问答模拟命令 |
+
+## 页面入口
+
+| 页面 | 路径 |
+| --- | --- |
+| 登录页 | `http://127.0.0.1:8000/login/` |
+| 首页 | `http://127.0.0.1:8000/` |
+| 审核智能体 | `http://127.0.0.1:8000/chat/` |
+| 知识库管理 | `http://127.0.0.1:8000/knowledge-base/` |
+| 附件管理 | `http://127.0.0.1:8000/attachments/` |
+| 管理后台 | `http://127.0.0.1:8000/admin/` |
+
+## 项目结构
+
+```text
+config/                         Django 配置和总路由
+review_agent/                   核心业务应用
+  application_form_fill/         申报表自动填充
+  file_summary/                  文件汇总、附件和导出
+  regulatory_review/             法规核查与整改复核
+  regulatory_info_package/       第 1 章监管信息材料包生成
+  notifications/                 飞书通知和消息适配
+  feishu_questions/              飞书问答预留能力
+static/                         前端脚本和样式
+templates/                      Django 模板
+docs/                           需求、设计、开发计划和原始材料
+tests/                          pytest 测试
+```

 ## 本地运行

@@ -13,65 +56,68 @@ python manage.py createsuperuser
 python manage.py runserver
 ```

-访问：
+项目会自动读取仓库根目录 `.env`。当前仓库保留了 V2 的 `.env` 文件；后续如果要面向外部协作，请先确认其中没有不应公开的密钥。

- 登录页：http://127.0.0.1:8000/login/
- 首页：http://127.0.0.1:8000/
- 管理后台：http://127.0.0.1:8000/admin/
-
-## 文件汇总依赖
-
-自动汇总文件目录与页数功能使用轻量 Python 库读取 PDF、Word、Excel、PowerPoint 文件。
-Docker 或生产环境如需处理 `.7z` 与 `.rar` 压缩包，还需要安装系统 `7z`/`p7zip`
-命令，并确认以下命令可用：
-
-```bash
-7z
-7z i
-```
-
-LibreOffice 不是必需依赖，仅作为未来增强老格式文档解析的可选能力。
-
-上传原始文件、批次工作目录和导出文件默认存储在 Django `MEDIA_ROOT` 下的
-`file_summary/users/<user_id>/<conversation_id>/` 或批次 `work_dir` 目录中。生产环境
-需要把 `MEDIA_ROOT` 挂载到持久化卷，并纳入备份或归档策略。
-
-## 飞书通知与问答预留
-
-飞书接入使用企业自建应用/智能体的消息 API。敏感信息只允许写入本地 `.env`
-或部署环境变量，不要提交真实 App Secret、tenant token、open_id 或 user_id。
-
-常用环境变量：
+## 常用环境变量

 | 变量名 | 用途 |
 | --- | --- |
-| `FEISHU_NOTIFY_ENABLED` | 是否启用真实飞书通知，未启用时只写未启用记录 |
-| `FEISHU_NOTIFY_CHANNEL` | 通知通道，首期使用 `feishu_api` |
+| `DJANGO_SECRET_KEY` | Django secret key |
+| `DJANGO_DEBUG` | 是否开启调试模式 |
+| `DJANGO_ALLOWED_HOSTS` | 允许访问的主机列表 |
+| `LLM_PROVIDER` | LLM provider 选择 |
+| `LLM_API_KEY` | LLM API key |
+| `LLM_BASE_URL` | OpenAI 兼容 LLM API 地址 |
+| `LLM_MODEL` | 默认对话/抽取模型 |
+| `SILICONFLOW_API_KEY` | SiliconFlow API key，默认可复用 `LLM_API_KEY` |
+| `SILICONFLOW_EMBEDDING_MODEL` | 法规 RAG 使用的 embedding 模型 |
+| `SILICONFLOW_EMBEDDING_DIMENSIONS` | embedding 维度 |
+| `REGULATORY_RAG_CHROMA_PATH` | 法规 RAG Chroma 存储路径 |
+| `REGULATORY_RAG_COLLECTION` | 法规 RAG collection 名称 |
+| `FEISHU_NOTIFY_ENABLED` | 是否启用真实飞书通知 |
 | `FEISHU_APP_ID` | 飞书应用 App ID |
 | `FEISHU_APP_SECRET` | 飞书应用 App Secret |
-| `FEISHU_DEFAULT_USER_OPEN_ID` | 默认个人接收人的 open_id，优先使用 |
-| `FEISHU_DEFAULT_USER_ID` | 默认个人接收人的 user_id，open_id 为空时使用 |
-| `FEISHU_DEFAULT_TARGET_NAME` | 默认接收人展示名，用于记录和页面展示 |
-| `FEISHU_TENANT_TOKEN_CACHE_SECONDS` | tenant_access_token 缓存秒数 |
-| `PUBLIC_BASE_URL` | 飞书消息中的系统入口根地址，默认 `http://127.0.0.1:8000` |
+| `FEISHU_DEFAULT_USER_OPEN_ID` | 默认飞书接收人 open_id |
+| `PUBLIC_BASE_URL` | 飞书消息中的系统入口根地址 |

-自动化测试会 mock 飞书 token API 和消息 API，不请求真实飞书接口。真实发送只通过
-本地手动命令验证：
+## 外部依赖

-```bash
-python manage.py send_test_feishu_notification --username owner
-```
+Python 依赖见 `requirements.txt`，主要包括：

-问答预留能力可用本地模拟命令验证：
+- Django
+- PyYAML
+- httpx
+- chromadb
+- pypdf
+- python-docx
+- python-pptx
+- openpyxl / xlrd
+- py7zr
+- playwright

-```bash
-python manage.py feishu_question_simulate --username owner "查最新法规核查"
-```
+文件汇总支持 `.7z` 和 `.rar` 时，运行环境还需要可用的 `7z`/`p7zip` 命令。LibreOffice 不是必需依赖，仅作为后续增强老格式文档处理能力的可选项。

-集中测试建议在补齐 `.env` 后执行：
+## 常用命令

 ```bash
 python manage.py check
+pytest
+pytest tests -k regulatory_info_package
 pytest tests/test_feishu_*.py
-pytest tests/test_file_summary_workflow.py tests/test_regulatory_notification.py tests/test_application_form_fill_notification.py
+python manage.py send_test_feishu_notification --username owner
+python manage.py feishu_question_simulate --username owner "查最新法规核查"
 ```
+
+已知情况：当前全量 `pytest` 中仍有少量历史测试与当前页面/LLM 调用策略不完全一致；监管信息材料包主链路测试已通过。
+
+## 文档入口
+
+- [产品说明](PRODUCT.md)
+- [Agent 协作约定](AGENTS.md)
+- [docs 文档索引](docs/README.md)
+- [需求分析](docs/1.需求分析)
+- [功能设计](docs/2.功能设计)
+- [数据库设计](docs/3.数据库设计)
+- [详细设计](docs/4.详细设计)
+- [开发计划](docs/5.开发计划)
+
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,34 @@
+# Documentation Index
+
+This directory keeps the working documents for DEMO-AGENT V2. The docs are organized by project phase rather than by code module.
+
+## Main Sections
+
+| Directory | Purpose |
+| --- | --- |
+| `0.原始材料/` | Source materials, templates, sample instructions, regulatory references |
+| `1.需求分析/` | Requirement analysis for each workflow |
+| `2.功能设计/` | Functional design and user-facing behavior |
+| `3.数据库设计/` | Data model and persistence design |
+| `4.详细设计/` | Module-level design, services, workflow details |
+| `5.开发计划/` | Implementation plans and staged delivery notes |
+| `6.待办计划/` | Deferred items |
+| `7.汇报材料/` | Presentation and reporting material |
+
+## Workflow Documents
+
+| Workflow | Requirement | Functional Design | Detailed Design | Plan |
+| --- | --- | --- | --- | --- |
+| 自动汇总 | `1.需求分析/1.自动汇总.md` | `2.功能设计/1.自动汇总.md` | `4.详细设计/1.自动汇总.md` | `5.开发计划/1.自动汇总.md` |
+| NMPA 注册资料法规核查 | `1.需求分析/2.NMPA注册资料法规核查与整改闭环.md` | `2.功能设计/2.NMPA注册资料法规核查与整改闭环.md` | `4.详细设计/2.NMPA注册资料法规核查与整改闭环.md` | `5.开发计划/2.NMPA注册资料法规核查与整改闭环-第一批主链路.md` |
+| 申报文件自动填表 | `1.需求分析/3.产品关键信息提取与申报文件自动填表.md` | `2.功能设计/3.产品关键信息提取与申报文件自动填表.md` | `4.详细设计/3.产品关键信息提取与申报文件自动填表.md` | `5.开发计划/3.产品关键信息提取与申报文件自动填表.md` |
+| 飞书通知与问答 | `1.需求分析/4.飞书通知与问答接入.md` | `2.功能设计/4.飞书通知与问答接入.md` | `4.详细设计/4.飞书通知与问答接入.md` | `5.开发计划/4.飞书通知与问答接入.md` |
+| 第 1 章监管信息材料包 | `1.需求分析/5.第1章监管信息材料包生成.md` | `2.功能设计/5.第1章监管信息材料包生成.md` | `4.详细设计/5.第1章监管信息材料包生成.md` | `5.开发计划/5.第1章监管信息材料包生成.md` |
+
+## Maintenance Notes
+
+- Keep README-level docs aligned with current `master`.
+- When a workflow changes behavior, update the requirement/design/plan document closest to that behavior.
+- Do not paste secrets from `.env` into docs.
+- Prefer concrete file paths, command examples, and verification notes over broad prose.
+