第14章　学生项目冲刺二：建立工程基线

立项合并请求已经确认项目原点。本周把“准备做什么”转化为“系统怎样分工、首先验证什么、团队怎样协作”。周末前，仓库应形成可构建骨架、系统规格、物料清单、关键技术验证和v0.1任务树。

项目章程
→ 系统边界
→ 接口契约
→ 约束驱动选型
→ 核心技术验证
→ 仓库与AI规则
→ 里程碑和议题
→ 工程基线

工程基线不是大量空目录和模板。每个进入仓库的文件都应服务于下周的最小闭环。

组件先行的开发容易使各部分分别可用，却在集成时才暴露接口冲突。工程基线先固定系统边界、关键接口和最大风险。它不会消除变化，但能使变化的位置、理由和影响更容易判断。

完成本章后，应当能够：

• 从项目闭环画出系统上下文和组件关系；
• 明确设备、数据模型、服务器和用户端接口；
• 根据需求与资源约束比较硬件候选；
• 用技术验证尽早暴露最大风险；
• 记录物料清单、契约、预算和关键决策；
• 初始化适合本项目的真实代码骨架；
• 为Cline和校内Qwen设置项目级稳定规则；
• 把v0.1拆成有依赖、可验收的议题；
• 使用GitLab里程碑和看板显示真实进度；
• 通过基线合并请求决定项目是否进入完整开发。

14.1 画出系统上下文

只画项目系统与外部对象：

物理对象/环境
      │信号
      ↓
学生项目设备 ──事件/状态──→ 项目服务
      ↑                         │
      │配置                     │反馈
      └──────── 授权用户 ←─────┘

根据项目实际情况删除不需要的部分。例如完全离线的本地提示产品可以没有服务器，但要说明数据、配置和用户反馈怎样完成。

图中每一条连接都回答：

• 谁向谁发送；
• 发送什么；
• 何时发送；
• 失败怎样表现；
• 是否包含敏感信息；
• 哪一版本文件定义格式。

docs/architecture/context.md保存图和文字说明。

14.2 确定组件和替换边界

从闭环拆分：

输入适配器
→ 数据窗口
→ 预处理
→ 基线判断/模型
→ 事件策略
→ 反馈适配器

若需要服务器：

事件编码
→ 通信适配器
→ 接收与校验
→ 存储
→ 用户查询

接口边界应支持逐步替换：

• 第15章可重复输入替换为第16章真实模型输入；
• 确定性判断替换为模型运行器；
• 课程统一开发板适配器可替换为本组硬件；
• 本地反馈可替换或补充为远程反馈；
• 测试数据回放与真实传感器共用上层接口。

组件不应按成员姓名划分。以工程职责划分，成员变化时接口仍然成立。

14.3 把产品需求转成最小规格

为每项最小可行产品需求建立：

## FR-001 <功能名称>
- 来源：PR-01
- 输入：
- 行为：
- 输出：
- 错误：
- 验收：
- 责任组件：

非功能预算：

| 编号 | 指标 | 目标 | 当前估计 | 当前实测 | 截止版本 |
|---|---|---:|---:|---:|---|
| NFR-001 | 反馈延迟 | <目标> | 待估计 | 尚未测量 | v0.1 |
| NFR-002 | 闪存 | <硬件约束> | 待估计 | 尚未测量 | `v0.5` |
| NFR-003 | RAM | <硬件约束> | 待估计 | 尚未测量 | v0.5 |
| NFR-004 | 原型成本 | <项目约束> | <当前物料清单> | 尚未核对 | v0.1 |

本周必须填写目标依据，保留尚未测量状态；不要为使文档完整而填写假数据。

14.4 定义最小接口契约

14.4.1 输入样本和数据窗口

至少说明：

• 传感器与通道；
• 数据类型与单位；
• 时间戳；
• 采样率；
• 窗口长度与步长；
• 错误状态；
• 硬件和配置版本。

若模型参数尚未确定，把它标为需要在第16章前确认的议题，不复制教师项目参数。

14.4.2 产品事件

事件至少包含：

schema_version
event_id
device_id
event_type
observed_at或明确的时间策略
firmware_version
model_or_rule_version
sequence

根据项目需要增加字段，但默认不携带原始个人数据。建立模式和一个脱敏示例，并使用工具检查语法。

14.4.3 模型构建物

向数据科学课程约定：

模型格式
输入形状、类型和预处理
输出形状和标签
数据集版本
评价摘要
模型卡
基准输入输出
文件散列
预计交付时间

没有该接口，第16章容易出现“模型已经训练，但设备无法接入”。

14.5 由约束选择硬件

14.5.1 先使用课程统一硬件作为基线

如果统一硬件满足输入、资源和通信需要，优先使用它完成v0.1。更换硬件只有在以下情况具有明确理由：

• 缺少必须传感接口；
• 模型资源有可测证据不满足；
• 安装、功耗或尺寸使核心场景不可验证；
• 统一硬件无法取得；
• 项目研究目标就是验证另一种硬件，且课程批准。

更换带来工具链、驱动、供货、数据分布和团队学习成本。

14.5.2 建立候选与物料清单

| 物料 | 必须约束 | 候选 | 参数来源 | 价格/日期 | 供货 | 替代 | 状态 |
|---|---|---|---|---|---|---|---|

所有数值带条件和来源。AI可以列出待核查参数，不能作为数据手册和供货状态的最终来源。

14.5.3 用技术决策记录保存关键选择

至少建立：

• 技术决策记录-0001：传感输入与安装方式；
• 技术决策记录-0002：设备与用户反馈链路；
• 若更换课程硬件，再建立主控/板卡决策。

每份记录包含问题、约束、候选、证据、决定、后果和重新评估条件。

14.6 先验证最可能使项目失败的技术

14.6.1 找出最大不确定性

常见最大风险：

• 目标事件信号与主要干扰无法区分；
• 传感器在实际安装位置无法稳定采样；
• 模型预计资源超过设备；
• 课程网络不支持计划协议；
• 用户反馈链路依赖未经批准的外部服务；
• 必需数据无法在本周取得。

每组只选择当前最大的一个风险进行验证，不同时研究所有技术。

14.6.2 技术验证有时间上限和判据

# 技术验证TV-01

## 问题
<一个可以用证据回答的问题>

## 时间上限
<本周明确时段>

## 输入与环境
-

## 通过条件
-

## 失败条件
-

## 实际结果
-

## 决定
继续当前方案 / 调整 / 使用课程基线 / 停止项目

例如，可把“研究传感器”改为可验证的任务。任务要求在批准位置连续采集10 min。记录中应给出初始化错误数和缓冲溢出数。还要比较目标动作与静止数据的差异。各项结果必须填写实际值。

14.6.3 技术验证代码怎样进入Git

建立：

git switch -c issue-5-verify-core-signal

保留：

• 最小代码；
• 构建方法；
• 输入和硬件身份；
• 结果与证据；
• 最终决定。

若验证代码不适合作为产品代码，在合并请求中说明哪些部分只用于验证，不直接复制到main。可以只合并脚本、接口和结论，舍弃临时实现。

14.7 初始化真实仓库骨架

根据已确认组件建立：

project/
├─ README.md
├─ CHANGELOG.md
├─ contracts/
├─ docs/
│  ├─ product/
│  ├─ architecture/
│  └─ verification/
├─ firmware/
├─ server/          # 仅在项目需要时
├─ models/
├─ hardware/
├─ tests/
├─ tools/
│  └─ project.py
├─ .clinerules/
├─ .env.example
└─ .gitignore

没有服务器的项目不创建空server/。没有可公开数据时，datasets/只在需要数据集清单时创建。

统一命令至少提供：

python tools/project.py doctor
python tools/project.py build
python tools/project.py test

命令可以先只覆盖当前骨架，但不得用固定输出伪装构建成功。

14.8 设置AI协同规则

.clinerules/project.md记录稳定约束：

# 项目AI协同规则

## 产品边界
- 核心用户结果：
- 本期不做：
- 高风险禁止范围：

## 工程结构
- 设备：
- 数据模型：
- 服务：
- 契约：

## 修改规则
- 一个议题对应一个任务分支；
- 先Plan，批准后实施；
- 未经议题批准不得改变契约、物料清单、模型和产品范围；
- 不自动提交、推送、合并和发布；
- 不读取或写入真实秘密和未授权数据。

## 验证
- 本地命令：
- 实机要求：
- MR必须提供的证据：

## 三课程接口
- 数据与模型责任：
- 硬件与嵌入式责任：
- Git与集成责任：

规则文件不能取代议题。它保存长期约束，议题保存当前变化。

14.9 建立v0.1任务树

从用户结果反向拆解：

用户看到结果
└─ 反馈组件
   └─ 产品事件
      ├─ 事件契约
      ├─ 发送与确认
      └─ 输入适配器
         └─ 真实或可重复输入

议题大小建议能在半天到一天半内产生可评审结果。每个议题包含：

• 目标；
• 前置依赖；
• 允许与禁止范围；
• 验收条件；
• 验证命令与实机要求；
• 负责人和评审者；
• 预计进入版本。

第15章必须完成的议题优先，其余进入后续里程碑。

14.10 使用GitLab显示真实进度

建立里程碑：

v0.1 最小闭环
v0.5 智能能力
v1.0-rc 系统候选
v1.0 正式发布

建立简单看板：

Open → Doing → Review → Closed

团队同时进行的议题数量不超过实际成员数。一个任务进入Review后，负责人优先推动评审和合并，而不是继续开启新任务。

进度由已关闭且满足验收的议题表示，不按AI生成代码量或完成百分比估计。

14.11 形成工程基线合并请求

基线合并请求包含：

• 系统上下文和组件图；
• 功能需求与预算；
• 数据、事件和模型接口；
• 物料清单与技术决策；
• 核心技术验证；
• 仓库骨架和统一命令；
• AI规则；
• v0.1任务树和里程碑。

评审：

[ ] 架构只包含项目实际需要的组件
[ ] 最小接口足以支持并行开发
[ ] 最大技术风险已有实际验证
[ ] 物料清单满足需求且来源可核查
[ ] 数据和模型交付时间明确
[ ] 仓库命令执行真实检查
[ ] AI规则与产品边界一致
[ ] v0.1依赖链可以在一周内完成
[ ] 每个议题有验收条件
[ ] 失败时有降级方案

通过后可创建内部基线标签：

git tag -a v0.0.1 -m "project engineering baseline"
git push origin v0.0.1

该标签不是产品发布，只固定进入v0.1开发前的工程状态。

14.12 本章小结

本章把学生项目章程转化为工程基线。团队建立系统边界、接口契约、预算和物料清单。技术决策、AI规则和v0.1任务树也进入仓库。限时技术验证用于处理最主要的不确定性。

第15章将沿任务树实现真实设备最小闭环。若核心技术验证仍未通过，应执行已经批准的降级方案。不能把该风险带入最后四周。

14.13 综合实践

1. 为本组项目形成系统上下文图、组件关系和接口契约。每条连接标明数据、失败结果和版本责任。
2. 选择最大技术风险，设计一项半天内能够得出继续、降级或停止结论的验证，并保存原始证据。
3. 建立物料清单、资源预算和一份技术决策记录。参数须有来源，未知项须有责任人和确认版本。
4. 建立最小仓库骨架和AI协同规则。邀请另一组尝试依据规则提出越界任务，再修订规则。
5. 把v0.1拆成有依赖和验收条件的议题，形成工程基线合并请求与v0.0.1内部标签。