# SY02 — 核心设计原则

> **版本：V1.2 | 状态：强制 | 最后更新：2026-08-16**
>
> **文档状态：V1 基线，已升级。** 本项目已于 2026-08 升级为「知识库中心化智能体平台」，产品主轴与目标态见 [SY03](SY03_Knowledge_Centric_Agent_Platform_Strategy.md) 及 SY04–SY17。本文档为 V1 培训平台基线的设计原则，其中「不做向量检索 / 无学情分析 / 无能力档案」等约束已随 V1.6 起逐步放开，当前实现以 `docs/changelog.md` 与 `docs/db_schema.md` 为准。

---

## 原则 1：100% 本地化部署

- 不上云、无 OSS、无 MinIO、不依赖任何公网云服务
- AI 所用 LLM 必须为内网可达地址（Ollama / vLLM / 内网统一 LLM 网关）
- 严禁直连公网 AI API
- 数据库使用 SQLite 单文件（本地实例）+ Go 原生 brute-force 向量检索（余弦相似度）+ 关键词兜底
- 文件存储使用本地磁盘（backend/data/media → 现为 `data/kb_data`）

## 原则 2：极致极简（V1 约束，已随平台升级部分放开）

- 所有功能以"够用"为标准，不做任何冗余
- **V1.1 曾明确不做、现已放开的：** 学情分析、能力档案、学习进度仪表盘（V1.6 起已实现积分/排行榜/证书/学习档案/能力雷达）；岗位与部门概念（V1.4 / V1.7 已引入）。复杂权限与多级角色仍保持单租户极简，暂不引入多租户洋葱模型
- 保持前端轻量：Vue3 + Element Plus，不用状态管理库（如 Pinia 按需判断）
- 保持后端简洁：Go + Gin + GORM 单二进制，不加消息队列（异步任务用简单线程池）
- AI 知识检索：Go 层 brute-force 向量检索（余弦）+ 关键词兜底（不依赖外部向量库）

## 原则 3：审批前置

- 所有素材必须经过审批才能生效
- 未审批/驳回素材：前台完全不可见、不解析、不进 AI 知识库
- 审批通过后才执行文档转换管线（PPT/Word → PDF → 文本提取 → 入库）
- 员工提交素材建议走弹窗，管理员直接上传自动通过

## 原则 4：视频仅预览

- MP4 不做转码（仅支持 H.264 标准格式）
- 不做语音转写（ASR）
- 视频不进 AI 文本知识库
- 审批通过后仅支持在线原生 video 播放

## 原则 5：后端安全第一

- JWT 认证 + bcrypt 密码哈希
- 后端 API 统一鉴权（不是前端路由）
- 管理员接口额外校验 role == admin
- 文件上传严格执行白名单（仅 7 种扩展名）
- 文件名重命名为 UUID，杜绝路径穿越
- 禁用账号即时失效（token 校验时检查 status）

## 原则 6：数据库只存元数据

- 不存文件二进制
- 文件存储路径：data/kb_data/approved/（已审批）· pending/（待审批）· rejected/（已驳回）

## 原则 7：异步非阻塞转换

- 审批通过后的文档转换 + 文本提取为后台异步任务
- 不阻塞请求（后端立即返回，任务后台执行）
- 前端轮询或接口查询转换状态
- 任务结果写入 media_file.extracted 字段 + 日志

## 原则 8：数据对齐业务

- 所有产品数据严格对齐《博昇产品与渠道合作表 V1.0》
- 产品编号、名称、分类、佣金比例、分成规则等字段不可随意修改
- 支持批量导入（Excel / JSON），导入数据需管理员确认后生效