nex_docus/docs/sdd/architecture/constraints.md

约束与待决事项（Constraints & Open Points）

技术约束（当前代码库既定）

1. Python 3.12 + FastAPI 0.109：异步栈；requirements.txt 固定大部分版本。
2. SQLAlchemy 2.0（async）+ aiomysql；同步连接供 Alembic 风格脚本（pymysql）。
3. MySQL 5.7.5+ / 生产镜像 MySQL 8.0，utf8mb4。
4. Redis：Token 缓存、会话状态、通知等。
5. JWT（python-jose HS256）+ bcrypt（passlib）。
6. 前端 React 18 + Vite 5 + Ant Design 5 + Tailwind + Zustand；路由 React Router v6。
7. Whoosh3（全文）+ ZVec（向量）+ jieba（中文分词）。
8. WeasyPrint（PDF 导出）、pdfjs-dist/react-pdf（前端 PDF 预览）、react-virtuoso/react-window（虚拟列表）。
9. 部署：Docker Compose v2 + Engine ≥ 25（ADR-0008）。

约束来源

• 依赖锁定：backend/requirements.txt、frontend/package.json。
• 配置默认：backend/app/core/config.py、.env.example、docker-compose.yml。

待决事项（Open Points）

编号	事项	现状	建议
OP-1	Alembic vs 幂等 ALTER	采用幂等 ALTER（migrations.py）	评估引入 Alembic 以支撑大规模结构变更
OP-2	敏感日志	security.py/deps.py 记录 SECRET_KEY 前缀/JWT 载荷	脱敏，见 OI-1
OP-3	Compose v2 官方化	deploy.sh 探测 v2 但根文档仍提及 v1	统一 v2 路径，见 OI-2
OP-4	测试覆盖	仅 3 个后端单测	增加集成/E2E，见 OI-3
OP-5	实时协同编辑	明确不在此版本做（vision 边界）	另立项评估 OT/CRDT
OP-6	多实例/高可用	单机部署，无状态服务仅后端（Redis/DB 独立）	若需要再评估

约束的规格化引用

• 以上条目若成为刚性承诺，须固化为 ADR 并登记到 decisions/README.md。