eaiadmin
4e8817d768
包含前端（Vue3 + VueFlow 画布）、后端（Go）、文档体系。 - 工作台画布：节点拖放、连线模式、右键菜单、AI 助手 - 后端：连接器 API、专员种子数据 - 导航：左侧导航、工坊、市场、控制台
243 lines
13 KiB
Markdown
243 lines
13 KiB
Markdown
# eaisalestrain_app 博昇内部培训平台 — 编码与调试最高准则
|
||
|
||
> **版本：V1.0**
|
||
> **日期：2026-08-15**
|
||
> **状态：必须强制执行 (Highest Priority)**
|
||
> **适用范围：博昇内部培训平台前端、后端、数据库、考试引擎、AI PathCoach、素材上传与审批**
|
||
> **AI 助手启动任何任务前必须先读取并确认本文件。**
|
||
|
||
---
|
||
|
||
> **整理说明**：参考 pj034-oeamgt TOP_CODING_RULES.md 结构体系重组。
|
||
> **分组方式**：第一部分是 EAIHub 博昇 AI 中心通用规则；第二部分是本项目专用规则。
|
||
> **编号方式**：第一部分 G01-G08；第二部分 P01-P05。
|
||
|
||
---
|
||
|
||
# 第一部分：通用开发规则
|
||
|
||
> **适用范围**：适用于 eaisalestrain_app 及 EAIHub 下其他涉及 FastAPI/Vue3/AI 的项目。
|
||
> **使用方式**：新任务开始前应先通读本部分；项目专用规则(P)在遵守本部分基础上叠加。
|
||
|
||
## 索引
|
||
|
||
- G01：深度调试日志 — 全链路埋点 + 特殊日志文件
|
||
- G02：Fail Fast 与零静默兜底
|
||
- G03：变量命名锚定 — 防命名漂移
|
||
- G04：测试与验收 — 完成判定必须靠事实
|
||
- G05：安全迁移与重构流程
|
||
- G06：AI 助手行为规范
|
||
- G07：交互控件可用态颜色统一
|
||
- G08：分层清晰，禁止前后端职责串线
|
||
|
||
---
|
||
|
||
## G01 最高原则：深度调试日志 (Special Log & Console Print)
|
||
|
||
**任何**涉及功能异常、逻辑排错、API 失败或模板渲染问题的任务，必须遵循以下调试流程：
|
||
|
||
1. **强制全链路埋点**：禁止盲目猜测，必须在后端路由、中间件、服务层以及前端 JS 关键回调中，大量写入过程性输出。
|
||
2. **统一特殊日志文件**：
|
||
- 路径：`backend/logs/special_trace_YYYY-MM-DD.log`（按天生成）
|
||
- 内容：必须包含 `[时间戳] [模块名] [详细描述]`
|
||
- 必须包含：请求参数、Session 状态、关键业务变量
|
||
- **脱敏红线**：落盘前必须脱敏/删除敏感信息（Authorization/Cookie/JWT/密码/API Key 等）
|
||
3. **同步控制台输出**：所有写入调试日志的内容必须同步 `print` 到 Console，以便开发者实时观察。
|
||
4. **排查先读日志**：在提出任何修复方案前，必须先调用读取工具检查该日志。
|
||
|
||
### 关键埋点清单
|
||
|
||
| 埋点位置 | 必须记录内容 |
|
||
|---|---|
|
||
| API 调用 | 请求参数、响应状态、异常栈 |
|
||
| 数据库交互 | 查询关键参数、结果集摘要 |
|
||
| 文件操作 | 上传/转换/提取的文件路径、大小、状态 |
|
||
| AI LLM 调用 | 发送给 AI 的完整 Payload + 返回原始正文；落盘前脱敏密钥/令牌 |
|
||
|
||
---
|
||
|
||
## G02 最高原则：Fail Fast 与零静默兜底 (Fail Fast & Zero-Fallback)
|
||
|
||
1. **禁止隐式回退**：所有涉及配置、运行时资产的读取，**严禁使用硬编码的默认值进行静默兜底**。
|
||
2. **配置/字段缺失即报错**：如果代码依赖某项配置或 JSON 字段且其缺失，必须立即抛出异常并终止流程。
|
||
3. **禁止入口层吞错**：路由入口不得 `try/except` 后静默放行；凡关键身份、权限、业务校验失败，必须返回明确错误（4xx/5xx）并阻断流程。
|
||
4. **禁止"先跑通再修正"策略**：不得为"先可用"加入 hardcode 默认值、临时跳过校验等行为。这类行为视为质量事故。
|
||
5. **错误可见性强制**：任何违反业务规则或数据约束的问题，必须对开发者显式可见（日志 + 返回错误 + 可复现路径），禁止隐藏真实错误来源。
|
||
6. **图片不做 OCR**：严格按照 PRD V1.1 规定，图片（png/jpg/jpeg）不做 OCR、不进 AI 文本库。
|
||
|
||
### 反例与正例
|
||
|
||
| | 反例 ❌ | 正例 ✅ |
|
||
|---|---|---|
|
||
| A | 文件审批状态未知时默认视为"已通过" | 状态非 `approved` 则拦截并返回明确错误 |
|
||
| B | LLM 配置缺失时使用硬编码的默认地址 | 配置缺失立即报错，引导管理员在系统参数补充 |
|
||
| C | 考试 session 不存在时返回空结果 | Session 不存在返回 404 + 明确错误信息 |
|
||
|
||
---
|
||
|
||
## G03 原则：变量命名锚定 — 防命名漂移 (Identity Anchoring)
|
||
|
||
1. **变量名前缀强制化**：所有业务相关变量必须带明确前缀（如 `media_file_id`, `exam_session_key`, `product_code`）。禁止使用 `id`, `data`, `res` 等模糊命名。
|
||
2. **变量名全链路同步**：同一业务参数在 API、Service、Model 层必须保持变量名完全一致。
|
||
3. **最小长度约束**：变量名原则上不短于 5 个字符（循环索引除外）。
|
||
4. **AI 引用已定义标识符必须按字符复制**：AI 在生成或修改代码时，引用任何**已在项目中定义过**的标识符，必须先 Read/Grep 找到定义处，**按字符原样复制**，禁止自行改写大小写或分隔符。例如 `user_id` 不应被写成 `userId` 或 `uid`。
|
||
|
||
---
|
||
|
||
## G04 最高原则：测试与验收 — 「我说完成」必须靠观察的事实
|
||
|
||
1. **完成判定必须看 exit code，禁止仅看屏幕末尾文字**：命令后立刻 `echo $?` 或 `if [ $? -ne 0 ]`；链式命令必须确认每一段都退出 0。
|
||
2. **修改既存文件前必须 Read 整文件**，禁止凭印象 Edit。
|
||
3. **新依赖必须同步进 `requirements.txt` / `package.json`**：任何新 import 出现必检查此包是否在依赖清单中。
|
||
4. **测试/build 失败时禁止"再试一次"侥幸**：失败原因必须先找出来。
|
||
5. **声明完成前的最小验证清单**：
|
||
- [ ] 后端：`python -c "from app.main import app"` 无 import error
|
||
- [ ] 前端：`npx vite build` exit 0
|
||
- [ ] API smoke：`/api/health` 返回 200，管理员 login 返回 200
|
||
- [ ] 任何新 import 在依赖清单中
|
||
|
||
---
|
||
|
||
## G05 原则：安全迁移与重构流程 (Secure Migration)
|
||
|
||
1. **非简化原则**：重构不得以简化逻辑为目的，必须保留所有原始业务深度。
|
||
2. **实质性内容保护**：除非内容明确放错位置、存在重复副本或已经完成等价迁移验证，否则不得删除原有实质性内容与技术细节。
|
||
3. **全量备份**：大规模操作前，将原始文件完整备份。
|
||
4. **文件安全强制**：
|
||
- 文件扩展名白名单校验（仅允许 ppt/pptx/pdf/doc/docx/mp4/png/jpg/jpeg）
|
||
- 文件名重命名为存储 UUID，杜绝路径穿越
|
||
- 上传目录对静态预览只读，禁止直接执行
|
||
|
||
---
|
||
|
||
## G06 原则：AI 助手行为规范
|
||
|
||
1. **任务启动预读**：AI 助手在接收到新任务后的第一步操作中，必须读取本项目根目录下的 `CODING_RULES.md` 与 `eaisalestrain_app/CLAUDE.md`。
|
||
2. **持续追踪**：直到问题完全解决并经由日志或接口验证通过前，不得结束任务。
|
||
3. **新对话启动仪式**：新对话必须先读 `eaisalestrain_app/PROJECT_STATE.md` → `CODING_RULES.md`，再开始干活。
|
||
4. **发现规则与实现冲突时**，优先提醒并修正，不得静默忽略。
|
||
|
||
---
|
||
|
||
## G07 原则：交互控件可用态颜色统一规范
|
||
|
||
1. **按钮可用态统一蓝底**：所有可点击的关键交互按钮必须使用蓝色底（推荐 `#1677ff`）。
|
||
2. **按钮不可用态统一灰底**：所有不可点击按钮必须使用灰色底（推荐 `#cbd5e1`）与灰色文字（推荐 `#64748b`），并保持 `cursor: not-allowed`。
|
||
3. **状态变化必须实时联动视觉**：按钮的 `disabled` 状态变化后，底色必须立即同步变化。
|
||
4. **Element Plus 严格类型约束**：`el-tag` / `el-button` 的 type prop 禁止传入 `""` 或 `null`；无条件匹配时应传 `undefined`。
|
||
|
||
---
|
||
|
||
## G08 原则：分层清晰，禁止前后端职责串线
|
||
|
||
1. **前端只负责**：页面渲染、用户交互、表单收集、数据展示
|
||
2. **后端必须负责**：登录认证、权限校验、文件操作、AI 接口调用、业务判分逻辑、数据库操作
|
||
3. **前端不可以直接持有 JWT Secret 或 AI API Key** — 敏感凭据只在后端
|
||
4. **前端可以做格式和必填校验，但后端必须再次做强校验**
|
||
5. **所有权限以后端鉴权为准**：前端路由守卫仅作 UX 隐藏，不作为安全边界
|
||
|
||
---
|
||
|
||
# 第二部分：eaisalestrain_app 项目专用规则
|
||
|
||
> **适用范围**：仅适用于博昇内部培训平台项目。
|
||
> **使用方式**：本部分在通用规则之上叠加。若两者看似冲突，应先检查是否为项目专用规则对通用规则的场景化收敛。
|
||
|
||
## 索引
|
||
|
||
- P01：培训平台定位 — 知识库 + 考试 + 素材审批
|
||
- P02：知识库安全与检索边界
|
||
- P03：考试判分与记录规则
|
||
- P04：素材上传与审批流程
|
||
- P05：AI PathCoach 对话安全边界
|
||
|
||
---
|
||
|
||
## P01 最高原则：培训平台定位 — 知识库 + 考试 + 素材审批
|
||
|
||
1. 博昇内部培训平台是**公司培训知识库 + 考试引擎 + 素材审批**系统，不是在线课程平台，不是 AI 对话机器人平台。
|
||
2. **四个核心业务模块**不可偏移：
|
||
- **公司介绍**：博昇介绍 + 资质荣誉 + 发展历程（静态内容）
|
||
- **产品知识**：四大产品线（资本咨询/资质辅导/AI咨询/AI工具）的知识体系
|
||
- **销售培训**：对应四大产品的销售课程（话术/流程/异议处理/避坑）
|
||
- **考试中心**：自测练习 + 正式考试 + 成绩记录
|
||
3. **知识库是后台能力**：素材审批 → 文本提取 → 知识切片 → AI PathCoach 检索，不独立为前台页面。
|
||
4. **AI PathCoach 是辅助工具**：嵌入全局右侧栏，提供产品知识问答 + 情景演练 + 佣金查询 + 产品对比，不是产品中心。
|
||
5. 开始写某个模块前，先明确对应文档：
|
||
- `docs/04_Backend/BE*.md`（后端详细设计）
|
||
- `docs/06_Product_Lines/PL*.md`（产品原型）
|
||
- `docs/08_Design_Rules/DR*.md`（设计规则）
|
||
|
||
### 关联
|
||
|
||
- 关联 G08：前端不持有业务逻辑，AI PathCoach 调用必须走后端 API
|
||
- 关联 G02：配置/素材缺失必须报错，不静默兜底
|
||
|
||
---
|
||
|
||
## P02 最高原则：知识库安全与检索边界
|
||
|
||
1. **只存元数据，不存文件二进制**：数据库仅存储文件路径、大小、类型等元数据。
|
||
2. **素材文本存 knowledge_chunk 表**：审批通过的文档类素材经异步转换提取文本，切片写入。
|
||
3. **FULLTEXT 全文检索**：AI PathCoach 知识检索基于 MySQL FULLTEXT 索引，不做向量检索（不上 Milvus/Elasticsearch）。
|
||
4. **图片不进知识库**：png/jpg/jpeg 仅做存储预览，不做 OCR 提取，不进 AI 文本检索。
|
||
5. **审批前置**：素材只有 `approved` 状态才会触发异步转换；`pending` / `rejected` 的素材不进知识库。
|
||
6. **视频仅存储**：mp4 文件上传后仅做存储和预览，不做视频分析、不做帧提取。
|
||
|
||
### 关联
|
||
|
||
- 关联 G02：状态非 `approved` 的前端预览请求必须拦截
|
||
- 关联 G05：文件安全校验（扩展名 + UUID存储 + 只读预览）
|
||
- 关联 P04：审批是转换的前置条件
|
||
|
||
---
|
||
|
||
## P03 原则：考试判分与记录规则
|
||
|
||
1. **确定性判分**：判分逻辑采用确定性规则（单选/多选/判断），不涉及 AI 评分。
|
||
2. **判分逻辑必须在后端**：前端仅做选项展示和提交，不得在前端判分。
|
||
3. **自测 vs 正式考**：
|
||
- **自测(self_test)**：提交后立即显示正确答案 + 解析，不持久化成绩
|
||
- **正式考(formal)**：提交后判分落 `exam_record` 表，不显示正确答案
|
||
4. **考试 session 内存存储**：`_exam_sessions: dict[str, dict]` — 启动考试时抽题存入内存，不落数据库。
|
||
5. **正式考不可重做**：同一用户对同一正式考卷仅可提交一次（后端校验）。
|
||
|
||
---
|
||
|
||
## P04 原则：素材上传与审批流程
|
||
|
||
1. **管理员上传自动通过**：管理员（`role=admin`）上传的素材直接 `approved` + 立即触发异步转换。
|
||
2. **员工上传需审批**：员工上传后状态为 `pending`，管理员审批通过后才转 `approved`。
|
||
3. **驳回必须填写理由**：管理员驳回素材时，`reject_reason` 字段必填。
|
||
4. **异步转换管线**：审批通过 → 后台线程执行 `LibreOffice(ppt/docx→pdf) → PyMuPDF(提取文本) → 切片 → 写入 knowledge_chunk`。
|
||
5. **前端轮询状态**：前端通过 `GET /api/media/{id}/status` 轮询素材/转换状态，不使用 WebSocket。
|
||
6. **分片上传**：> 100MB 的视频文件走分片上传（init → chunk → complete）。
|
||
|
||
### 关联
|
||
|
||
- 关联 G02：状态/配置缺失必须报错
|
||
- 关联 G05：文件安全校验
|
||
- 关联 P02：审批是知识库转换的前置条件
|
||
|
||
---
|
||
|
||
## P05 原则：AI PathCoach 对话安全边界
|
||
|
||
1. **SSE 流式响应**：AI PathCoach 对话采用 SSE (Server-Sent Events)，末包采集 token usage。
|
||
2. **上下文注入规则**：AI 回答基于知识库检索结果 + 当前页面上下文，禁止注入管理员凭据/内部配置。
|
||
3. **快捷动作限范围**：
|
||
- `scenario`（情景演练）— 使用预设 prompt 模拟客户对话
|
||
- `commission`（查佣金）— 检索产品佣金数据
|
||
- `compare`（产品对比）— 对比两个产品参数
|
||
4. **LLM 配置链**：system_config 表 → .env 文件两层优先级，缺失任何一项（base_url/api_key/model）抛 `501 LLMNotConfiguredError`。
|
||
5. **禁止功能**：AI PathCoach 不做图片生成、不做代码生成、不做外部 API 调用。
|
||
|
||
### 关联
|
||
|
||
- 关联 G02：配置缺失 Fail Fast（501），不静默兜底
|
||
- 关联 G01：AI LLM 调用完整 Payload + 返回正文必须埋点日志
|
||
- 关联 G08：AI 调用全程在后端，前端仅展示流式输出
|
||
|
||
---
|
||
|
||
*注：本准则放置于项目根目录，作为全局 Rule 永久锁定。* |