Phase 7.6: README更新 + 公开API XML文档注释, 128测试
This commit is contained in:
parent
c28954335c
commit
cde7702b12
86
README.md
86
README.md
@ -1,68 +1,52 @@
|
||||
# [项目名称]
|
||||
# 反无人机仿真系统后端
|
||||
|
||||
> 一句话描述项目：是什么，解决什么问题，面向谁。
|
||||
> C# 仿真引擎，集成到 Unity 22.3.62 前端。
|
||||
|
||||
## 项目概述
|
||||
|
||||
本系统对气溶胶武器的三种防空毁伤机制（吸入式灭火、爆燃式、吸入式爆炸）进行数字化仿真。通过参数化配置与可视化推演，量化评估新型气溶胶武器对不同类型空中威胁源目标的毁伤效能。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
├── README.md # 项目概述与快速开始（本文件）
|
||||
├── CHANGELOG.md # 对外发布变更记录（用户视角）
|
||||
├── VERSION # 语义化版本号
|
||||
├── LICENSE # 许可证
|
||||
├── CONTRIBUTING.md # 贡献规范
|
||||
├── .gitignore # Git 忽略规则
|
||||
├── AGENTS.md # AI 编码助手上下文
|
||||
│
|
||||
├── src/ # 源代码（所有业务模块）
|
||||
├── data/ # 项目数据（知识库源、SQL dump 等非代码数据）
|
||||
├── test/ # 测试代码
|
||||
│ ├── unit/ # 单元测试
|
||||
│ ├── integration/ # 集成测试
|
||||
│ └── e2e/ # 端到端测试
|
||||
│
|
||||
├── docs/ # 开发文档
|
||||
│ ├── design/ # 设计方案（架构 + 技术方案）
|
||||
│ │ ├── architecture/ # 架构设计 & ADR
|
||||
│ │ └── technical/ # 技术方案 / 详细设计
|
||||
│ ├── features/ # 功能规格说明
|
||||
│ ├── requirements/ # 需求与变更管理（可选）
|
||||
│ ├── implementation/ # 实施计划与任务跟踪（可选）
|
||||
│ └── verify/ # 人工检查清单（可选）
|
||||
│
|
||||
├── skills/ # AI 辅助技能（pi 专用，可选）
|
||||
├── scripts/ # 构建、部署、工具脚本
|
||||
└── config/ # 项目级配置文件（非代码）
|
||||
├── src/CounterDrone.Core/ # 核心类库（.NET Standard 2.1，零 Unity 依赖）
|
||||
│ ├── Models/ # 数据模型（POCO + 枚举）
|
||||
│ ├── Repository/ # 数据访问层（SQLite）
|
||||
│ ├── Services/ # 业务逻辑 + 报告生成
|
||||
│ ├── Algorithms/ # 扩散/毁伤/推荐算法
|
||||
│ └── Simulation/ # 仿真引擎（纯执行器）
|
||||
├── test/unit/ # 单元测试（xUnit，128 测试）
|
||||
├── test/reports/ # 集成测试生成的报告
|
||||
└── docs/ # 架构设计文档
|
||||
```
|
||||
|
||||
> - **可选目录**：已有 Jira/TAPD 等工单系统的团队可删除 `requirements/` 和 `implementation/`；不用 pi 编码助手的可删除 `skills/`
|
||||
> - **`src/` vs 根目录**：业务代码放 `src/`，入口文件（`app.py`、`main.go`）和配置文件（`pytest.ini`、`ruff.toml`、`.env.example`）留根目录
|
||||
> - **`data/` vs `test/fixtures/`**：`data/` 放项目级数据（知识库源文件等），`test/fixtures/` 放测试专用 fixture 数据
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 克隆项目
|
||||
git clone <repo-url>
|
||||
cd <project-name>
|
||||
# 构建
|
||||
dotnet build src/CounterDrone.Core/
|
||||
|
||||
# [安装 / 构建 / 运行步骤，根据项目补充]
|
||||
# 运行测试
|
||||
dotnet test test/unit/CounterDrone.Core.Tests/
|
||||
|
||||
# 查看覆盖率
|
||||
dotnet test test/unit/CounterDrone.Core.Tests/ --collect:"XPlat Code Coverage"
|
||||
reportgenerator -reports:test/unit/CounterDrone.Core.Tests/TestResults/*/coverage.cobertura.xml -targetdir:coverage_report -reporttypes:Html
|
||||
```
|
||||
|
||||
## 文档导航
|
||||
## 测试状态
|
||||
|
||||
| 你想做的事 | 去哪看 |
|
||||
|------------|--------|
|
||||
| 了解项目背景和架构 | `docs/design/architecture/` |
|
||||
| 查看需求与变更 | `docs/requirements/`（可选） |
|
||||
| 查看功能设计 | `docs/features/` |
|
||||
| 查看任务进度 | `docs/implementation/tasks/`（可选） |
|
||||
| 参与开发 | `CONTRIBUTING.md` |
|
||||
| 查看版本历史 | `CHANGELOG.md` |
|
||||
| 指标 | 值 |
|
||||
|------|------|
|
||||
| 测试总数 | 128 |
|
||||
| 行覆盖率 | 95.4% |
|
||||
| 分支覆盖率 | 80.5% |
|
||||
| 执行时间 | ~9 秒 |
|
||||
|
||||
## 架构
|
||||
|
||||
详见 [docs/design/architecture/总体架构设计.md](docs/design/architecture/总体架构设计.md)
|
||||
|
||||
## 维护者
|
||||
|
||||
- [@维护者](https://github.com/xxx)
|
||||
|
||||
## 许可证
|
||||
|
||||
[LICENSE](./LICENSE)
|
||||
- [@Tellme](https://github.com/Tellme)
|
||||
|
||||
@ -2,6 +2,7 @@ using CounterDrone.Core.Models;
|
||||
|
||||
namespace CounterDrone.Core.Algorithms
|
||||
{
|
||||
/// <summary>云团扩散模型接口</summary>
|
||||
public interface ICloudDispersionModel
|
||||
{
|
||||
void Initialize(AmmunitionSpec ammo, CombatScene env, Vector3 releasePos, float releaseTime);
|
||||
|
||||
@ -2,6 +2,7 @@ using CounterDrone.Core.Models;
|
||||
|
||||
namespace CounterDrone.Core.Algorithms
|
||||
{
|
||||
/// <summary>毁伤模型接口</summary>
|
||||
public interface IDamageModel
|
||||
{
|
||||
float CalculateDamage(TargetType droneType, PowerType powerType,
|
||||
|
||||
@ -2,6 +2,7 @@ using CounterDrone.Core.Models;
|
||||
|
||||
namespace CounterDrone.Core.Algorithms
|
||||
{
|
||||
/// <summary>防御推荐接口 — 威胁驱动</summary>
|
||||
public interface IDefenseAdvisor
|
||||
{
|
||||
DefenseRecommendation Recommend(ThreatProfile threat);
|
||||
|
||||
@ -3,6 +3,7 @@ using CounterDrone.Core.Models;
|
||||
|
||||
namespace CounterDrone.Core.Services
|
||||
{
|
||||
/// <summary>编组管理服务</summary>
|
||||
public interface IGroupService
|
||||
{
|
||||
Group CreateGroup(string name, GroupType type, string description);
|
||||
|
||||
@ -3,6 +3,7 @@ using CounterDrone.Core.Models;
|
||||
|
||||
namespace CounterDrone.Core.Services
|
||||
{
|
||||
/// <summary>模型管理服务 — 3D 模型的导入、删除、查询</summary>
|
||||
public interface IModelService
|
||||
{
|
||||
ModelInfo ImportModel(string filePath, string name);
|
||||
|
||||
@ -4,6 +4,7 @@ using SimEvent = CounterDrone.Core.Simulation.SimEvent;
|
||||
|
||||
namespace CounterDrone.Core.Services
|
||||
{
|
||||
/// <summary>报告服务</summary>
|
||||
public interface IReportService
|
||||
{
|
||||
SimulationReport Generate(string taskId, TaskFullConfig config,
|
||||
|
||||
@ -3,6 +3,7 @@ using CounterDrone.Core.Models;
|
||||
|
||||
namespace CounterDrone.Core.Services
|
||||
{
|
||||
/// <summary>想定管理服务</summary>
|
||||
public interface IScenarioService
|
||||
{
|
||||
SimTask CreateTask(string name, string taskNumber);
|
||||
|
||||
@ -19,6 +19,7 @@ namespace CounterDrone.Core.Simulation
|
||||
}
|
||||
|
||||
/// <summary>仿真引擎 — 纯执行器，不包含任何决策逻辑</summary>
|
||||
/// <summary>仿真引擎 — 纯执行器，接收发射计划按时间表执行</summary>
|
||||
public class SimulationEngine
|
||||
{
|
||||
private readonly IScenarioService _scenarioService;
|
||||
|
||||
47
test/reports/喷气拦截_20260611_084520.md
Normal file
47
test/reports/喷气拦截_20260611_084520.md
Normal file
@ -0,0 +1,47 @@
|
||||
# 仿真评估报告
|
||||
|
||||
**任务名称**：喷气拦截
|
||||
**任务编号**：SIM-20260611-004
|
||||
**仿真耗时**：106.4 秒
|
||||
|
||||
## 一、仿真前 — 我方配置
|
||||
|
||||
| 配置项 | 值 |
|
||||
|--------|-----|
|
||||
| 目标数量 | 1 |
|
||||
| 发射平台 | 6 台 |
|
||||
| 探测设备 | 1 台 |
|
||||
| 气溶胶类型 | ActiveMaterial |
|
||||
|
||||
## 二、仿真中 — 关键事件时序
|
||||
|
||||
| 时间(s) | 事件 | 描述 |
|
||||
|---------|------|------|
|
||||
| 92.2 | MunitionLaunched | 计划发射 mun_1 |
|
||||
| 92.2 | MunitionLaunched | 计划发射 mun_2 |
|
||||
| 92.2 | MunitionLaunched | 计划发射 mun_3 |
|
||||
| 92.2 | MunitionLaunched | 计划发射 mun_4 |
|
||||
| 92.2 | MunitionLaunched | 计划发射 mun_5 |
|
||||
| 92.2 | MunitionLaunched | 计划发射 mun_6 |
|
||||
| 101.8 | CloudGenerated | 云团生成 |
|
||||
| 101.8 | CloudGenerated | 云团生成 |
|
||||
| 101.8 | CloudGenerated | 云团生成 |
|
||||
| 101.8 | CloudGenerated | 云团生成 |
|
||||
| 101.8 | CloudGenerated | 云团生成 |
|
||||
| 101.8 | CloudGenerated | 云团生成 |
|
||||
| 106.4 | DroneDestroyed | 无人机 drone_1 被摧毁 |
|
||||
| 106.4 | SimulationEnd | |
|
||||
|
||||
## 三、仿真后 — 数据统计
|
||||
|
||||
| 统计项 | 值 |
|
||||
|--------|-----|
|
||||
| 无人机总数 | 1 |
|
||||
| 被摧毁 | 1 |
|
||||
| 到达目标 | 0 |
|
||||
| 侵入管控区 | 0 |
|
||||
| 弹药发射次数 | 6 |
|
||||
| 云团生成次数 | 6 |
|
||||
|
||||
**对抗结果**：成功拦截
|
||||
|
||||
46
test/reports/活塞拦截_20260611_084524.md
Normal file
46
test/reports/活塞拦截_20260611_084524.md
Normal file
@ -0,0 +1,46 @@
|
||||
# 仿真评估报告
|
||||
|
||||
**任务名称**：活塞拦截
|
||||
**任务编号**：SIM-20260611-041
|
||||
**仿真耗时**：185.6 秒
|
||||
|
||||
## 一、仿真前 — 我方配置
|
||||
|
||||
| 配置项 | 值 |
|
||||
|--------|-----|
|
||||
| 目标数量 | 1 |
|
||||
| 发射平台 | 5 台 |
|
||||
| 探测设备 | 1 台 |
|
||||
| 气溶胶类型 | InertGas |
|
||||
|
||||
## 二、仿真中 — 关键事件时序
|
||||
|
||||
| 时间(s) | 事件 | 描述 |
|
||||
|---------|------|------|
|
||||
| 167.4 | MunitionLaunched | 计划发射 mun_1 |
|
||||
| 167.4 | MunitionLaunched | 计划发射 mun_2 |
|
||||
| 167.4 | MunitionLaunched | 计划发射 mun_3 |
|
||||
| 167.4 | MunitionLaunched | 计划发射 mun_4 |
|
||||
| 167.4 | MunitionLaunched | 计划发射 mun_5 |
|
||||
| 177.0 | CloudGenerated | 云团生成 |
|
||||
| 177.0 | CloudGenerated | 云团生成 |
|
||||
| 177.0 | CloudGenerated | 云团生成 |
|
||||
| 177.0 | CloudGenerated | 云团生成 |
|
||||
| 177.0 | CloudGenerated | 云团生成 |
|
||||
| 185.6 | DroneDestroyed | 无人机 drone_1 被摧毁 |
|
||||
| 185.6 | DroneDestroyed | 无人机 drone_1 被摧毁 |
|
||||
| 185.6 | SimulationEnd | |
|
||||
|
||||
## 三、仿真后 — 数据统计
|
||||
|
||||
| 统计项 | 值 |
|
||||
|--------|-----|
|
||||
| 无人机总数 | 1 |
|
||||
| 被摧毁 | 2 |
|
||||
| 到达目标 | 0 |
|
||||
| 侵入管控区 | 0 |
|
||||
| 弹药发射次数 | 5 |
|
||||
| 云团生成次数 | 5 |
|
||||
|
||||
**对抗结果**：成功拦截
|
||||
|
||||
Loading…
Reference in New Issue
Block a user