shanxia2.0/openspec/changes/zkxw-engineering-standards/specs/architecture-conventions/spec.md

ADDED Requirements

Requirement: 仓库采用前后端分离的一体化门户形态

山峡化工 SHALL 以「Python 后端 + Web 管理端 + 小程序端」的形态组织代码与部署单元；业务域（细胞存储、中试、系统管理等）共享同一后端与租户模型，除非需求文档明确声明独立子系统。

Scenario: 新人识别工程边界

• WHEN 阅读仓库根目录说明或 OpenSpec architecture-conventions
• THEN 文档 SHALL 指明后端入口、管理端入口、小程序工程目录及 API 前缀约定（与 AGENTS.md 一致）

Requirement: 技术栈与需求文档 §3 对齐

系统 SHALL 使用 MySQL 5.7 作为关系型数据库；后端 SHALL 使用 Python 实现；Web 管理端 SHALL 基于 Vue 技术栈在精简后的管理端模板工程上扩展；小程序 SHALL 基于 uni-app、Vue 3 与 Vant 体系实现业务界面（与《shanxia2.0需求 V0.3》§3 及当前 miniprogram 工程一致或可文档化迁移）。

Scenario: 技术选型评审

• WHEN 新增服务或子工程选型
• THEN 选型说明 SHALL 论证与上述栈的兼容性，或作为独立变更更新本 spec 与 proposal.md

Requirement: 附件与对象存储

业务附件 SHALL 通过对象存储（如 MinIO）保存可访问 URL；多附件在同一字段内存储时 SHALL 使用英文逗号分隔多个 URL（与需求 §3 一致）。

端侧分工：

• web-admin：通用附件（图片/视频/办公文档等）按 ui-conventions「附件上传卡片化布局」上传与展示。
• miniprogram（当前基线）：仅拍照/相册图片凭证，按 ui-conventions「小程序拍照凭证上传（基线）」与 api-conventions「小程序拍照凭证上传接口」；文档类附件不在小程序基线范围内。

Scenario: 上传列表回显

• WHEN 业务实体包含多个附件
• THEN 持久化字段 SHALL 为逗号分隔的 URL 字符串，且接口契约与前端解析逻辑一致

Scenario: 小程序与 Web 附件能力边界

• WHEN 同一业务在 Web 与小程序均需留存材料
• THEN 小程序侧 SHALL 仅实现拍照凭证 URL 链路；若业务必须上传 PDF 等文档，SHALL 引导在 Web 完成或先扩展 OpenSpec 后再实现

Requirement: 权威文档索引

实现类变更 SHALL 将 工程规范、docs/web-admin-ui-spec-fresh-mint.md、docs/miniprogram-ui-spec-sanqiang.md 及 AGENTS.md 视为架构与规范的索引入口；多系统 SQL 与 CRM/地磅边界 SHALL 以 ecosystem-landscape spec 为准；OpenSpec 变更 SHALL 在 proposal.md / design.md 中保持对上述路径的引用。

Scenario: UI 相关 PR 描述

• WHEN 提交涉及 Web 或小程序界面的 PR
• THEN PR 或关联 OpenSpec SHALL 声明遵循的 UI 规范文档路径