zkxw/openspec/changes/zkxw-engineering-standards/design.md

Context

• 业务与数据规则来源：docs/中科兴皖需求V0.3.md（含菜单、表模型、§3 技术要求、§2.1.11 工作流、§2.1.5 权限等）。
• Web 端视觉与交互权威：docs/web-admin-ui-spec-fresh-mint.md 及其中引用的 docs/fresh-mint-green.html。
• 小程序端权威：docs/miniprogram-ui-spec-sanqiang.md 及其中列出的 mobile-ui/sanqiang-*.html。
• 工程运行与目录约定：AGENTS.md、.cursorrules、后端 app/ 与前端 web-admin/、miniprogram/ 现状。

本变更的 specs/*/spec.md 为可测试的规范摘要；凡涉及色值、类名、组件级布局的细则，不以本 design 重复展开，而以对应 Markdown/HTML 为准，避免双源漂移。

Goals / Non-Goals

Goals:

• 用 OpenSpec 将「架构 / 接口 / UI / 编码 / 库表 / 工作流 / 权限」七类约束写成可追溯的 SHALL 与场景。
• 明确「需求 §3」与「两份 UI 规范」之间的分工：前者定数据与租户/API 行为，后者定界面 Token 与页面骨架。

Non-Goals:

• 不替代需求文档中的完整表字段与业务流程叙述。
• 不规定具体 REST 路径命名或 Pydantic 字段命名（除非需求或仓库已有全局约定）；此类细节留在各功能变更的 spec 中展开。
• 不在此变更中实现工作流引擎或权限中间件代码。

Decisions

1. 规范分层

   • Normative（强制执行）：需求 V0.3 §3、specs/database-conventions、specs/api-conventions 中与租户/软删/排序/附件相关的条目。
     
   • Normative（UI）：specs/ui-conventions 中「以文档为权威、禁止跨端调色板混用」等；像素与类名级规则引用原文档。
     
   • Descriptive（设计说明）：本 design.md 仅解释如何阅读上述分层。

2. 能力拆分粒度
   按用户请求的七大主题拆为七个 capability，便于按域评审与归档；跨域条目（如「租户」同时影响 API 与库表）在相关 spec 中各写一条，避免单文件过长。

3. 与实现仓库的关系
   后端已为 FastAPI + /api 前缀等（见 AGENTS.md）；与需求 §3 中「前端基于 art-design-pro + pnpm clean:dev」「小程序 HBuilderX + uni-app + Vue3 + Vant」在 architecture-conventions 中记为 SHALL「须与当前仓库技术栈一致或可渐进迁移」，具体迁移不在本变更范围。

Risks / Trade-offs

• [规范与代码漂移] → 大版本或基线发布时执行 openspec archive 将变更合入 openspec/specs/，并在 PR 模板中引用对应 requirement id。
  
• [摘要过粗导致落地争议] → UI/表结构仍以原文档与 docs/sql/ 为准；争议时以需求/设计稿变更驱动增量 spec。
  
• [七文件维护成本] → 跨域同一概念允许多处一句话重复，优先可读性而非 DRY。

Migration Plan

• 无数据迁移。团队采纳后可将 openspec/config.yaml 增加 context 摘要指向本变更目录。
• 若后续归档：按 OpenSpec 归档流程将 specs/ 合并入 openspec/specs/。

Open Questions

• 需求 §3 写明的「前端 art-design-pro」与当前仓库 web-admin 若存在差异，是否以仓库为准统一需求文档（产品决策）。
• 工作流「SQL 模式审批人」的安全边界（只读从库、语句白名单等）待专项安全设计补充。