Day 4 - 文档完善

现象：执行 dotnet run 失败。
可能原因：没有安装 .NET SDK，或者 SDK 版本太低。
处理办法：先执行 dotnet --version，确认版本是 8 或更高。

- [ ] 新增商品时，名称为空会显示错误提示。
- [ ] 搜索商品时，输入关键词后列表会变少。
- [ ] 关闭应用后重新打开，商品数据仍然存在。

- [ ] 功能正常。
- [ ] 体验良好。
- [ ] 质量不错。

README.md
docs/USER_GUIDE.md
docs/TROUBLESHOOTING.md
docs/RELEASE_CHECKLIST.md

# 商品管理应用
 
## 第三部分：跟着写文档
 
从这里开始动手。下面给出完整文档，可以直接放进项目里。
 
### 第 1 步：创建文档目录
 
在项目根目录创建：
 
```text
docs

README.md
docs/USER_GUIDE.md
docs/TROUBLESHOOTING.md
docs/RELEASE_CHECKLIST.md

# 商品管理应用
 
## 项目用途
 
这是一个本地桌面商品管理应用，用于练习 C#、Avalonia、MVVM、文件保存、搜索筛选、权限、导入导出、日志和发布流程。
 
应用支持：
 
- 查看商品列表。
- 新增商品。
- 编辑商品。
- 删除商品。
- 按关键词搜索商品。
- 保存商品数据到本地 JSON 文件。
- 导入和导出 CSV 文件。
- 记录关键操作日志。
 
## 运行环境
 
- .NET SDK 8 或更高版本。
- macOS、Windows 或 Linux。
- 能执行 `dotnet` 命令的终端。
 
## 启动步骤
 
1. 打开项目根目录。
2. 执行依赖还原：
 
   ```bash
   dotnet restore
   ```
 
3. 启动应用：
 
   ```bash
   dotnet run
   ```
 
4. 如果项目有多个 `.csproj` 文件，进入 Avalonia 应用所在目录后再执行 `dotnet run`。
 
## 常用命令
 
```bash
dotnet restore
dotnet build
dotnet run
dotnet test
dotnet publish -c Release
```
 
## 数据保存位置
 
商品数据保存到本地 JSON 文件。具体路径由代码里的仓储类决定，通常位于应用数据目录。
 
如果数据没有保存成功，请先检查：
 
- 应用是否有写入权限。
- JSON 文件是否被其他程序占用。
- 日志文件里是否有保存失败原因。
 
## 文档入口
 
- 用户操作说明：`docs/USER_GUIDE.md`
- 常见问题处理：`docs/TROUBLESHOOTING.md`
- 发布检查清单：`docs/RELEASE_CHECKLIST.md`

# 用户操作说明
 
## 打开应用
 
1. 启动商品管理应用。
2. 等待主窗口显示商品列表。
3. 如果列表为空，页面会显示“暂无商品”之类的提示。
 
## 新增商品
 
1. 找到商品名称输入框。
2. 输入商品名称，例如 `Keyboard`。
3. 输入价格，例如 `199`。
4. 输入库存，例如 `10`。
5. 点击“保存”。
6. 在商品列表里确认新增的商品出现。
 
## 编辑商品
 
1. 在商品列表中选中一个商品。
2. 修改名称、价格或库存。
3. 点击“保存”或“更新”。
4. 确认列表中的商品信息已经变化。
 
## 删除商品
 
1. 在商品列表中选中一个商品。
2. 点击“删除”。
3. 如果出现确认提示，确认要删除。
4. 确认商品从列表中消失。
 
## 搜索商品
 
1. 在搜索框输入关键词，例如 `key`。
2. 商品列表会只显示名称包含关键词的商品。
3. 清空搜索框后，列表恢复显示全部商品。
 
## 导入 CSV
 
1. 点击“导入”。
2. 选择 CSV 文件。
3. 等待导入完成提示。
4. 查看成功数量和失败数量。
 
CSV 建议格式：
 
```text
Id,Name,Price,Stock
1,Keyboard,199,10
2,Mouse,99,20
```
 
## 导出 CSV
 
1. 点击“导出”。
2. 选择保存位置。
3. 导出完成后，打开 CSV 文件确认内容。
 
## 常见输入规则
 
- 商品名称不能为空。
- 价格必须是大于 0 的数字。
- 库存必须是大于或等于 0 的整数。
- 删除商品前要先选中商品。

# 常见问题处理
 
## 执行 dotnet run 失败
 
### 现象
 
终端提示找不到 `dotnet`，或者提示 SDK 版本不匹配。
 
### 可能原因
 
- 没有安装 .NET SDK。
- 安装的是 Runtime，不是 SDK。
- SDK 版本低于项目要求。
 
### 处理办法
 
1. 执行：
 
   ```bash
   dotnet --version
   ```
 
2. 如果命令不存在，安装 .NET SDK。
3. 如果版本过低，升级到项目要求的版本。
4. 回到项目目录重新执行：
 
   ```bash
   dotnet restore
   dotnet run
   ```
 
## 保存数据失败
 
### 现象
 
点击保存后，界面提示保存失败，或者重新打开应用后数据消失。
 
### 可能原因
 
- 数据文件没有写入权限。
- 数据文件被其他程序占用。
- JSON 文件格式已经损坏。
 
### 处理办法
 
1. 关闭正在打开数据文件的编辑器。
2. 查看日志文件里的错误原因。
3. 检查数据目录是否允许当前用户写入。
4. 如果 JSON 文件损坏，先备份文件，再用空数组 `[]` 重建文件。
 
## CSV 导入失败
 
### 现象
 
导入后部分数据没有进入列表。
 
### 可能原因
 
- CSV 标题不正确。
- 价格不是数字。
- 库存不是整数。
- 商品名称为空。
 
### 处理办法
 
1. 确认 CSV 第一行是：
 
   ```text
   Id,Name,Price,Stock
   ```
 
2. 确认价格列都是数字。
3. 确认库存列都是整数。
4. 重新导入并查看失败数量。
 
## 删除按钮不可用
 
### 现象
 
删除按钮是灰色的，无法点击。
 
### 可能原因
 
没有选中商品，或者当前账号没有删除权限。
 
### 处理办法
 
1. 先在列表中选中商品。
2. 确认当前角色是否允许删除。
3. 如果仍然不可用，查看权限配置或日志。

# 发布检查清单
 
## 环境检查
 
- [ ] `dotnet --version` 能正常输出版本。
- [ ] `dotnet restore` 执行成功。
- [ ] `dotnet build` 执行成功。
- [ ] `dotnet test` 执行成功。
 
## 功能检查
 
- [ ] 新增商品成功后，列表出现新商品。
- [ ] 商品名称为空时，保存会显示错误提示。
- [ ] 价格小于等于 0 时，保存会显示错误提示。
- [ ] 库存小于 0 时，保存会显示错误提示。
- [ ] 编辑商品后，列表显示最新内容。
- [ ] 删除商品前需要选中商品。
- [ ] 搜索关键词后，列表会过滤。
- [ ] 清空搜索后，列表恢复。
 
## 数据检查
 
- [ ] 关闭应用后重新打开，商品数据仍然存在。
- [ ] JSON 文件损坏时，应用能给出可理解的错误提示。
- [ ] CSV 导入能显示成功数量和失败数量。
- [ ] CSV 导出后，文件能被表格软件打开。
 
## 发布检查
 
- [ ] `dotnet publish -c Release` 执行成功。
- [ ] 发布目录里有可执行文件。
- [ ] README、用户手册、排错文档已更新。
- [ ] CHANGELOG 已写清本次变化。
- [ ] 已知问题已经记录。

这不是最终文档，但已经有三个关键点：项目用途、运行环境、启动步骤。

## 文档常用操作速查

| 需求 | 文件 | 必须包含 |
| --- | --- | --- |
| 项目入口 | `README.md` | 项目用途、环境、启动命令、数据位置 |
| 用户操作 | `docs/USER_GUIDE.md` | 新增、编辑、删除、搜索、导入导出 |
| 排错说明 | `docs/TROUBLESHOOTING.md` | 现象、可能原因、处理办法 |
| 发布检查 | `docs/RELEASE_CHECKLIST.md` | 环境、功能、数据、发布目录 |
| 版本变化 | `CHANGELOG.md` | 新增、修复、文档、已知问题 |
| 已知问题 | `docs/KNOWN_ISSUES.md` | 影响、临时处理、后续计划 |

## 常见错误和修法

| 错误 | 为什么错 | 修法 |
| --- | --- | --- |
| README 只写项目名 | 接手的人不知道怎么运行 | 补环境、恢复依赖、启动命令 |
| 用户手册写太多代码 | 使用者不关心实现细节 | 按界面操作步骤写 |
| 排错文档只写“重试” | 没有定位方向 | 写清现象、可能原因、处理办法 |
| 数据路径没写 | 换电脑后不知道文件在哪里 | 在 README 和排错文档里写路径 |
| 检查清单没有结果 | 发布前无法证明检查过 | 每项写通过、失败、备注 |

## 小白重复敲写训练

文档日仍然要敲代码：练公开 API 注释、启动命令和最小示例。

### 训练 1：给公开方法写 XML 注释

```csharp
/// <summary>
/// 根据单价和数量计算总价。
/// </summary>
/// <param name="price">单价，必须大于等于 0。</param>
/// <param name="count">数量，必须大于等于 0。</param>
/// <returns>计算后的总价。</returns>
public decimal CalculateTotal(decimal price, int count)
{
    return price * count;
}

dotnet restore
dotnet build
dotnet run --project src/ProductManager.App
dotnet test

var service = new ProductService(repository);
service.Create("Keyboard", 199m, 5);
 
foreach (Product product in service.GetAll())
{
    Console.WriteLine(product.Name);
}

1. 写清项目入口文档 `README.md`
2. 写清用户操作文档 `USER_GUIDE.md`
3. 写清排错文档 `TROUBLESHOOTING.md`

1. 解压 Hmi.App-win-x64.zip
2. 打开 appsettings.json 设置设备 IP
3. 双击 Hmi.App.exe
4. 首次启动确认日志目录已生成

没有开发环境也能按步骤启动

开始采集: 首页 -> 开始采集
停止采集: 首页 -> 停止 -> 确认
确认报警: 报警页 -> 选择记录 -> 确认
导出报警: 报警页 -> 导出 CSV

常用动作有明确路径

现象 | 检查 | 处理
设备离线 | 网线、IP、端口 | 修正后点击重连
无实时值 | 点位地址、采集状态 | 修正配置并重启采集
程序打不开 | crash.log | 将日志交给维护人员

常见故障有检查顺序

# 更新记录
 
## 1.0.0
 
发布日期：待定
 
### 新增
 
- 新增商品列表。
- 新增商品创建、编辑、删除功能。
- 新增商品搜索和筛选功能。
- 新增 JSON 本地保存。
- 新增 CSV 导入和导出。
- 新增操作日志。
- 新增角色权限判断。
- 新增发布检查清单。
 
### 修复
 
- 修复商品名称为空时仍可保存的问题。
- 修复价格为 0 时提示不清楚的问题。
- 修复保存中重复点击导致重复提交的问题。
 
### 文档
 
- 新增 README。
- 新增用户操作说明。
- 新增常见问题处理。
- 新增已知问题记录。

# 已知问题
 
## 1. CSV 导入失败时暂时只显示失败数量
 
### 影响
 
用户能知道有多少行失败，但不能直接看到每一行失败的详细原因。
 
### 临时处理
 
导入失败后，先检查 CSV 标题、价格列、库存列和空名称。
 
### 后续计划
 
在导入结果中显示失败行号和失败原因。
 
## 2. 当前数据保存在本地文件
 
### 影响
 
多台电脑之间不会自动同步数据。
 
### 临时处理
 
需要迁移数据时，手动复制 JSON 数据文件。
 
### 后续计划
 
后续可以接入数据库或接口服务。
 
## 3. 删除商品后暂时不能一键撤销
 
### 影响
 
误删后需要重新新增商品。
 
### 临时处理
 
删除前确认选中的商品是否正确。
 
### 后续计划
 
后续增加删除确认和撤销功能。