Imported from fh-369/tcm-consultation-platform (AGENTS.md). Install upstream with npx skills add fh-369/tcm-consultation-platform. Copyright stays with the author.

AGENTS.md

本文件记录本项目中 Codex 与用户协作时必须遵守的默认规则。每次开始工作前，先阅读并遵守这些规则。

主线文档

• 严格按照 docs/中医问诊与养生平台_Git与GitHub双线实战指南.md 的 Day 顺序推进。
• backend/README.md 只用于澄清具体代码要求，不用于改变实战指南的执行顺序。
• 不提前实现后续 Day 的功能；如果发现前置阻断，应说明属于哪个后续 Day。

每个 Day 的开始方式

• 每个 Day 开始前，先说明：
  • 这个 Day 属于哪个模块。
  • 本 Day 要实现哪些具体功能。
  • 会修改哪些类型的文件。
  • 验收方式是什么。
• 说明后等待用户确认。
• 用户确认后，非 Git 操作可以连续执行到本 Day 技术验收完成。
• 只有遇到 Git 操作、高风险选择、凭据缺失、需求冲突或用户明确要求亲手操作时，才停下来让用户处理或确认。

代码与文件修改

• 补全、完善、修复代码时，Codex 可以直接修改源文件。
• 如果创建文件是当前开发任务的一部分，Codex 可以创建并填充；如果用户明确要求亲手创建文件，则等待用户创建后再继续。
• 不做无关重构，不提前实现未来 Day 的内容。
• 不把数据库密码、JWT 密钥、API Key 等敏感信息写入源码、配置文件或提交记录。
• 优先使用当前电脑已有环境，例如本机 JDK、Maven、MySQL；确实缺失时再提示安装。

验证规则

• 功能验证通过后，再进入 Git 操作。
• 验证要基于实际命令或可解释的检查结果，不用“应该可以”代替验证。
• 如果完整编译被后续 Day 的已知 TODO 阻断，要明确说明阻断文件和原因，并尽量验证当前 Day 的局部功能。

需求确认与执行

• 涉及较多代码、页面布局、交互方式、数据结构或接口协议的修改前，必须先输出执行方案。
• 方案应说明目标、修改范围、数据流、验收方式和可能影响。
• 等待用户明确确认后再修改文件。
• 已确认方案内的非 Git 操作可以连续执行到验证完成，不需要每修改一个文件就停下询问。
• 小范围、目标明确的文字、样式或单点 Bug 修复，可以说明后直接执行。

页面体验修改

• 优先保留现有页面结构和已经确认的设计语言，不进行未经确认的整体重做。
• 用户指出局部问题时，先局部修复，不顺带改造其他区域。
• 涉及视觉方案时，应区分占位图和正式素材。
• 页面修改后必须检查真实数据、空状态、加载状态、错误状态和权限失效状态。
• 桌面端是当前优先目标，除非用户明确要求，不额外扩展手机端适配。

调试规范

• Bug 修复前先复现并定位根因，不连续叠加猜测性补丁。
• 前后端问题应分别检查请求、响应、鉴权、状态更新和页面渲染。
• 配置、环境变量、安全规则或后端接口发生变化后，明确提醒需要重启后端。
• 不将“模型超时”“网络错误”或 403 简单归为单一原因，应结合日志和请求状态判断。

验证与汇报

• 修改完成后说明实际运行过的测试、构建和页面验证。
• 无法执行的验证必须明确说明原因。
• 不使用“应该可以”代替验证结果。
• 用户完成实际页面验证后，再进入 Git 提交步骤。

Git 默认规则

• Git 操作默认由用户在 VS Code 中完成。
• Codex 只在以下情况执行 Git 操作：
  • 用户明确要求 Codex 执行。
  • 操作复杂、容易出错，或学习价值较低。
  • 只读 Git 检查，例如 git status、git log、git diff。
• 不自动提交、合并、推送、变基、打标签或创建 PR。
• 需要提交时，先说明推荐提交拆分和提交信息。
• 推送、合并、打标签前必须再次确认。
• 提交前由 Codex 只读检查分支、工作树和改动范围。
• Codex 应提供推荐的暂存范围、英文提交信息和提交内容摘要。
• 功能分支推送后通过 PR 合并到 main；合并后同步本地 main。
• 删除分支前确认 PR 已合并、main 已同步且该分支不再需要。

删除规则

• 禁止批量删除文件或目录。
• 不要使用：
  • del /s
  • rd /s
  • rmdir /s
  • Remove-Item -Recurse
  • rm -rf
• 需要删除文件时，只能一次删除一个明确路径的文件。
• 如果需要批量删除文件，应停止操作并让用户手动删除。
• 如仅删除一个明确文件，删除后可以删除由此产生的明确空目录，但不得使用递归删除。

Day 结束规则

• 每个 Day 完成后，输出压缩上下文摘要，包含：
  • 当前分支和远程同步状态。
  • 本 Day 完成的功能。
  • 关键提交。
  • 工作树状态。
  • 已知后续问题。
  • 下一 Day 的入口。

当前产品完善总路线

实战指南主线完成后，当前产品完善阶段按以下大体进度推进。每个大阶段仍需拆成可独立测试、提交和回滚的小阶段，不得一次性完成全部内容。

1. 人员管理
   • 管理员查看用户、医生列表及账号状态。
2. 多医生分配模型
   • 完善医生信息、问诊分配、认领和转派机制。
3. 医生个人工作台
   • 仅显示待认领、分配给自己、处理中和已完成问诊。
4. 管理员问诊调度
   • 查看全部问诊，按医生、状态、紧急度筛选并进行分配。
5. 问诊详情与处理流程
   • 医生接诊、填写回复、更新状态并记录随访。
6. 后台内容管理
   • 完善养生文章和药膳的新增、编辑、发布及封面管理。
7. 数据与系统优化
   • 完善统计、导出、角色权限和操作反馈。
8. 后台整体验收
   • 分角色测试权限、空状态、异常状态和完整业务流程。

当前多医生体系继续按以下子阶段顺序推进：

1. 科室与医生准入基础
   • 建立科室数据、医生申请、管理员审核和医生资料编辑。
2. 问诊科室分诊
   • 用户提交时选择科室，旧问诊归入“综合咨询”，管理员可修改科室。
3. 医生工作台拆分
   • 增加“科室问诊池”和“我的问诊”，回复只在个人问诊中进行。
4. 管理员调度升级
   • 按科室、医生、状态筛选，支持跨科室转诊和重新分配。
5. 智能自动分配
   • 根据科室、启用状态、未完成数量和排班自动选择医生。

执行新子阶段前，必须说明它在上述总路线中的位置、明确本阶段不包含的后续功能，并等待用户确认。