backend/docs/08-疑问与决策记录.md

疑问与决策记录

一、垂直科室 vs 多科室 SaaS

决策：一套代码 = 一个垂直科室产品，每个部署实例独立。

背景：最开始讨论时考虑过在一套系统里支持多科室切换（肿瘤/心血管/神经…），平台端建科室模板。

结论：不做多科室共享框架。肿瘤科是一个独立部署实例；将来做心内科或神经科时，用同一套代码 + 不同的科室配置文件，在另一台服务器上独立部署运行。

原因：

• 垂直领域数据隔离要求更高（医院不愿自己的肿瘤数据和其他科室混在一起）
• 配置驱动的单部署架构更简单、更安全
• 部署成本低（Docker Compose 一条命令）
• 新科室部署只需 3 步：写配置 → 生成 Docker → 启动

# 不同科室不同的配置文件
config/specialties/oncology.yaml    → scilit-oncology.com
config/specialties/cardiology.yaml  → scilit-cardiology.com
config/specialties/neurology.yaml   → scilit-neurology.com

---

二、TIMESTAMPTZ vs Unix 时间戳

决策：数据库存储使用 TIMESTAMPTZ，API JSON 输出转 10 位 Unix 时间戳。

背景：讨论过用整数时间戳存储，省存储空间、无时区问题。

结论：禁止在数据库中用整数代替时间类型。

原因：

• PostgreSQL TIMESTAMPTZ 内部就是 UTC，数据库自动处理时区转换
• SQL 中日期/时间运算自然（date_trunc、interval、now()）
• 调试时可读性决定排查效率（2025-07-04 08:30 一眼看懂 vs 1751596200 要去算）
• 存储空间差 4 bytes 在现在的硬件上完全可忽略
• API 序列化时可以在 Pydantic schema 里转成时间戳，这是应用层的事

---

三、分表 vs 分区

决策：不需要分表。唯一需要分区的是 user_feed。

背景：global_literature 预估约 600 万行，担心性能。

结论：

• global_literature (600万)：不需要分区。B-tree 索引足够，600万对 PostgreSQL 是小意思（单表 1000-2000万以下不需要分）
• global_literature_tags (6000万)：不需要分区。两种查询模式都命中 B-tree 索引，分区反而跨区扫描
• user_feed (年增数千万)：唯一需要分区的表。PARTITION BY RANGE (pushed_at) 按月分区 + 自动删除旧分区（保留最近 3 个月）

分区管理：定时任务每月 25 号创建下月分区 + 删除 3 个月前的分区（DROP TABLE 秒删，无需 VACUUM）

---

四、FastapiAdmin 版权风险

决策：无风险。基于 MIT 协议，可以 Fork、修改、商用、闭源。

背景：评估了是否基于 Gitee 上的 tao__tao/FastapiAdmin 搭建。需要确认协议兼容商业化。

结论：

• MIT License：允许商业使用、修改、分发、私用，唯一要求是保留版权声明
• 实际操作：在项目根目录 LICENSE 文件保留 Copyright (c) 2025 1014TaoTao 声明即可
• 能直接复用的：RBAC + 认证 + 日志 + 监控 + 定时任务 + 前端布局 ≈ 基础设施的 30%
• 必须自研的：多租户 RLS、PubMed 管道、标签引擎、Stripe 计费、审批流、AI 功能 ≈ 核心差异化的 70%
• 这不是法律问题，是效率问题——复用它省的主要是基础骨架，不是业务代码

---

五、注册流程的设计

决策：注册后直接进入肿瘤科文献平台，不需要选择科室。

背景：最早一版设计里有"注册→选择肿瘤科→设置癌种偏好"的流程。

结论：既然定位为垂直肿瘤科产品，注册后默认就是肿瘤科。用户直接进入"设置关注的癌种和靶点"环节。

类似产品参考：

• 不是"先选科室再看内容"（像 UpToDate）
• 而是"直接看肿瘤科内容，再微调个性化"（像 Feedly for oncology）

---

六、标签体系的"可配置但预设"

决策：标签树在配置文件里预设完整的肿瘤科标签树，平台管理员可在后台微调。

背景：MeSH 有 31,000 个描述符，但用户只需要肿瘤相关的。而且 MeSH 不覆盖靶点、临床分期、终点等临床维度。

结论：

• MeSH C04 + E02(治疗) + D27(药物) ≈ 标签树的 60%
• 靶点/基因（EGFR/ALK…）+ 临床场景（新辅助/一线…）+ 终点（OS/PFS…）≈ 标签树的 40%，手工维护
• 不是"让用户从 31000 个 MeSH 词里选"，而是"预设肿瘤科精选标签，用户勾选感兴趣的子集"

---

七、AI 功能的成本控制

决策：只用 GPT-4.1-mini 做摘要/翻译/解读。全量用规则引擎。

背景：每天 400-600 篇肿瘤文献，如果每篇都调 GPT-4.1-mini，成本会很高。

结论：

• 只对用户"必读"（must_read）级别的文献调 AI（日均约 100 篇/全部用户共享）
• GPT-4.1-mini：~$0.02/篇 → 日均 $2 → 月均 $60（全平台）
• 其余文献用模板规则生成摘要（填充式："{drug} 联合 {drug2} 治疗 {cancer}，{endpoint} 显著改善"）
• 成本计入 Enterprise 方案定价（$20/人/月 含 AI 功能）

---

八、个人→团队升级的数据迁移

决策：零数据迁移。个人版租户有一个 tenant_id，升级时只改 is_personal=FALSE + plan_type。

背景：参考了 Claude、Manus、Neon 的个人→组织迁移实践。

结论：

• 所有文献/笔记/标签都 scoped 到个人版的 tenant_id
• 升级后同一 tenant_id 变成企业版
• 用户已经是这个租户的 owner
• 不需要数据迁移脚本，不需要复制数据
• 零停机，零风险

---

九、首发为什么是肿瘤科

决策：肿瘤科是第一垂直领域，最优选。

维度	肿瘤科优势
文献量最大	PubMed 约 18% 是肿瘤相关 → 自动化价值最高
亚专科最多	肺/乳腺/消化/血液/妇科/泌尿/头颈… 每个都是独立市场
付费意愿最强	抗癌新药层出不穷 → 错过一篇可能意味着"不知道有更好的治疗方案"
MDT 天然需要协作	肿瘤内科+外科+放疗+病理+影像 → 企业版团队功能的完美场景
药企预算	药企医学部可以为科室采购 → B2B 付费路径清晰

---

十、配置驱动 vs 代码硬编码

决策：所有科室差异化逻辑走配置文件（YAML），不走代码分支。

# 正确：配置在 YAML 里
pubmed_filter:
  mesh_include_categories: ["C04"]  # 肿瘤科

# 错误：硬编码在代码里  
if specialty == "oncology":
    filter_mesh = ["C04"]

原因：

• 新增科室只需要改 YAML，不需要改 Python 代码
• 配置文件可以做版本管理（Git）
• 可视化编辑器可以直接操作 YAML
• 部署脚本模板化，./deploy.sh --specialty cardiology 自动生成

---

十一、参考文献与数据源

用途	来源
PubMed 全量数据	ftp.ncbi.nlm.nih.gov/pubmed/
MeSH 词表 (XML)	ftp.ncbi.nlm.nih.gov/mesh/2025/
FDA 新药审批	https://www.fda.gov/drugs/development-approval-process-drugs
NMPA 批件	https://www.nmpa.gov.cn
NCCN 指南	https://www.nccn.org/guidelines
CSCO 指南	http://www.csco.org.cn
ESMO 指南	https://www.esmo.org/guidelines
Stripe 计费	https://docs.stripe.com/billing
PostgreSQL RLS	https://www.postgresql.org/docs/current/ddl-rowsecurity.html
ARQ 任务队列	https://github.com/python-arq/arq
FastapiAdmin (参考)	https://gitee.com/tao__tao/FastapiAdmin
Karakeep (AI打标参考)	https://github.com/karakeep-app/karakeep
I, Librarian (参考)	https://github.com/mkucej/i-librarian-free

---

十二、管道增强字段的两条入库路径需保持同步

决策：_process_article()（新建）和 _update_lit_from_article()（更新）两条路径必须同时维护。

背景：Phase 1 实现 PubMed 增强字段（ChemicalList、GeneSymbolList、NumberOfReferences 等 7 个）时，只给 _update_lit_from_article() 的 fields 列表追加了字段名，忘记在 _process_article() 的 GlobalLiterature() 构造器参数中传递——导致新建的文章增强字段全部为空。

教训：

• 两条路径通过的字段列表必须人工保持一致
• 增加新字段需要同时检查两个地点：
  1. _process_article() → GlobalLiterature() 构造器参数（约第 938 行）
  2. _update_lit_from_article() → fields 列表（约第 833 行）
• 最好加一个共享的 ENRICHMENT_FIELDS 常量列表，避免再次不同步

---

十三、Windows 进程管理：kill 不掉旧进程的原因

决策：Windows 开发环境下使用 taskkill //f //im python.exe（双斜杠防止 Git Bash 路径转义）。

背景：修改代码后 API 仍返回旧数据，猜测是旧 uvicorn worker 进程残留。kill -9 在 Git Bash 内不工作（Windows 无 SIGKILL），taskkill /f /im python.exe 起效但 Git Bash 把 /f 转换为 F:/ 路径导致失败。

教训：

• Git Bash 中单斜杠参数（/f、/im）会被 MSYS 解释为 Windows 路径
• 必须用双斜杠 //f、//im 阻止转义
• 或使用 cmd //c "taskkill /f /im python.exe" 也是一个选择
• 之后再清除 __pycache__ 确保 bytecode 缓存刷新
• Docker Compose 部署场景无此问题（容器内 Linux 环境）

---

十四、管道依赖种子数据的启动顺序

决策：新建 PostgreSQL 数据库后，必须先运行种子数据脚本再启动管道。

背景：第 0 次管道运行时，global_tags 和 global_journals 为空（TRUNCATE CASCADE 不会删除标签，但全新 DB 确实无标签）。_tag_article() 通过 mesh_ui 查找 global_tags，空表导致 0 打标——前端标签页面全部报"加载标签失败"。

教训：

• scripts/seed_tags_only.py 是专为此场景设计的种子脚本
• 管道只创建 GlobalLiterature 和 GlobalLiteratureTag，不负责标签定义
• 部署顺序必须为：seed_tags_only → pipeline run → verify tag coverage
• 全量测试时若 TRUNCATE 后重新导入，只需重新运行管道（打标会自动完成），不需要再次 seed

---

十五、团队邀请流程设计

决策：创建邀请时异步发送邮件 + 未注册用户引导注册。

背景：初始版本邀请功能只创建数据库记录并返回 invite_link，不发送邮件通知。被邀请通过邀请链接进入后，未注册用户直接被跳转到登录页，账号不存在则卡死。

结论：

1. 邮件发送 — create_invitation 端点中通过 FastAPI BackgroundTasks 异步调用 send_email()。邮件发送在 HTTP 响应返回后执行，不阻塞接口响应。

2. SMTP 配置要求 — send_email() 只有在 SMTP_HOST 配置了值时才真实发送邮件。开发环境（SMTP_HOST 为空）仅记日志 "DEV mode — email to ..."，不会真实发信。生产环境需在 .env 中配置 SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASSWORD / SMTP_FROM。代码已支持 465（SSL）和 587（TLS）两种端口自动切换。

3. SMTP 配置 — 使用腾讯云邮件推送 SES（smtp.qcloudmail.com:465）。密码需在腾讯云 SES 控制台生成 SMTP 密码，非登录密码。代码已支持 465（SSL）和 587（TLS）两种端口自动切换。

4. 未注册用户处理 — AcceptInviteView.vue 中不再自动跳转登录页，而是并行显示"去登录"和"去注册"两个按钮。注册页面（RegisterView.vue）支持 ?redirect 参数，注册成功后自动跳回邀请接受页完成流程。

5. Token 传递 — 邀请 token 通过 sessionStorage 暂存（pending_invite），不在 URL 中持久暴露。登录/注册完成后自动取回。

Flow：

邀请人 → POST /teams/invitations → INSERT invitation + 异步发送邮件
                                           ↓
被邀请人点击邮件链接 → /auth/accept?token=xxx
    ├─ 已登录 → 自动接受邀请，加入租户
    └─ 未登录 → 显示"去登录"和"去注册"
                    ├─ 登录成功 → 自动取回 token 接受邀请
                    └─ 注册成功 → redirect=/auth/accept → 接受邀请

实现文件： backend/app/api/v1/teams.py、backend/app/services/email_service.py、backend/app/services/email_templates.py、frontend/src/views/auth/AcceptInviteView.vue、frontend/src/views/auth/RegisterView.vue

---