zkxw/AGENTS.md

AGENTS.md — 中科兴皖一体化门户（zkxw）

工程与查阅范围

共享 FastAPI 后端的四应用仓库。项目说明见 README，文档入口见 docs/README。

目录	职责	专用规则
backend/	API、权限、业务数据、工作流与 OA 引擎	backend/AGENTS.md
web-admin/	Vue 3 管理端	web-admin/AGENTS.md
mobile-h5/	HBuilderX uni-app，小程序及移动宿主	mobile-h5/AGENTS.md
mobile-oa-h5/	Vue/Vant H5，OA 表单与市场业务	mobile-oa-h5/AGENTS.md

修改前阅读目标目录规则；跨端改动同时阅读涉及端的规则。

工作方式

• 用户使用中文时用简体中文沟通；代码命名、注释、格式遵循所在模块。
• 仅做任务必要的改动，不夹带无关重构或全仓库格式化；保留用户已有改动。
• 不得自行停止、启动或重启 web-admin 开发服务与 backend 服务。 需要重启时告知用户，由用户操作。
• 提交使用 Conventional Commits，完整说明“改了什么、为什么”。
• 需求开发与 Bug 修复：用户给出 Gitea 工单编号或链接时，先读取该工单描述、评论和验收条件再处理；未给编号时，先在当前工程 Gitea 仓库创建工单，再开发。继续当前已关联任务时复用原工单，不重复创建；已有授权下由 AI 创建和回写，不再要求用户代建。
• 修改端不明确时，先查当前任务和工单的已确认范围；仍不明确则询问修改 Web、小程序、移动 OA、后端中的哪些端，还是所有相关端。确认前仅只读定位、回写工单待确认范围，不修改业务代码；截图不能代替确认。已有明确范围直接沿用，答复“所有端”须记录具体应用清单；共享后端/API 影响范围外的端时，说明影响并确认扩展后再实施。
• 默认由 Agent 测试：自动进入任务分支/worktree，核对实际运行版本，完成测试与审查后合入 V2.0、提交推送、同步本地主分支并关闭 Gitea 工单。用户已授予这条常规收尾链路持续授权，不逐次询问合并；打 tag、部署与服务启停仍分别受原有授权限制。
• 用户明确“我来测试”时，该任务由用户测试：Agent 不运行测试或构建，仍完成代码审查和 Git 核对；交付时提醒切换到具体分支，提供 worktree 路径、提交、前后端配套入口和验证要点。用户确认通过后直接合并推送、关闭工单；未确认或失败时不合并、不关闭。
• 合并前核对验收提交与最新目标；目标更新或冲突处理改变代码时，按原测试责任补验，用户模式仍交用户验证。合并后代码树与验收版本一致不重复测试；确认远端同步成功后回写验收结果、合并提交和 PR 并关单。
• 不把真实凭据、业务导出、虚拟环境、构建产物和工具临时状态新增到版本管理。
• 清理文件前核查代码、测试、脚本、部署及文档引用；不能只凭名称、日期或搜索无结果删除。

跨端数据与权限底线

• 业务查询必须按当前用户 tenant_no 隔离并应用数据权限；写入租户来自认证上下文，不信任客户端覆盖。多租户管理例外须有安全评审。
• 菜单和数据权限使用所有有效角色的并集；选中子菜单必须包含祖先菜单。Web 与移动菜单使用各自 parent_id=0 的虚拟根。
• 租户管理仅 super_admin 可访问，其他系统管理运行在租户上下文。
• 业务数据软删除（del_flag=1），查询默认排除已删除数据。
• 保存子行使用 backend/app/crud/child_row_sync.py：原行更新、新行插入、只软删除移除行，禁止全删重建。拒绝其他父记录或租户的 ID；复制时生成新 ID。
• 细胞存储样本跨表匹配使用 tenant_no + sample_code，不用可变化的协议关联 ID 作为匹配键。
• 业务附件使用 MinIO；单字段多附件按英文逗号分隔 URL，前后端解析一致。
• 数据库变更维护 docs/sql/，同时检查 API Schema、CRUD、前端字段及类型；不绕过鉴权、加密、审计中间件。

规范入口

• 工程 SHALL 要求：OpenSpec 工程标准。按改动范围查阅 API、数据库、权限、编码、架构、工作流及 UI 专题。
• Web UI：Fresh Mint 规范、P01–P27 模式索引。主色 #10b981，不得混入移动端主色。
• 移动 UI：移动端规范。规范品牌绿 #0a9f6d；现有 Token 存在差异，按各端 AGENTS 记录处理，禁止直接套用 Web 主色。
• Cursor 配置仅作入口，不再独立维护另一套规则。规范与实现冲突需查明依据，不以代码现状默认为新规范。
• OpenSpec 长期规范尚未完成归档；不要因 openspec/specs/ 目录存在就认定其中已有基线。

验证与交付

• 按任务测试责任验证，报告实际结果和未执行项：Agent 模式按改动范围检查文档链接或业务测试与构建；用户模式记录用户验收结论，不由 Agent 运行测试和构建。
• CRUD 字段一致性按 开发指南 检查；根目录命令是 python backend/scripts/check_field_consistency.py。该工具仅覆盖注册实体，已知失效路径见该指南。
• 使用源码、引用检索和测试核对影响范围。已移除的 graphify 不再是开发依赖或交付步骤，不安装、运行或恢复其自动 hook。

维护边界

• 当前 SQL 初始化基线不完整，部分测试引用的迁移文件已缺失；未验证前不宣称可从空库部署。
• 业务历史方案、执行计划、Demo 与整理报告已清理；保留四个应用目录、现行工程规范及被部署或脚本读取的 SQL、SOP 等资源。
• 文档优先更新现有 README 或规范入口，避免重复生成历史业务方案和整理报告。
• 更改规则应同步唯一的对应入口，不在多个文件复制完整细则。