pj0235-eai_agentplatform/CODING_RULES.md

eai_agentplatform_app 博昇内部培训平台 — 编码与调试最高准则

版本：V1.0 日期：2026-08-15 状态：必须强制执行 (Highest Priority) 适用范围：博昇内部培训平台前端、后端、数据库、考试引擎、AI PathCoach、素材上传与审批 AI 助手启动任何任务前必须先读取并确认本文件。

---

整理说明：参考 pj034-oeamgt TOP_CODING_RULES.md 结构体系重组。 分组方式：第一部分是 EAIHub 博昇 AI 中心通用规则；第二部分是本项目专用规则。 编号方式：第一部分 G01-G08；第二部分 P01-P05。

---

第一部分：通用开发规则

适用范围：适用于 eai_agentplatform_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 与 eai_agentplatform_app/CLAUDE.md。
2. 持续追踪：直到问题完全解决并经由日志或接口验证通过前，不得结束任务。
3. 新对话启动仪式：新对话必须先读 eai_agentplatform_app/PROJECT_STATE.md → CODING_RULES.md，再开始干活。
4. 发现规则与实现冲突时，优先提醒并修正，不得静默忽略。
5. Git 同步状态必须用 -sb 显式确认：首次执行 git 相关操作时，必须使用 git status -sb 或 git status -v 而非简短版本，确保能清晰看到本地与远端的 ahead/behind 关系。禁止依赖 git diff HEAD origin/HEAD 单条链式命令判断，因其 && 链在中间出错时会导致后续输出丢失。
6. Git 检查必须指定分支名：使用 origin/<branch>（如 origin/main）而非 origin/HEAD，避免 origin/HEAD 歧义。
7. 验证输出后再总结：在给出 git 状态结论前，必须确认所有关键信息（ahead/behind、clean/dirty、branch）均已成功读取，不得在未确认完整性的情况下返回结论。

---

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 隐藏，不作为安全边界

---

第二部分：eai_agentplatform_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 永久锁定。