常见问题与隐式机制

本页专门解释那些“框架已经帮你做了，但如果不说明就很像魔法”的默认设定，帮助读者理解 AgileLabs Framework 的运作机制。

适用场景

读规则时想知道“为什么这样设计”。
排查项目里某些默认行为的来源。
需要向团队解释框架隐式约定。

必须遵守

理解框架默认行为时，先确认正式规则页和宿主配置入口，不靠猜测默认值。
任何覆盖框架默认行为的实现都要在项目中显式记录。
不把隐式约定当作“谁都知道”的团队常识，文档和评审里都要写清楚。

推荐做法

从宿主配置、Json 配置、数据访问基类和 WorkContext 四个入口理解框架默认行为。
团队内部做规范解释时，优先引用本页和对应规则页。
发现项目里的隐式约定与正式规则不一致时，先补文档再讨论是否调整实现。

运作机制

PascalCase、snake_case、camelCase 分别对应代码层、数据库层和前端契约层，它们不是互相冲突，而是通过序列化配置、ORM 约定和映射层协同工作。
Json 命名与时间表现并不是控制器手写出来的，而是宿主阶段通过 JsonNetSerializerSettings 和相关转换器全局配置的。
审计时间、并发版本和用户展示时间不是同一类字段。框架默认处理的是存储和基础审计，项目级 resolver 处理的是用户视角时间。
数据访问默认路径已经收敛为 Dapper / SQL；EF Core 相关行为只应在遗留兼容和迁移过渡语境中理解。
统一返回包和 tid 的设计目标，是让前端错误处理、日志追踪和问题排查有一套稳定入口。

常见问题

“为什么 C# 用 PascalCase，数据库用 snake_case，前端又用 camelCase？” 因为三层分别遵循各自生态最稳定的约定，框架负责把层间差异变成统一转换，而不是要求所有层强行同一种写法。
“这些转换是谁做的？” 主要由 Json 序列化配置、ORM 命名约定、AutoMapper Profile 和必要的 DTO 层负责。
“现在数据访问默认是 EF Core 还是 Dapper？” 默认是 Dapper / SQL。EF Core 仅保留给存量项目兼容和迁移过渡。
“为什么 API 时间不用 ISO 字符串？” 因为字符串解析和时区语义容易漂移，统一成毫秒时间戳更稳定。
“为什么前端必须自己做本地时间展示？” 因为用户看到的是本地交互时间，而服务端保存和传输的是统一 UTC 语义。

相关检查

示例项目对照

gmandarin-backend：项目级时间 resolver 和多前端入口。
niusys-webapi：统一 Json 配置、统一封包和 Swagger 对齐。
woscm：数据库命名约定、UTC 审计时间和 TraceId 回写。