docs: complete documentation system (250+ files)

- System architecture and design documentation - Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST) - ASL module complete design (quality assurance, tech selection) - Platform layer and common capabilities docs - Development standards and API specifications - Deployment and operations guides - Project management and milestone tracking - Architecture implementation reports - Documentation templates and guides
2025-11-16 15:43:55 +08:00
parent 0fe6821a89
commit e52020409c
173 changed files with 46227 additions and 11964 deletions
--- a/docs/00-系统总体设计/00-核心问题解答.md
+++ b/docs/00-系统总体设计/00-核心问题解答.md
@@ -0,0 +1,698 @@
+# 核心问题解答
+
+> **创建日期：** 2025-11-06  
+> **文档目的：** 回答用户提出的关键架构问题
+
+---
+
+## 📋 您提出的问题
+
+您提出了非常核心的架构问题，这些问题直接影响了整个系统的设计。让我逐一深入解答：
+
+---
+
+## 1️⃣ 文档系统重构
+
+### 您的建议
+
+> （1）系统总体架构、总体需求PRD、系统总体设计、系统总体部署等，应该是一个独立的文件夹  
+> （2）7个模块应该是独立的7个文件夹，每个模块有：项目概述、设计文档、业务规则、开发计划、每日进度、部署文档
+
+### 我的回复
+
+✅ **完全认同！这是非常正确的架构思路！**
+
+我已经创建了详细的文档重构方案：
+- 📄 [文档体系重构方案](./02-文档体系重构方案.md)
+
+**新文档结构：**
+```
+docs/
+  ├── 00-系统总体设计/          # ✅ 总体独立
+  │   ├── 01-系统架构分层设计.md
+  │   ├── 02-文档体系重构方案.md
+  │   ├── 03-总体需求文档(PRD).md
+  │   ├── 04-技术架构白皮书.md
+  │   └── 05-部署架构设计.md
+  │
+  ├── 01-平台基础层/           # 平台层（用户权限、存储、通知等）
+  ├── 02-通用能力层/           # 通用能力（LLM网关、文档处理、RAG等）
+  │
+  └── 03-业务模块/             # ✅ 7个模块独立
+      ├── AIA-AI智能问答/
+      ├── ASL-AI智能文献/
+      ├── PKB-个人知识库/
+      ├── DC-数据清洗整理/
+      ├── SSA-智能统计分析/
+      ├── ST-统计分析工具/
+      └── RVW-稿件审查系统/
+```
+
+**每个模块的标准结构：**
+```
+XXX-模块名称/
+  ├── 00-项目概述/         # PRD、功能清单、用户故事
+  ├── 01-设计文档/         # 技术架构、数据库、API、前端组件、UI原型
+  ├── 02-业务规则/         # 业务规则、验证规则
+  ├── 03-开发计划/         # 里程碑、任务分解
+  ├── 04-测试文档/         # 测试计划、测试用例
+  ├── 05-部署文档/         # 部署指南、配置说明
+  ├── 06-开发进度/         # 每日/每周进度（可选）
+  └── README.md           # 模块导航
+```
+
+**核心优势：**
+- ✅ 总体与模块分离
+- ✅ 层次清晰（平台层、通用能力层、业务模块层）
+- ✅ 支持模块独立销售（每个模块文档可独立打包）
+- ✅ 易于扩展（新增模块复制模板即可）
+
+---
+
+## 2️⃣ 不考虑混合部署
+
+### 您的决策
+
+> 只考虑云端、本地化（私有化）、单机版，不考虑混合部署
+
+### 我的回复
+
+✅ **完全赞同！混合部署技术难度极高，需求不明确，应该暂缓。**
+
+**调整后的部署模式：**
+| 部署模式 | 目标用户 | 技术难度 | 优先级 |
+|---------|---------|---------|-------|
+| **云端SaaS版** | 个人用户、小机构 | ⭐⭐⭐ 中等 | P0（当前） |
+| **私有化部署** | 医院、大机构 | ⭐⭐⭐⭐ 高 | P1（阶段二） |
+| **单机版（Electron）** | 个人医生 | ⭐⭐⭐⭐⭐ 很高 | P2（阶段二） |
+| ~~混合部署~~ | ~~高级客户~~ | ~~⭐⭐⭐⭐⭐ 极高~~ | ❌ 不考虑 |
+
+**简化后的好处：**
+- ✅ 降低技术复杂度
+- ✅ 聚焦核心场景
+- ✅ 加快开发速度
+- ✅ 降低维护成本
+
+**阶段规划：**
+```
+阶段一（当前-6个月）：云端SaaS版
+- 专注云端部署
+- 验证市场需求
+- 快速迭代
+
+阶段二（6-18个月）：私有化部署
+- 触发条件：有客户明确要求
+- 引入K8s
+- Docker一键部署
+
+阶段三（18个月+）：单机版（可选）
+- 触发条件：有大量单机版需求
+- 开发Electron应用
+- 本地化运行
+```
+
+---
+
+## 3️⃣ 审稿系统的独立性
+
+### 您的计划
+
+> 未来还会增加一个审稿系统的开发，目前已经有核心审稿功能了，可能需要独立成一个系统
+
+### 我的回复
+
+✅ **审稿系统非常适合独立！这是一个极具商业价值的决策！**
+
+**为什么审稿系统适合独立？**
+
+**1. 用户群完全不同**
+```
+主平台用户：临床医生、研究者
+审稿系统用户：期刊编辑部、出版社、学会
+
+→ 两类用户没有交集，完全独立
+```
+
+**2. 业务逻辑完全独立**
+```
+主平台：科研全流程（统计分析、文献筛选、数据清洗）
+审稿系统：稿件审查流程（投稿、审稿、修改、决策）
+
+→ 业务逻辑无关联
+```
+
+**3. 部署场景独立**
+```
+主平台：云端SaaS为主，部分私有化
+审稿系统：期刊编辑部独立部署
+
+→ 部署需求不同
+```
+
+**4. 商业模式独立**
+```
+主平台：按版本订阅（基础版、高级版、旗舰版）
+审稿系统：按期刊订阅，或按稿件数量计费
+
+→ 商业模式完全不同
+```
+
+**当前状态：**
+- ✅ 核心功能已实现（文档提取、规范性评估、方法学评估）
+- ✅ 数据库表已独立（review_tasks）
+- ⚠️ 需要扩展（审稿人管理、审稿流程、多轮审稿）
+
+**建议：**
+```
+短期（当前）：
+- 审稿系统作为主平台的一个模块
+- 但在架构设计上保持独立（独立Schema、独立API）
+
+中期（6-12个月）：
+- 开发完整审稿系统（审稿人、流程、多轮审稿）
+- 验证市场需求
+
+长期（12个月+）：
+- 完全独立为单独产品"AI辅助审稿系统"
+- 独立部署、独立销售
+- 目标客户：期刊编辑部、出版社
+```
+
+**独立销售价值：⭐⭐⭐⭐⭐ 极高！**
+- 市场空白：国内缺乏AI审稿工具
+- 刚需：期刊编辑部审稿压力大
+- 付费能力强：期刊有预算
+
+---
+
+## 4️⃣ 总体 vs 通用 vs 模块独立
+
+### 您的核心问题
+
+> 哪些是总体的？哪些是通用的技术能力？哪些是各模块独立的？  
+> 哪些能力是复用的？哪些技术架构可以复用？
+
+### 我的回复
+
+这是最核心的架构问题！我已经创建了详细的架构分层设计：
+- 📄 [系统架构分层设计](./01-系统架构分层设计.md)
+
+**三层架构总览：**
+
+### 第一层：平台基础层（Platform Layer）
+
+**定义：** 所有业务模块的地基，提供通用的基础设施能力
+
+**包含模块：**
+1. ✅ **用户与权限中心（UAM）** - 用户认证、权限管理、Feature Flag
+2. ✅ **存储服务** - 文件上传下载、OSS/本地文件系统
+3. ✅ **通知服务** - 站内消息、邮件、WebSocket推送
+4. ✅ **监控与日志** - 操作日志、错误日志、审计日志
+5. ✅ **系统配置** - 系统级配置管理
+
+**特征：**
+- ✅ 全局唯一（整个平台只有一套）
+- ✅ 业务无关（不涉及具体业务逻辑）
+- ✅ 强依赖性（所有业务模块都必须依赖）
+- ✅ 稳定性高（很少变动）
+
+---
+
+### 第二层：通用能力层（Capability Layer）
+
+**定义：** 跨业务模块共享的核心技术能力
+
+**包含能力：**
+
+#### 1. LLM大模型网关 ⭐⭐⭐⭐⭐ **最核心**
+
+**职责：**
+- 统一管理所有LLM调用
+- 根据用户版本动态切换模型
+- 成本控制与限流
+- Token计数与计费
+
+**使用模块：**
+- ✅ AIA（AI智能问答）
+- ✅ ASL（AI智能文献）
+- ✅ PKB（个人知识库）
+- ✅ DC（数据清洗）
+- ✅ RVW（稿件审查）
+
+**复用率：** 5/7 = 71%
+
+**为什么是核心？**
+```
+这是商业模式的技术保障：
+- 基础版：只能用DeepSeek-V3（¥1/百万tokens）
+- 高级版：可用DeepSeek + Qwen3
+- 旗舰版：可用DeepSeek + Qwen3 + Qwen-Long + Claude
+
+成本控制：
+- 统一监控所有LLM API调用
+- 超出配额自动限流
+- 按版本计费
+```
+
+**当前状态：** ❌ 未实现（P0优先级）
+
+---
+
+#### 2. 文档处理引擎 ⭐⭐⭐⭐⭐ **最核心**
+
+**职责：**
+- 多格式文档提取（PDF/Docx/Txt/Excel）
+- 文本清洗与预处理
+- OCR处理
+- 表格提取
+
+**使用模块：**
+- ✅ ASL（文献PDF提取）
+- ✅ PKB（知识库文档）
+- ✅ DC（Excel/Docx导入）
+- ✅ SSA（数据导入）
+- ✅ ST（数据导入）
+- ✅ RVW（稿件提取）
+
+**复用率：** 6/7 = 86%
+
+**当前状态：** ✅ 已实现（Python微服务）
+
+---
+
+#### 3. RAG引擎 ⭐⭐⭐⭐ **核心**
+
+**职责：**
+- 向量化存储（Embedding）
+- 语义检索（Semantic Search）
+- 检索增强生成（RAG）
+
+**使用模块：**
+- ✅ PKB（个人知识库问答）
+- ✅ ASL（文献内容检索）
+- ✅ AIA（@知识库问答）
+
+**复用率：** 3/7 = 43%
+
+**当前状态：** ✅ 已实现（基于Dify）
+
+---
+
+#### 4. 数据ETL引擎 ⭐⭐⭐ **中等**
+
+**职责：**
+- Excel多表JOIN
+- 数据清洗
+- 数据转换
+
+**使用模块：**
+- ✅ DC（数据清洗）
+- ✅ SSA（统计分析数据预处理）
+
+**复用率：** 2/7 = 29%
+
+**当前状态：** ❌ 未实现（P2优先级）
+
+---
+
+#### 5. 医学NLP引擎 ⭐⭐⭐ **中等**
+
+**职责：**
+- 医学实体识别（NER）
+- 医学术语标准化
+
+**使用模块：**
+- ✅ DC（病例数据NER提取）
+
+**复用率：** 1/7 = 14%
+
+**当前状态：** ❌ 未实现（P2优先级）
+
+---
+
+### 第三层：业务模块层（Product Layer）
+
+**定义：** 面向用户的产品功能，每个模块都是独立的产品单元
+
+**7个业务模块：**
+
+| 模块 | 名称 | 商业价值 | 独立性 | 状态 |
+|------|------|---------|-------|------|
+| **AIA** | AI智能问答 | ⭐⭐⭐⭐ | ⭐⭐⭐ | ✅ 已完成 |
+| **ASL** | AI智能文献 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⏳ 下一步重点 |
+| **PKB** | 个人知识库 | ⭐⭐⭐ | ⭐⭐⭐ | ✅ 已完成 |
+| **DC** | 数据清洗整理 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⏳ 规划中 |
+| **SSA** | 智能统计分析 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⏳ 规划中 |
+| **ST** | 统计分析工具 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⏳ 规划中 |
+| **RVW** | 稿件审查系统 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⚡ 独立系统 |
+
+**特征：**
+- ✅ 独立部署：可以单独打包部署
+- ✅ 独立销售：可以单独售卖
+- ✅ 低耦合：模块间不直接依赖
+- ✅ 高内聚：模块内功能完整
+
+---
+
+### 可复用能力总结
+
+| 能力 | 使用频率 | 复用模块数 | 优先级 | 状态 |
+|------|---------|-----------|--------|------|
+| **LLM网关** | 71% | 5/7 | P0 | ❌ 待实现 |
+| **文档处理引擎** | 86% | 6/7 | P0 | ✅ 已实现 |
+| **RAG引擎** | 43% | 3/7 | P1 | ✅ 已实现 |
+| **ETL引擎** | 29% | 2/7 | P2 | ❌ 待实现 |
+| **医学NLP** | 14% | 1/7 | P2 | ❌ 待实现 |
+
+---
+
+## 5️⃣ 数据库架构
+
+### 您的问题
+
+> 设计多Schema架构是非常必要的。  
+> 目前当前系统的数据库似乎是DIFY的？  
+> 目前我们有自己独立的数据库吗？
+
+### 我的回复
+
+✅ **我们有自己独立的PostgreSQL数据库，不是Dify的！**
+
+**当前数据库情况：**
+
+```typescript
+// 数据源：backend/prisma/schema.prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+```
+
+**当前表结构：**
+```
+当前数据库（PostgreSQL，独立于Dify）：
+├── users                    # 用户表
+├── projects                 # 项目表
+├── conversations            # 对话表（AI问答）
+├── messages                 # 消息表
+├── knowledge_bases          # 知识库表
+├── documents                # 文档表
+├── admin_logs               # 管理员日志
+├── general_conversations    # 通用对话
+├── general_messages         # 通用消息
+├── batch_tasks              # 批处理任务（Phase 3）
+├── batch_results            # 批处理结果
+├── task_templates           # 任务模板
+└── review_tasks             # 稿件审查任务
+
+Dify数据库（完全独立）：
+├── dify自己的表（不在我们的数据库）
+└── 通过Dify API调用，不直接访问
+```
+
+**关键澄清：**
+- ✅ 我们有自己的PostgreSQL数据库
+- ✅ Dify有自己的数据库（我们不直接访问）
+- ✅ 我们通过Dify API调用（HTTP REST API）
+- ✅ 两个数据库完全独立
+
+**但是存在的问题：**
+- ❌ **所有表在同一Schema（public）**
+- ❌ 未来微服务拆分困难
+- ❌ 不支持模块独立部署
+
+---
+
+### Schema隔离方案
+
+**目标架构：**
+```sql
+-- 平台层Schema
+CREATE SCHEMA platform_schema;
+  ├── users
+  ├── roles
+  ├── permissions
+  ├── feature_flags
+  ├── notifications
+  └── admin_logs
+
+-- 通用能力Schema
+CREATE SCHEMA capability_schema;
+  ├── llm_usage_logs
+  ├── llm_quotas
+  └── document_processing_logs
+
+-- 业务模块Schema
+CREATE SCHEMA aia_schema;        -- AI智能问答
+  ├── aia_projects
+  ├── aia_conversations
+  └── aia_messages
+
+CREATE SCHEMA asl_schema;        -- AI智能文献
+  ├── asl_projects
+  ├── asl_literature_items
+  ├── asl_screening_results
+  └── ...
+
+CREATE SCHEMA pkb_schema;        -- 个人知识库
+  ├── pkb_knowledge_bases
+  └── pkb_documents
+
+CREATE SCHEMA dc_schema;         -- 数据清洗
+  ├── dc_projects
+  ├── dc_raw_files
+  └── dc_cleaned_data
+
+CREATE SCHEMA ssa_schema;        -- 智能统计分析
+  ├── ssa_projects
+  └── ssa_analysis_tasks
+
+CREATE SCHEMA st_schema;         -- 统计分析工具
+  └── st_tool_usage
+
+CREATE SCHEMA review_schema;     -- 稿件审查
+  ├── review_tasks
+  ├── review_journals
+  ├── review_reviewers
+  └── review_workflows
+```
+
+---
+
+### 迁移策略
+
+**阶段一：逻辑隔离（当前阶段，立即实施）**
+```
+目标：在代码层面按Schema组织，但数据库还是public
+方式：Prisma中使用@@map指定表名前缀
+
+例如：
+model AiaProject {
+  id        String @id @default(uuid())
+  // ...
+  @@map("aia_projects")     // 表名前缀标识模块
+}
+
+model AslProject {
+  id        String @id @default(uuid())
+  // ...
+  @@map("asl_projects")
+}
+
+model DcProject {
+  id        String @id @default(uuid())
+  // ...
+  @@map("dc_projects")
+}
+```
+
+**好处：**
+- ✅ 立即可实施，无需数据迁移
+- ✅ 为未来物理隔离打基础
+- ✅ 代码层面已经按模块组织
+
+---
+
+**阶段二：物理隔离（微服务拆分时，阶段二）**
+```
+目标：真正创建独立Schema
+时机：当需要拆分某个模块为独立微服务时
+
+步骤：
+1. CREATE SCHEMA xxx_schema;
+2. CREATE TABLE xxx_schema.table_name ...
+3. INSERT INTO xxx_schema.table SELECT * FROM public.old_table;
+4. 更新Prisma Schema（指定schema）
+5. 测试验证
+6. 切换生产
+```
+
+---
+
+## 6️⃣ 下一步开发重点
+
+### 您的决策
+
+> 下一步着重开发的功能肯定是AI智能文献模块。  
+> 当然在总体架构讨论清楚前，我们先不开发。
+
+### 我的回复
+
+✅ **完全赞同！AI智能文献是核心竞争力，应该是下一步重点。**
+
+**开发顺序建议：**
+
+**第一步：架构设计（本周，1-2天）**
+```
+P0文档（必须完成）：
+1. ✅ 系统架构分层设计（已完成）
+2. ✅ 文档体系重构方案（已完成）
+3. ⚠️ LLM大模型网关设计（关键）
+4. ⚠️ 数据库Schema隔离方案（关键）
+```
+
+**第二步：文档整理（本周，1-2天）**
+```
+1. 调整ASL模块文档结构（按新模板）
+2. 补充缺失的设计文档
+3. 明确开发里程碑
+```
+
+**第三步：关键技术验证（下周，1-2天）**
+```
+1. ⚠️ R语言技术验证（SSA模块需要，可延后）
+2. ⚠️ LLM Gateway原型验证
+3. ⚠️ Schema隔离迁移测试
+```
+
+**第四步：开始ASL模块开发（下周开始）**
+```
+优先级：
+- P0：标题摘要初筛（核心功能，已有原型）
+- P1：全文复筛（核心功能，已有原型）
+- P2：全文解析与数据提取
+- P3：数据分析与报告生成
+```
+
+---
+
+## 🎯 总体策略建议
+
+### 核心原则
+
+**1. 架构先行，文档先行**
+```
+✅ 先把总体架构讨论清楚
+✅ 先把文档结构调整好
+✅ 然后再开始开发
+```
+
+**2. 聚焦核心，逐步扩展**
+```
+阶段一（当前-6个月）：
+- 云端SaaS版
+- 核心模块：ASL、DC、AIA优化
+- 关键能力：LLM网关、Schema隔离
+
+阶段二（6-18个月）：
+- 私有化部署
+- 扩展模块：SSA、ST
+- 独立系统：RVW（审稿系统）
+
+阶段三（18个月+）：
+- 单机版（可选）
+- 全面微服务
+```
+
+**3. 模块独立，能力复用**
+```
+✅ 业务模块独立设计（低耦合）
+✅ 通用能力统一提供（高复用）
+✅ 支持模块独立销售
+```
+
+---
+
+## ✅ 立即行动清单
+
+### 本周行动（P0）
+
+**1. 架构设计（1-2天）**
+- [x] 系统架构分层设计 ✅
+- [x] 文档体系重构方案 ✅
+- [ ] LLM大模型网关设计
+- [ ] 数据库Schema隔离方案
+
+**2. 文档迁移（1-2天）**
+- [ ] 创建新文件夹结构
+- [ ] 迁移ASL模块文档
+- [ ] 调整文档结构（按新模板）
+
+---
+
+### 下周行动（P1）
+
+**3. 关键文档补充（2-3天）**
+- [ ] ASL模块缺失文档
+- [ ] LLM网关详细设计
+- [ ] RVW独立系统规划
+
+**4. 开始ASL模块开发（启动）**
+- [ ] 数据库表设计（asl_schema）
+- [ ] API设计
+- [ ] 前端组件设计
+
+---
+
+## 📊 总结
+
+### 您的想法非常正确！
+
+1. ✅ **文档系统重构**：总体独立，模块独立
+2. ✅ **不考虑混合部署**：简化技术复杂度
+3. ✅ **审稿系统独立**：极具商业价值
+4. ✅ **架构分层清晰**：平台层、通用能力层、业务模块层
+5. ✅ **Schema隔离必要**：支持模块独立和微服务拆分
+6. ✅ **ASL是下一步重点**：核心竞争力
+
+### 当前最关键的工作
+
+**P0（本周）：**
+1. 完成架构设计文档（LLM网关、Schema隔离）
+2. 调整文档结构（迁移ASL模块）
+
+**P1（下周）：**
+3. 补充关键文档
+4. 开始ASL模块开发
+
+### 我们不着急，先把总体思路沟通清楚
+
+✅ **完全认同您的想法！**
+
+架构设计是地基，地基不牢，后面开发会很痛苦。
+
+我们先把架构和文档梳理清楚，再开始开发。
+
+---
+
+**接下来您想讨论什么？**
+1. LLM大模型网关的详细设计？
+2. 数据库Schema隔离的具体实施？
+3. ASL模块的开发计划？
+4. 审稿系统的独立规划？
+5. 其他架构问题？
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+