Day 1 - 项目范围与需求

本次做什么。
本次不做什么。

只保留最少功能，但这些功能必须能完整解决一个真实问题。

作为某类使用者，我想做某件事，这样我能得到某个结果。

作为使用者，我想搜索商品，这样我能快速找到目标商品。

能新增商品。

1. 输入合法名称、价格、库存后能新增。
2. 名称为空时不能新增，并显示提示。
3. 价格小于或等于 0 时不能新增，并显示提示。
4. 库存小于 0 时不能新增，并显示提示。

Name、Price、Stock、CreatedAt、UpdatedAt

public string Name { get; set; } = "";
public decimal Price { get; set; }
public int Stock { get; set; }
public DateTime CreatedAt { get; set; }
public DateTime UpdatedAt { get; set; }

商品名称不能为空。
商品价格必须大于 0。
库存必须大于或等于 0。

名称为空 -> 返回失败
价格 <= 0 -> 返回失败
库存 < 0 -> 返回失败

目标
-> 使用者
-> MVP 范围
-> 字段
-> 业务规则
-> 页面
-> 验收标准

product-mvp-requirements.md

# 商品管理 MVP 需求文档
 
## 第三部分：跟着写需求文档
 
从这里开始动手。新建一个文件：
 
```text
product-mvp-requirements.md

## 1. 项目目标
 
做一个桌面端商品管理工具，帮助用户维护一份本地商品清单。
 
第一版只解决本地商品的新增、查看、编辑、删除、搜索和保存，不做账号系统，不做云同步。

## 2. 使用者
 
使用者是需要维护商品清单的人。
 
他要完成的事情：
1. 查看当前有哪些商品。
2. 新增一个商品。
3. 修改商品名称、价格和库存。
4. 删除录入错误的商品。
5. 按关键字搜索商品。
6. 关闭程序后，下次打开还能看到上次保存的数据。

## 3. 第一版范围
 
第一版包含：
1. 商品列表。
2. 新增商品。
3. 编辑商品。
4. 删除商品。
5. 关键字搜索。
6. JSON 本地保存。
7. JSON 本地读取。
8. 输入错误提示。

## 4. 第一版暂不包含
 
第一版不做：
1. 登录。
2. 多用户。
3. 云同步。
4. 图片上传。
5. 条形码扫描。
6. 复杂报表。
7. 权限管理。
8. 自动更新。

## 5. 商品字段
 
| 字段 | 类型 | 必填 | 规则 |
| --- | --- | --- | --- |
| Id | Guid | 是 | 新增时自动生成 |
| Name | string | 是 | 不能为空，最多 50 个字符 |
| Price | decimal | 是 | 必须大于 0 |
| Stock | int | 是 | 必须大于或等于 0 |
| CreatedAt | DateTime | 是 | 新增时自动记录 |
| UpdatedAt | DateTime | 是 | 新增和编辑时更新 |

## 6. 页面清单
 
| 页面 | 作用 |
| --- | --- |
| 商品列表页 | 显示商品列表、搜索框、新增按钮 |
| 商品编辑区 | 输入名称、价格、库存 |
| 状态提示区 | 显示保存成功、校验失败、读取失败 |

## 8. 业务规则
 
1. 商品名称不能为空。
2. 商品名称最多 50 个字符。
3. 商品价格必须大于 0。
4. 商品库存必须大于或等于 0。
5. 新增商品时自动生成 Id。
6. 新增商品时自动设置 CreatedAt 和 UpdatedAt。
7. 编辑商品时只更新 Name、Price、Stock、UpdatedAt。
8. 删除商品前必须先选中一条商品。
9. 搜索时匹配商品名称。
10. 搜索关键字为空时显示全部商品。

## 9. 验收标准
 
### 新增商品
 
1. 输入合法名称、价格、库存后能新增。
2. 名称为空时不能新增，并显示提示。
3. 价格小于或等于 0 时不能新增，并显示提示。
4. 库存小于 0 时不能新增，并显示提示。

## 10. 完成定义
 
满足以下条件，第一版才算完成：
 
1. 第一版范围里的功能全部能跑。
2. 验收标准全部通过。
3. 错误输入有提示。
4. 数据能保存和读取。
5. 发布后从发布目录启动仍然能使用。

这份文档不是摆设。后面几天会直接按照它来写：

- Day 2：根据商品字段写数据模型和存储。
- Day 3：根据业务规则写服务层。
- Day 4：根据页面清单写主列表。
- Day 5：根据编辑验收标准写详情和编辑。
- Day 6：根据搜索验收标准写过滤。

## 常见错误和修法

| 错误 | 为什么错 | 修法 |
| --- | --- | --- |
| 需求只写“做商品管理” | 范围太大，后面不知道先做什么 | 拆成新增、编辑、删除、搜索、保存这些具体功能 |
| 字段没有类型 | 后面模型和表单无法落地 | 每个字段写清 `string`、`decimal`、`int`、`DateTime` |
| 规则只写一句“校验输入” | 不知道哪些输入算非法 | 写清空值、长度、数字范围、重复数据 |
| MVP 放太多功能 | 第一版做不完，项目容易失控 | 先保留最小闭环，其他放到后续版本 |
| 验收标准不具体 | 做完无法判断是否通过 | 写清操作、输入、期望结果 |

## 小白重复敲写训练

需求要立刻转成可运行的小模型和规则。

### 训练 1：写最小商品模型

```csharp
public class Product
{
    public Guid Id { get; set; } = Guid.NewGuid();
    public string Name { get; set; } = "";
    public decimal Price { get; set; }
    public int Stock { get; set; }
}

bool CanSave(Product product)
{
    return !string.IsNullOrWhiteSpace(product.Name)
        && product.Price >= 0
        && product.Stock >= 0;
}

[Fact]
public void CanSave_EmptyName_ReturnsFalse()
{
    var product = new Product { Name = "", Price = 10m, Stock = 1 };
    Assert.False(CanSave(product));
}

1. 为什么项目要先写范围
2. 什么是 MVP
3. 什么是用户故事

作为现场操作员
我想看到所有设备的在线状态和实时温度
以便及时发现停机与高温

明确了谁、要什么、为什么

必须完成:
- 设备总览
- 实时点位
- 报警确认
- 配置保存

暂不完成:
- 云端同步
- 手机 App

项目边界清楚

场景: PLC-01 温度达到 80 C
当: 新采集值为 82 C
那么: 2 秒内显示高温报警
并且: 报警日志记录设备、时间和值

需求可以被实际测试

# 商品管理 MVP 需求文档
 
## 1. 项目目标
 
做一个桌面端商品管理工具，帮助用户维护一份本地商品清单。
 
第一版只解决本地商品的新增、查看、编辑、删除、搜索和保存，不做账号系统，不做云同步。
 
## 2. 使用者
 
使用者是需要维护商品清单的人。
 
他要完成的事情：
1. 查看当前有哪些商品。
2. 新增一个商品。
3. 修改商品名称、价格和库存。
4. 删除录入错误的商品。
5. 按关键字搜索商品。
6. 关闭程序后，下次打开还能看到上次保存的数据。
 
## 3. 第一版范围
 
第一版包含：
1. 商品列表。
2. 新增商品。
3. 编辑商品。
4. 删除商品。
5. 关键字搜索。
6. JSON 本地保存。
7. JSON 本地读取。
8. 输入错误提示。
 
## 4. 第一版暂不包含
 
第一版不做：
1. 登录。
2. 多用户。
3. 云同步。
4. 图片上传。
5. 条形码扫描。
6. 复杂报表。
7. 权限管理。
8. 自动更新。
 
## 5. 商品字段
 
| 字段 | 类型 | 必填 | 规则 |
| --- | --- | --- | --- |
| Id | Guid | 是 | 新增时自动生成 |
| Name | string | 是 | 不能为空，最多 50 个字符 |
| Price | decimal | 是 | 必须大于 0 |
| Stock | int | 是 | 必须大于或等于 0 |
| CreatedAt | DateTime | 是 | 新增时自动记录 |
| UpdatedAt | DateTime | 是 | 新增和编辑时更新 |
 
## 6. 页面清单
 
| 页面 | 作用 |
| --- | --- |
| 商品列表页 | 显示商品列表、搜索框、新增按钮 |
| 商品编辑区 | 输入名称、价格、库存 |
| 状态提示区 | 显示保存成功、校验失败、读取失败 |
 
## 7. 用户故事
 
1. 作为使用者，我想查看商品列表，这样我能知道当前有哪些商品。
2. 作为使用者，我想新增商品，这样我能把新商品录入系统。
3. 作为使用者，我想编辑商品，这样我能修正名称、价格或库存。
4. 作为使用者，我想删除商品，这样我能移除录入错误的数据。
5. 作为使用者，我想搜索商品，这样我能快速找到目标商品。
6. 作为使用者，我想保存数据，这样关闭程序后数据不会丢失。
 
## 8. 业务规则
 
1. 商品名称不能为空。
2. 商品名称最多 50 个字符。
3. 商品价格必须大于 0。
4. 商品库存必须大于或等于 0。
5. 新增商品时自动生成 Id。
6. 新增商品时自动设置 CreatedAt 和 UpdatedAt。
7. 编辑商品时只更新 Name、Price、Stock、UpdatedAt。
8. 删除商品前必须先选中一条商品。
9. 搜索时匹配商品名称。
10. 搜索关键字为空时显示全部商品。
 
## 9. 验收标准
 
### 商品列表
 
1. 启动后能看到商品列表区域。
2. 没有商品时显示空列表，不崩溃。
3. 有商品时能显示名称、价格、库存。
 
### 新增商品
 
1. 输入合法名称、价格、库存后能新增。
2. 名称为空时不能新增，并显示提示。
3. 价格小于或等于 0 时不能新增，并显示提示。
4. 库存小于 0 时不能新增，并显示提示。
 
### 编辑商品
 
1. 选中商品后，编辑区显示商品信息。
2. 修改合法内容后能保存。
3. 保存后列表同步更新。
 
### 删除商品
 
1. 选中商品后可以删除。
2. 没有选中商品时不能删除，并显示提示。
 
### 搜索商品
 
1. 输入关键字后只显示匹配商品。
2. 关键字为空时显示全部商品。
3. 没有匹配结果时显示空列表，不崩溃。
 
### 本地保存
 
1. 点击保存后生成 JSON 文件。
2. 关闭程序再打开，能读取上次保存的数据。
3. JSON 文件损坏时显示读取失败提示。
 
## 10. 完成定义
 
满足以下条件，第一版才算完成：
 
1. 第一版范围里的功能全部能跑。
2. 验收标准全部通过。
3. 错误输入有提示。
4. 数据能保存和读取。
5. 发布后从发布目录启动仍然能使用。