✨ feat: 初始化飞拍替换方案仓库骨架
* 建立 .NET 8 解决方案及分层项目结构 * 添加 Flyshot.Core.Domain 领域模型(机器人、轨迹、运动学) * 添加 Flyshot.Core.Planning 规划层(ICSP、CubicSpline、采样器) * 添加 Flyshot.Core.Triggering 触发时序与 IO 时间轴 * 添加 Flyshot.Core.Config 配置兼容与 .robot 解析 * 添加 Flyshot.Server.Host 最小宿主及 /healthz 端点 * 补充单元测试与集成测试项目 * 添加 CLAUDE.md、AGENTS.md、README.md 项目规范
This commit is contained in:
150
CLAUDE.md
Normal file
150
CLAUDE.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Flyshot Replacement 仓库规范
|
||||
|
||||
## 1. 仓库目标
|
||||
|
||||
本仓库用于重写并替代现有 RVBUST/FANUC 飞拍服务端链路。
|
||||
|
||||
第一版目标固定为:
|
||||
|
||||
- 使用 `C# + .NET 8`
|
||||
- 提供跨平台独立服务端
|
||||
- 兼容现有 `50001/TCP+JSON` 上层接入语义
|
||||
- 重写轨迹生成、触发时序、FANUC 控制链路和状态监控
|
||||
- Windows / Linux 都能运行完整服务端
|
||||
- 只支持当前现场这套组合
|
||||
|
||||
明确不做:
|
||||
|
||||
- GUI 桌面程序
|
||||
- 多机器人同时控制
|
||||
- 面向多控制柜的通用平台化框架
|
||||
|
||||
## 2. 代码与资料边界
|
||||
|
||||
本仓库是新的独立实现仓库,不复用旧的 RVBUST 二进制作为运行时依赖。
|
||||
|
||||
允许依赖的内容:
|
||||
|
||||
- 旧仓库中的逆向分析文档
|
||||
- 旧仓库中的协议样本、轨迹样本和配置样本
|
||||
- 旧仓库中的 `ControllerClient.h` 公开接口
|
||||
|
||||
不允许把旧服务端实现直接包装成“新系统”。
|
||||
|
||||
## 3. 当前目录结构
|
||||
|
||||
```text
|
||||
flyshot-replacement/
|
||||
├─ src/
|
||||
│ ├─ Flyshot.Server.Host/
|
||||
│ ├─ Flyshot.Core.Domain/
|
||||
│ └─ Flyshot.Runtime.Common/
|
||||
├─ tests/
|
||||
│ ├─ Flyshot.Server.IntegrationTests/
|
||||
│ └─ Flyshot.Core.Tests/
|
||||
├─ FlyshotReplacement.sln
|
||||
├─ Directory.Build.props
|
||||
├─ README.md
|
||||
└─ AGENTS.md
|
||||
```
|
||||
|
||||
后续新增模块时,优先保持以下边界:
|
||||
|
||||
- `Flyshot.Core.Domain`
|
||||
- 纯领域对象
|
||||
- 不依赖网络、文件系统、HTTP、UI、操作系统
|
||||
- `Flyshot.Core.Config`
|
||||
- 配置兼容
|
||||
- `.robot` 解析
|
||||
- 路径兼容
|
||||
- `Flyshot.Core.Planning`
|
||||
- `icsp`
|
||||
- `self-adapt-icsp`
|
||||
- `doubles`
|
||||
- `Flyshot.Core.Triggering`
|
||||
- `TrajectoryDO` 等价时间轴
|
||||
- `shot_flags / offset_values / addr` 解析
|
||||
- `Flyshot.LegacyGateway`
|
||||
- `50001/TCP+JSON` 兼容接入
|
||||
- `Flyshot.Runtime.Fanuc`
|
||||
- `10010 / 10012 / 60015`
|
||||
- `Flyshot.Web.Status`
|
||||
- 状态查看
|
||||
- 诊断页
|
||||
- 不直接处理底层协议细节
|
||||
|
||||
## 4. 开发规范
|
||||
|
||||
### 4.1 通用要求
|
||||
|
||||
- 正式文档默认使用中文。
|
||||
- 不要把临时验证脚本直接塞进正式运行时代码。
|
||||
- 兼容性优先级高于“重新发明接口”。
|
||||
- 第一版默认围绕当前现场组合实现,不提前做泛化设计。
|
||||
|
||||
### 4.2 实现约束
|
||||
|
||||
- 旧协议兼容以“语义兼容”为主,不追求二进制逐字节一致。
|
||||
- 轨迹规划必须与底层 Socket / HTTP / Web UI 解耦。
|
||||
- 领域层不允许引用 ASP.NET Core、Socket、文件系统 API。
|
||||
- 网页只做状态监控,不把复杂控制流程放进前端。
|
||||
- 多机型切换通过不同 `.robot` 文件加载,不在第一版做插件化机型框架。
|
||||
|
||||
### 4.3 测试要求
|
||||
|
||||
- 默认采用 TDD。
|
||||
- 至少先写失败测试,再写最小实现。
|
||||
- 每完成一个阶段,要补最小可运行验证,而不是只看代码编译是否“像是对的”。
|
||||
|
||||
### 4.4 注释要求
|
||||
|
||||
- 所有生成代码都必须带中文注释,不可缺漏。
|
||||
- 所有类定义都必须在类头提供 XML 注释。
|
||||
- 所有静态变量都必须提供 XML 注释。
|
||||
- 关键代码块必须补充单行注释,说明该段逻辑为什么存在、在做什么,不允许只写空泛注释。
|
||||
|
||||
## 5. 构建与验证命令
|
||||
|
||||
在当前环境中,推荐使用下面两条命令:
|
||||
|
||||
```bash
|
||||
/bin/bash -lc 'DOTNET_CLI_HOME=/tmp NUGET_PACKAGES=/tmp/nuget-packages dotnet test tests/Flyshot.Server.IntegrationTests/Flyshot.Server.IntegrationTests.csproj -v minimal'
|
||||
/bin/bash -lc 'DOTNET_CLI_HOME=/tmp NUGET_PACKAGES=/tmp/nuget-packages dotnet build FlyshotReplacement.sln --no-restore -v minimal'
|
||||
```
|
||||
|
||||
说明:
|
||||
|
||||
- 第一条命令当前已经验证通过,可用于检查最小宿主和 `/healthz`。
|
||||
- 第二条命令当前已经验证通过,可用于检查解决方案骨架是否完整。
|
||||
|
||||
后续新增模块时,继续补充:
|
||||
|
||||
- `Flyshot.Core.Tests`
|
||||
- 协议回放测试
|
||||
- golden sample 对拍测试
|
||||
- 端到端集成测试
|
||||
|
||||
## 6. 修改前优先查看的资料
|
||||
|
||||
本仓库上层是独立实现,但上下文仍然依赖父目录中的逆向资料。开始重要改动前,优先阅读:
|
||||
|
||||
- `../analysis/ControllerServer_analysis.md`
|
||||
- `../analysis/ICSP_algorithm_reverse_analysis.md`
|
||||
- `../analysis/CommonMsg_protocol_analysis.md`
|
||||
- `../analysis/J519_stream_motion_analysis.md`
|
||||
- `../analysis/FANUC_realtime_comm_analysis.md`
|
||||
- `../FlyingShot/FlyingShot/Include/ControllerClient/ControllerClient.h`
|
||||
|
||||
## 7. 任务推进方式
|
||||
|
||||
- `README.md` 中的 Todo 需要随着阶段推进同步更新。
|
||||
- 如果实现范围发生收敛或扩展,先更新设计或计划,再继续改代码。
|
||||
- 如果发现计划漏了关键对象或模块,直接补到文档里,不要把缺口留到后面。
|
||||
|
||||
## 8. 当前已验证状态
|
||||
|
||||
- 独立仓库已初始化。
|
||||
- `dotnet 8` 解决方案骨架已建立。
|
||||
- `Flyshot.Server.Host` 已提供最小 `/healthz`。
|
||||
- 最小集成测试已通过。
|
||||
- 解决方案构建已通过。
|
||||
Reference in New Issue
Block a user