3.1 KiB
3.1 KiB
SY02 — 核心设计原则
版本：V2.0 | 状态：强制 | 最后更新：2026-09-21
文档状态：当前有效。 本文档只保留当前系统仍然生效的硬约束与设计原则，不再承载历史演进说明。具体实现以
docs/01_System_Overall/变更日志.md、docs/04_Backend/01_平台治理底座/BG04_数据库总览.md与docs/02_Architecture/部署文档.md为准。
原则 1：100% 本地化部署
- 不上云、无 OSS、无 MinIO、不依赖任何公网云服务
- AI 所用 LLM 必须为内网可达地址（Ollama / vLLM / 内网统一 LLM 网关）
- 严禁直连公网 AI API
- 数据库使用 SQLite 单文件（本地实例）+ Go 原生 brute-force 向量检索（余弦相似度）+ 关键词兜底
- 文件存储使用本地磁盘（backend/data/media → 现为
data/kb_data）
原则 2：极致极简
- 所有功能以"够用"为标准，不做任何冗余
- 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），导入数据需管理员确认后生效