查看“MDCS跨切面约定”的源代码

<languages/>

== 概述 / Overview ==
本页汇总 MDCS 平台 ''跨子系统''的约定 —— 命名、线程、错误处理、版本、文件布局。新加入团队或修改核心代码前先读这里。

This page collects MDCS-wide ''cross-cutting conventions'' — naming, threading, error handling, versioning, file layout. Read this before joining the team or modifying core code.

== 命名约定 / Naming conventions ==
{| class="wikitable"
! 实体 / Entity !! 约定 / Convention !! 例 / Example
|-
| Medulla 插件入口类 / Medulla plugin entry || `MainIOObject`（严格大小写）|| `LidarController.MainIOObject`
|-
| 插件文件夹（一方）|| `D:\src\M2\OfficialPlugins\<VendorModel>\` || `OfficialPlugins\LidarController\`
|-
| 引用程序集 / Reference DLL || `Ref<Name>.dll` || `RefMedullaCore.dll`
|-
| Simple 车型类 / Simple car class || 用 `[CarType]` 属性，类名任意 || `[CarType] public class LB14 : ClumsyCar`
|-
| DObject 槽名 / DObject slot name || `<Producer><Tag>` || `MedullaCartLowerIO<tag>`
|-
| Wiki 页 / Wiki page || 现有约定 ：`开发手册 - ...`, `使用手册 - ...`, `XXX适配案例`, `XXX技术概述` || `开发手册 - SimpleComposer界面开发 - CAD工具`
|-
| 上下位 IO 字段 / IO field || 上位 `*Cmd`，下位 `*Est`（或更具体的 `*OK`, `*Pct` 等）|| `vCmd`, `vEst`, `batteryPercent`
|}

== 线程约定 / Threading conventions ==
* '''LadderLogic''' 每个 `[UseLadderLogic]` 类自己的线程；threads 共享 CartDefinition 字段，自行同步。
* '''DriveTask''' 每个 Movement 自己的线程（`ThreadPriority.AboveNormal`）。
* '''DObject `Wait()`''' 阻塞当前线程；要并行多源就开多线程。
* '''CycleGUI Draw 调用''' 从任意线程都安全（内部 marshall 到 UI 线程）。
* '''SimpleComposer Nancy 处理器''' 在 Nancy 线程池跑；不要长阻塞。
* '''Tasks''' 多用 `async`/`await`；尽量避免 `Task.Run`（除非 explicit 后台计算）。

* LadderLogic, DriveTask each have own thread.
* DObject `Wait()` is blocking; parallelise across sources via worker threads.
* CycleGUI Draw is thread-safe.
* Nancy handlers run on Nancy's thread pool; no long blocks.
* Use `async/await`; avoid `Task.Run` unless explicit background work.

== 错误处理三层 / 3-layer error model ==
=== Layer 1 — 插件级 / Plugin-level ===
`[UseLadderLogic(resume = true)]`（默认）捕获 `Operation()` 异常并在 `resumeRetryDelay` 后重试。日常 ''可恢复''错误用这一层。

The default `resume = true` catches LadderLogic exceptions + retries after `resumeRetryDelay`. Use for routine recoverable errors.

=== Layer 2 — 进程级 / Process-level ===
`Hedingben.ToastText(message, source)` 把异常呈现给操作工。逻辑能继续但人需要知道时用。

`Hedingben.ToastText` surfaces errors as UI toasts. Use when logic can proceed but the human should know.

<syntaxhighlight lang="csharp">
catch (Exception e)
{
    Hedingben.ToastText($"Failed: {e.Message}", $"{Name}:ERR");
}
</syntaxhighlight>

=== Layer 3 — 看门狗级 / Watchdog-level ===
Wawa（[[Special:MyLanguage/看门狗Wawa使用说明|看门狗Wawa使用说明]]）是进程监控；进程崩了会重启。对应"世界着火"级别的错误 —— 让它 `throw`，让 watchdog 接手。

Wawa is the process watchdog. For "the world is on fire" — `throw` and let the watchdog restart.

=== 选层 / Picking the right layer ===
{| class="wikitable"
! 情况 / Situation !! 用哪层 / Use
|-
| PLC 通讯偶尔超时 || Layer 1（resume + 重试）
|-
| 雷达连接断开 || Layer 1（重连循环）+ Layer 2（toast）
|-
| 关键传感器永久失效 || Layer 2（toast）+ 把 `eStop = true`
|-
| 内存溢出 / panic || Layer 3（throw → watchdog 重启）
|}

不要 ''同时''做三层 —— 选最合适的。
Don't do all three; pick the right one.

== 版本与助记词 / Versioning ==
每次修改编译产物 ：
Every modification of a compiled artefact:

* `AssemblyInformationalVersion` 加 ''单词助记词'' ：`1.4.0+kindling`
* 下次改 ：`1.4.1+lantern`
* 助记词 ''单一''单词；不要 hyphen / 空格

或用 `[ReplaceWithCompileInfo]` —— LessokajiWeaver 自动注入时间戳 + git hash。
Or `[ReplaceWithCompileInfo]` — auto-inject timestamp + git hash.

目的 ：现场调试时区分两个数字看起来一样的二进制。
Purpose: visually disambiguate field binaries with same number.

== 文件 / 路径 约定 / Path conventions ==
{| class="wikitable"
! 用途 / Use !! 约定路径 / Convention
|-
| 临时工作文件 / 草稿 || `D:\src\ai-deck\<project>\` （非 repo 根；可丢弃）
|-
| 项目级开发日志 || `D:\src\<repo>\DEV_LOG.md`（仓库根；append-only）
|-
| 插件 csproj 引用 / HintPath || `..\tools\Ref<Name>.dll`
|-
| 部署时 plugin 位置 || `medulla/plugins/<vendor>/<plugin>.dll`，`simplecomposer/plugins/`
|-
| startup 脚本 || `startup.iocmd`（Medulla CWD）
|-
| SLAM 地图文件 || `*.2dlm` / `*.gtex` / `*.gtm` / `*.memslam` / `tagmap.json`
|-
| DObject 录制 || `.dorec`
|-
| 日志 / Logs || `logs/<YYYY-MM-DD>.log`（DLog）+ `hedingben.log`
|}

== DEV_LOG.md ==
仓库根 `DEV_LOG.md` 是 ''append-only''的开发日志 ：
The `DEV_LOG.md` at each repo root is the '''append-only''' dev log:

* 每条新条目追加到末尾，绝不修改旧条目。
* 重要发现用前缀 ：`【发现】 / 【注意】 / 【灵感】`
* 编译产物的版本助记词也记在这里。

DEV_LOG 的目的是让 ''下一个读者''（也许 6 个月后的自己）能复原当时的判断。
DEV_LOG's goal: the next reader (maybe you in 6 months) can reconstruct the decisions.

== 注释风格 / Comment style ==
* '''头部注释稀疏''' —— 代码应自解释。
* '''中文注释常见'''于领域特定处（运动学、标定、传感）。
* '''关键代码用 ''发现''标记''' —— 文件里也用 `// 【发现】 ...` 提醒后续读者。

* Header comments sparse — code should be self-evident.
* Chinese comments are normal in domain-specific spots.
* `// 【发现】 ...` flags for important inline notes.

== 测试纪律 / Testing discipline ==
* 单元测试稀疏；机器人代码本质上靠 ''集成''测试。
* `D:\src\Fundamentals\Test\` 覆盖 DObject + DLog（最关键基础）。
* 多数"测试"通过 `[MovementTest]` / `[IOObjectUtility]` UI 按钮跑。
* '''改 DObject 后必跑 Fundamentals 单元测试''' —— IPC bug 灾难性。
* '''改 *Core 后跑仿真车 SimpleComposer 集成测试'''。

== 文档 / Documentation ==
* '''Wiki 是事实标准'''；代码注释 / DEV_LOG 是 ''临时记''。
* 公共 API 改动必同时 update wiki。
* 私下试验在 `ai-deck/`，不要污染 wiki。

== Git 约定 / Git ==
* Branch 名 ：`feature/<short-name>`, `fix/<issue>`, `release/<version>`
* Commit 消息含助记词与一句话变更摘要
* PR / MR 描述含 ：变更动机 + 关键决策 + 测试方法

== License / 许可 ==
* 客户机器绑定 license 由 `auth.lessokaji.com` 签发；`LessokajiProtect.dll` 在 Fundamentals。
* 开发机用 ''dev license''（无限期但带水印）。
* 不要在源码里 hardcode license / serial。

== 相关页面 / See also ==
* [[Special:MyLanguage/MDCS仓库布局与构建链|MDCS仓库布局与构建链]]
* [[Special:MyLanguage/插件契约与打包约定|插件契约与打包约定]]
* [[Special:MyLanguage/插件开发清单|插件开发清单]]
* [[Special:MyLanguage/核心开发指南|核心开发指南]]
* [[Special:MyLanguage/看门狗Wawa使用说明|看门狗Wawa使用说明]]
* [[Special:MyLanguage/通用约定|通用约定]] — 已有的"通用约定"页（业务侧）

[[Category:二次开发相关说明]]
[[Category:开发手册]]
[[Category:通识和入门教学]]