shanxia2.0/AGENTS.md

AGENTS.md — shanxia2.0（山峡化工）

本仓库是三个应用共享后端与租户模型的单仓库，内部也使用 sanqiang 名称。 与用户交流时，用户使用简体中文则回复简体中文；业务文案与注释遵循现有语言习惯。

修改前必读

• 通用约束：工程规则。修改或评审代码前必须阅读。
• 后端：backend/AGENTS.md。
• Web 管理端与移动 H5：web-admin/AGENTS.md。
• 小程序：miniprogram/AGENTS.md。
• 保存、导入、复制、子数据移除、流程配置：子数据保存规则，必须完整阅读。
• UI 变更先查对应视觉规范，再选择参考页面；工具适配文件只提供入口。

工程结构与当前边界

路径	职责
backend/	Python 3.9 / FastAPI / SQLAlchemy / Pydantic v2 后端
web-admin/	Vue 3 / Vite / Element Plus / Tailwind CSS 管理端
web-admin/src/views/m/	同一 Web 应用内的移动 H5 页面
miniprogram/	uni-app 微信小程序
docs/	UI 规范、SQL、业务资料、开发文档与计划
openspec/	变更配置、需求与设计规范

CRM、地磅（db）、报销（bx）、运输（pl）已有本仓库实现，维护时追踪本地调用链。 工作流已有后端引擎和设计器、待办、已办页面；不能据此假定全部目标能力已实现。 旧生态规范的外部 CRM / 独立地磅边界已不适合限制当前代码维护，见工程规则中的冲突说明。 外部系统仍须按实际接口与表归属确认集成范围，不能仅凭名称决定修改位置。

业务数据红线

• 所有业务查询按当前用户 tenant_no 隔离，写入使用当前租户，不信任客户端覆盖。
• 数据权限与菜单权限均取当前用户全部角色的并集，业务查询必须执行数据范围过滤。
• 业务数据软删除：del_flag=1；默认查询排除删除记录，禁止物理删除。
• 无自定义排序时列表使用 create_time DESC。
• 子数据保存必须差量更新，保留已有有效明细 ID、创建信息和未提交业务字段。
• 遗漏集合保持不变，显式空集合才申请清空；校验与引用保护先于写入。
• 主单、子单和关系在同一事务内；严禁全删全增或通过客户端分步调用绕过。
• 编辑/复制 ID 往返、引用保护与例外范围以子数据专题文档为准，适用于所有客户端。
• 文件附件使用 MinIO，同字段多个附件使用逗号分隔 URL。
• 细胞存储样本关联规则仍适用于已有相关代码，详见后端规则，不推广到其他领域。

数据库、权限与 API

• MySQL 5.7 / utf8mb4；UUID 主键 id VARCHAR(64) NOT NULL。
• 字段顺序：id → 业务字段 → tenant_no、order_num、remark、create_by、create_dept_id、create_time、update_by、update_time、del_flag（默认 0）。
• 数据库变更同步维护 docs/sql/，同时评估 API、Pydantic、TypeScript 字段影响。
• 本库快照 docs/sql/shanxia2.0.sql；sx.sql / dibang.sql 是来源系统参考，不替代当前 schema 与迁移。
• 新路由同时注册 backend/app/api/__init__.py 和 backend/app/main.py；不得绕过认证、加密、审计。
• 角色选择子菜单自动包含祖先；Web / 小程序分别挂在各自 parent_id=0 虚拟根下。
• 租户管理仅 super_admin 可用；其他系统管理在租户上下文内执行。
• 自定义数据范围、工作流版本和审批策略等完整约束见工程规则。

UI 权威与共通要求

• Web：Fresh Mint 规范，主色 #10b981。
• 小程序：三墙规范，主色 #0a9f6d；跨端不得混用主色。
• Web 新页面按 界面模式索引 选 P01–P27；PR 写明模式编号和参考页路径。
• 树节点显示本级名称；输入框、表格、导出、查看态显示完整路径，分隔符 /。
• Web 弹窗顶部标签、无背景模糊；布局、按钮、表格、状态 Tag 和附件规则见 Web AGENTS。
• 小程序媒体比例、触达尺寸、拍照凭证上传规则见小程序 AGENTS。
• 不另造布局与色值；按已指定模板页和全局样式实现，保留各端约束。

常用开发入口

• 后端：在 backend/ 使用 ./start.sh --reload；参数先看 ./start.sh --help。
• 后端测试：启用项目虚拟环境后执行对应 pytest 测试；具体步骤见后端 AGENTS。
• 生产脚本是 backend/start-prod.sh；生产动作不属于默认本地检查。
• Web：在 web-admin/ 使用 pnpm dev、pnpm build、pnpm build:typecheck、pnpm lint。
• 小程序：遵循已有 HBuilderX / uni-app 流程和子目录 README；不要把占位 test 当成有效测试。
• 依赖、脚本与环境变量以当前文件为准；不要凭过时文档发明不存在的命令。

改动与验证

• 只做最小必要改动，不重构或格式化无关文件，不移动真实业务代码来整理工程。
• 路由保持薄层，业务放 services / crud；前端遵循周边命名、类型和导入风格。
• Web 使用 pnpm；Vue 和 Element Plus 自动导入规则见子目录，不重复手工导入。
• CRUD 可读字段以 _row_to_dict 为准；schema 与前端覆盖全部可写字段，排除计算和只读字段。
• 逐项核对字段并执行相关回归；不要调用或声称通过不存在的通用一致性脚本。
• 实际执行与变更风险匹配的验证，记录结果；未运行项明确说明，不能声称已通过。
• 提交遵循 Conventional Commits，以完整句子说明改了什么、为何；提交范围保持最小。

规范与文档维护

• 工程规则 汇总 API、数据库、权限、工作流及历史规范冲突的处理方式。
• OpenSpec 入口是 openspec/config.yaml，保留现有 changes 结构与能力命名约定。
• 实现和评审对照 Requirement / Scenario，并交叉核对 UI 权威文档。
• 历史规范未被本次目录清理改写或归档；未冲突的 SHALL 继续遵守。
• 验收与归档是独立动作，不能按文档日期、文件位置或清理需求自动判断已完成。
• 新设计与计划遵循所用技能指定路径，例如 docs/superpowers/specs/ 与 docs/superpowers/plans/。
• 文档索引记录原位置与状态，不为分类擅自移动历史资料或业务源码。
• .cursorrules、Cursor mdc、OpenCode 入口引用上述共同规则，避免维护重复规范。
• graphify 已停用；旧计划中的图谱生成与更新步骤不再执行。