nex_docus/docs/sdd/product/principles.md

产品与工程原则（Principles）

产品原则

1. 文件即真理：内容数据以文件为本，数据库只承载元数据/权限/状态。
2. 透明可迁移：任何时刻都应能通过「拷贝目录 + 导出 DB」完成迁移。
3. 严格隔离：项目级磁盘隔离 + RBAC 权限，双保险。
4. 答案可溯源：知识库问答必须可验证，禁止无依据编造。
5. 开放接入：优先用行业标准协议（如 MCP）暴露能力。

工程原则

1. 异步优先：后端 FastAPI + 异步 I/O（aiofiles/aiomysql/aioredis），长任务走后台任务。
2. 写路径不阻塞：索引/向量同步放后台（FileVectorSyncService、ProjectVectorizationTaskService），主请求线程不等待。
3. 路径安全第一：任何文件访问必须先过 get_secure_path 校验。
4. 健壮降级：LLM/embedding/对齐失败不阻断主流程；无配置时跳过。
5. 幂等变更：数据库结构演进用幂等 ALTER；初始化脚本可重复执行。
6. 单一真相源：本 SDD 中心是规格/追踪入口，细节指向源文档与代码。
7. 小步可追踪：一次合并一个逻辑单元，切片（TS）可被证据（VER）验证。