19 lines
1.2 KiB
Markdown
19 lines
1.2 KiB
Markdown
|
# 产品与工程原则（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）验证。
|
|||
|
|
|