light-system-design

# 后端系统与数据库设计

## 适用场景
科研系统、管理系统、数据分析/可视化平台、竞赛作品、软著申请项目。设计要既能落地(交 a03 实现)又能写进软著/论文(交 m15/m07)。

## 系统架构
- 模块划分(分层：接口层/业务层/数据层)、职责边界、数据流转图。
- 技术选型按需(见 a09，各框架起手式/分层/配置见 references.md)：**FastAPI**(路由+Pydantic 校验+`Depends` 注入+`/docs` Swagger)、**Django REST**(serializer+ModelViewSet+Router，`REST_FRAMEWORK` 集中配)、**Spring Boot**(`@RestController→@Service→@Repository` 分层+构造器注入+多 profile)。
- 非功能性：性能(缓存/索引/分页)、可扩展、可观测。
- **向量检索选型**（科研 RAG/语义检索常用）：百万级以内优先 **pgvector + HNSW**（一套 Postgres 管关系+向量，运维简单），算子类与查询距离要一致（cosine→`vector_cosine_ops`）；千万~亿级、高 QPS 或需分布式才上专用向量库（Milvus/Qdrant/Weaviate）。选型对照见 references「pgvector + HNSW」节。
- **可观测**：科研 AI 服务用 **OpenTelemetry** 统一采 trace/metric/log（`opentelemetry-instrument` 零改代码自动埋点，OTLP 导出到 Jaeger/Prometheus），定位"一次推理耗时花在哪、哪步报错"，别用 print 调试；注意采样率与别把密钥/PII 写进 span。详见 references「OpenTelemetry」节。

## 数据库设计
- **ER 图**：实体、关系、基数。可用 `scripts/er_diagram.py` 把表结构定义（YAML/JSON：entities + columns(PK/FK/UK) + relationships(基数)）一键转成 Mermaid `erDiagram` 文本，粘进 Markdown/软著文档或 mermaid.live 预览（`python scripts/er_diagram.py --in schema.yaml`，纯离线）。**需要更强表达力/可编辑矢量源/纳入 Git 版本控制**（复杂 ER、系统架构图、分层图、数据流转图，尤其软著功能说明/论文系统描述用的正式图）时，用 **Draw.io MCP**（diagram-as-code，官方 jgraph/drawio-mcp，`.drawio` 即 XML 可程序化生成与版本管理，导出 PNG/SVG/PDF）——比 Mermaid 排版更可控、可反复改稿（配置见 README 推荐 MCP 表，规划走 m09 figure-planning）。
- **表结构**：字段、类型、约束、主外键、范式 vs 反范式权衡。刻意选型，别无脑 text/超大 numeric。
- **索引**：按查询模式选型——B-Tree(等值/范围/排序/前缀 `LIKE 'x%'`)、GIN(数组/JSONB/全文/trigram)、BRIN(超大表+物理有序时间列)、GiST(几何/最近邻)、Hash(纯等值)。**外键必须建索引**(最常见漏建)；生产建索引用 `CREATE INDEX CONCURRENTLY` 避免锁表；上线前 `EXPLAIN ANALYZE` 验证计划。
- **迁移**：Alembic `revision --autogenerate` 生成后**必须人工审**（检不出重命名/匿名约束，报成 drop+add），`upgrade head` 应用，CI `alembic check`；Prisma 开发 `migrate dev`、**生产只能 `migrate deploy`**（不 reset/shadow DB），手改 SQL 用 `--create-only`。
- **ORM 防 N+1**：SQLAlchemy 用 `selectinload`(二次 IN 查询)/`joinedload`(JOIN) 预加载；DRF 用 `select_related`/`prefetch_related`。连接必须用连接池。
- 最佳实践参考 supabase-postgres-best-practices(下方安全段含 RLS 具体写法、命名规范)。

## 接口设计
- RESTful/OpenAPI 3.x 规范：顶层 `openapi`/`info`/`servers`(完整 base URL，版本化放 `/v1`)/`paths`/`components`。
- 资源命名、方法、状态码(201 Created/204/4xx)、版本化。
- 请求/响应 schema 放 `components.schemas` 用 `$ref` 复用；`securitySchemes` 定义 bearer/oauth2。
- 错误码体系、分页(游标优先于大 OFFSET)/过滤/排序约定。
- 接口文档可导出：FastAPI `/openapi.json`、DRF/Spring 均可自动产出 OpenAPI；手写时别漏 error 响应码与示例。

## 安全与运维
- **权限**：认证(JWT/session)+授权(RBAC)；最小权限原则。
- **行级安全(RLS)**：多租户表 `enable row level security` + 显式 policy，别只靠应用层 WHERE；性能上函数包进 `select` 触发 initPlan 缓存、policy 引用列建索引、永远写 `to` 子句、复杂跨表用 `security definer` 函数；授权数据用 `raw_app_meta_data`（用户改不了）。骨架与写法见 references「supabase RLS」段。
- **缓存(Redis)**：Cache-aside(查缓存→未命中读 DB→写回带 TTL)；`maxmemory-policy` 默认 `allkeys-lru`；TTL 加随机抖动防雪崩、空值缓存防穿透；监控命中率与 `evicted_keys`。
- **日志**：分级日志、请求追踪、审计日志。
- **异常处理**：统一异常响应、不泄露内部细节。
- **安全策略**：输入校验、防注入、限流、密钥管理(不入库/不硬编码)。
- **部署**（完整配置/骨架见 references.md 与 `templates/ci.yml`）：Docker 多阶段构建、依赖清单先于源码护缓存、非 root + slim/distroless + 钉 digest；K8s Deployment+三探针(readiness/liveness/startup)+requests/limits+HPA、Secret 配 RBAC；Nginx 反代透传 XFF/TLS 终止/`limit_req`、改配 `nginx -t` 后 reload；CI(Actions) checkout→install→lint→test→`alembic check`/`migrate deploy`，最小权限 `contents: read`、回滚 `kubectl rollout undo`。
⚠ 网络暴露服务若无鉴权必须主动提示(security_awareness)。

## 产出
架构图 + ER 图 + 表结构 DDL + 接口文档(OpenAPI) + 权限/安全/部署说明。设计文档可直接喂 m15 软著功能说明。起手骨架见 `templates/`(schema.sql / openapi.yaml / rls_policy.sql / ci.yml)，按项目改字段即可。

## 衔接
设计→a03 实现→a06 规整目录；与论文系统描述、软著材料保持一致(a07)；版本入 db09。

> 各工具真实端点/语法/配置/已知坑见 references.md（逐工具核查笔记）。