shanxia2.0/docs/development/engineering-rules.md

# 工程规则与当前系统边界

本文承接根 AGENTS.md 的通用硬约束。修改代码前必读；子目录 AGENTS.md 补充各端规则。

## 当前工程事实与历史资料

本仓库是 Python FastAPI 后端、Vue 3 Web 管理端、uni-app 小程序三个应用组成的单仓库。Web 同时承载 `web-admin/src/views/m/` 移动 H5 页面；各端共用后端与租户模型。

当前仓库已经包含 CRM、地磅（db）、报销（bx）、运输（pl）业务，不能再按“CRM 或地磅只能去外部仓库”限制维护现有实现。证据入口：`backend/app/api/crm.py`、`backend/app/api/db/`、`backend/app/api/bx/`、`backend/app/api/pl/`，以及 `web-admin/src/views/crm/`、`web-admin/src/views/db/`、`web-admin/src/views/bx/`、`web-admin/src/views/pl/`。

`docs/sql/shanxia2.0.sql` 是本仓库数据库快照；`docs/sql/sx.sql` 和 `docs/sql/dibang.sql` 是 CRM / 地磅来源系统模型资料，不能替代当前表结构与迁移。并列的 `shanxia/crm/` 是历史来源位置描述，不是本仓库现有 CRM 的唯一代码位置。跨系统修改须先确认实际 API、表归属和变更范围，不能仅凭表名前缀推断。

旧生态规范 `openspec/changes/zkxw-engineering-standards/specs/ecosystem-landscape/spec.md` 中“CRM 仅在外部 / 地磅独立”的描述与当前实现冲突，此处明确为历史参考；本文件的当前事实用于代码定位。这不表示旧变更已经归档，也不表示所有历史需求均已实现。其他未冲突的 SHALL 约束仍须遵守。

## API 与数据访问

- **Cell-storage sample cross-table key**（仅在涉及现有细胞存储样本功能时适用）: Matching `biz_protocol_sample` to downstream rows (sample reception, QC work orders, etc.) SHALL use `tenant_no` + `sample_code` only—not `collection_protocol_id` or `protocol_sample_id` (protocol may change; sample code does not). See `openspec/changes/zkxw-engineering-standards/specs/api-conventions/spec.md` §「细胞存储样本跨表关联键」.
- **Tenant isolation**: All business data queries SHALL filter by current user's `tenant_no`. All write/update endpoints SHALL set `tenant_no` to the current user's tenant. MUST NOT trust client-submitted tenant overrides (unless multi-tenant admin API with security review).
- **Data permission**: All business queries SHALL apply data scope filtering based on the union of all roles assigned to the current user (menu + data permissions both use union semantics).
- **Default sort**: Lists SHALL sort by `create_time DESC` when no custom sort is specified.
- **Route registration**: New route modules SHALL be registered in `app/api/__init__.py` AND `app/main.py`. SHALL NOT bypass auth/crypto/audit middleware.

## 数据库

- **Engine**: MySQL 5.7, charset utf8mb4.
- **Public fields** (every business table SHALL include these after business fields): `id` VARCHAR(64) UUID, `tenant_no`, `order_num`, `remark`, `create_by`, `create_dept_id`, `create_time`, `update_by`, `update_time`, `del_flag` (default `0`).
- **Field order**: `id` → business fields → public fields (`tenant_no` through `del_flag`).
- **Soft delete**: SHALL NOT physically delete business data. Delete = set `del_flag=1`. Queries SHALL exclude `del_flag=1` by default.
- **Primary key**: `id` SHALL be `VARCHAR(64) NOT NULL`, UUID value.

数据库改动必须同步维护 `docs/sql/` 的 schema / 迁移 SQL，并评估 API、Pydantic 和 TypeScript 类型影响。数据库快照不代表可直接执行的生产迁移。

## 子数据与附件

涉及子数据写入必须阅读 [子数据保存规则](child-data-save-rules.md)，包括差量更新、字段遗漏语义、身份校验、引用保护、事务与客户端 ID 往返；不能以摘要代替完整规则。

文件附件必须使用 MinIO 对象存储，同一字段的多个附件使用逗号分隔 URL。小程序拍照凭证与 Web 通用附件分别遵守各端 AGENTS.md。

## 编码与字段一致性

- **Minimal changes**: Commits SHALL contain only what's needed. No unrelated refactoring or formatting.
- **Frontend (web-admin)**: pnpm, Prettier (single quotes, no semicolons, 2-space indent). Vue/Element Plus auto-imports — SHALL NOT manually import auto-imported APIs/components.
- **Backend**: Python 3.9, FastAPI + SQLAlchemy + Pydantic v2. Routes stay thin; business logic goes in `app/services/` and `app/crud/`. Config via `pydantic-settings` + `.env` files.
- **DB changes**: SHALL maintain SQL in `docs/sql/`. Schema changes SHALL align with `database-conventions` public field rules.
- **Commit messages**: SHALL be complete sentences describing "what changed and why". Follow Conventional Commits (`feat|fix|docs|…`).
- **Field consistency (CRUD ↔ Schema ↔ Frontend)**: When implementing CRUD for any entity, the `_row_to_dict` function is the **single source of truth** for all readable fields. The CreateBody/UpdateBody Pydantic schemas and the frontend `formData` initialization SHALL include every writable field present in `_row_to_dict` (excluding computed/read-only fields like `id`, `createTime`, `updateTime`, `stockQty`). 逐项核对 CRUD、CreateBody/UpdateBody 与前端 formData，并执行对应回归测试；仓库当前没有通用字段一致性检查脚本，不得宣称已通过不存在的检查。

## 权限

- **Role-menu**: Selecting a child menu SHALL auto-include all ancestor menus (no orphan leaves).
- **Data scope**: Per role — all / own dept / own dept and below / self only / custom. Custom uses `sys_role_data_scope_detail` with `scope_type` (dept/user) + `scope_value`.
- **Multi-role union**: A user with multiple roles gets the **union** of menu permissions and the **union** of data scopes across all roles.
- **Dual menu trees**: Web and miniprogram each have a separate top-level virtual root (`parent_id=0`). New menus SHALL be placed under the correct root.
- **Tenant management**: Accessible ONLY by `super_admin`. All other system management runs within tenant context.

## 工作流：现有实现与后续约束

已有 `backend/app/services/workflow_engine.py`、`backend/app/api/workflow.py` 和 `web-admin/src/views/system/workflow/` 的流程设计、待办、已办页面。以下为持续维护的设计约束，不能据此声称所有节点、策略或版本能力都已完备；每次修改应对照代码和测试确认支持范围。

- **Engine**: 工作流子系统已存在于 Python 后端；继续按独立、可配置的审批/流程子系统演进。
- **Node types**: Start, End, Approver, Conditional Branch (multi-branch supported). Extensible but SHALL NOT break published definitions.
- **Approver strategies**: Specified users, specified roles, or SQL-based resolution. Per-node: "any one passes" or "all must pass".
- **Versioning**: Each flow definition has a version. Running instances SHALL stick to their launch version; new versions only affect new launches.
- **Task centers**: System SHALL provide "Pending Tasks" and "Completed Tasks" views.

## 规范和文档生命周期

需求依据为工程规范及对应变更，UI 权威为 [Web UI 规范](../web-admin-ui-spec-fresh-mint.md)、[小程序 UI 规范](../miniprogram-ui-spec-sanqiang.md)。工具适配文件只索引规范，不复制新的规则版本。

使用 OpenSpec 时遵守 `openspec/config.yaml`，proposal 的 Capabilities 须与 `specs/<kebab-name>/spec.md` 对应。实现和评审须对照 Requirement / Scenario。`openspec/changes/` 下的变更不可因为日期久或目录整理就自动归档；只有完成验收并执行归档流程后，才按实际 `openspec/specs/` 基线管理。

设计和实施计划遵循所用技能要求的路径（例如 `docs/superpowers/specs/`、`docs/superpowers/plans/`）；文档索引记录状态与原路径，不为整理目录擅自移动或归档。历史 SQL、需求、计划与业务资料保持可追溯。