SL.Net 2.0 / Admin.NET 系统开发规范
用途
提供该技术栈下的项目结构、命名、实体/DTO/Service 写法、权限模型、缓存、事务、EventBus、定时任务、Excel 导入导出、i18n 与已知陷阱，使新增或修改功能时产出与现有代码库一致的代码。
第一步：确认框架版本
两套规范并存，动手前先判定，不要混用：
| 判定依据 | 版本 | 读取 |
|---|---|---|
后端是 {系统名称}.Application / Web.Entry / Plat.Application 多工程结构，用 IDynamicApiController、ApplicationConst.GroupName、EntityBaseData、SysCacheService、SerilogHelper |
新框架 | references/spec-slnet2.md |
后端是单工程 Entity/ DTO/ Service/ 目录，用 AdminResult<object> 手工赋码、Coravel 调度 |
旧框架 | references/spec-legacy.md |
无法从代码判定时询问用户，不要猜测。项目实际约定与规范冲突时以项目为准，并提示用户同步更新规范文档。
核心约定速查
后端新增接口（标准四步）
实体 → DTO → Service → 权限/菜单。
- 实体：放
Entity/Master（主数据）或Entity/Operation（业务单据）；类名主表{模块}MstrEntity、明细{模块}DetEntity；表名小写下划线{业务前缀}_mstr/_det；每个属性带[SugarColumn(ColumnName, ColumnDescription)]与 XML 注释；主键long Id，新增用YitIdHelper.NextId()。基类按需选择（EntityBaseId/EntityBase/EntityBaseData/EntityTenant*），没有IsDelete，删除即物理删除。 - DTO：
Page/List/Add/Update/Delete/Export入参一个文件，出参一个文件；加[Required]/[DataValidation]校验；日期范围用XxxFrom / XxxTo。 - Service：
IDynamicApiController, ITransient+[ApiDescriptionSettings(groups: ApplicationConst.GroupName, Order = N)]；仓储与依赖全部构造注入，禁止new、禁止静态实例；方法标[ApiDescriptionSettings(Name = "Page"), HttpPost]+[DisplayName]。 - 配权限：菜单管理里加按钮权限，权限码
{service}:{Name}（如whMstr:Page），并同步前端v-auth。不配权限码的接口对所有登录用户开放。
前端新增页面
api/api/{模块}-api.ts加接口函数（必须用封装的axiosInstance，禁止裸 axios/fetch）。api/model/加{模块}-model.ts与search{模块}-model.ts，字段 camelCase 对齐后端。{模块}/index.vue用tableHeader数组驱动表格列。_lang/三语言（zh-cn / en / zh-tw）同步加 key，页面不硬编码中文。- 按钮加权限码
v-auth。
关键红线（最容易踩）
- 新接口默认裸奔：未配按钮权限码的接口判定为放行，新增接口必须第一时间配权限。
- 动态列必须把所有用到的属性绑到
el-table-column（:prop/:label/:sortable/:width/:fixed），漏绑即不生效。 - PostgreSQL 行锁：SqlSugar 的
.With(SqlWith.UpdLock)不生成FOR UPDATE，需要行锁必须写原生 SQL。 - 日期参数显式转 DateTime（
GetCDate()）再比较，否则可能被绑成 text 导致类型不匹配。 - 缓存：统一走
SysCacheService，禁止拿内存缓存当分布式缓存；键名模块:业务:对象；增删改后必须清对应 key。 - 先提交事务，再调用外部接口或异步落库，避免长事务锁表；事务内异步落库需新开 scope。
- 配置文件格式敏感：Furion 的 json 只支持整行
//注释，行内注释或多余逗号会导致启动崩溃。 - 初始化开关
EnableInitDb / EnableInitTable / EnableInitSeed生产必须关闭，改表走 SQL 脚本（ADD COLUMN IF NOT EXISTS+COMMENT ON）。 - 雪花 Id 是 19 位 long，前端 number 会丢精度，出现回显错乱时后端序列化为 string。
- 任何网络 IO（UDP/HTTP/Redis）必须带超时与取消令牌。
- Redis 密码必须与服务器一致，本地无密码时连接串不要带
password=。
参考文件
references/spec-slnet2.md—— 新框架完整规范（SL.Net 2.0 / Admin.NET），含实体基类对照表、错误码表、事务与行锁写法、Excel 导入导出、14 条通用踩坑。references/spec-legacy.md—— 旧框架通用模板（单工程 +AdminResult<object>+ Coravel）。references/how-to-place.md—— 这两份 md 在 Claude Code / Codex 中的放置位置（全局默认 vs 项目根目录）。
需要具体代码示例、完整字段清单或错误码语义时，读取对应 reference 文件，不要在未读取的情况下凭记忆作答。
