公共开发约定

本页维护跨端、跨模块的公共契约、实现简洁性与调查验证范围。具体实现要求见后端工程规范、前端工程规范；文档交付要求见软件交付文档；工程树、权限模型等业务语义见业务地图。

代码与契约

• 后端包名使用 com.bokun.*，Maven 模块使用 digital-construction-*。
• 标准 CRUD 沿用项目 Entity、BO、VO、Mapper、Service、Controller 分层和 generator 骨架；前端标准 B 端页面先参考同类型成熟页面。
• 已有模块改造的取向按根 AGENTS.md“改造取向”执行：默认按新方案直接实现，不兼容旧数据、旧口径和旧方案。接口字段、枚举、状态、权限标识和分页结构发生变化时，仍须检索并同步全部调用方、删除被取代的旧路径，不能留下静默失配；破坏兼容、权限或状态变化须覆盖对应失败风险并说明影响范围，实施与证据依赖按根 AGENTS.md 执行。
• 逻辑删除必须与唯一性校验保持一致；金额单位、状态编码、字典值和名称快照必须在契约中明确。
• 数据库可迁移性是硬约束，DM8 只是当前运行环境；厂商方言集中到 Mapper/XML 或明确适配点，不散落到 Controller、Service。

实现简洁性

• 防止过度防御：针对缺少实际触发依据的假设性边界，不默认增加防护代码。针对此类边界提出、超出已确认需求的额外防护，先说明触发条件、发生可能性、后果和实现成本，经用户确认后增加；无法量化概率时明确不确定性，不编造数字。已确认业务契约、安全和数据一致性要求仍须满足；并发的处理与缺陷认定遵循根 AGENTS.md，不以理论竞争时序追加整改。
• 边界集中校验：外部输入在各自信任边界完成必要校验，同一可信调用链内已保证的条件通过明确类型与契约流转，不逐层重复判断。权限、资源归属、业务状态和适用的写入条件在责任层检查；前端校验不能替代后端校验，Java/TypeScript 类型不能代替外部数据的运行时校验。
• 拒绝提前抽象：单次使用且简短清晰的逻辑默认就近内联，不为未来可能复用创建 helper、通用层或配置框架。已有实际复用，或提取能明显隔离复杂职责、改善理解时才抽取；遵守既有分层，不以减少函数数目混合协议、业务和持久化职责。
• 控制复杂度：优先使用直接清晰的控制流，能在一个函数中清楚表达的同一职责不机械拆分。仅在需要恢复、转换异常或补充必要上下文时使用 try/catch，其余沿用统一异常处理；不吞异常、不重复捕获后原样抛出，不重复记录同一错误。必要资源清理和失败状态恢复仍须保留，优先复用现有机制。

组织单位契约

• orgType 是组织结构判定依据，deptCategory 只作业务标签。真实业主单位统一为 deptType=1 且 orgType ∈ {group, company, branch, joint_venture}；部门与项目部不能作为单位。共享单位选择器、服务端校验、最近单位解析及默认归属必须一致识别合资公司。
• 业主 company 下允许 joint_venture；集团及其他父级规则见组织架构。这不改变参建单位管理入口的写入规则，也不扩大权限或数据可见范围。
• 企业身份与业务角色分离：同一企业保留组织 ID，不因参与不同业务重复建档。项目参建主体与联合体企业候选另按工程基础需求规定的范围校验。

三段式权限码

权限标识统一使用三段式 模块:资源:动作（如 business:engineeringProcedure:list）。后端 @SaCheckPermission、SYS_MENU.PERMS/菜单按钮权限和前端 v-hasPermi 必须逐字一致。

禁止使用 模块:动作 两段式权限码：项目超级管理员默认通配权限为 *:*:*，段数不一致时也会被拒绝，表现为超级管理员访问接口 403。

动作动词白名单为 query、list、add、edit、remove、export、import、submit，以及已登记的特殊动作（如 resetPwd、publish、forceLogout、upload、download、unlock、cancel、invalid、active、copy、code、preview、gen、currentUpdate（czw 台账“本期更新”）等，以存量菜单为准登记）；禁止新增使用 update、delete 及未登记动词的权限码。存量动词漂移（czw 的 edit/update 并存、costUnit 与 investment 的 delete）已于 2026-09-30 清理：czw 的 update 改为特殊动作 currentUpdate，costUnit 与 investment 的 delete 统一为 remove；本规则生效起禁止新增。

新增业务域必须在模块 requirements.md 显式声明数据过滤策略（不过滤 / 工程数据授权），不允许缺省；角色数据范围（@DataPermission）机制已于 2026-09-29 整体移除，不再作为数据过滤选项。各业务域的现行定性基线见业务地图 · 权限模型，改变某域的可见范围须同步该表。

工程数据授权分类与契约

工程数据授权按业务资源属性严格划分为三类，由 EngineeringDataAccessHelper 统一执行：

1. 标段工点专属资源（单位工程、工程变更、质量报验、建渣台账，以及单位工程所属BIM模型等）：必须命中同线整线授权或同一条当前有效的 (bidId, siteId) 授权明细组合，严禁三维独立 OR 放行；BIM工点汇总只合并有权单位工程，见BIM需求；
2. 工点共享资源（三权移交等）：必须命中同线整线授权或至少存在一条当前有效且投影到该工点的授权组合；
3. 线路级完整资源（全线统筹文件等）：必须命中该线路的整线（FULL_LINE）授权。

授权配置通过 revision 乐观锁机制防止多管理员并发覆盖，接口发生 409 冲突时前端保留本地草稿并提示重新加载。

新增或调整权限时，检索后端、菜单和前端的适用位置，只修改受影响或不一致的内容；适用的三处权限标识仍须逐字一致，不为不存在的使用位置新增无业务需要的菜单或按钮。验证须覆盖三段式格式、适用位置的一致性及受影响的后端鉴权行为；自动化复用与真实链路替代方式按根 AGENTS.md 和测试与验证执行，不另设必须新增自动化用例的门槛。后端、SYS_MENU.PERMS 与前端三方一致性可用 .agents/tools/check-perms.mjs（verify.ps1 -Check Perms）辅助静态校验；菜单快照经项目 MCP 只读回读生成，不入仓库。

前后端大整数 ID 约定

项目数据库中的雪花 ID 使用 Java Long / 数据库 BIGINT 保存。JavaScript Number 的安全整数范围为 [-9007199254740991, 9007199254740991]；超出范围的 ID 一旦被解析为数字就会失真，不能再通过转回字符串恢复原值。

• 后端统一复用 digital-construction-common/digital-construction-common-json/src/main/java/com/bokun/common/json/handler/BigNumberSerializer.java：安全范围内保持数字，超出范围自动序列化为字符串；接口不得绕过项目 JSON 映射器自行输出 Long。
• 前端 ID 类型按 string | number 兼容历史数据，但收到大 ID 后必须保持字符串，不得使用 Number()、parseInt()、一元 + 或其他数字化转换；URL、请求体、树节点 key、表格 row-key、Map/Set 查找都要沿用原始 ID。
• 列表和详情合并时不得让可能失真的数字详情 ID 覆盖列表中的原始字符串 ID；编辑请求按本接口契约携带当前记录完整、未舍入的主键。

菜单接口排查示例

菜单接口的 menuId、parentId 同样遵守上述契约。当前 SysMenuVo 已明确使用 BigNumberSerializer，避免菜单编辑因 ID 失真而无法排除当前记录，错误提示“菜单名称已存在”。menuId 是菜单接口的主键字段名，其他业务使用各自接口约定的主键。

排查时先检查响应 JSON：超出 JavaScript 安全整数范围的 ID 应带双引号；再检查菜单更新请求中的 menuId 是否与数据库原值完全一致。例如数据库值 2100000000000001908 被前端解析后可能变成 2100000000000001800，会表现为详情为空、编辑保存时报同级菜单名称重复。

流程菜单与分类命名

菜单命名与排序

• 每个流程办理页在菜单管理中必须使用“流程定义名称 + 办理”作为菜单名称，例如“安全质量环保目标办理”“工作计划上报办理”；禁止将不同流程的办理页统一命名为“办理”。
• 菜单名称是动态路由的页面标题来源，流程名称变更时同步维护菜单名称；流程路径、组件路径和权限编码不因改名而改变。
• 办理页通常为隐藏菜单，但仍必须配置显示顺序：与对应业务台账使用同一父菜单，并紧跟在业务台账之后，确保动态路由和页面标签顺序可读、可定位。
• 新增流程或流程办理页时，完成菜单名称、父菜单、显示顺序和隐藏状态配置后，必须重新加载菜单路由核对；不得直接复制“办理”作为默认菜单名称。
• 隐藏的「xx办理」菜单仍须与对应业务台账一起授权给办理角色，用于侧边栏和面包屑；办理页已按业务归属在 src/router/flowFormRoutes.ts 固定注册，路由本身不依赖菜单授权。页面能否显示业务内容由后端接口权限与任务归属决定；新模块上线前按「角色 → 菜单、办理页、按钮权限」核对，不能把固定办理页的 404 归因于菜单未生成路由。
• 仅供系统内部跳转、且没有对应菜单行的页面同样要固定注册，否则按钮点击即 404：当前包括流程设计器 /workflow/design/index（流程定义的「修改流程/查看流程」）与代码生成内部地址 /tool/gen、/tool/gen-edit/index/:tableId。新增此类入口时，先在 src/router/index.ts 登记路由，再核对页面内的跳转地址。

流程分类与定义命名

• 流程分类必须先按页面层级建立对应的模块分类树，流程定义再归属到所属分类；流程定义名称使用该分类下对应页面的同名叶子名称，不重复拼接上级分类名称或模块前缀。例如页面层级为“非依法必招标管理 / 立项管理”时，分类为“非依法必招标管理”，流程定义名称为“立项管理”。
• 新建流程时先确认或创建页面对应的流程分类，再在该分类下创建同名流程定义，并同步核对流程编码、表单路径和办理菜单；流程编码保持稳定，名称、分类和页面层级不得互相冲突。

流程定义 JSON 编排

Warm-Flow 流程定义的 JSON 导入、画布布局、四向锚点坐标和版本管理统一遵循流程图编排规范。

任务分级

先调查再判断风险，不按改动行数、文件名或前后端层数预设范围。从目标问题和直接依赖开始，核对需求与规范、当前实现、历史依据及适用运行证据，依据共享调用、契约变化、数据流或实际失败证据扩展上下游与间接依赖，明确必须保持的正确行为。关键事实交叉核验；根因、基线或实际影响不明时继续查证。分类由 Agent 自行完成，不要求用户选档、填表或逐项确认。

能够解释触发条件与根因、确定必须保持的行为和实际影响范围，并选定相应验证后，调查即已充分，按当前授权进入方案、实施或交付阶段；非缺陷任务以明确目标行为和影响为准。没有关联证据的理论可能性不要求继续扩展。发现范围外问题或可选优化不自动纳入本次整改或完成条件；并发问题按根规则认定，不以理论并发时序扩大任务。

任务类型	调查重点	验证和交付
一两个局部样式、文案调整	核对真实可见影响及规范，确认无行为、共享机制和其他页面影响	默认核对差异与规范；浏览器由 Agent 判断或按用户显式要求执行，不机械运行类型检查或完整构建
功能、交互与缺陷修复	根因、相关需求、稳定契约、调用方及必须保持的行为	验证目标与受影响既有路径，浏览器分工按根规则；文档按事实是否变化同步
前置模块、共享机制、权限、金额、状态、数据范围、事务、持久化或工作流	上下游、间接依赖、历史数据及边界和失败场景；方案说明改造取向、影响范围与必要联动	对相应风险取得回归和实际链路证据，不能只验证目标模块或编译结果
发布或正式验收	环境差异、依赖版本、执行顺序与适用资料	按授权验证目标环境；流程定义默认双库同步及 prod 不可达例外按根规则

影响范围依据证据确定；有广泛依赖的小修改不能按局部任务处理，也不因一个部分风险高就扩大无关部分。必要技术调整和补充验证自主推进，只有新的业务取舍、实质扩围或越权才回到讨论。新规则、接口和表结构的记录见文档同步矩阵。

验证范围

• 验证依据是需求、稳定契约和已核实的正确行为，不照着新实现复制测试。先确定原问题、需保持的行为、实际影响与预期结果，再选择必要检查；只有新修改、新失败或新影响证据才扩大范围，不因复核中出现无依据的假设性建议追加完成条件。
• 复用有效用例，对关键且适合自动化的 BUG 和行为补齐可重复回归；不追求形式覆盖率，不机械全量测试或逐层重复。权限、金额、状态、数据范围、工作流、事务、接口和复杂查询的实际风险必须有证据。
• 验证方式与用户指定的分工统一按根 AGENTS.md“验证与页面证据”执行：Agent 依据风险选择足够证据，用户显式要求浏览器时执行。静态、构建、测试、接口、数据库与日志各证明其覆盖内容；未操作页面不得称页面交互或视觉验证通过，不因未选浏览器自动增加用户待验收项。
• 核对受测代码已加载，按实际角色、状态、数据及适用异常检查结果；写入检查回读实际持久化结果。既有失败先分析与本次关系，不直接归为历史问题。后续修改影响已验证行为时重跑相应检查。
• 环境障碍在授权内排查，继续独立检查，如实报受阻；不能自动把 Agent 检查转给用户，也不追加无关检查。必要范围均通过后结束验证；必要检查仍有证据缺口时不得称整体开发完成，但可按交付状态定义报告已完成的实现与当前验证结果。
• 普通任务可以引用可复核工具证据，无需额外建立矩阵或正式报告。命令见验证入口，记录见最新验证证据。

文档与协作边界

• 文档单一事实源、六类交付文档的生命周期和正式交付完成定义，统一见软件交付文档。
• 文档是否需更新及对应正文由代码变更与文档同步矩阵统一判定，不按代码文件类型机械联动。
• 业务规则澄清、批准、暂停和完成口径以仓库根目录 AGENTS.md 为准；验证层次、复用与范围收敛见本章验证范围，根规则的必要行为及证据要求仍适用。
• 代码与设计差异按软件交付文档 · 编写顺序与协作方式区分缺陷、文档滞后和基线冲突，不一律要求用户裁决；完成表述按该文档的最新验证证据口径限定范围。