第6章　设计系统方案与工程规格

第5章说明了智能感知终端的问题和最小产品范围。本章把产品需求转化为系统边界、接口契约和资源预算。可追溯的技术决策使各部分能够按共同约定并行开发。

技术方案不是一幅只用于汇报的架构图。它至少要回答：

系统由哪些部分组成？
→ 各部分交换什么信息？
→ 每项需求由谁实现、怎样验证？
→ 关键器件和方案为什么这样选择？
→ 条件变化时怎样替换而不破坏整体？

本章不展开芯片内部结构、传感器电路和模型算法。本章只确定它们进入产品工程时必须满足的接口与证据。相关深入内容分别在《感知与异构计算系统原型》和《人工智能数据科学》中完成。

小型原型可以依靠成员之间的口头约定。项目分为设备、模型和服务等部分后，隐含假设容易产生分歧。接口契约和资源预算把这些假设写成可检查对象，其代价是每次不兼容变化都要同步更新相关文件。

完成本章后，应当能够：

• 从产品需求提取功能需求和非功能需求；
• 画出系统上下文和主要组件关系；
• 明确三门课程的工程接口与交付物；
• 用约束比较芯片、传感器、通信和电源候选方案；
• 建立可版本化的物料清单与参数来源记录；
• 定义设备事件、服务接口和模型构建物契约；
• 区分目标、估计与实测资源数据；
• 使用技术决策记录保存选择、理由和后果；
• 让AI协助调研和检查一致性，同时保留人工核查证据；
• 通过合并请求形成第一份系统规格基线。

6.1 从产品需求得到系统规格

6.1.1 产品需求说明结果，系统规格约束实现

第5章的产品需求可以写为：

PR-02：设备应把事件发送给课程服务器，并获得明确确认。

系统规格需要继续回答：

• 一条事件包含哪些字段；
• 使用什么传输方式；
• 成功和失败怎样区分；
• 设备怎样识别重复发送；
• 服务器在多长时间内回应；
• 断网时设备怎样处理；
• 哪些内容不得进入消息。

将规格写成带标识的条目：

## FR-004 事件上报
设备端应按照EVENT-001生成事件消息，并提交给事件接收接口API-001。

验收：
- 合法消息被服务器接受并返回event_id；
- 缺少必填字段时返回可区分的4xx错误；
- 网络失败不能被设备记录为发送成功。

来源：PR-02
验证：IT-004接口测试、ST-002端云测试

产品需求（Product Requirement，PR）说明用户需要的结果。功能需求（Functional Requirement，FR）说明系统应有的行为。非功能需求（Non-functional Requirement，NFR）说明性能、资源和安全等约束。EVENT和API分别作为事件契约与服务接口的项目标识。稳定标识使需求、代码、测试和议题能够互相引用。

6.1.2 建立需求追踪表

在docs/architecture/traceability.md中建立：

| 产品需求 | 系统规格 | 实现位置 | 验证 | 状态 |
|---|---|---|---|---|
| PR-01 | FR-001、FR-002 | 待开发 | ST-001 | Planned |
| PR-02 | FR-004、NFR-003 | 待开发 | IT-004、ST-002 | Planned |
| PR-03 | FR-006、NFR-005 | 待开发 | ST-003 | Planned |

本章的“实现位置”仍可写为“待开发”，不能提前填写不存在的文件。后续每次合并请求只更新实际完成的状态。

追踪表主要用于发现三类遗漏：

1. 产品需求没有对应实现；
2. 代码或功能没有对应需求；
3. 需求已经变化，但测试仍验证旧行为。

6.1.3 规格从说明文字发展为可检查契约

只用自然语言编写规格时，设备端和服务器端可能对同一句话作出不同解释。项目扩大后，接口说明逐步增加字段表、错误语义和示例。机器可检查的数据模式又把部分约束转成自动测试。

机器检查能够发现字段缺失和类型错误，却不能判断需求本身是否合理。规格越精确，修改成本也越高。因此，本章只固定跨组件必须共享的边界，并把仍需验证的参数保留为待定项。

6.2 明确系统边界

6.2.1 系统上下文

先画系统与外部对象的关系：

             配置与查看
授权用户 ───────────────→ 用户端
   ↑                         │
   │事件反馈                 │查询/确认
   │                         ↓
物理场景 → 智能感知终端 → 课程服务器
              │              │
              │时间/网络      │受控存储
              ↓              ↓
        基础设施服务      项目数据存储

图中每个箭头都应能在规格中找到信息内容和方向。不要只画“设备—云—应用”三个方框而不说明数据。

系统边界建议定义为：

• 设备端：采集输入、形成数据窗口、执行模型或规则、应用事件策略、上报事件；
• 服务器端：验证身份和消息、保存事件、返回确认、向授权用户提供查询；
• 用户端：显示事件和状态，接收用户操作；
• 外部基础设施：网络、时间、校内模型服务和开发平台，不作为产品自行实现的组件。

6.2.2 主要组件

设备内部再拆为可以独立验证的组件：

输入适配器
→ 数据窗口
→ 预处理
→ 模型推理/规则判断
→ 事件策略
→ 事件编码
→ 通信适配器

服务器内部先保留最小结构：

事件接收接口
→ 消息验证
→ 事件存储
→ 查询接口
→ 用户端

第7章将用可重复输入和确定性判断打通全部组件；第8章接入真实传感器；第9章接收数据科学课程的模型构建物；第10章将模型部署到设备端。组件边界保持稳定，内部实现逐步替换。

6.3 建立三门课程的工程接口

三门课程围绕同一项目工作，但关注点不同。不能把“协同”理解为在三本教材中重复相同内容。

6.3.1 数据科学课程交付接口

本项目接收的模型构建物至少包括：

model.tflite或课程规定的模型文件
model-manifest.json
model-card.md
labels.txt
preprocessing.json
evaluation-summary.json

本课程不重新训练模型来“修复集成问题”。若模型输入、量化参数或类别顺序不符合工程契约，应建立议题。对应课程负责确认数据或模型构建过程。

6.3.2 硬件课程交付接口

硬件与嵌入式侧至少提供：

hardware/BOM.md
hardware/pin-map.md
hardware/power-notes.md
firmware中的传感器适配器
构建和烧录说明
板级验证记录

本课程通过Git版本、接口头文件、构建结果和测试证据接收成果。正文不重复讲解寄存器配置或电路设计。

6.4 把非功能要求写成预算

6.4.1 非功能要求决定方案是否可用

功能正确只说明系统能够产生结果。物理AI产品还受到时间、资源、功耗、可靠性、隐私和成本限制。RAM保存程序运行时的数据。闪存保存固件、模型和静态资源。

建立docs/architecture/budgets.md：

| 编号 | 指标 | 目标 | 当前估计 | 当前实测 | 测量条件 | 责任接口 |
|---|---|---:|---:|---:|---|---|
| NFR-001 | 端到端反馈延迟 | <待确认> | 待估计 | 尚未测量 | 待定义 | 系统 |
| NFR-002 | 固件闪存占用 | <课程板约束> | 待估计 | 尚未测量 | 发布构建 | 设备端 |
| NFR-003 | 峰值RAM占用 | <课程板约束> | 待估计 | 尚未测量 | 推理期间 | 设备端 |
| NFR-004 | 平均功耗 | <场景目标> | 待估计 | 尚未测量 | 指定工作周期 | 硬件 |
| NFR-005 | 事件送达成功率 | <试用目标> | 待估计 | 尚未测量 | 指定网络条件 | 端云 |
| NFR-006 | 原始数据保留 | 最小必要 | 不适用 | 尚未审计 | 隐私检查 | 数据 |

尖括号内容必须在团队决策后替换。表格初建时保留“尚未测量”，比填入缺乏条件的示例数字更符合工程事实。

6.4.2 预算需要分解

例如端到端反馈延迟可以分解为：

采样窗口
+ 预处理
+ 模型推理
+ 事件策略
+ 网络传输
+ 服务器处理
+ 用户端刷新
= 端到端反馈延迟

若产品目标为5 s，不能让每个组件各自假设拥有5 s。系统负责人应分配各部分目标，并在后续实测中更新。

资源预算同样需要分解：

闪存 = 固件代码 + 库 + 模型 + 静态资源 + 升级余量
RAM   = 采样缓冲 + 特征缓冲 + 推理张量 + 通信缓冲 + 任务栈

模型和硬件课程提供各自部分的估计与测量，本课程负责检查总预算和版本一致性。

6.5 由约束驱动器件与通信选型

6.5.1 先列筛选条件

不要从“某芯片功能很多”开始。先从规格提取筛选条件：

课程统一开发板可以作为第一候选，但仍应记录它满足或不满足哪些约束。第7章打通闭环后，若真实测量表明资源不足，可以通过适配器和技术决策记录替换方案。

6.5.2 参数必须带来源和条件

建立候选表：

| 候选 | 参数 | 值 | 条件 | 原始来源 | 文档版本/页码 | 核查日期 |
|---|---|---:|---|---|---|---|
| A | 可用RAM | <核查值> | <说明保留区域> | <数据手册> | <版本/页码> | <日期> |
| A | 工作电流 | <核查值> | <电压、频率、外设状态> | <数据手册> | <版本/页码> | <日期> |

参数离开测试条件可能没有比较意义。例如“低功耗”不能替代指定电压、时钟、外设状态和测量方式下的电流数据。

AI可用于生成候选型号和需要核对的参数列表；进入物料清单和技术决策记录的数值必须由人回到厂商数据手册或实际测量核对。

6.5.3 选型要考虑可替换性

把硬件差异封装在接口后：

struct SensorSample {
  std::uint32_t timestamp_ms;
  float x;
  float y;
  float z;
};

class SensorSource {
 public:
  virtual bool begin() = 0;
  virtual bool read(SensorSample& sample) = 0;
  virtual ~SensorSource() = default;
};

这是接口示意，最终类型和错误处理应根据课程固件框架确定。上层数据窗口只依赖SensorSource，真实传感器和数据回放适配器分别实现该接口。替换器件时，主要变化被限制在适配器和硬件配置，而不是扩散到模型、事件和通信模块。

6.5.4 建立初版物料清单

物料清单（Bill of Materials，BOM）记录器件、数量、成本、来源和替代方案。它既是硬件清单，也是成本、供应和版本追踪的共同入口。

hardware/BOM.md至少包含：

# 物料清单

> 阶段：方案基线
> 数量口径：课程原型1套
> 价格核查日期：<日期>

| 类别 | 物料/候选 | 关键约束 | 数量 | 参考单价 | 小计 | 供货来源 | 状态 | 替代方案 |
|---|---|---|---:|---:|---:|---|---|---|
| 主控 | <课程板或候选> | RAM、闪存、通信 | 1 | <核查> | <计算> | <来源> | 候选/选定 | <候选> |
| 传感器 | <候选> | 量程、采样率、FIFO | 1 | <核查> | <计算> | <来源> | 候选/选定 | <候选> |
| 电源 | <候选> | 容量、安全、接口 | 1 | <核查> | <计算> | <来源> | 候选/选定 | <候选> |

物料清单进入Git后，器件替换要通过合并请求说明：

• 哪项需求或风险触发变更；
• 接口是否兼容；
• 成本、供货和验证怎样变化；
• 是否影响数据分布或模型；
• 哪些测试必须重新执行。

6.6 定义设备事件契约

6.6.1 先定义一条最小事件

在contracts/examples/event.example.json保存一条不含真实身份信息的示例：

{
  "schema_version": "1.0",
  "event_id": "01JEXAMPLE0000000000000000",
  "device_id": "course-device-001",
  "event_type": "target_event",
  "observed_at": "<ISO 8601格式的实际时间>",
  "device_uptime_ms": 125400,
  "confidence": 0.91,
  "firmware_version": "0.1.0-dev",
  "model_version": "baseline-rule-1",
  "sequence": 17
}

字段含义：

示例中的数值只用于说明结构，不是项目实测结果。

6.6.2 用模式使契约可检查

JavaScript对象表示法（JavaScript Object Notation，JSON）适合传递结构化数据。contracts/event.schema.json使用JSON模式表达字段、类型和范围。最小片段如下：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:course:intelligent-sensing-terminal:event:1",
  "title": "Intelligent Sensing Terminal Event",
  "type": "object",
  "required": [
    "schema_version",
    "event_id",
    "device_id",
    "event_type",
    "observed_at",
    "device_uptime_ms",
    "firmware_version",
    "model_version",
    "sequence"
  ],
  "properties": {
    "schema_version": { "type": "string" },
    "event_id": { "type": "string", "minLength": 8 },
    "device_id": { "type": "string", "minLength": 1 },
    "event_type": { "type": "string", "minLength": 1 },
    "observed_at": {
      "type": ["string", "null"],
      "format": "date-time"
    },
    "device_uptime_ms": { "type": "integer", "minimum": 0 },
    "confidence": {
      "type": ["number", "null"],
      "minimum": 0,
      "maximum": 1
    },
    "firmware_version": { "type": "string" },
    "model_version": { "type": "string" },
    "sequence": { "type": "integer", "minimum": 0 }
  },
  "additionalProperties": false
}

先检查JSON语法：

python -m json.tool contracts/event.schema.json
python -m json.tool contracts/examples/event.example.json

语法正确不等于示例符合模式。第7章将增加契约验证脚本，第11章把它接入GitLab持续集成。

6.6.3 设计兼容性规则

契约演进遵守：

• 增加可选字段通常可以保持向后兼容；
• 删除字段、改变类型或改变含义通常不兼容；
• 消费方不得假设未声明字段一定存在；
• 设备和服务器都记录所用模式版本；
• 不兼容变化必须建立议题、更新样例与测试，并说明迁移方法。

AI修改消息结构时，必须同时检查模式、示例、设备编码、服务端解析和测试。只修改某一处会形成“局部编译通过、系统集成失败”。

6.7 定义服务接口和失败语义

第一版事件接口可以抽象为：

POST /api/v1/events
Content-Type: application/json
Authorization: <设备凭据>

请求体：EVENT-001

建议明确：

“发送函数返回”不等于“服务器已经接受”。设备状态至少区分：

CREATED → QUEUED → SENT → ACKNOWLEDGED
                    └──→ RETRYABLE_FAILED
                    └──→ PERMANENT_FAILED

第7章实现最小状态，第8章再加入缓存和重传。接口文档应说明超时、重试次数、重复事件处理和凭据存放方式。

6.8 定义模型构建物契约

6.8.1 模型不是一个孤立文件

设备端集成需要知道：

• 输入张量形状、类型和量化参数；
• 采样率、窗口长度和预处理；
• 输出张量、类别顺序和含义；
• 模型版本、文件散列和生成来源；
• 评价指标与适用边界；
• 运行需要的算子和资源。

models/model-manifest.example.json可以定义：

{
  "manifest_version": "1.0",
  "model_version": "pending",
  "file": "pending",
  "sha256": "pending",
  "input": {
    "sample_rate_hz": 0,
    "window_samples": 0,
    "channels": 0,
    "dtype": "pending"
  },
  "preprocessing_version": "pending",
  "labels": [],
  "output_dtype": "pending",
  "source_commit": "pending"
}

本章保留pending，表示接口尚待《人工智能数据科学》课程交付。不得用看似真实的占位指标冒充模型结果。

6.8.2 硬件变化可能使模型失效

更换传感器、量程、安装位置、采样率或滤波配置，会改变输入数据分布。物料清单合并请求必须检查：

硬件变化
→ 数据模式是否变化
→ 旧数据能否继续使用
→ 预处理是否变化
→ 模型是否需要重新评价或训练

因此，器件选型不是只属于硬件目录的局部变化；GitLab议题和合并请求要通知数据与模型责任人。

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

6.9.1 什么情况需要记录

当一项决定具有以下特征之一时，应建立技术决策记录：

• 影响多个组件或课程；
• 改变代价较高；
• 存在两个以上合理方案；
• 与成本、隐私、资源或供应风险相关；
• 后续成员可能不理解选择理由。

文件采用：

docs/architecture/decisions/ADR-0001-<简短主题>.md

技术决策记录（Architecture Decision Record，ADR）保存重要选择及其理由。它还说明选择的代价和重新评估条件。

6.9.2 技术决策记录模板

# ADR-0001：第一版事件传输方式

- 状态：Proposed
- 日期：<日期>
- 关联：PR-02、FR-004、NFR-001

## 问题
设备需要把低频、小体积事件发送到课程服务器并获得明确确认。

## 约束
- 校园网络条件：
- 设备资源：
- 消息频率与大小：
- 凭据与隐私：
- 课程时间：

## 候选方案
### 方案A
- 优点：
- 缺点：
- 证据：

### 方案B
- 优点：
- 缺点：
- 证据：

## 决定
<选择及生效范围>

## 理由
<如何满足当前约束>

## 后果
- 获得：
- 代价：
- 新风险：
- 需要重新评估的条件：

## 验证
- 原型：
- 测试：
- 截止版本：

状态从Proposed经过合并请求评审变为Accepted。若以后改变决定，不删除旧文件，而是新增决策记录并把旧记录标记为Superseded，保留原因和历史。

6.10 让AI协助方案研究和一致性检查

6.10.1 研究请求要要求来源

芯片、传感器、协议和框架变化较快，AI内部知识可能过时。可以提交：

任务：为FR-001、NFR-002和NFR-003形成主控候选核查清单。

输入：
- docs/architecture/specification.md
- docs/architecture/budgets.md
- hardware/BOM.md

要求：
1. 先提取必须约束，不增加产品功能；
2. 提出不超过3个候选方向；
3. 列出每个候选必须人工核查的参数；
4. 优先给出原厂数据手册或官方文档入口；
5. 参数无法确认时写“待核查”，不得推测；
6. 不直接修改物料清单和技术决策记录；
7. 不把价格和供货状态写成长期事实。

对AI给出的链接、参数和结论逐项人工核对。选型表中记录实际打开的原始来源、版本、页码和核查日期。

6.10.2 用AI检查跨文件矛盾

规格文件形成后，执行只读检查：

请检查以下文件的一致性：
- docs/product/prd.md
- docs/architecture/specification.md
- docs/architecture/budgets.md
- docs/architecture/traceability.md
- hardware/BOM.md
- contracts/event.schema.json
- models/model-manifest.example.json

只报告：
1. 同一指标出现不同值；
2. 需求没有规格或验证；
3. 数据模式字段与文档字段不一致；
4. 物料清单中的选择不满足已声明约束；
5. 目标、估计和实测混写；
6. 待确认内容被当成确定事实。

每项必须给出文件和位置。不修改文件。

AI适合发现跨文件的候选矛盾，但最终仍要打开对应位置核查。第11章将把可以机械判断的一部分规则写成自动检查。

6.11 建立系统规格目录

本章结束时，仓库目录扩展为：

intelligent-sensing-terminal/
├─ README.md
├─ contracts/
│  ├─ event.schema.json
│  └─ examples/
│     └─ event.example.json
├─ docs/
│  ├─ product/
│  │  ├─ research-log.md
│  │  ├─ product-brief.md
│  │  └─ prd.md
│  └─ architecture/
│     ├─ context.md
│     ├─ specification.md
│     ├─ budgets.md
│     ├─ traceability.md
│     └─ decisions/
│        └─ ADR-0001-transport.md
├─ hardware/
│  └─ BOM.md
└─ models/
   └─ model-manifest.example.json

创建议题“建立智能感知终端系统规格基线”，从任务分支完成这些真实文件。不要把本章模板原样复制后不填写；每个字段应来自本组产品需求文档、课程硬件条件或明确的待验证项。

6.12 验证并提交规格基线

6.12.1 执行可自动完成的基础检查

python -m json.tool contracts/event.schema.json
python -m json.tool contracts/examples/event.example.json
python -m json.tool models/model-manifest.example.json
git diff --check

git diff --check可发现部分空白符错误。再进行人工检查：

[ ] 每个PR都有对应系统规格或明确待办
[ ] 系统边界和数据方向清楚
[ ] 三课程交付接口已经写明
[ ] 所有数字标明目标、估计或实测
[ ] 器件参数有原始来源和条件
[ ] 物料清单有价格与供货核查日期
[ ] 事件示例能够通过JSON语法检查
[ ] 数据模式与字段字典一致
[ ] 模型清单未填写虚假结果
[ ] 关键选择有技术决策记录

6.12.2 组织提交

可以按三个逻辑提交：

git add docs/architecture
git commit -m "docs(architecture): define system specification baseline"

git add contracts
git commit -m "feat(contract): define event message version 1"

git add hardware/BOM.md models/model-manifest.example.json
git commit -m "docs(integration): record hardware and model interfaces"

创建合并请求，邀请三门课程的相关成员分别从产品、数据模型和硬件原型角度评审。评审意见要指向需求、约束、接口或证据，不能只表达个人偏好。

合并后在GitLab建立后续议题：

• 建立最小设备事件输入；
• 实现事件接收接口；
• 验证EVENT-001契约；
• 显示最近事件；
• 形成v0.1发布检查。

这些议题进入v0.1 最小端云闭环里程碑。第7章选择最短依赖链依次实施。

6.13 本章小结

本章把产品定义转化为一组工程约束。其中包括系统边界、组件关系、需求追踪和资源预算。还包括物料清单、事件契约、模型构建物接口和技术决策记录。

AI参与候选调研和跨文件一致性检查。器件参数、供货状态、接口含义和性能数据仍需人工核查。Git使这些决策与产品版本共同演进。硬件、模型或场景变化后，团队可以定位受影响的规格与测试。

第7章将依据本章契约实现最小端云闭环。系统先用按键或可重复输入产生事件。待设备编码、网络传输和用户显示通过验证后，再接入传感器与模型。

6.14 综合实践

1. 从本组核心需求建立功能规格、非功能规格、实现责任和验证方法。用追踪表说明4项内容的关系。
2. 画出系统上下文图和组件图。每条连接标明数据、错误和版本信息，不画没有语义的箭头。
3. 为一个主控或传感器建立候选表和物料清单。关键参数追溯到原始数据手册或实际测量，并写明条件和核查日期。
4. 为端到端时延或内存建立预算。区分目标、估计与实测，并说明预算不足时怎样调整产品范围。
5. 定义一条事件数据模式和脱敏示例。邀请另一组依据契约编写接收检查，再记录双方产生分歧的位置。
6. 编写一份技术决策记录，比较两种真实候选方案。决定应包含获得的能力、承担的代价和重新评估条件。

6.15 拓展阅读

• JSON模式官方规范；
• 所选芯片、传感器和通信组件的原厂数据手册；
• arc42关于技术决策记录的说明。