95 lines
6.7 KiB
Markdown
95 lines
6.7 KiB
Markdown
# AGENTS.md — shanxia2.0（山峡化工）
|
||
|
||
本仓库是三个应用共享后端与租户模型的单仓库，内部也使用 sanqiang 名称。
|
||
与用户交流时，用户使用简体中文则回复简体中文；业务文案与注释遵循现有语言习惯。
|
||
|
||
## 修改前必读
|
||
|
||
- 通用约束：[工程规则](docs/development/engineering-rules.md)。修改或评审代码前必须阅读。
|
||
- 后端：[backend/AGENTS.md](backend/AGENTS.md)。
|
||
- Web 管理端与移动 H5：[web-admin/AGENTS.md](web-admin/AGENTS.md)。
|
||
- 小程序：[miniprogram/AGENTS.md](miniprogram/AGENTS.md)。
|
||
- 保存、导入、复制、子数据移除、流程配置：[子数据保存规则](docs/development/child-data-save-rules.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 规范](docs/web-admin-ui-spec-fresh-mint.md)，主色 `#10b981`。
|
||
- 小程序：[三墙规范](docs/miniprogram-ui-spec-sanqiang.md)，主色 `#0a9f6d`；跨端不得混用主色。
|
||
- Web 新页面按 [界面模式索引](docs/web-admin-ui-pattern-index.md) 选 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，以完整句子说明改了什么、为何；提交范围保持最小。
|
||
|
||
## 规范与文档维护
|
||
|
||
- [工程规则](docs/development/engineering-rules.md) 汇总 API、数据库、权限、工作流及历史规范冲突的处理方式。
|
||
- OpenSpec 入口是 [openspec/config.yaml](openspec/config.yaml)，保留现有 changes 结构与能力命名约定。
|
||
- 实现和评审对照 Requirement / Scenario，并交叉核对 UI 权威文档。
|
||
- 历史规范未被本次目录清理改写或归档；未冲突的 SHALL 继续遵守。
|
||
- 验收与归档是独立动作，不能按文档日期、文件位置或清理需求自动判断已完成。
|
||
- 新设计与计划遵循所用技能指定路径，例如 `docs/superpowers/specs/` 与 `docs/superpowers/plans/`。
|
||
- 文档索引记录原位置与状态，不为分类擅自移动历史资料或业务源码。
|
||
- `.cursorrules`、Cursor mdc、OpenCode 入口引用上述共同规则，避免维护重复规范。
|
||
- graphify 已停用；旧计划中的图谱生成与更新步骤不再执行。
|