1
   specify init <PROJECT_NAME>

1
   specify init . --integration <AI code agent>
2
   # or
3
   specify init --here --integration <AI code agent>

1
   specify integration install <agent>

1
   specify integration uninstall <agent>

1
   $speckit-constitution

1
<!--
2
Sync Impact Report
3
Version change: 1.0.0 → 1.0.1
4
Modified principles:
5
- I. Detection Core First → I. 检测内核优先
6
- II. Shared KMP Contracts Before Platform Code → II. 共享 KMP 契约先于平台代码
7
- III. Kotest Verification Is Mandatory → III. Kotest 验证强制执行
8
- IV. Runtime Observability and Evidence → IV. 运行时可观测性与证据
9
- V. Scoped Simplicity and Delivery Boundaries → V. 范围克制、简单交付
10
Added sections:
11
- None
12
Removed sections:
13
- None
14
Templates requiring updates:
15
- ✅ .specify/templates/plan-template.md
16
- ✅ .specify/templates/spec-template.md
17
- ✅ .specify/templates/tasks-template.md
18
- ⚠ .specify/templates/commands/*.md not present in this project
19
- ✅ README.md
20
- ✅ docs/testing/kotest-allure.md
21
Follow-up TODOs:
22
- None
23
-->
24

25
# monitor_detection 项目宪章
26

27
## 核心原则
28

29
### I. 检测内核优先
30

31
本项目 MUST 优先服务监控识别系统本体：输入源接入、推理调用、场景识别、
32
规则判定、告警聚合、证据输出与运行时状态。Web UI、Android 展示 UI、
33
告警大屏和管理后台均不属于当前项目范围，除非未来通过宪章修订明确改变
34
项目边界。
35

36
理由：本仓库的目标是交付可复用的检测内核与运行时，而不是被展示层或管理端
37
分散核心部署目标。
38

39
### II. 共享 KMP 契约先于平台代码
40

41
核心模型、规则契约、场景处理器、DTO、运行时契约和业务行为，只要能被 JVM
42
与 Android 共用，就 MUST 放在 Kotlin Multiplatform 共享 source set 中。
43
平台 source set MUST 只承载输入源、模型执行、服务、存储和生命周期等适配
44
职责。任何契约变更 MUST 同时考虑 JVM 与 Android 装配，避免双端行为漂移。
45

46
理由：项目价值在于一套共享检测行为服务两个部署运行时。把业务逻辑复制到
47
平台侧会造成长期分叉和维护风险。
48

49
### III. Kotest 验证强制执行
50

51
每个行为变更 MUST 在最小有效层级补充 Kotest 测试：共享逻辑使用 common
52
测试，JVM 适配器和运行时使用 JVM 测试，Android 运行时行为使用 Android host
53
测试。测试 MUST 使用 Kotest 风格编写，测试报告 MUST 通过 Allure 生成以便
54
本地和 CI 审查。相关 compile、ktlint、Kotest 和 Allure report 命令通过前，
55
变更不得视为完成；如无法执行，MUST 明确记录原因。
56

57
理由：检测规则、运行时契约和平台装配容易回归，测试与报告是验收记录。
58

59
### IV. 运行时可观测性与证据
60

61
运行时代码 MUST 通过共享契约暴露健康状态、源连接状态、最后处理帧时间、
62
告警记录和证据元数据。错误 MUST 更新运行时健康状态，并提供可行动的错误
63
信息。证据存储可以先以 no-op 元数据形式实现，但公开契约 MUST 为后续文件
64
或对象存储实现保持稳定。
65

66
理由：监控部署必须在没有 UI 或调试器的情况下可诊断、可复盘。
67

68
### V. 范围克制、简单交付
69

70
变更 MUST 严格限定在当前需求或失败验证所需范围内。新增抽象 MUST 解决真实
71
重复或维护共享契约，MUST NOT 为未来假设增加投机性灵活性。平台能力 SHOULD
72
优先在现有契约背后增量实现，而不是用无关框架替换既有架构。
73

74
理由：项目已经是多平台运行时。小而可验证的变更能保护共享模型并降低交付
75
风险。
76

77
## 项目约束
78

79
- Kotlin Multiplatform 是共享逻辑的强制实现模型。
80
- JVM 与 Android 是当前有效部署目标。
81
- Kotest 是强制测试框架；JUnit 仅作为 JVM 测试执行平台，不作为测试编写风格。
82
- Allure 是测试报告的强制格式。
83
- MUST 保持 `ktlint` 格式化和现有 Gradle version catalog 约定。
84
- `com.smartwater.ai.*` 直接运行时链路是当前有效路径；MUST NOT 重新引入旧
85
  bridge 或重复 pipeline 路径。
86

87
## 开发流程
88

89
1. 用检测或运行时行为定义需求范围，并明确非目标。
90
2. 共享行为优先修改 common source set；平台 source set 仅用于适配职责。
91
3. 实现前或实现同时补充 Kotest 覆盖。
92
4. 运行相关验证命令：
93
    - `./gradlew :monitor_detection:jvmTest`
94
    - Android 运行时行为变化时运行
95
      `./gradlew :monitor_detection:testAndroidHostTest`
96
    - `./gradlew :monitor_detection:allureReport --no-configuration-cache`
97
    - `./gradlew :monitor_detection:ktlintCheck`
98
    - 与触达目标相关的 compile 任务
99
5. 命令、契约、运行时行为或项目边界变化时，MUST 更新 README 或 docs。
100

101
## 治理
102

103
本宪章优先于非正式项目习惯。所有 specification、plan、task list、code review
104
和 implementation 都 MUST 检查是否符合核心原则与项目约束。
105

106
修订本宪章 MUST 满足：
107

108
1. 对本文件进行书面修改。
109
2. 在 Sync Impact Report 中列出受影响原则、模板和文档。
110
3. 在同一变更中同步更新依赖模板和运行时指导文档。
111
4. 按语义版本规则升级版本：
112
    - MAJOR：不兼容的治理或原则重定义、删除。
113
    - MINOR：新增原则、章节或实质扩展指导。
114
    - PATCH：澄清、文字调整、非语义变更。
115

116
实现规划前和交付前 MUST 进行合规审查。任何违反宪章的情况 MUST 写入 plan，
117
并给出具体理由和被拒绝的更简单替代方案。
118

119
**Version**: 1.0.1 | **Ratified**: 2026-05-11 | **Last Amended**: 2026-05-11

1
$speckit-specify

1
# Feature Specification: JVM 与 Android 多平台监控识别报警
2

3
**Feature Branch**: `001-kmp-monitor-alerts`
4
**Created**: 2026-05-12
5
**Status**: Draft
6
**Input**: User description: "
7
帮我生成一份需求文档，主要用于JVM和Android的KMP多平台的监控识别报警项目，主要识别场景有工程机械作业预警、水面异物预警、非运维人员入侵预警、监测设施位移预警、水体颜色变化预警、船舶异常停留预警、闸坝开启/关闭状态识别、非法排污预警"
8

9
## User Scenarios & Testing *(mandatory)*
10

11
### User Story 1 - 多平台统一识别八类监控场景 (Priority: P1)
12

13
运维负责人需要在 JVM 部署环境和 Android 设备环境中使用同一套监控识别能力，
14
对水利、水域或设施监控画面进行实时分析，并识别八类业务场景：工程机械作业、
15
水面异物、非运维人员入侵、监测设施位移、水体颜色变化、船舶异常停留、闸坝
16
开启/关闭状态、非法排污。
17

18
**Why this priority**: 八类场景识别是系统核心价值；若不能统一识别并输出结果，
19
后续告警、证据和状态能力都无法成立。
20

21
**Independent Test**: 准备包含八类场景的样例输入，分别在 JVM 和 Android 目标中
22
触发识别流程，验证每类场景均能产生对应的场景事件或正常状态结果。
23

24
**Acceptance Scenarios**:
25

26
1. **Given** 一个启用工程机械作业预警的监控任务，**When** 画面中出现工程机械
27
   作业目标，**Then** 系统输出工程机械作业预警事件。
28
2. **Given** 一个启用闸坝状态识别的监控任务，**When** 画面中出现闸门开启或
29
   关闭状态，**Then** 系统输出对应的闸坝状态识别结果。
30
3. **Given** 同一业务场景在 JVM 与 Android 两端运行，**When** 两端接收等价
31
   输入，**Then** 两端输出的场景类型、任务标识和告警语义保持一致。
32

33
---
34

35
### User Story 2 - 按规则生成预警并聚合告警 (Priority: P2)
36

37
运维值守人员需要系统根据任务规则判断识别结果是否达到预警条件，并将连续或
38
重复出现的同类事件聚合为可跟踪的告警记录，避免同一风险在短时间内产生大量
39
重复告警。
40

41
**Why this priority**: 识别结果只有经过规则判定和告警聚合，才能成为可处置的
42
运维事件。
43

44
**Independent Test**: 为每类场景配置启用状态、目标类别、区域条件和持续命中
45
要求，输入命中与未命中的样例，验证告警创建、更新和未触发路径。
46

47
**Acceptance Scenarios**:
48

49
1. **Given** 非运维人员入侵预警任务要求连续命中，**When** 入侵目标持续出现并
50
   满足规则，**Then** 系统创建入侵告警记录。
51
2. **Given** 同一船舶异常停留事件已经存在打开的告警，**When** 后续画面继续
52
   满足同一事件条件，**Then** 系统更新该告警的最后发现时间，而不是创建重复告警。
53
3. **Given** 水面异物检测目标未进入指定关注区域，**When** 系统完成识别，
54
   **Then** 不生成水面异物预警告警。
55

56
---
57

58
### User Story 3 - 输出证据、任务状态和设备健康 (Priority: P3)
59

60
平台对接方和现场运维人员需要查询每个任务的运行状态、设备健康、告警记录和
61
证据信息，以便确认系统是否正常工作，并在发生预警后进行复核。
62

63
**Why this priority**: 监控识别项目通常部署在边缘或无人值守环境中；没有状态
64
和证据输出时，告警可信度和运维可用性不足。
65

66
**Independent Test**: 启动一个任务并模拟识别、告警、异常和停止过程，验证任务
67
状态、设备健康、告警列表和证据元数据均可被查询且字段完整。
68

69
**Acceptance Scenarios**:
70

71
1. **Given** 一个监控任务正在处理输入，**When** 查询任务状态，**Then** 返回
72
   运行状态、源连接状态、最近心跳和最近处理帧时间。
73
2. **Given** 一个非法排污预警已经触发，**When** 查询告警详情，**Then** 返回
74
   告警类型、等级、任务、设备、首次发现时间、最后发现时间和证据信息。
75
3. **Given** 输入源异常中断，**When** 查询设备健康，**Then** 返回非健康状态和
76
   可用于定位问题的错误信息。
77

78
---
79

80
### Edge Cases
81

82
- 输入画面无任何目标时，系统必须保持任务运行状态并不生成告警。
83
- 同一画面中同时出现多个场景目标时，系统必须按已启用任务分别识别和输出。
84
- 目标出现在关注区域外时，系统必须保留识别事实，但不触发要求区域命中的告警。
85
- 目标短暂出现后消失时，系统必须重置连续命中状态，避免误报持续性预警。
86
- 设备或输入源断开时，系统必须更新健康状态，并避免输出伪造的场景告警。
87
- 同一告警持续出现时，系统必须更新既有告警，而不是无限制创建重复记录。
88
- 场景规则未配置时，系统必须使用统一默认规则：任务启用、场景默认目标标签、置信度 ≥ 0.7、连续命中 ≥
89
  2；未配置关注区域时默认全画面有效。
90

91
## Requirements *(mandatory)*
92

93
### Functional Requirements
94

95
- **FR-001**: 系统 MUST 支持 JVM 和 Android 两类部署目标，并保持共享业务语义一致。
96
- **FR-002**: 系统 MUST 支持工程机械作业预警，识别工程机械相关作业目标并输出预警事件。
97
- **FR-003**: 系统 MUST 支持水面异物预警，识别水面漂浮物、垃圾或异常异物并输出预警事件。
98
- **FR-004**: 系统 MUST 支持非运维人员入侵预警，识别非授权人员进入监控区域并输出预警事件。
99
- **FR-005**: 系统 MUST 支持监测设施位移预警，识别监测设施位置异常或疑似位移并输出预警事件。
100
- **FR-006**: 系统 MUST 支持水体颜色变化预警，识别水体颜色异常变化并输出预警事件。
101
- **FR-007**: 系统 MUST 支持船舶异常停留预警，识别船舶在关注区域内异常停留并输出预警事件。
102
- **FR-008**: 系统 MUST 支持闸坝开启/关闭状态识别，并输出明确的开启、关闭或未知状态。
103
- **FR-009**: 系统 MUST 支持非法排污预警，识别排污口、排放行为或疑似排污异常并输出预警事件。
104
- **FR-010**: 系统 MUST 支持为每个监控任务配置启用状态、场景类型、关注区域和规则条件。
105
- **FR-011**: 系统 MUST 根据任务规则判断识别结果是否触发告警，包括目标类别、置信程度、关注区域和持续命中条件。
106
- **FR-011a**: 系统 MUST 在场景规则未配置时使用统一默认规则：任务启用、场景默认目标标签、置信度 ≥
107
  0.7、连续命中 ≥ 2，且未配置关注区域时全画面有效。
108
- **FR-012**: 系统 MUST 将同一任务、同一设备、同一风险类型的持续事件聚合为同一告警记录。
109
- **FR-013**: 系统 MUST 为告警记录输出首次发现时间、最后发现时间、告警等级、标题、任务、站点和设备信息。
110
- **FR-014**: 系统 MUST 为每次告警输出证据元数据，至少包括任务、输入源、时间和关联告警。
111
- **FR-015**: 系统 MUST 输出任务运行状态，包括启动、运行、停止、错误、源连接状态和最近心跳。
112
- **FR-016**: 系统 MUST 输出设备健康状态，并在输入源或运行异常时提供可诊断的错误信息。
113
- **FR-017**: 系统 MUST 提供任务列表、任务状态、告警列表、设备健康、规则配置和证据信息的统一输出。
114
- **FR-018**: 系统 MUST 在无目标、未满足规则或任务未启用时不产生告警。
115
- **FR-019**: 系统 MUST 保证 JVM 与 Android 对同一场景类型使用一致的场景命名、告警语义和输出字段。
116
- **FR-020**: 系统 MUST 为八类场景分别提供可独立验证的测试样例和验收结果。
117

118
### Project Boundary Requirements
119

120
- **PBR-001**: 功能 MUST 保持检测内核范围；本规格不包含 Web UI、Android 展示 UI、告警大屏或管理后台。
121
- **PBR-002**: 共享行为 MUST 先按 Kotlin Multiplatform common 行为描述，再描述平台适配行为。
122
- **PBR-003**: 验证方案 MUST 标明 Kotest 覆盖和用于证明功能的 Allure 报告命令。
123

124
### Key Entities *(include if feature involves data)*
125

126
- **监控任务**: 表示一个运行中的识别配置，包含任务标识、站点、设备、场景类型、启用状态、关注区域和规则。
127
- **输入帧**: 表示一次来自监控源的画面输入，包含来源、时间、宽高和可选原始数据引用。
128
- **检测目标**: 表示画面中识别出的对象或状态，包含标签、置信程度、位置、跟踪标识和附加属性。
129
- **关注区域**: 表示用户关心的监控区域，用于判断目标是否进入有效告警范围。
130
- **场景观测**: 表示某个任务在一次或多次输入中形成的业务观测结果，包括场景类型、命中目标、连续命中和区域信息。
131
- **场景事件**: 表示规则判定前后形成的业务事件，用于后续告警聚合。
132
- **告警记录**: 表示可处置的预警结果，包含告警标识、场景类型、任务、设备、等级、状态和时间信息。
133
- **证据包**: 表示告警关联的复核信息，包含截图、视频片段或元数据。
134
- **任务运行状态**: 表示任务当前是否启动、运行、停止或错误，以及源连接和最近心跳信息。
135
- **设备健康状态**: 表示设备或运行环境是否健康，以及异常原因。
136

137
## Success Criteria *(mandatory)*
138

139
### Measurable Outcomes
140

141
- **SC-001**: 八类场景均具备至少 1 个可独立验收的成功识别样例，验收结果覆盖 JVM 和 Android 两类部署目标。
142
- **SC-002**: 对同一组等价输入，JVM 与 Android 输出的场景类型和告警关键字段一致率达到 100%。
143
- **SC-003**: 对未满足规则的样例输入，系统不产生告警的准确率达到 100%。
144
- **SC-004**: 同一持续事件在 10 次连续命中内只产生 1 条打开告警记录，并持续更新最后发现时间。
145
- **SC-005**: 任务状态和设备健康查询在任务启动、运行、错误、停止四类状态下均返回完整字段。
146
- **SC-006**: 每条告警记录均能关联到证据元数据，关联完整率达到 100%。
147
- **SC-007**: 规格覆盖的核心用户场景均可通过测试报告复核，且报告中能看到通过、失败和执行时间信息。
148
- **SC-008**: 新增或变更场景后，已有场景的验收样例仍全部通过。
149

150
## Assumptions
151

152
- 监控输入源、模型来源和外部对接系统由部署方提供，本规格只定义识别报警项目的业务能力和输出要求。
153
- 八类场景都可以通过目标、状态或属性识别结果映射到统一场景事件。
154
- 默认告警等级为预警级别；具体等级升级策略可在后续规则增强规格中细化。
155
- 关注区域用于减少误报；未配置关注区域时，任务默认在整个画面范围内生效。
156
- 告警证据可以先以元数据形式交付，截图或视频片段落盘属于后续增强能力。
157
- 本规格不包含展示端、管理后台、权限系统或人工处置流程。

1
$speckit-clarify

1
## Clarifications
2

3
### Session 2026-05-13
4

5
- Q: 场景规则未配置时系统应如何处理？ → A: 使用统一默认规则：任务启用、场景默认目标标签、置信度 ≥
6
  0.7、连续命中 ≥ 2、未配置 ROI 时全画面有效。

1
$speckit-checklist

1
# Specification Quality Checklist: JVM 与 Android 多平台监控识别报警
2

3
**Purpose**: Validate specification completeness and quality before proceeding to planning
4
**Created**: 2026-05-12
5
**Feature**: [spec.md](../spec.md)
6

7
## Content Quality
8

9
- [x] No implementation details (languages, frameworks, APIs)
10
- [x] Focused on user value and business needs
11
- [x] Written for non-technical stakeholders
12
- [x] All mandatory sections completed
13

14
## Requirement Completeness
15

16
- [x] No [NEEDS CLARIFICATION] markers remain
17
- [x] Requirements are testable and unambiguous
18
- [x] Success criteria are measurable
19
- [x] Success criteria are technology-agnostic (no implementation details)
20
- [x] All acceptance scenarios are defined
21
- [x] Edge cases are identified
22
- [x] Scope is clearly bounded
23
- [x] Dependencies and assumptions identified
24

25
## Feature Readiness
26

27
- [x] All functional requirements have clear acceptance criteria
28
- [x] User scenarios cover primary flows
29
- [x] Feature meets measurable outcomes defined in Success Criteria
30
- [x] No implementation details leak into specification
31

32
## Notes
33

34
- 自检通过。规格可进入 `/speckit-plan`。

1
$speckit-plan

1
# Implementation Plan: JVM 与 Android 多平台监控识别报警
2

3
**Branch**: `001-kmp-monitor-alerts` | **Date**: 2026-05-12 | **Spec**: [spec.md](./spec.md)
4
**Input**: Feature specification from `specs/001-kmp-monitor-alerts/spec.md`
5

6
## Summary
7

8
本功能把 `monitor_detection` 完整规划为 JVM 与 Android 双端共享的 KMP 监控识别
9
报警能力。实现策略是在现有单 KMP 模块中补齐共享检测内核：八类场景处理器、
10
统一规则判定、ROI/连续命中、告警聚合、证据元数据、任务状态与设备健康输出；
11
JVM 与 Android 仅保留输入源、推理引擎、生命周期和平台服务适配。
12

13
## Technical Context
14

15
**Language/Version**: Kotlin Multiplatform，Kotlin 2.3.20
16
**Primary Dependencies**: Kotlin Coroutines、kotlinx.serialization、kotlinx.datetime、ONNX
17
Runtime、TensorFlow Lite、JavaCV/FFmpeg、RootEncoder、Kotest、Allure
18
**Storage**: 当前以共享内存仓库与证据元数据为交付基线；文件证据落盘作为后续增强
19
**Testing**: Kotest 与 Allure 报告
20
**Target Platform**: JVM 部署版与 Android 设备部署版
21
**Project Type**: 单模块 Kotlin Multiplatform 检测运行时库
22
**Performance Goals**: 任务状态与告警输出保持实时可查询；每个目标平台至少能完成八类场景样例验证
23
**Constraints**: 不引入 Web UI、Android 展示 UI、告警大屏或管理后台；共享行为必须在 common source
24
set；平台代码仅做适配
25
**Scale/Scope**: 8 类场景、JVM/Android 双端、任务配置、规则判定、告警聚合、证据元数据、运行状态和健康输出
26

27
## Constitution Check
28

29
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
30

31
- **检测内核范围**：PASS。计划仅覆盖输入、推理、场景识别、规则、告警、证据、
32
  运行时状态和共享契约；明确排除 UI、大屏、管理后台。
33
- **共享 KMP 优先**：PASS。核心模型、规则、场景处理、DTO、状态和证据契约均规划
34
  在 `commonMain`；JVM/Android 只保留适配器和运行时装配。
35
- **Kotest 与 Allure**：PASS。计划要求 common/JVM/Android host Kotest 覆盖，并用
36
  `:monitor_detection:allureReport --no-configuration-cache` 生成报告。
37
- **可观测性与证据**：PASS。计划包含任务状态、设备健康、告警记录和证据元数据。
38
- **范围克制与简单性**：PASS。保留现有单模块 KMP 架构，不新增 UI、后台或额外模块。
39

40
## Project Structure
41

42
### Documentation (this feature)
43

44

45
specs/001-kmp-monitor-alerts/
46
├── plan.md
47
├── research.md
48
├── data-model.md
49
├── quickstart.md
50
├── contracts/
51
│   ├── runtime-query-contract.md
52
│   └── scenario-output-contract.md
53
└── checklists/
54
    └── requirements.md
55

56

57
### Source Code (repository root)
58

59

60
monitor_detection/
61
├── src/
62
│   ├── commonMain/kotlin/com/smartwater/ai/
63
│   │   ├── core/model/
64
│   │   ├── core/rule/
65
│   │   ├── core/alarm/
66
│   │   ├── data/contract/
67
│   │   ├── runtime/contract/
68
│   │   └── scenario/
69
│   ├── commonTest/kotlin/com/smartwater/ai/
70
│   ├── jvmMain/kotlin/
71
│   ├── jvmTest/kotlin/
72
│   ├── androidMain/kotlin/
73
│   └── androidHostTest/kotlin/
74
└── build.gradle.kts
75

76

77
**Structure Decision**: 继续使用现有单 KMP 模块 `:monitor_detection`。共享业务能力进入
78
`commonMain`，共享测试进入 `commonTest`；JVM 和 Android 仅补平台适配与运行时验证。
79

80
## Complexity Tracking
81

82
无宪章违反项。
83

84
| Violation | Why Needed | Simpler Alternative Rejected Because |
85
|-----------|------------|--------------------------------------|

1
$speckit-tasks

1
# Tasks: JVM 和 Android 多平台监控识别报警
2

3
**Input**: Design documents from `specs/001-kmp-monitor-alerts/`
4
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/`,
5
`quickstart.md`
6

7
**Tests**: 本功能受项目原则约束，所有行为变更必须包含 Kotest 测试，并通过 Allure 报告复核。
8
**Organization**: 任务按用户故事分组，确保每个故事可独立实现和验证。
9

10
## Format: `[ID] [P?] [Story] Description`
11

12
- **[P]**: 可并行执行，涉及不同文件且不依赖未完成任务
13
- **[Story]**: 用户故事标签，仅用于用户故事阶段
14
- 每个任务描述都包含明确文件路径
15

16
---
17

18
## Phase 1: Setup (Shared Infrastructure)
19

20
**Purpose**: 确认 KMP、Kotest、Allure 和文档入口满足本功能交付前提。
21

22
- [X] T001 校验 Kotest 与 Allure 依赖和任务入口，必要时调整 `gradle/libs.versions.toml` 和
23
  `monitor_detection/build.gradle.kts`
24
- [X] T002 [P] 校验 Kotest 全局配置和 Allure 标签输出，必要时调整
25
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/test/KotestProjectConfig.kt`
26
- [X] T003 [P] 对齐测试报告说明和命令，更新 `docs/testing/kotest-allure.md`
27
- [X] T004 [P] 对齐功能验收命令和报告路径，更新 `specs/001-kmp-monitor-alerts/quickstart.md`
28

29
---
30

31
## Phase 2: Foundational (Blocking Prerequisites)
32

33
**Purpose**: 建立所有用户故事共用的模型、规则、场景引擎、DTO 和测试夹具。
34

35
**CRITICAL**: 完成本阶段前，不应开始任一用户故事实现。
36

37
- [X] T005 [P] 校验八类场景枚举、告警级别和运行状态定义，更新
38
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/core/model/Enums.kt`
39
- [X] T006 [P] 校验监控任务、场景观测、告警记录和设备健康字段，更新
40
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/core/model/Task.kt`、
41
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/core/model/Scenario.kt`、
42
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/core/model/Alarm.kt` 和
43
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/core/model/Infrastructure.kt`
44
- [X] T007 [P] 补齐关注区域默认全画面、区域命中和非法区域校验逻辑，更新
45
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/core/model/Geometry.kt`
46
- [X] T008 [P] 补齐规则默认值、置信度阈值、目标标签、连续命中和区域条件模型，更新
47
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/core/rule/RuleEngine.kt`
48
- [X] T009 实现场景连续命中状态、未命中重置和事件键辅助逻辑，更新
49
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/engine/ScenarioSupport.kt`
50
- [X] T010 注册并校验八类场景处理器工厂，更新
51
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/engine/DefaultScenarioRegistryFactory.kt`
52
- [X] T011 [P] 对齐运行时查询和场景输出 DTO 字段，更新
53
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/data/contract/ApiContracts.kt`
54
- [X] T012 [P] 对齐平台服务、视觉引擎、视频源和运行时契约，更新
55
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/runtime/contract/RuntimeAdapters.kt` 和
56
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/runtime/contract/PlatformServices.kt`
57
- [X] T013 [P] 建立八类场景共享测试夹具和样例输入，新增
58
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/test/ScenarioTestFixtures.kt`
59

60
**Checkpoint**: Foundation ready - 用户故事实现可并行启动。
61

62
---
63

64
## Phase 3: User Story 1 - 多平台统一识别八类监控场景 (Priority: P1) MVP
65

66
**Goal**: JVM 和 Android 使用同一套共享场景识别语义，识别工程机械、水面异物、非运维人员入侵、设施位移、水体颜色变化、船舶异常停留、闸坝状态和非法排污。
67

68
**Independent Test**: 使用八类样例输入分别运行 common 场景处理器、JVM runtime 和 Android host
69
runtime，验证场景类型、任务标识和输出语义一致。
70

71
### Tests for User Story 1 (Kotest first)
72

73
- [X] T014 [P] [US1] 为八类场景处理器补齐成功识别和无目标输入 Kotest 覆盖，更新
74
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/scenario/ScenarioProcessorTests.kt`
75
- [X] T015 [P] [US1] 为场景标签归一化、属性映射和连续命中辅助逻辑补齐 Kotest 覆盖，更新
76
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/scenario/engine/ScenarioSupportTest.kt`
77
- [X] T016 [P] [US1] 为 ScenarioEngine 输出八类场景观测补齐 Kotest 覆盖，更新
78
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/scenario/engine/ScenarioEngineTest.kt`
79
- [X] T017 [P] [US1] 为 JVM runtime 八类场景识别烟测补齐 Kotest 覆盖，更新
80
  `monitor_detection/src/jvmTest/kotlin/com/smartwater/ai/runtime/jvm/JvmMonitoringRuntimeTest.kt`
81
- [X] T018 [P] [US1] 为 Android host runtime 八类场景识别烟测补齐 Kotest 覆盖，更新
82
  `monitor_detection/src/androidHostTest/kotlin/com/smartwater/ai/runtime/android/AndroidMonitoringRuntimeTest.kt`
83

84
### Implementation for User Story 1
85

86
- [X] T019 [P] [US1] 完成工程机械作业目标标签、事件标题和属性输出，更新
87
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/machinery/MachineryScenarioProcessor.kt`
88
- [X] T020 [P] [US1] 完成水面异物目标标签、事件标题和属性输出，更新
89
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/floating/FloatingObjectScenarioProcessor.kt`
90
- [X] T021 [P] [US1] 完成非运维人员入侵目标标签、事件标题和属性输出，更新
91
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/intrusion/IntrusionScenarioProcessor.kt`
92
- [X] T022 [P] [US1] 完成监测设施位移目标标签、事件标题和属性输出，更新
93
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/displacement/FacilityDisplacementScenarioProcessor.kt`
94
- [X] T023 [P] [US1] 完成水体颜色变化目标标签、事件标题和属性输出，更新
95
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/watercolor/WaterColorScenarioProcessor.kt`
96
- [X] T024 [P] [US1] 完成船舶异常停留目标标签、事件标题和属性输出，更新
97
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/vessel/VesselStayScenarioProcessor.kt`
98
- [X] T025 [P] [US1] 完成闸坝开启、关闭和未知状态识别输出，更新
99
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/gate/GateStatusScenarioProcessor.kt`
100
- [X] T026 [P] [US1] 完成非法排污目标标签、事件标题和属性输出，更新
101
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/discharge/IllegalDischargeScenarioProcessor.kt`
102
- [X] T027 [US1] 串联处理器注册、观测生成和无目标输入空结果路径，更新
103
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/engine/ScenarioEngine.kt`
104
- [X] T028 [US1] 对齐 JVM 和 Android 默认视觉输出标签映射，更新
105
  `monitor_detection/src/jvmMain/kotlin/DefaultVisionEngine.jvm.kt` 和
106
  `monitor_detection/src/androidMain/kotlin/platform/DefaultVisionEngine.android.kt`
107
- [X] T029 [US1] 校验 JVM 与 Android runtime 默认任务装配使用同一场景注册表，更新
108
  `monitor_detection/src/jvmMain/kotlin/com/smartwater/ai/runtime/jvm/JvmMonitoringRuntime.kt` 和
109
  `monitor_detection/src/androidMain/kotlin/com/smartwater/ai/runtime/android/AndroidMonitoringRuntime.kt`
110

111
**Checkpoint**: User Story 1 可独立运行和验证，是本功能 MVP。
112

113
---
114

115
## Phase 4: User Story 2 - 按规则生成预警并聚合告警 (Priority: P2)
116

117
**Goal**: 根据任务规则判断识别结果是否触发预警，并将同一任务、设备和风险类型的持续事件聚合为同一条打开告警。
118

119
**Independent Test**: 为命中、未命中、区域外、连续命中不足和重复事件输入样例，验证告警创建、更新和不触发路径。
120

121
### Tests for User Story 2 (Kotest first)
122

123
- [X] T030 [P] [US2] 为置信度阈值、目标标签、区域条件和连续命中规则补齐 Kotest 覆盖，更新
124
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/core/rule/DefaultRuleEvaluatorTest.kt`
125
- [X] T031 [P] [US2] 为同一 eventKey 告警聚合和 lastSeenAt 更新补齐 Kotest 覆盖，更新
126
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/core/alarm/AlarmAggregatorTest.kt`
127
- [X] T032 [P] [US2] 为 ScenarioEngine 规则判定、区域外不告警和重复事件聚合补齐 Kotest 覆盖，更新
128
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/scenario/engine/ScenarioEngineTest.kt`
129
- [X] T033 [P] [US2] 为告警 DTO 输出字段和 eventKey 合同补齐 Kotest 覆盖，新增
130
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/data/contract/AlarmDtoPublishersTest.kt`
131

132
### Implementation for User Story 2
133

134
- [X] T034 [US2] 实现规则判定的默认规则、禁用任务、目标过滤、阈值、区域和连续命中逻辑，更新
135
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/core/rule/RuleEngine.kt`
136
- [X] T035 [US2] 统一八类场景 eventKey、title、details 和 alarmLevel 生成方式，更新
137
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/scenario/engine/ScenarioSupport.kt`
138
- [X] T036 [US2] 实现同一 eventKey 打开告警复用和 lastSeenAt 更新，更新
139
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/core/alarm/AlarmAggregator.kt`
140
- [X] T037 [US2] 输出符合合同的告警记录 DTO 和内存发布器行为，更新
141
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/data/contract/AlarmDtoPublishers.kt`
142
- [X] T038 [US2] 为八类场景提供可解释默认规则集，更新
143
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/runtime/contract/RuleSetProvider.kt`
144
- [X] T039 [US2] 将规则判定、告警聚合和发布器接入运行时主流程，更新
145
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/runtime/contract/DirectMonitoringRuntime.kt`
146

147
**Checkpoint**: User Story 1 和 2 均可独立验证，识别结果能转化为可查询告警。
148

149
---
150

151
## Phase 5: User Story 3 - 输出证据、任务状态和设备健康 (Priority: P3)
152

153
**Goal**: 提供任务列表、任务状态、设备健康、告警列表、规则配置和证据元数据输出，支持平台对接与现场复核。
154

155
**Independent Test**: 启动任务并模拟识别、告警、异常和停止过程，验证任务状态、设备健康、告警和证据字段完整。
156

157
### Tests for User Story 3 (Kotest first)
158

159
- [X] T040 [P] [US3] 为任务列表、任务状态、设备健康、规则配置和证据查询补齐 Kotest 覆盖，更新
160
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/runtime/contract/PlatformServicesTest.kt`
161
- [X] T041 [P] [US3] 为运行时启动、心跳、错误和停止状态转移补齐 Kotest 覆盖，新增
162
  `monitor_detection/src/commonTest/kotlin/com/smartwater/ai/runtime/contract/DirectMonitoringRuntimeTest.kt`
163
- [X] T042 [P] [US3] 为 JVM bootstrap 默认任务、规则和健康输出补齐 Kotest 覆盖，更新
164
  `monitor_detection/src/jvmTest/kotlin/com/smartwater/ai/runtime/jvm/JvmMonitoringRuntimeTest.kt`
165
- [X] T043 [P] [US3] 为 Android bootstrap 默认任务、规则和健康输出补齐 Kotest 覆盖，更新
166
  `monitor_detection/src/androidHostTest/kotlin/com/smartwater/ai/runtime/android/AndroidMonitoringRuntimeTest.kt`
167

168
### Implementation for User Story 3
169

170
- [X] T044 [US3] 实现 ApiExposureService 对任务、状态、健康、规则、告警和证据的统一查询输出，更新
171
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/runtime/contract/PlatformServices.kt`
172
- [X] T045 [US3] 在运行时维护任务状态、心跳、最近帧、错误和证据元数据关联，更新
173
  `monitor_detection/src/commonMain/kotlin/com/smartwater/ai/runtime/contract/DirectMonitoringRuntime.kt`
174
- [X] T046 [US3] 对齐 JVM 默认视频源、视觉引擎、任务和规则装配，更新
175
  `monitor_detection/src/jvmMain/kotlin/com/smartwater/ai/runtime/jvm/JvmRuntimeBootstrap.kt`
176
- [X] T047 [US3] 对齐 Android 默认视频源、视觉引擎、任务、规则和前台服务装配，更新
177
  `monitor_detection/src/androidMain/kotlin/com/smartwater/ai/runtime/android/AndroidRuntimeBootstrap.kt`
178
  和 `monitor_detection/src/androidMain/kotlin/service/AlertForegroundService.kt`
179

180
**Checkpoint**: 三个用户故事均可独立运行，运行状态和证据输出可供复核。
181

182
---
183

184
## Phase 6: Polish & Cross-Cutting Concerns
185

186
**Purpose**: 文档、合同、格式和验收报告收尾。
187

188
- [X] T048 [P] 根据最终实现同步场景输出合同，更新
189
  `specs/001-kmp-monitor-alerts/contracts/scenario-output-contract.md`
190
- [X] T049 [P] 根据最终实现同步运行时查询合同，更新
191
  `specs/001-kmp-monitor-alerts/contracts/runtime-query-contract.md`
192
- [X] T050 [P] 更新项目说明中的功能范围和测试入口，更新 `README.md`
193
- [X] T051 运行
194
  `./gradlew :monitor_detection:compileCommonMainKotlinMetadata :monitor_detection:compileKotlinJvm :monitor_detection:compileAndroidMain`
195
  并将结果记录到 `specs/001-kmp-monitor-alerts/quickstart.md`
196
- [X] T052 运行 `./gradlew :monitor_detection:jvmTest` 并将结果记录到
197
  `specs/001-kmp-monitor-alerts/quickstart.md`
198
- [X] T053 运行 `./gradlew :monitor_detection:testAndroidHostTest` 并将结果记录到
199
  `specs/001-kmp-monitor-alerts/quickstart.md`
200
- [X] T054 运行 `./gradlew :monitor_detection:allureReport --no-configuration-cache` 并确认报告目录
201
  `monitor_detection/build/reports/allure-report/allureReport`
202
- [X] T055 运行 `./gradlew :monitor_detection:ktlintCheck` 并将结果记录到
203
  `specs/001-kmp-monitor-alerts/quickstart.md`
204

205
---
206

207
## Dependencies & Execution Order
208

209
### Phase Dependencies
210

211
- **Setup (Phase 1)**: 无依赖，可立即执行
212
- **Foundational (Phase 2)**: 依赖 Setup，阻塞全部用户故事
213
- **User Story 1 (Phase 3)**: 依赖 Foundational，是 MVP
214
- **User Story 2 (Phase 4)**: 依赖 Foundational，可在 US1 后集成验证，也可与 US1 并行开发
215
- **User Story 3 (Phase 5)**: 依赖 Foundational，可在 US1/US2 之后做端到端复核，也可并行开发运行时输出
216
- **Polish (Phase 6)**: 依赖选定交付范围完成
217

218
### User Story Dependencies
219

220
- **US1 (P1)**: 八类场景识别，MVP 范围，无其他用户故事依赖
221
- **US2 (P2)**: 规则与告警聚合，依赖共享模型和规则基础，可独立用样例事件验证
222
- **US3 (P3)**: 状态、健康和证据输出，依赖共享运行时契约，可独立模拟任务生命周期验证
223

224
### Within Each User Story
225

226
- 先编写或补齐 Kotest 测试，并确认测试在实现前能暴露缺口
227
- 先 commonMain 共享行为，再 JVM/Android 适配
228
- 先场景观测，再规则判定，再告警聚合，再 DTO/运行时输出
229
- 每个用户故事完成后运行对应 Kotest，再进入下一优先级
230

231
### Parallel Opportunities
232

233
- T002、T003、T004 可并行处理配置和文档
234
- T005、T006、T007、T008、T011、T012、T013 可在不同文件中并行推进
235
- US1 的 T019 到 T026 可由不同人员分别处理八类场景处理器
236
- US2 的规则测试、聚合测试和 DTO 测试可并行编写
237
- US3 的 common、JVM、Android host 测试可并行编写
238

239
---
240

241
## Parallel Example: User Story 1
242

243
Task: "T014 [P] [US1] 更新 ScenarioProcessorTests.kt"
244
Task: "T015 [P] [US1] 更新 ScenarioSupportTest.kt"
245
Task: "T017 [P] [US1] 更新 JvmMonitoringRuntimeTest.kt"
246
Task: "T018 [P] [US1] 更新 AndroidMonitoringRuntimeTest.kt"
247

248
Task: "T019 [P] [US1] 更新 MachineryScenarioProcessor.kt"
249
Task: "T020 [P] [US1] 更新 FloatingObjectScenarioProcessor.kt"
250
Task: "T021 [P] [US1] 更新 IntrusionScenarioProcessor.kt"
251
Task: "T022 [P] [US1] 更新 FacilityDisplacementScenarioProcessor.kt"
252
Task: "T023 [P] [US1] 更新 WaterColorScenarioProcessor.kt"
253
Task: "T024 [P] [US1] 更新 VesselStayScenarioProcessor.kt"
254
Task: "T025 [P] [US1] 更新 GateStatusScenarioProcessor.kt"
255
Task: "T026 [P] [US1] 更新 IllegalDischargeScenarioProcessor.kt"
256

257

258
## Parallel Example: User Story 2
259

260

261
Task: "T030 [P] [US2] 更新 DefaultRuleEvaluatorTest.kt"
262
Task: "T031 [P] [US2] 更新 AlarmAggregatorTest.kt"
263
Task: "T033 [P] [US2] 新增 AlarmDtoPublishersTest.kt"
264

265

266
## Parallel Example: User Story 3
267

268

269
Task: "T040 [P] [US3] 更新 PlatformServicesTest.kt"
270
Task: "T041 [P] [US3] 新增 DirectMonitoringRuntimeTest.kt"
271
Task: "T042 [P] [US3] 更新 JvmMonitoringRuntimeTest.kt"
272
Task: "T043 [P] [US3] 更新 AndroidMonitoringRuntimeTest.kt"
273

274

275
---
276

277
## Implementation Strategy
278

279
### MVP First (User Story 1 Only)
280

281
1. 完成 Phase 1 和 Phase 2
282
2. 完成 Phase 3 中 US1 的 Kotest 测试和八类场景处理器
283
3. 运行 `./gradlew :monitor_detection:jvmTest`
284
4. 运行 `./gradlew :monitor_detection:testAndroidHostTest`
285
5. 生成 `./gradlew :monitor_detection:allureReport --no-configuration-cache`
286

287
### Incremental Delivery
288

289
1. Setup + Foundational: 保证 KMP 共享模型、规则、场景引擎和测试夹具可用
290
2. US1: 交付八类场景识别 MVP，并验证 JVM/Android 语义一致
291
3. US2: 增加规则判定和告警聚合，验证不重复告警和不触发路径
292
4. US3: 增加任务状态、设备健康和证据元数据输出
293
5. Polish: 同步合同、文档、格式检查和 Allure 报告
294

295
### Validation Commands
296

297

298
./gradlew :monitor_detection:compileCommonMainKotlinMetadata :monitor_detection:compileKotlinJvm :monitor_detection:compileAndroidMain
299
./gradlew :monitor_detection:jvmTest
300
./gradlew :monitor_detection:testAndroidHostTest
301
./gradlew :monitor_detection:allureReport --no-configuration-cache
302
./gradlew :monitor_detection:ktlintCheck
303

304

305
## Notes
306

307
- [P] 任务必须保持不同文件或无直接依赖，避免同一文件并发修改冲突
308
- 用户故事阶段的任务均带有 [US1]、[US2] 或 [US3] 标签
309
- 本任务清单不包含 Web UI、Android 展示 UI、告警大屏或管理后台
310
- 行为变更以 Kotest 为准，交付复核以 Allure 报告为准

1
$specify-implement

1
$specify-analyze