✨ feat: 完成aide decide设计文档
This commit is contained in:
@@ -1,5 +1,16 @@
|
|||||||
# aide decide 子命令设计文档
|
# aide decide 子命令设计文档
|
||||||
|
|
||||||
|
## 零、详细设计文档包
|
||||||
|
|
||||||
|
本文档为概览设计；更细的实现交接规格见：
|
||||||
|
|
||||||
|
- [aide-program/docs/commands/decide/README.md](decide/README.md)
|
||||||
|
- [aide-program/docs/commands/decide/cli.md](decide/cli.md)
|
||||||
|
- [aide-program/docs/commands/decide/server.md](decide/server.md)
|
||||||
|
- [aide-program/docs/commands/decide/web.md](decide/web.md)
|
||||||
|
- [aide-program/docs/commands/decide/storage.md](decide/storage.md)
|
||||||
|
- [aide-program/docs/commands/decide/verification.md](decide/verification.md)
|
||||||
|
|
||||||
## 一、背景
|
## 一、背景
|
||||||
|
|
||||||
### 1.1 解决的问题
|
### 1.1 解决的问题
|
||||||
|
|||||||
225
aide-program/docs/commands/decide/README.md
Normal file
225
aide-program/docs/commands/decide/README.md
Normal file
@@ -0,0 +1,225 @@
|
|||||||
|
# aide decide 详细设计（实现交接包）
|
||||||
|
|
||||||
|
本目录为 `aide decide` 子命令的**详细设计**。目标是让接手开发者在不阅读额外上下文的情况下，能够依据本文档集完成实现、联调与验证。
|
||||||
|
|
||||||
|
实现位置：
|
||||||
|
- 核心实现：`aide-program/aide/decide/`
|
||||||
|
- CLI 入口：`aide-program/aide/main.py` 的 `aide decide ...` 子命令树
|
||||||
|
|
||||||
|
上游/关联文档：
|
||||||
|
- 概览设计：[`aide-program/docs/commands/decide.md`](../decide.md)
|
||||||
|
- 数据格式规范（输入/输出格式）：[`aide-program/docs/formats/data.md`](../../formats/data.md)
|
||||||
|
- 配置格式规范：[`aide-program/docs/formats/config.md`](../../formats/config.md)
|
||||||
|
- 插件侧调用契约：[`/aide:prep`](../../../../aide-marketplace/aide-plugin/docs/commands/prep.md)
|
||||||
|
|
||||||
|
## 一、范围与目标
|
||||||
|
|
||||||
|
### 1.1 目标
|
||||||
|
|
||||||
|
- 提供**程序化的待定项确认机制**，替代终端中的逐项文本确认
|
||||||
|
- 以 Web 界面呈现待定项，支持选项选择与备注添加
|
||||||
|
- 存储决策记录，支持历史追溯
|
||||||
|
- 遵循"静默即成功"的输出原则
|
||||||
|
|
||||||
|
### 1.2 非目标
|
||||||
|
|
||||||
|
- 不分析待定项内容（这是 LLM 的职责）
|
||||||
|
- 不做决策建议或推荐排序
|
||||||
|
- 不修改业务代码
|
||||||
|
- 不实现复杂的用户认证或多用户支持
|
||||||
|
|
||||||
|
## 二、关键约定（必须先统一）
|
||||||
|
|
||||||
|
1. **技术选型**：
|
||||||
|
- HTTP 服务：使用 Python 标准库 `http.server`，无需额外依赖
|
||||||
|
- Web 前端：使用纯 HTML/CSS/JavaScript，无需构建工具，直接嵌入 Python 代码或作为静态资源
|
||||||
|
|
||||||
|
2. **服务生命周期**：
|
||||||
|
- `aide decide '<json>'` 启动服务并阻塞等待
|
||||||
|
- 用户在 Web 界面提交决策后，服务自动关闭
|
||||||
|
- 服务关闭后，LLM 调用 `aide decide result` 获取结果
|
||||||
|
|
||||||
|
3. **端口配置**：
|
||||||
|
- 默认端口：3721
|
||||||
|
- 端口被占用时：尝试下一个端口（3722、3723...），最多尝试 10 次
|
||||||
|
- 可通过配置文件 `decide.port` 指定固定端口
|
||||||
|
|
||||||
|
4. **数据存储**：
|
||||||
|
- 待处理数据：`.aide/decisions/pending.json`
|
||||||
|
- 历史记录：`.aide/decisions/{timestamp}.json`
|
||||||
|
- `.aide/` 默认被 gitignore
|
||||||
|
|
||||||
|
5. **超时策略**：
|
||||||
|
- 默认无超时（等待用户操作）
|
||||||
|
- 可通过配置 `decide.timeout` 设置超时时间（秒）
|
||||||
|
- 超时后服务关闭，`aide decide result` 返回错误
|
||||||
|
|
||||||
|
## 三、文档索引（按实现模块拆分）
|
||||||
|
|
||||||
|
| 文档 | 内容 |
|
||||||
|
|------|------|
|
||||||
|
| [cli.md](cli.md) | CLI 命令规格、参数校验、输出规范 |
|
||||||
|
| [server.md](server.md) | HTTP 服务设计、API 端点、生命周期管理 |
|
||||||
|
| [web.md](web.md) | Web 前端设计、组件结构、交互流程 |
|
||||||
|
| [storage.md](storage.md) | 数据存储设计、文件格式、生命周期 |
|
||||||
|
| [verification.md](verification.md) | 验证清单（实现完成后的自检） |
|
||||||
|
|
||||||
|
## 四、推荐实现模块划分（仅文件/职责约定）
|
||||||
|
|
||||||
|
实现位于 `aide-program/aide/decide/`，按职责拆分为：
|
||||||
|
|
||||||
|
```
|
||||||
|
aide/decide/
|
||||||
|
├── __init__.py # 模块导出
|
||||||
|
├── types.py # 数据类型定义（DecideInput, DecideOutput 等）
|
||||||
|
├── storage.py # 数据存储（pending.json 读写、历史记录）
|
||||||
|
├── server.py # HTTP 服务器（启动、路由、关闭）
|
||||||
|
├── handlers.py # API 请求处理器
|
||||||
|
└── web/ # 静态资源目录
|
||||||
|
├── index.html # 主页面
|
||||||
|
├── style.css # 样式
|
||||||
|
└── app.js # 交互逻辑
|
||||||
|
```
|
||||||
|
|
||||||
|
各模块职责：
|
||||||
|
|
||||||
|
- `types`：定义数据结构，与 `aide-program/docs/formats/data.md` 保持一致
|
||||||
|
- `storage`：负责 pending.json 和历史记录的读写、清理
|
||||||
|
- `server`：HTTP 服务器生命周期管理、端口探测、静态资源服务
|
||||||
|
- `handlers`：处理 API 请求（获取待定项、提交决策）
|
||||||
|
- `web/`：纯静态前端资源，由 server 提供服务
|
||||||
|
|
||||||
|
> 注：本文档只约定职责与接口，不提供实现代码。
|
||||||
|
|
||||||
|
## 五、实现任务拆分（建议顺序）
|
||||||
|
|
||||||
|
### 阶段1：基础设施
|
||||||
|
|
||||||
|
1. 创建 `aide/decide/` 目录结构
|
||||||
|
2. 实现 `types.py`：定义 DecideInput、DecideItem、Option、DecideOutput、Decision 等数据类型
|
||||||
|
3. 实现 `storage.py`：pending.json 读写、历史记录保存
|
||||||
|
|
||||||
|
### 阶段2：CLI 入口
|
||||||
|
|
||||||
|
4. 在 `main.py` 添加 `aide decide` 子命令路由
|
||||||
|
5. 实现 JSON 解析与验证逻辑
|
||||||
|
6. 实现 `aide decide result` 命令
|
||||||
|
|
||||||
|
### 阶段3：HTTP 服务
|
||||||
|
|
||||||
|
7. 实现 `server.py`：HTTP 服务器基础框架
|
||||||
|
8. 实现端口探测逻辑
|
||||||
|
9. 实现 `handlers.py`：API 端点处理
|
||||||
|
10. 实现服务生命周期管理（启动、等待、关闭）
|
||||||
|
|
||||||
|
### 阶段4：Web 前端
|
||||||
|
|
||||||
|
11. 创建 `web/index.html`：页面结构
|
||||||
|
12. 创建 `web/style.css`：样式设计
|
||||||
|
13. 创建 `web/app.js`：交互逻辑（加载数据、选择选项、提交决策）
|
||||||
|
|
||||||
|
### 阶段5：集成与验证
|
||||||
|
|
||||||
|
14. 端到端测试：完整流程验证
|
||||||
|
15. 按 `verification.md` 逐项检查
|
||||||
|
|
||||||
|
### 依赖关系
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
[阶段1: 基础设施] as P1
|
||||||
|
[阶段2: CLI入口] as P2
|
||||||
|
[阶段3: HTTP服务] as P3
|
||||||
|
[阶段4: Web前端] as P4
|
||||||
|
[阶段5: 集成验证] as P5
|
||||||
|
|
||||||
|
P1 --> P2
|
||||||
|
P1 --> P3
|
||||||
|
P2 --> P3
|
||||||
|
P3 --> P4
|
||||||
|
P1 --> P5
|
||||||
|
P2 --> P5
|
||||||
|
P3 --> P5
|
||||||
|
P4 --> P5
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
## 六、整体业务流程
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
participant LLM
|
||||||
|
participant "aide decide" as CLI
|
||||||
|
participant "HTTP Server" as Server
|
||||||
|
participant "Web Browser" as Browser
|
||||||
|
participant User
|
||||||
|
|
||||||
|
== 提交待定项 ==
|
||||||
|
LLM -> CLI : aide decide '<json>'
|
||||||
|
CLI -> CLI : 解析并验证 JSON
|
||||||
|
CLI -> CLI : 保存到 pending.json
|
||||||
|
CLI -> Server : 启动 HTTP 服务
|
||||||
|
CLI --> LLM : 输出访问链接
|
||||||
|
note right: → Web 服务已启动\n→ 请访问: http://localhost:3721\n→ 等待用户完成决策...
|
||||||
|
|
||||||
|
== 用户操作 ==
|
||||||
|
LLM -> User : 告知访问链接
|
||||||
|
User -> Browser : 打开链接
|
||||||
|
Browser -> Server : GET /
|
||||||
|
Server --> Browser : 返回 index.html
|
||||||
|
Browser -> Server : GET /api/items
|
||||||
|
Server --> Browser : 返回待定项数据
|
||||||
|
Browser -> User : 渲染界面
|
||||||
|
User -> Browser : 选择选项、添加备注
|
||||||
|
User -> Browser : 点击提交
|
||||||
|
Browser -> Server : POST /api/submit
|
||||||
|
Server -> Server : 保存决策结果
|
||||||
|
Server --> Browser : 返回成功
|
||||||
|
Server -> Server : 关闭服务
|
||||||
|
|
||||||
|
== 获取结果 ==
|
||||||
|
CLI --> LLM : 服务已关闭
|
||||||
|
LLM -> CLI : aide decide result
|
||||||
|
CLI -> CLI : 读取最新决策
|
||||||
|
CLI --> LLM : 返回 JSON 结果
|
||||||
|
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
## 七、风险与待定项（需要开发前确认）
|
||||||
|
|
||||||
|
### 7.1 需要确认的设计决策
|
||||||
|
|
||||||
|
| 问题 | 建议方案 | 备选方案 |
|
||||||
|
|------|----------|----------|
|
||||||
|
| 前端是否需要支持移动端 | 否，仅支持桌面浏览器 | 响应式设计 |
|
||||||
|
| 是否支持多个待定项会话并行 | 否，同一时间只能有一个 pending | 支持多会话 |
|
||||||
|
| 服务启动后是否自动打开浏览器 | 否，仅输出链接 | 使用 webbrowser 模块自动打开 |
|
||||||
|
|
||||||
|
### 7.2 潜在风险
|
||||||
|
|
||||||
|
| 风险 | 影响 | 缓解措施 |
|
||||||
|
|------|------|----------|
|
||||||
|
| 端口被占用 | 服务无法启动 | 自动尝试下一个端口 |
|
||||||
|
| 用户长时间不操作 | 服务一直阻塞 | 可配置超时时间 |
|
||||||
|
| 浏览器兼容性 | 界面显示异常 | 使用标准 HTML/CSS/JS，避免新特性 |
|
||||||
|
| JSON 数据过大 | 解析/传输慢 | 限制 items 数量（建议 ≤50） |
|
||||||
|
|
||||||
|
### 7.3 后续优化方向（不在本次实现范围）
|
||||||
|
|
||||||
|
- 支持键盘快捷键操作
|
||||||
|
- 支持决策历史查看
|
||||||
|
- 支持决策导出（Markdown/PDF）
|
||||||
|
- 支持自定义主题
|
||||||
|
|
||||||
|
## 八、相关文档
|
||||||
|
|
||||||
|
- [program 导览](../../README.md)
|
||||||
|
- [decide 概览设计](../decide.md)
|
||||||
|
- [数据格式文档](../../formats/data.md)
|
||||||
|
- [配置格式文档](../../formats/config.md)
|
||||||
|
- [aide skill 设计文档](../../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
|
||||||
365
aide-program/docs/commands/decide/cli.md
Normal file
365
aide-program/docs/commands/decide/cli.md
Normal file
@@ -0,0 +1,365 @@
|
|||||||
|
# aide decide CLI 规格
|
||||||
|
|
||||||
|
## 一、命令一览
|
||||||
|
|
||||||
|
`aide decide` 提供两个子命令：
|
||||||
|
|
||||||
|
| 子命令 | 语法（API 约定） | 成功输出 | 主要用途 |
|
||||||
|
|--------|------------------|----------|----------|
|
||||||
|
| (默认) | `aide decide '<json>'` | 输出访问链接，阻塞等待 | 提交待定项数据并启动 Web 服务 |
|
||||||
|
| result | `aide decide result` | 输出 JSON 结果 | 获取用户决策结果 |
|
||||||
|
|
||||||
|
## 二、命令详细规格
|
||||||
|
|
||||||
|
### 2.1 aide decide（提交数据并启动服务）
|
||||||
|
|
||||||
|
**语法**：
|
||||||
|
|
||||||
|
```
|
||||||
|
aide decide '<json_data>'
|
||||||
|
```
|
||||||
|
|
||||||
|
**参数**：
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| `<json_data>` | string | 是 | 待定项 JSON 数据，需用引号包裹 |
|
||||||
|
|
||||||
|
**输入数据格式**：
|
||||||
|
|
||||||
|
见 `aide-program/docs/formats/data.md` 的"待定项数据格式"章节。
|
||||||
|
|
||||||
|
**成功输出**：
|
||||||
|
|
||||||
|
```
|
||||||
|
→ Web 服务已启动
|
||||||
|
→ 请访问: http://localhost:3721
|
||||||
|
→ 等待用户完成决策...
|
||||||
|
```
|
||||||
|
|
||||||
|
服务关闭后：
|
||||||
|
|
||||||
|
```
|
||||||
|
✓ 决策已完成
|
||||||
|
```
|
||||||
|
|
||||||
|
**错误输出**：
|
||||||
|
|
||||||
|
```
|
||||||
|
✗ JSON 解析失败: <具体错误>
|
||||||
|
建议: 检查 JSON 格式是否正确
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
✗ 数据验证失败: <具体错误>
|
||||||
|
建议: 检查必填字段是否完整
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
✗ 无法启动服务: 端口 3721-3730 均被占用
|
||||||
|
建议: 关闭占用端口的程序，或在配置中指定其他端口
|
||||||
|
```
|
||||||
|
|
||||||
|
**行为流程**：
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
start
|
||||||
|
|
||||||
|
:接收 JSON 参数;
|
||||||
|
|
||||||
|
:解析 JSON;
|
||||||
|
if (解析成功?) then (是)
|
||||||
|
else (否)
|
||||||
|
:输出错误: JSON 解析失败;
|
||||||
|
stop
|
||||||
|
endif
|
||||||
|
|
||||||
|
:验证数据格式;
|
||||||
|
if (验证通过?) then (是)
|
||||||
|
else (否)
|
||||||
|
:输出错误: 数据验证失败;
|
||||||
|
stop
|
||||||
|
endif
|
||||||
|
|
||||||
|
:保存到 pending.json;
|
||||||
|
|
||||||
|
:探测可用端口;
|
||||||
|
if (找到可用端口?) then (是)
|
||||||
|
else (否)
|
||||||
|
:输出错误: 端口均被占用;
|
||||||
|
stop
|
||||||
|
endif
|
||||||
|
|
||||||
|
:启动 HTTP 服务;
|
||||||
|
|
||||||
|
:输出访问链接;
|
||||||
|
|
||||||
|
:阻塞等待用户操作;
|
||||||
|
|
||||||
|
:用户提交决策;
|
||||||
|
|
||||||
|
:保存决策结果;
|
||||||
|
|
||||||
|
:关闭服务;
|
||||||
|
|
||||||
|
:输出: 决策已完成;
|
||||||
|
|
||||||
|
stop
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 aide decide result（获取决策结果）
|
||||||
|
|
||||||
|
**语法**：
|
||||||
|
|
||||||
|
```
|
||||||
|
aide decide result
|
||||||
|
```
|
||||||
|
|
||||||
|
**参数**：无
|
||||||
|
|
||||||
|
**成功输出**：
|
||||||
|
|
||||||
|
直接输出 JSON 格式的决策结果（便于 LLM 解析）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"decisions": [
|
||||||
|
{"id": 1, "chosen": "option_a"},
|
||||||
|
{"id": 2, "chosen": "option_b", "note": "用户的补充说明"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**错误输出**：
|
||||||
|
|
||||||
|
```
|
||||||
|
✗ 尚无决策结果
|
||||||
|
建议: 请等待用户在 Web 界面完成操作
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
✗ 未找到待定项数据
|
||||||
|
建议: 请先执行 aide decide '<json>'
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
✗ 决策结果已过期
|
||||||
|
建议: 请重新执行 aide decide '<json>'
|
||||||
|
```
|
||||||
|
|
||||||
|
**行为流程**：
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
start
|
||||||
|
|
||||||
|
:检查 pending.json 是否存在;
|
||||||
|
if (存在?) then (是)
|
||||||
|
else (否)
|
||||||
|
:输出错误: 未找到待定项数据;
|
||||||
|
stop
|
||||||
|
endif
|
||||||
|
|
||||||
|
:查找最新决策记录;
|
||||||
|
if (存在决策记录?) then (是)
|
||||||
|
else (否)
|
||||||
|
:输出错误: 尚无决策结果;
|
||||||
|
stop
|
||||||
|
endif
|
||||||
|
|
||||||
|
:验证决策记录与 pending 匹配;
|
||||||
|
if (匹配?) then (是)
|
||||||
|
else (否)
|
||||||
|
:输出错误: 决策结果已过期;
|
||||||
|
stop
|
||||||
|
endif
|
||||||
|
|
||||||
|
:输出 JSON 结果;
|
||||||
|
|
||||||
|
stop
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
## 三、参数校验规则
|
||||||
|
|
||||||
|
### 3.1 JSON 数据校验
|
||||||
|
|
||||||
|
**必填字段**：
|
||||||
|
|
||||||
|
| 字段 | 类型 | 校验规则 |
|
||||||
|
|------|------|----------|
|
||||||
|
| `task` | string | 非空字符串 |
|
||||||
|
| `source` | string | 非空字符串 |
|
||||||
|
| `items` | array | 非空数组，至少包含 1 个待定项 |
|
||||||
|
|
||||||
|
**待定项（DecideItem）校验**：
|
||||||
|
|
||||||
|
| 字段 | 类型 | 校验规则 |
|
||||||
|
|------|------|----------|
|
||||||
|
| `id` | number | 正整数，在 items 中唯一 |
|
||||||
|
| `title` | string | 非空字符串 |
|
||||||
|
| `options` | array | 非空数组，至少包含 2 个选项 |
|
||||||
|
|
||||||
|
**选项（Option）校验**：
|
||||||
|
|
||||||
|
| 字段 | 类型 | 校验规则 |
|
||||||
|
|------|------|----------|
|
||||||
|
| `value` | string | 非空字符串，在同一 item 的 options 中唯一 |
|
||||||
|
| `label` | string | 非空字符串 |
|
||||||
|
|
||||||
|
**可选字段**：
|
||||||
|
|
||||||
|
| 字段 | 类型 | 默认值 |
|
||||||
|
|------|------|--------|
|
||||||
|
| `location` | object | null |
|
||||||
|
| `context` | string | null |
|
||||||
|
| `recommend` | string | null（若提供，必须是 options 中某个 value） |
|
||||||
|
| `score` | number | null（若提供，范围 0-100） |
|
||||||
|
| `pros` | array | null |
|
||||||
|
| `cons` | array | null |
|
||||||
|
|
||||||
|
### 3.2 校验错误信息
|
||||||
|
|
||||||
|
校验失败时，错误信息应明确指出：
|
||||||
|
|
||||||
|
1. 哪个字段出错
|
||||||
|
2. 期望的格式/值
|
||||||
|
3. 实际收到的值（如适用）
|
||||||
|
|
||||||
|
**示例**：
|
||||||
|
|
||||||
|
```
|
||||||
|
✗ 数据验证失败: items[0].options 至少需要 2 个选项，当前只有 1 个
|
||||||
|
建议: 为每个待定项提供至少 2 个可选方案
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
✗ 数据验证失败: items[1].recommend 值 "invalid" 不在 options 中
|
||||||
|
建议: recommend 必须是 options 中某个选项的 value
|
||||||
|
```
|
||||||
|
|
||||||
|
## 四、输出规范
|
||||||
|
|
||||||
|
### 4.1 静默原则
|
||||||
|
|
||||||
|
- 成功时输出必要的状态信息（访问链接、完成提示）
|
||||||
|
- 错误时输出详细的错误信息和建议
|
||||||
|
- `aide decide result` 成功时仅输出 JSON，便于程序解析
|
||||||
|
|
||||||
|
### 4.2 固定前缀
|
||||||
|
|
||||||
|
沿用 `aide-program/docs/README.md` 的输出规范：
|
||||||
|
|
||||||
|
| 前缀 | 函数 | 用途 |
|
||||||
|
|------|------|------|
|
||||||
|
| `✓` | `output.ok()` | 成功 |
|
||||||
|
| `✗` | `output.err()` | 失败 |
|
||||||
|
| `→` | `output.info()` | 进行中/信息 |
|
||||||
|
|
||||||
|
### 4.3 JSON 输出格式
|
||||||
|
|
||||||
|
`aide decide result` 的 JSON 输出：
|
||||||
|
|
||||||
|
- 使用 UTF-8 编码
|
||||||
|
- 紧凑格式（无缩进），便于程序解析
|
||||||
|
- 输出到 stdout，错误信息输出到 stderr
|
||||||
|
|
||||||
|
## 五、退出码
|
||||||
|
|
||||||
|
| 退出码 | 含义 |
|
||||||
|
|-------:|------|
|
||||||
|
| 0 | 成功 |
|
||||||
|
| 1 | 失败（参数错误、校验失败、服务启动失败等） |
|
||||||
|
|
||||||
|
## 六、典型调用序列
|
||||||
|
|
||||||
|
### 6.1 正常流程
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. LLM 提交待定项数据
|
||||||
|
$ aide decide '{"task":"实现用户认证","source":"task.md","items":[...]}'
|
||||||
|
→ Web 服务已启动
|
||||||
|
→ 请访问: http://localhost:3721
|
||||||
|
→ 等待用户完成决策...
|
||||||
|
✓ 决策已完成
|
||||||
|
|
||||||
|
# 2. LLM 获取决策结果
|
||||||
|
$ aide decide result
|
||||||
|
{"decisions":[{"id":1,"chosen":"jwt"},{"id":2,"chosen":"bcrypt"}]}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.2 服务超时
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 配置了超时时间的情况
|
||||||
|
$ aide decide '{"task":"...","source":"...","items":[...]}'
|
||||||
|
→ Web 服务已启动
|
||||||
|
→ 请访问: http://localhost:3721
|
||||||
|
→ 等待用户完成决策...
|
||||||
|
⚠ 服务超时，已自动关闭
|
||||||
|
|
||||||
|
$ aide decide result
|
||||||
|
✗ 尚无决策结果
|
||||||
|
建议: 请等待用户在 Web 界面完成操作
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.3 与 /aide:prep 的集成
|
||||||
|
|
||||||
|
```
|
||||||
|
/aide:prep 流程中：
|
||||||
|
1. LLM 分析任务，识别待定项
|
||||||
|
2. LLM 构造 JSON 数据
|
||||||
|
3. LLM 调用 aide decide '<json>'
|
||||||
|
4. LLM 告知用户访问链接
|
||||||
|
5. 用户在 Web 界面完成决策
|
||||||
|
6. LLM 调用 aide decide result 获取结果
|
||||||
|
7. LLM 根据决策结果继续任务
|
||||||
|
```
|
||||||
|
|
||||||
|
## 七、方法签名原型
|
||||||
|
|
||||||
|
```
|
||||||
|
# CLI 入口（在 main.py 中）
|
||||||
|
def cmd_decide(args: list[str]) -> int:
|
||||||
|
"""
|
||||||
|
处理 aide decide 命令
|
||||||
|
|
||||||
|
args[0] 为 JSON 数据或 "result"
|
||||||
|
返回退出码
|
||||||
|
"""
|
||||||
|
|
||||||
|
def cmd_decide_submit(json_data: str) -> int:
|
||||||
|
"""
|
||||||
|
提交待定项数据并启动服务
|
||||||
|
|
||||||
|
1. 解析并验证 JSON
|
||||||
|
2. 保存到 pending.json
|
||||||
|
3. 启动 HTTP 服务
|
||||||
|
4. 等待用户操作
|
||||||
|
5. 返回退出码
|
||||||
|
"""
|
||||||
|
|
||||||
|
def cmd_decide_result() -> int:
|
||||||
|
"""
|
||||||
|
获取决策结果
|
||||||
|
|
||||||
|
1. 检查 pending.json
|
||||||
|
2. 查找最新决策记录
|
||||||
|
3. 验证匹配性
|
||||||
|
4. 输出 JSON 结果
|
||||||
|
5. 返回退出码
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
## 八、相关文档
|
||||||
|
|
||||||
|
- [decide 详细设计入口](README.md)
|
||||||
|
- [HTTP 服务设计](server.md)
|
||||||
|
- [数据存储设计](storage.md)
|
||||||
|
- [数据格式文档](../../formats/data.md)
|
||||||
472
aide-program/docs/commands/decide/server.md
Normal file
472
aide-program/docs/commands/decide/server.md
Normal file
@@ -0,0 +1,472 @@
|
|||||||
|
# aide decide HTTP 服务设计
|
||||||
|
|
||||||
|
## 一、概述
|
||||||
|
|
||||||
|
aide decide 使用内置 HTTP 服务器提供 Web 界面，供用户确认待定项。本文档定义服务器的设计规格。
|
||||||
|
|
||||||
|
### 1.1 技术选型
|
||||||
|
|
||||||
|
- 使用 Python 标准库 `http.server`
|
||||||
|
- 无需额外依赖
|
||||||
|
- 单线程阻塞模式（简化实现，满足单用户场景）
|
||||||
|
|
||||||
|
### 1.2 服务职责
|
||||||
|
|
||||||
|
| 职责 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| 静态资源服务 | 提供 HTML/CSS/JS 文件 |
|
||||||
|
| API 服务 | 提供数据获取和提交接口 |
|
||||||
|
| 生命周期管理 | 启动、等待、关闭 |
|
||||||
|
|
||||||
|
## 二、服务生命周期
|
||||||
|
|
||||||
|
### 2.1 状态机
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
[*] --> 初始化 : 调用 start()
|
||||||
|
初始化 --> 端口探测 : 配置加载完成
|
||||||
|
端口探测 --> 启动失败 : 无可用端口
|
||||||
|
端口探测 --> 运行中 : 找到可用端口
|
||||||
|
启动失败 --> [*]
|
||||||
|
运行中 --> 关闭中 : 收到提交/超时/中断
|
||||||
|
关闭中 --> 已关闭
|
||||||
|
已关闭 --> [*]
|
||||||
|
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 启动流程
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
start
|
||||||
|
|
||||||
|
:加载配置;
|
||||||
|
note right: decide.port, decide.timeout
|
||||||
|
|
||||||
|
:确定起始端口;
|
||||||
|
if (配置了固定端口?) then (是)
|
||||||
|
:使用配置端口;
|
||||||
|
else (否)
|
||||||
|
:使用默认端口 3721;
|
||||||
|
endif
|
||||||
|
|
||||||
|
:端口探测循环;
|
||||||
|
repeat
|
||||||
|
:尝试绑定端口;
|
||||||
|
if (绑定成功?) then (是)
|
||||||
|
:记录实际端口;
|
||||||
|
break
|
||||||
|
else (否)
|
||||||
|
:端口 += 1;
|
||||||
|
endif
|
||||||
|
repeat while (尝试次数 < 10?)
|
||||||
|
|
||||||
|
if (找到可用端口?) then (是)
|
||||||
|
else (否)
|
||||||
|
:返回错误;
|
||||||
|
stop
|
||||||
|
endif
|
||||||
|
|
||||||
|
:创建 HTTP 服务器;
|
||||||
|
|
||||||
|
:注册请求处理器;
|
||||||
|
|
||||||
|
:输出访问链接;
|
||||||
|
|
||||||
|
:进入服务循环;
|
||||||
|
|
||||||
|
stop
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.3 关闭流程
|
||||||
|
|
||||||
|
服务在以下情况下关闭：
|
||||||
|
|
||||||
|
| 触发条件 | 处理方式 |
|
||||||
|
|----------|----------|
|
||||||
|
| 用户提交决策 | 正常关闭，返回成功 |
|
||||||
|
| 超时（若配置） | 正常关闭，返回警告 |
|
||||||
|
| 键盘中断（Ctrl+C） | 正常关闭，返回中断 |
|
||||||
|
| 异常错误 | 异常关闭，返回错误 |
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
start
|
||||||
|
|
||||||
|
:收到关闭信号;
|
||||||
|
|
||||||
|
:停止接受新请求;
|
||||||
|
|
||||||
|
:等待当前请求完成;
|
||||||
|
note right: 最多等待 5 秒
|
||||||
|
|
||||||
|
:关闭 socket;
|
||||||
|
|
||||||
|
:清理资源;
|
||||||
|
|
||||||
|
:返回关闭原因;
|
||||||
|
|
||||||
|
stop
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
## 三、端口配置
|
||||||
|
|
||||||
|
### 3.1 端口探测策略
|
||||||
|
|
||||||
|
| 配置项 | 默认值 | 说明 |
|
||||||
|
|--------|--------|------|
|
||||||
|
| `decide.port` | 3721 | 起始端口 |
|
||||||
|
| 最大尝试次数 | 10 | 从起始端口开始尝试 |
|
||||||
|
|
||||||
|
**探测逻辑**：
|
||||||
|
|
||||||
|
1. 从 `decide.port` 开始
|
||||||
|
2. 尝试绑定端口
|
||||||
|
3. 若失败，尝试下一个端口
|
||||||
|
4. 最多尝试 10 次
|
||||||
|
5. 全部失败则返回错误
|
||||||
|
|
||||||
|
### 3.2 端口占用检测
|
||||||
|
|
||||||
|
```
|
||||||
|
check_port_available(port: int) -> bool:
|
||||||
|
"""
|
||||||
|
检查端口是否可用
|
||||||
|
|
||||||
|
1. 创建 socket
|
||||||
|
2. 尝试绑定到 127.0.0.1:port
|
||||||
|
3. 成功则端口可用，关闭 socket 返回 True
|
||||||
|
4. 失败则端口被占用，返回 False
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
## 四、API 端点设计
|
||||||
|
|
||||||
|
### 4.1 端点一览
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| GET | `/` | 返回主页面（index.html） |
|
||||||
|
| GET | `/style.css` | 返回样式文件 |
|
||||||
|
| GET | `/app.js` | 返回脚本文件 |
|
||||||
|
| GET | `/api/items` | 获取待定项数据 |
|
||||||
|
| POST | `/api/submit` | 提交决策结果 |
|
||||||
|
|
||||||
|
### 4.2 GET /api/items
|
||||||
|
|
||||||
|
**请求**：无参数
|
||||||
|
|
||||||
|
**响应**：
|
||||||
|
|
||||||
|
成功（200）：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"task": "实现用户认证模块",
|
||||||
|
"source": "task-now.md",
|
||||||
|
"items": [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"title": "认证方式选择",
|
||||||
|
"context": "任务描述中未明确指定认证方式",
|
||||||
|
"options": [
|
||||||
|
{"value": "jwt", "label": "JWT Token 认证", "score": 85, "pros": [...], "cons": [...]},
|
||||||
|
{"value": "session", "label": "Session 认证", "score": 70, "pros": [...], "cons": [...]}
|
||||||
|
],
|
||||||
|
"recommend": "jwt"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
失败（500）：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": "无法读取待定项数据",
|
||||||
|
"detail": "文件不存在或格式错误"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 POST /api/submit
|
||||||
|
|
||||||
|
**请求**：
|
||||||
|
|
||||||
|
Content-Type: `application/json`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"decisions": [
|
||||||
|
{"id": 1, "chosen": "jwt"},
|
||||||
|
{"id": 2, "chosen": "bcrypt", "note": "团队更熟悉 bcrypt"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**响应**：
|
||||||
|
|
||||||
|
成功（200）：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "决策已保存"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
校验失败（400）：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": "决策数据无效",
|
||||||
|
"detail": "缺少待定项 2 的决策"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
服务器错误（500）：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": "保存失败",
|
||||||
|
"detail": "无法写入文件"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**提交后行为**：
|
||||||
|
|
||||||
|
1. 验证决策数据完整性（所有待定项都有决策）
|
||||||
|
2. 保存决策结果到历史记录
|
||||||
|
3. 设置关闭标志
|
||||||
|
4. 返回成功响应
|
||||||
|
5. 服务器在响应发送后关闭
|
||||||
|
|
||||||
|
### 4.4 静态资源服务
|
||||||
|
|
||||||
|
| 路径 | 文件 | Content-Type |
|
||||||
|
|------|------|--------------|
|
||||||
|
| `/` | `web/index.html` | `text/html; charset=utf-8` |
|
||||||
|
| `/style.css` | `web/style.css` | `text/css; charset=utf-8` |
|
||||||
|
| `/app.js` | `web/app.js` | `application/javascript; charset=utf-8` |
|
||||||
|
|
||||||
|
**资源加载方式**：
|
||||||
|
|
||||||
|
- 方案A：从文件系统读取（开发时便于修改）
|
||||||
|
- 方案B：嵌入 Python 代码（部署时无需额外文件）
|
||||||
|
|
||||||
|
建议：使用方案A，资源文件放在 `aide/decide/web/` 目录下。
|
||||||
|
|
||||||
|
## 五、请求处理
|
||||||
|
|
||||||
|
### 5.1 请求处理流程
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
start
|
||||||
|
|
||||||
|
:接收 HTTP 请求;
|
||||||
|
|
||||||
|
:解析请求路径和方法;
|
||||||
|
|
||||||
|
switch (路径)
|
||||||
|
case (/)
|
||||||
|
:返回 index.html;
|
||||||
|
case (/style.css)
|
||||||
|
:返回 style.css;
|
||||||
|
case (/app.js)
|
||||||
|
:返回 app.js;
|
||||||
|
case (/api/items)
|
||||||
|
if (方法 == GET?) then (是)
|
||||||
|
:读取 pending.json;
|
||||||
|
:返回 JSON 数据;
|
||||||
|
else (否)
|
||||||
|
:返回 405 Method Not Allowed;
|
||||||
|
endif
|
||||||
|
case (/api/submit)
|
||||||
|
if (方法 == POST?) then (是)
|
||||||
|
:解析请求体;
|
||||||
|
:验证决策数据;
|
||||||
|
:保存决策结果;
|
||||||
|
:设置关闭标志;
|
||||||
|
:返回成功响应;
|
||||||
|
else (否)
|
||||||
|
:返回 405 Method Not Allowed;
|
||||||
|
endif
|
||||||
|
case (其他)
|
||||||
|
:返回 404 Not Found;
|
||||||
|
endswitch
|
||||||
|
|
||||||
|
stop
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 CORS 处理
|
||||||
|
|
||||||
|
由于前端和后端在同一服务器，通常不需要 CORS。但为了开发调试方便，建议添加以下响应头：
|
||||||
|
|
||||||
|
```
|
||||||
|
Access-Control-Allow-Origin: *
|
||||||
|
Access-Control-Allow-Methods: GET, POST, OPTIONS
|
||||||
|
Access-Control-Allow-Headers: Content-Type
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.3 错误处理
|
||||||
|
|
||||||
|
| HTTP 状态码 | 场景 |
|
||||||
|
|-------------|------|
|
||||||
|
| 200 | 请求成功 |
|
||||||
|
| 400 | 请求数据无效 |
|
||||||
|
| 404 | 路径不存在 |
|
||||||
|
| 405 | 方法不允许 |
|
||||||
|
| 500 | 服务器内部错误 |
|
||||||
|
|
||||||
|
## 六、超时处理
|
||||||
|
|
||||||
|
### 6.1 配置项
|
||||||
|
|
||||||
|
| 配置项 | 默认值 | 说明 |
|
||||||
|
|--------|--------|------|
|
||||||
|
| `decide.timeout` | 0 | 超时时间（秒），0 表示无超时 |
|
||||||
|
|
||||||
|
### 6.2 超时实现
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
start
|
||||||
|
|
||||||
|
fork
|
||||||
|
:服务循环;
|
||||||
|
:处理请求;
|
||||||
|
fork again
|
||||||
|
:超时计时器;
|
||||||
|
:等待 timeout 秒;
|
||||||
|
:设置超时标志;
|
||||||
|
end fork
|
||||||
|
|
||||||
|
if (超时?) then (是)
|
||||||
|
:关闭服务;
|
||||||
|
:输出警告;
|
||||||
|
else (否)
|
||||||
|
:正常关闭;
|
||||||
|
endif
|
||||||
|
|
||||||
|
stop
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
**注意**：由于使用单线程模型，超时检测需要在请求处理间隙进行，或使用 `select` 实现非阻塞等待。
|
||||||
|
|
||||||
|
## 七、方法签名原型
|
||||||
|
|
||||||
|
```
|
||||||
|
class DecideServer:
|
||||||
|
"""HTTP 服务器"""
|
||||||
|
|
||||||
|
root: Path # 项目根目录
|
||||||
|
port: int # 实际使用的端口
|
||||||
|
timeout: int # 超时时间（秒）
|
||||||
|
pending_path: Path # pending.json 路径
|
||||||
|
web_dir: Path # 静态资源目录
|
||||||
|
should_close: bool # 关闭标志
|
||||||
|
close_reason: str # 关闭原因
|
||||||
|
|
||||||
|
def __init__(self, root: Path) -> None:
|
||||||
|
"""初始化服务器"""
|
||||||
|
|
||||||
|
def start(self) -> bool:
|
||||||
|
"""
|
||||||
|
启动服务器
|
||||||
|
|
||||||
|
1. 加载配置
|
||||||
|
2. 探测可用端口
|
||||||
|
3. 创建 HTTP 服务器
|
||||||
|
4. 输出访问链接
|
||||||
|
5. 进入服务循环
|
||||||
|
6. 返回是否成功完成
|
||||||
|
"""
|
||||||
|
|
||||||
|
def stop(self, reason: str) -> None:
|
||||||
|
"""
|
||||||
|
停止服务器
|
||||||
|
|
||||||
|
1. 设置关闭标志和原因
|
||||||
|
2. 关闭 socket
|
||||||
|
"""
|
||||||
|
|
||||||
|
def _find_available_port(self) -> int | None:
|
||||||
|
"""
|
||||||
|
探测可用端口
|
||||||
|
|
||||||
|
从配置端口开始，最多尝试 10 次
|
||||||
|
返回可用端口或 None
|
||||||
|
"""
|
||||||
|
|
||||||
|
def _serve_forever(self) -> None:
|
||||||
|
"""
|
||||||
|
服务循环
|
||||||
|
|
||||||
|
处理请求直到 should_close 为 True
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class DecideHandler:
|
||||||
|
"""请求处理器"""
|
||||||
|
|
||||||
|
server: DecideServer # 服务器引用
|
||||||
|
|
||||||
|
def handle_request(self, method: str, path: str, body: bytes) -> Response:
|
||||||
|
"""
|
||||||
|
处理请求
|
||||||
|
|
||||||
|
根据 method 和 path 分发到具体处理函数
|
||||||
|
"""
|
||||||
|
|
||||||
|
def handle_index(self) -> Response:
|
||||||
|
"""返回主页面"""
|
||||||
|
|
||||||
|
def handle_static(self, filename: str) -> Response:
|
||||||
|
"""返回静态资源"""
|
||||||
|
|
||||||
|
def handle_get_items(self) -> Response:
|
||||||
|
"""处理 GET /api/items"""
|
||||||
|
|
||||||
|
def handle_submit(self, body: bytes) -> Response:
|
||||||
|
"""处理 POST /api/submit"""
|
||||||
|
|
||||||
|
|
||||||
|
Response = tuple[int, dict[str, str], bytes]
|
||||||
|
# (状态码, 响应头, 响应体)
|
||||||
|
```
|
||||||
|
|
||||||
|
## 八、安全考虑
|
||||||
|
|
||||||
|
### 8.1 绑定地址
|
||||||
|
|
||||||
|
- 默认绑定到 `127.0.0.1`（仅本地访问）
|
||||||
|
- 不绑定到 `0.0.0.0`（避免外部访问）
|
||||||
|
|
||||||
|
### 8.2 输入验证
|
||||||
|
|
||||||
|
- 验证 JSON 格式
|
||||||
|
- 验证决策数据完整性
|
||||||
|
- 限制请求体大小（建议 1MB）
|
||||||
|
|
||||||
|
### 8.3 路径遍历防护
|
||||||
|
|
||||||
|
- 静态资源只从 `web/` 目录提供
|
||||||
|
- 不允许 `..` 路径
|
||||||
|
|
||||||
|
## 九、相关文档
|
||||||
|
|
||||||
|
- [decide 详细设计入口](README.md)
|
||||||
|
- [CLI 规格](cli.md)
|
||||||
|
- [Web 前端设计](web.md)
|
||||||
|
- [数据存储设计](storage.md)
|
||||||
383
aide-program/docs/commands/decide/storage.md
Normal file
383
aide-program/docs/commands/decide/storage.md
Normal file
@@ -0,0 +1,383 @@
|
|||||||
|
# aide decide 数据存储设计
|
||||||
|
|
||||||
|
## 一、概述
|
||||||
|
|
||||||
|
aide decide 的数据存储负责管理待定项数据和决策记录的持久化。
|
||||||
|
|
||||||
|
### 1.1 存储位置
|
||||||
|
|
||||||
|
所有数据存储在项目根目录的 `.aide/decisions/` 下：
|
||||||
|
|
||||||
|
```
|
||||||
|
.aide/
|
||||||
|
└── decisions/
|
||||||
|
├── pending.json # 当前待处理的待定项
|
||||||
|
└── 2025-01-15T10-30-00.json # 历史决策记录
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.2 数据格式规范
|
||||||
|
|
||||||
|
数据格式以 `aide-program/docs/formats/data.md` 为准，本文档补充存储相关的实现细节。
|
||||||
|
|
||||||
|
## 二、文件说明
|
||||||
|
|
||||||
|
### 2.1 pending.json
|
||||||
|
|
||||||
|
**用途**：存储当前待处理的待定项数据
|
||||||
|
|
||||||
|
**生命周期**：
|
||||||
|
- 创建：`aide decide '<json>'` 执行时
|
||||||
|
- 读取：Web 前端通过 API 获取
|
||||||
|
- 保留：决策完成后保留，用于 `aide decide result` 验证匹配性
|
||||||
|
- 覆盖：下次 `aide decide '<json>'` 执行时覆盖
|
||||||
|
|
||||||
|
**内容格式**：与输入数据格式相同（DecideInput）
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"task": "实现用户认证模块",
|
||||||
|
"source": "task-now.md",
|
||||||
|
"items": [...],
|
||||||
|
"_meta": {
|
||||||
|
"created_at": "2025-01-15T10:30:00+08:00",
|
||||||
|
"session_id": "2025-01-15T10-30-00"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**元数据字段**（`_meta`）：
|
||||||
|
- `created_at`：创建时间（ISO 8601 格式）
|
||||||
|
- `session_id`：会话标识（用于匹配决策记录）
|
||||||
|
|
||||||
|
### 2.2 历史决策记录
|
||||||
|
|
||||||
|
**文件名格式**：`{session_id}.json`
|
||||||
|
|
||||||
|
**示例**：`2025-01-15T10-30-00.json`
|
||||||
|
|
||||||
|
**内容格式**：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"input": {
|
||||||
|
"task": "实现用户认证模块",
|
||||||
|
"source": "task-now.md",
|
||||||
|
"items": [...]
|
||||||
|
},
|
||||||
|
"output": {
|
||||||
|
"decisions": [
|
||||||
|
{"id": 1, "chosen": "jwt"},
|
||||||
|
{"id": 2, "chosen": "bcrypt", "note": "团队更熟悉 bcrypt"}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"completed_at": "2025-01-15T10:35:00+08:00"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 三、存储操作
|
||||||
|
|
||||||
|
### 3.1 保存待定项数据
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
start
|
||||||
|
|
||||||
|
:接收 DecideInput 数据;
|
||||||
|
|
||||||
|
:生成 session_id;
|
||||||
|
note right: 格式: YYYY-MM-DDTHH-mm-ss
|
||||||
|
|
||||||
|
:添加 _meta 字段;
|
||||||
|
|
||||||
|
:确保 .aide/decisions/ 目录存在;
|
||||||
|
|
||||||
|
:写入 pending.json;
|
||||||
|
note right: 原子写入
|
||||||
|
|
||||||
|
stop
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 保存决策结果
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
start
|
||||||
|
|
||||||
|
:接收 DecideOutput 数据;
|
||||||
|
|
||||||
|
:读取 pending.json;
|
||||||
|
|
||||||
|
:提取 session_id;
|
||||||
|
|
||||||
|
:构造 DecisionRecord;
|
||||||
|
note right: input + output + completed_at
|
||||||
|
|
||||||
|
:写入 {session_id}.json;
|
||||||
|
note right: 原子写入
|
||||||
|
|
||||||
|
stop
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 读取决策结果
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
start
|
||||||
|
|
||||||
|
:检查 pending.json 是否存在;
|
||||||
|
if (存在?) then (是)
|
||||||
|
else (否)
|
||||||
|
:返回错误: 未找到待定项数据;
|
||||||
|
stop
|
||||||
|
endif
|
||||||
|
|
||||||
|
:读取 pending.json;
|
||||||
|
|
||||||
|
:提取 session_id;
|
||||||
|
|
||||||
|
:构造历史记录文件名;
|
||||||
|
note right: {session_id}.json
|
||||||
|
|
||||||
|
:检查历史记录是否存在;
|
||||||
|
if (存在?) then (是)
|
||||||
|
else (否)
|
||||||
|
:返回错误: 尚无决策结果;
|
||||||
|
stop
|
||||||
|
endif
|
||||||
|
|
||||||
|
:读取历史记录;
|
||||||
|
|
||||||
|
:返回 output.decisions;
|
||||||
|
|
||||||
|
stop
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
## 四、并发与原子性
|
||||||
|
|
||||||
|
### 4.1 原子写入
|
||||||
|
|
||||||
|
为避免写入过程中断导致文件损坏，必须使用原子写入：
|
||||||
|
|
||||||
|
1. 写入临时文件：`{filename}.tmp`
|
||||||
|
2. 确保写入完成（fsync，如实现选择支持）
|
||||||
|
3. 原子重命名为目标文件
|
||||||
|
|
||||||
|
```
|
||||||
|
save_atomic(path: Path, data: dict) -> None:
|
||||||
|
"""
|
||||||
|
原子写入 JSON 文件
|
||||||
|
|
||||||
|
1. 序列化为 JSON 字符串
|
||||||
|
2. 写入 {path}.tmp
|
||||||
|
3. 重命名为 {path}
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 并发控制
|
||||||
|
|
||||||
|
由于 aide decide 是单用户场景，且同一时间只有一个会话，通常不需要复杂的并发控制。
|
||||||
|
|
||||||
|
但为了安全，建议：
|
||||||
|
- 写入前检查文件是否被其他进程占用
|
||||||
|
- 使用文件锁（可选）
|
||||||
|
|
||||||
|
### 4.3 编码规范
|
||||||
|
|
||||||
|
- 文件编码：UTF-8
|
||||||
|
- 换行符：`\n`（Unix 风格）
|
||||||
|
- JSON 格式：缩进 2 空格，便于人工阅读
|
||||||
|
|
||||||
|
## 五、生命周期管理
|
||||||
|
|
||||||
|
### 5.1 文件生命周期
|
||||||
|
|
||||||
|
| 文件 | 创建时机 | 删除时机 |
|
||||||
|
|------|----------|----------|
|
||||||
|
| pending.json | `aide decide '<json>'` | 不自动删除，下次覆盖 |
|
||||||
|
| {session_id}.json | 用户提交决策 | 不自动删除 |
|
||||||
|
|
||||||
|
### 5.2 历史记录清理
|
||||||
|
|
||||||
|
历史记录不自动清理，由用户手动管理。
|
||||||
|
|
||||||
|
建议的清理策略（可作为后续功能）：
|
||||||
|
- 保留最近 N 条记录
|
||||||
|
- 保留最近 N 天的记录
|
||||||
|
- 提供 `aide decide clean` 命令
|
||||||
|
|
||||||
|
### 5.3 目录初始化
|
||||||
|
|
||||||
|
首次使用时，需要确保目录存在：
|
||||||
|
|
||||||
|
```
|
||||||
|
ensure_decisions_dir(root: Path) -> Path:
|
||||||
|
"""
|
||||||
|
确保 .aide/decisions/ 目录存在
|
||||||
|
|
||||||
|
1. 检查 .aide/ 是否存在
|
||||||
|
2. 若不存在，返回错误（需要先执行 aide init）
|
||||||
|
3. 创建 decisions/ 子目录（如不存在）
|
||||||
|
4. 返回目录路径
|
||||||
|
"""
|
||||||
|
```
|
||||||
|
|
||||||
|
## 六、容错与恢复
|
||||||
|
|
||||||
|
### 6.1 JSON 解析失败
|
||||||
|
|
||||||
|
当文件存在但无法解析时：
|
||||||
|
|
||||||
|
```
|
||||||
|
✗ 无法解析 pending.json: <具体错误>
|
||||||
|
建议: 文件可能已损坏，请重新执行 aide decide '<json>'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.2 文件缺失
|
||||||
|
|
||||||
|
| 场景 | 错误信息 |
|
||||||
|
|------|----------|
|
||||||
|
| .aide/ 不存在 | `✗ .aide 目录不存在，请先执行 aide init` |
|
||||||
|
| pending.json 不存在 | `✗ 未找到待定项数据，请先执行 aide decide '<json>'` |
|
||||||
|
| 历史记录不存在 | `✗ 尚无决策结果，请等待用户完成操作` |
|
||||||
|
|
||||||
|
### 6.3 数据不一致
|
||||||
|
|
||||||
|
当 pending.json 和历史记录的 session_id 不匹配时：
|
||||||
|
|
||||||
|
```
|
||||||
|
✗ 决策结果已过期
|
||||||
|
建议: pending.json 已被更新，请重新执行 aide decide '<json>'
|
||||||
|
```
|
||||||
|
|
||||||
|
## 七、方法签名原型
|
||||||
|
|
||||||
|
```
|
||||||
|
class DecideStorage:
|
||||||
|
"""决策数据存储管理"""
|
||||||
|
|
||||||
|
root: Path # 项目根目录
|
||||||
|
decisions_dir: Path # .aide/decisions/ 目录
|
||||||
|
pending_path: Path # pending.json 路径
|
||||||
|
|
||||||
|
def __init__(self, root: Path) -> None:
|
||||||
|
"""
|
||||||
|
初始化存储管理器
|
||||||
|
|
||||||
|
1. 设置路径
|
||||||
|
2. 确保目录存在
|
||||||
|
"""
|
||||||
|
|
||||||
|
def save_pending(self, data: DecideInput) -> str:
|
||||||
|
"""
|
||||||
|
保存待定项数据
|
||||||
|
|
||||||
|
1. 生成 session_id
|
||||||
|
2. 添加 _meta 字段
|
||||||
|
3. 原子写入 pending.json
|
||||||
|
4. 返回 session_id
|
||||||
|
"""
|
||||||
|
|
||||||
|
def load_pending(self) -> DecideInput | None:
|
||||||
|
"""
|
||||||
|
加载待定项数据
|
||||||
|
|
||||||
|
返回 DecideInput 或 None（文件不存在）
|
||||||
|
"""
|
||||||
|
|
||||||
|
def get_session_id(self) -> str | None:
|
||||||
|
"""
|
||||||
|
获取当前会话 ID
|
||||||
|
|
||||||
|
从 pending.json 的 _meta.session_id 读取
|
||||||
|
"""
|
||||||
|
|
||||||
|
def save_result(self, output: DecideOutput) -> None:
|
||||||
|
"""
|
||||||
|
保存决策结果
|
||||||
|
|
||||||
|
1. 读取 pending.json 获取 input 和 session_id
|
||||||
|
2. 构造 DecisionRecord
|
||||||
|
3. 原子写入 {session_id}.json
|
||||||
|
"""
|
||||||
|
|
||||||
|
def load_result(self) -> DecideOutput | None:
|
||||||
|
"""
|
||||||
|
加载决策结果
|
||||||
|
|
||||||
|
1. 获取 session_id
|
||||||
|
2. 读取 {session_id}.json
|
||||||
|
3. 返回 output 部分
|
||||||
|
"""
|
||||||
|
|
||||||
|
def has_pending(self) -> bool:
|
||||||
|
"""检查是否有待处理的待定项"""
|
||||||
|
|
||||||
|
def has_result(self) -> bool:
|
||||||
|
"""检查是否有决策结果"""
|
||||||
|
|
||||||
|
def _ensure_dir(self) -> None:
|
||||||
|
"""确保目录存在"""
|
||||||
|
|
||||||
|
def _save_atomic(self, path: Path, data: dict) -> None:
|
||||||
|
"""原子写入 JSON 文件"""
|
||||||
|
|
||||||
|
def _load_json(self, path: Path) -> dict | None:
|
||||||
|
"""加载 JSON 文件"""
|
||||||
|
|
||||||
|
|
||||||
|
# 数据类型定义（与 types.py 一致）
|
||||||
|
|
||||||
|
DecideInput:
|
||||||
|
task: str
|
||||||
|
source: str
|
||||||
|
items: list[DecideItem]
|
||||||
|
_meta: MetaInfo | None
|
||||||
|
|
||||||
|
MetaInfo:
|
||||||
|
created_at: str
|
||||||
|
session_id: str
|
||||||
|
|
||||||
|
DecideOutput:
|
||||||
|
decisions: list[Decision]
|
||||||
|
|
||||||
|
DecisionRecord:
|
||||||
|
input: DecideInput
|
||||||
|
output: DecideOutput
|
||||||
|
completed_at: str
|
||||||
|
```
|
||||||
|
|
||||||
|
## 八、与其他模块的关系
|
||||||
|
|
||||||
|
### 8.1 被调用方
|
||||||
|
|
||||||
|
| 调用方 | 调用的方法 |
|
||||||
|
|--------|------------|
|
||||||
|
| CLI (cmd_decide_submit) | save_pending() |
|
||||||
|
| CLI (cmd_decide_result) | load_result(), has_pending(), has_result() |
|
||||||
|
| Server (handle_get_items) | load_pending() |
|
||||||
|
| Server (handle_submit) | save_result() |
|
||||||
|
|
||||||
|
### 8.2 依赖
|
||||||
|
|
||||||
|
| 依赖项 | 用途 |
|
||||||
|
|--------|------|
|
||||||
|
| core/config.py | 读取项目根目录 |
|
||||||
|
| json | JSON 序列化/反序列化 |
|
||||||
|
| pathlib | 路径操作 |
|
||||||
|
| datetime | 时间戳生成 |
|
||||||
|
|
||||||
|
## 九、相关文档
|
||||||
|
|
||||||
|
- [decide 详细设计入口](README.md)
|
||||||
|
- [CLI 规格](cli.md)
|
||||||
|
- [HTTP 服务设计](server.md)
|
||||||
|
- [数据格式文档](../../formats/data.md)
|
||||||
528
aide-program/docs/commands/decide/verification.md
Normal file
528
aide-program/docs/commands/decide/verification.md
Normal file
@@ -0,0 +1,528 @@
|
|||||||
|
# 验证清单（实现完成后的自检）
|
||||||
|
|
||||||
|
本清单用于在实现 `aide decide` 后进行验证，确保行为符合设计文档与 plugin 契约。
|
||||||
|
|
||||||
|
## 一、准备条件
|
||||||
|
|
||||||
|
- 已执行 `aide init`，确保 `.aide/` 目录存在
|
||||||
|
- 准备测试用的 JSON 数据（见附录）
|
||||||
|
- 确保端口 3721 未被占用（或准备测试端口探测）
|
||||||
|
|
||||||
|
## 二、CLI 用例
|
||||||
|
|
||||||
|
### 2.1 正常提交待定项
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 执行 `aide decide '<valid_json>'`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 输出包含 `→ Web 服务已启动`
|
||||||
|
- 输出包含 `→ 请访问: http://localhost:3721`（或其他端口）
|
||||||
|
- 输出包含 `→ 等待用户完成决策...`
|
||||||
|
- `.aide/decisions/pending.json` 被创建
|
||||||
|
- 服务阻塞等待
|
||||||
|
|
||||||
|
### 2.2 JSON 解析失败
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 执行 `aide decide 'invalid json'`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 输出 `✗ JSON 解析失败: ...`
|
||||||
|
- 退出码为 1
|
||||||
|
- 不创建 pending.json
|
||||||
|
- 不启动服务
|
||||||
|
|
||||||
|
### 2.3 数据验证失败
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 执行 `aide decide '{"task":"test"}'`（缺少必填字段）
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 输出 `✗ 数据验证失败: ...`
|
||||||
|
- 错误信息明确指出缺少的字段
|
||||||
|
- 退出码为 1
|
||||||
|
|
||||||
|
### 2.4 获取决策结果（无数据）
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 确保 `.aide/decisions/` 为空
|
||||||
|
2. 执行 `aide decide result`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 输出 `✗ 未找到待定项数据`
|
||||||
|
- 退出码为 1
|
||||||
|
|
||||||
|
### 2.5 获取决策结果（有 pending 无 result）
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 执行 `aide decide '<json>'` 并立即中断（Ctrl+C）
|
||||||
|
2. 执行 `aide decide result`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 输出 `✗ 尚无决策结果`
|
||||||
|
- 退出码为 1
|
||||||
|
|
||||||
|
### 2.6 获取决策结果（正常）
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 完成一次完整的决策流程
|
||||||
|
2. 执行 `aide decide result`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 输出 JSON 格式的决策结果
|
||||||
|
- JSON 可被正确解析
|
||||||
|
- 包含所有待定项的决策
|
||||||
|
- 退出码为 0
|
||||||
|
|
||||||
|
## 三、HTTP 服务用例
|
||||||
|
|
||||||
|
### 3.1 端口探测
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 占用端口 3721（如 `nc -l 3721`）
|
||||||
|
2. 执行 `aide decide '<json>'`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 服务在 3722 端口启动
|
||||||
|
- 输出显示正确的端口号
|
||||||
|
|
||||||
|
### 3.2 端口全部被占用
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 占用端口 3721-3730
|
||||||
|
2. 执行 `aide decide '<json>'`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 输出 `✗ 无法启动服务: 端口 3721-3730 均被占用`
|
||||||
|
- 退出码为 1
|
||||||
|
|
||||||
|
### 3.3 GET /api/items
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 启动服务
|
||||||
|
2. 使用 curl 访问 `http://localhost:3721/api/items`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 返回 200 状态码
|
||||||
|
- Content-Type 为 `application/json`
|
||||||
|
- 返回的 JSON 与 pending.json 内容一致
|
||||||
|
|
||||||
|
### 3.4 POST /api/submit（正常）
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 启动服务
|
||||||
|
2. 使用 curl 提交决策：
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:3721/api/submit \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"decisions":[{"id":1,"chosen":"jwt"}]}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 返回 200 状态码
|
||||||
|
- 返回 `{"success":true,"message":"决策已保存"}`
|
||||||
|
- 服务关闭
|
||||||
|
- 历史记录文件被创建
|
||||||
|
|
||||||
|
### 3.5 POST /api/submit（数据不完整）
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 启动服务（待定项有 2 个）
|
||||||
|
2. 提交只包含 1 个决策的数据
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 返回 400 状态码
|
||||||
|
- 返回错误信息指出缺少的决策
|
||||||
|
- 服务不关闭
|
||||||
|
|
||||||
|
### 3.6 静态资源服务
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 启动服务
|
||||||
|
2. 访问 `http://localhost:3721/`
|
||||||
|
3. 访问 `http://localhost:3721/style.css`
|
||||||
|
4. 访问 `http://localhost:3721/app.js`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 所有资源返回 200 状态码
|
||||||
|
- Content-Type 正确
|
||||||
|
- 内容非空
|
||||||
|
|
||||||
|
### 3.7 404 处理
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 启动服务
|
||||||
|
2. 访问 `http://localhost:3721/nonexistent`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 返回 404 状态码
|
||||||
|
|
||||||
|
### 3.8 服务中断（Ctrl+C）
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 启动服务
|
||||||
|
2. 按 Ctrl+C
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 服务正常关闭
|
||||||
|
- 无异常输出
|
||||||
|
- 退出码为 0 或 130（SIGINT）
|
||||||
|
|
||||||
|
## 四、Web 前端用例
|
||||||
|
|
||||||
|
### 4.1 页面加载
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 启动服务
|
||||||
|
2. 在浏览器中打开页面
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 页面正常渲染
|
||||||
|
- 显示任务名称和来源
|
||||||
|
- 显示所有待定项
|
||||||
|
- 提交按钮为禁用状态
|
||||||
|
|
||||||
|
### 4.2 选项选择
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 点击某个选项
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 选项被选中（视觉反馈）
|
||||||
|
- 进度更新（如 "已完成 1/2 项"）
|
||||||
|
- 若所有项已选择，提交按钮启用
|
||||||
|
|
||||||
|
### 4.3 推荐选项显示
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 提交包含 recommend 字段的数据
|
||||||
|
2. 查看页面
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 推荐选项有特殊标记
|
||||||
|
- 卡片头部显示推荐信息
|
||||||
|
|
||||||
|
### 4.4 备注输入
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 在备注框中输入文字
|
||||||
|
2. 提交决策
|
||||||
|
3. 查看决策结果
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 备注内容被保存
|
||||||
|
- 决策结果中包含 note 字段
|
||||||
|
|
||||||
|
### 4.5 提交决策
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 选择所有待定项的选项
|
||||||
|
2. 点击提交按钮
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 显示提交中状态
|
||||||
|
- 提交成功后显示成功提示
|
||||||
|
- 页面提示可以关闭
|
||||||
|
|
||||||
|
### 4.6 提交失败处理
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 模拟服务端错误（如断开网络）
|
||||||
|
2. 点击提交按钮
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 显示错误提示
|
||||||
|
- 提交按钮恢复可用
|
||||||
|
- 可以重试
|
||||||
|
|
||||||
|
### 4.7 浏览器兼容性
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 在 Chrome、Firefox、Safari、Edge 中分别测试
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 页面正常渲染
|
||||||
|
- 交互功能正常
|
||||||
|
- 无 JavaScript 错误
|
||||||
|
|
||||||
|
## 五、数据存储用例
|
||||||
|
|
||||||
|
### 5.1 pending.json 创建
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 执行 `aide decide '<json>'`
|
||||||
|
2. 检查 `.aide/decisions/pending.json`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 文件存在
|
||||||
|
- JSON 格式正确
|
||||||
|
- 包含 `_meta` 字段
|
||||||
|
- `_meta.session_id` 格式正确
|
||||||
|
|
||||||
|
### 5.2 历史记录创建
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 完成一次决策流程
|
||||||
|
2. 检查 `.aide/decisions/` 目录
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 存在 `{session_id}.json` 文件
|
||||||
|
- 文件包含 input、output、completed_at 字段
|
||||||
|
- session_id 与 pending.json 中的一致
|
||||||
|
|
||||||
|
### 5.3 pending.json 覆盖
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 执行 `aide decide '<json1>'`
|
||||||
|
2. 中断服务
|
||||||
|
3. 执行 `aide decide '<json2>'`
|
||||||
|
4. 检查 pending.json
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- pending.json 内容为 json2
|
||||||
|
- session_id 已更新
|
||||||
|
|
||||||
|
### 5.4 原子写入验证
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 在写入过程中模拟中断
|
||||||
|
2. 检查文件状态
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 文件要么是完整的旧内容，要么是完整的新内容
|
||||||
|
- 不会出现部分写入的损坏状态
|
||||||
|
|
||||||
|
## 六、端到端用例
|
||||||
|
|
||||||
|
### 6.1 完整流程
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 执行 `aide decide '<json>'`
|
||||||
|
2. 在浏览器中打开链接
|
||||||
|
3. 选择所有选项
|
||||||
|
4. 添加备注
|
||||||
|
5. 点击提交
|
||||||
|
6. 执行 `aide decide result`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 整个流程无错误
|
||||||
|
- 决策结果正确反映用户选择
|
||||||
|
- 备注内容正确保存
|
||||||
|
|
||||||
|
### 6.2 与 /aide:prep 集成
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 模拟 LLM 调用流程
|
||||||
|
2. 构造待定项 JSON
|
||||||
|
3. 调用 aide decide
|
||||||
|
4. 完成决策
|
||||||
|
5. 获取结果
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 流程符合 plugin 契约
|
||||||
|
- 输出格式便于 LLM 解析
|
||||||
|
|
||||||
|
## 七、异常用例
|
||||||
|
|
||||||
|
### 7.1 .aide 目录不存在
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 删除 .aide 目录
|
||||||
|
2. 执行 `aide decide '<json>'`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 输出 `✗ .aide 目录不存在，请先执行 aide init`
|
||||||
|
- 退出码为 1
|
||||||
|
|
||||||
|
### 7.2 pending.json 损坏
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 手动写入无效 JSON 到 pending.json
|
||||||
|
2. 执行 `aide decide result`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 输出解析错误信息
|
||||||
|
- 建议重新执行 aide decide
|
||||||
|
|
||||||
|
### 7.3 超大 JSON 数据
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 构造包含 100 个待定项的 JSON
|
||||||
|
2. 执行 `aide decide '<json>'`
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 正常处理或给出合理的限制提示
|
||||||
|
- 不会导致内存溢出或崩溃
|
||||||
|
|
||||||
|
### 7.4 特殊字符处理
|
||||||
|
|
||||||
|
**步骤**：
|
||||||
|
|
||||||
|
1. 在 task、title、note 中包含特殊字符（中文、emoji、引号、换行）
|
||||||
|
2. 完成决策流程
|
||||||
|
|
||||||
|
**期望**：
|
||||||
|
|
||||||
|
- 特殊字符正确保存和显示
|
||||||
|
- 不会导致 JSON 解析错误
|
||||||
|
|
||||||
|
## 八、附录：测试数据
|
||||||
|
|
||||||
|
### 8.1 最小有效数据
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"task": "测试任务",
|
||||||
|
"source": "test.md",
|
||||||
|
"items": [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"title": "测试问题",
|
||||||
|
"options": [
|
||||||
|
{"value": "a", "label": "选项A"},
|
||||||
|
{"value": "b", "label": "选项B"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.2 完整数据
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"task": "实现用户认证模块",
|
||||||
|
"source": "task-now.md",
|
||||||
|
"items": [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"title": "认证方式选择",
|
||||||
|
"location": {
|
||||||
|
"file": "task-now.md",
|
||||||
|
"start": 5,
|
||||||
|
"end": 7
|
||||||
|
},
|
||||||
|
"context": "任务描述中未明确指定认证方式，需要确认",
|
||||||
|
"options": [
|
||||||
|
{
|
||||||
|
"value": "jwt",
|
||||||
|
"label": "JWT Token 认证",
|
||||||
|
"score": 85,
|
||||||
|
"pros": ["无状态", "易于扩展", "跨域友好"],
|
||||||
|
"cons": ["Token 无法主动失效", "需要处理刷新"]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"value": "session",
|
||||||
|
"label": "Session 认证",
|
||||||
|
"score": 70,
|
||||||
|
"pros": ["实现简单", "可主动失效"],
|
||||||
|
"cons": ["需要存储", "扩展性差"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"recommend": "jwt"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 2,
|
||||||
|
"title": "密码加密算法",
|
||||||
|
"context": "选择密码存储的加密算法",
|
||||||
|
"options": [
|
||||||
|
{
|
||||||
|
"value": "bcrypt",
|
||||||
|
"label": "bcrypt",
|
||||||
|
"score": 90,
|
||||||
|
"pros": ["安全性高", "自带盐值"],
|
||||||
|
"cons": ["计算较慢"]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"value": "argon2",
|
||||||
|
"label": "Argon2",
|
||||||
|
"score": 95,
|
||||||
|
"pros": ["最新标准", "抗GPU攻击"],
|
||||||
|
"cons": ["库支持较少"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"recommend": "bcrypt"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.3 期望的决策结果
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"decisions": [
|
||||||
|
{"id": 1, "chosen": "jwt"},
|
||||||
|
{"id": 2, "chosen": "bcrypt", "note": "团队更熟悉 bcrypt"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 九、相关文档
|
||||||
|
|
||||||
|
- [decide 详细设计入口](README.md)
|
||||||
|
- [CLI 规格](cli.md)
|
||||||
|
- [HTTP 服务设计](server.md)
|
||||||
|
- [Web 前端设计](web.md)
|
||||||
|
- [数据存储设计](storage.md)
|
||||||
560
aide-program/docs/commands/decide/web.md
Normal file
560
aide-program/docs/commands/decide/web.md
Normal file
@@ -0,0 +1,560 @@
|
|||||||
|
# aide decide Web 前端设计
|
||||||
|
|
||||||
|
## 一、概述
|
||||||
|
|
||||||
|
aide decide 的 Web 前端提供待定项确认界面，供用户选择选项并提交决策。
|
||||||
|
|
||||||
|
### 1.1 技术选型
|
||||||
|
|
||||||
|
| 技术 | 选择 | 理由 |
|
||||||
|
|------|------|------|
|
||||||
|
| 框架 | 纯 HTML/CSS/JS | 无需构建工具，无 Node.js 依赖 |
|
||||||
|
| 样式 | 原生 CSS | 简单场景无需预处理器 |
|
||||||
|
| 交互 | 原生 JavaScript | 避免引入框架依赖 |
|
||||||
|
|
||||||
|
### 1.2 设计原则
|
||||||
|
|
||||||
|
- **简洁**：聚焦核心功能，无多余装饰
|
||||||
|
- **清晰**：信息层次分明，操作明确
|
||||||
|
- **可用**：支持主流浏览器，无障碍友好
|
||||||
|
|
||||||
|
## 二、页面结构
|
||||||
|
|
||||||
|
### 2.1 整体布局
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ ┌─────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ 页面头部 │ │
|
||||||
|
│ │ 标题: Aide 待定项确认 │ │
|
||||||
|
│ │ 任务: <task> │ │
|
||||||
|
│ │ 来源: <source> │ │
|
||||||
|
│ └─────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ 待定项列表 │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ┌─────────────────────────────────────────────┐ │ │
|
||||||
|
│ │ │ 待定项卡片 1 │ │ │
|
||||||
|
│ │ │ ... │ │ │
|
||||||
|
│ │ └─────────────────────────────────────────────┘ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ┌─────────────────────────────────────────────┐ │ │
|
||||||
|
│ │ │ 待定项卡片 2 │ │ │
|
||||||
|
│ │ │ ... │ │ │
|
||||||
|
│ │ └─────────────────────────────────────────────┘ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ └─────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ 页面底部 │ │
|
||||||
|
│ │ [提交决策] │ │
|
||||||
|
│ └─────────────────────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 待定项卡片结构
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ 1. <title> [推荐: xxx] │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ <context> │
|
||||||
|
│ │
|
||||||
|
│ 位置: <file>:<start>-<end> │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ 选项: │
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ ○ <option_a.label> 评分: 85 │ │
|
||||||
|
│ │ 优点: xxx, xxx │ │
|
||||||
|
│ │ 缺点: xxx │ │
|
||||||
|
│ └─────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ ● <option_b.label> ← 已选中 评分: 70│ │
|
||||||
|
│ │ 优点: xxx │ │
|
||||||
|
│ │ 缺点: xxx, xxx │ │
|
||||||
|
│ └─────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ 备注（可选）: │
|
||||||
|
│ ┌─────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ │ │
|
||||||
|
│ └─────────────────────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## 三、HTML 结构原型
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="zh-CN">
|
||||||
|
<head>
|
||||||
|
<meta charset="UTF-8">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||||
|
<title>Aide 待定项确认</title>
|
||||||
|
<link rel="stylesheet" href="/style.css">
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div class="container">
|
||||||
|
<!-- 页面头部 -->
|
||||||
|
<header class="header">
|
||||||
|
<h1>Aide 待定项确认</h1>
|
||||||
|
<div class="task-info">
|
||||||
|
<p><strong>任务:</strong> <span id="task-name"></span></p>
|
||||||
|
<p><strong>来源:</strong> <span id="task-source"></span></p>
|
||||||
|
</div>
|
||||||
|
</header>
|
||||||
|
|
||||||
|
<!-- 待定项列表 -->
|
||||||
|
<main class="items-container" id="items-container">
|
||||||
|
<!-- 动态生成待定项卡片 -->
|
||||||
|
</main>
|
||||||
|
|
||||||
|
<!-- 页面底部 -->
|
||||||
|
<footer class="footer">
|
||||||
|
<div class="progress">
|
||||||
|
<span id="progress-text">已完成 0/0 项</span>
|
||||||
|
</div>
|
||||||
|
<button class="submit-btn" id="submit-btn" disabled>
|
||||||
|
提交决策
|
||||||
|
</button>
|
||||||
|
</footer>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<!-- 提交成功提示 -->
|
||||||
|
<div class="success-overlay" id="success-overlay" hidden>
|
||||||
|
<div class="success-message">
|
||||||
|
<h2>决策已提交</h2>
|
||||||
|
<p>您可以关闭此页面</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<script src="/app.js"></script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.1 待定项卡片模板
|
||||||
|
|
||||||
|
```html
|
||||||
|
<article class="item-card" data-item-id="{id}">
|
||||||
|
<header class="item-header">
|
||||||
|
<h2 class="item-title">
|
||||||
|
<span class="item-number">{id}.</span>
|
||||||
|
{title}
|
||||||
|
</h2>
|
||||||
|
<span class="recommend-badge" data-show="{hasRecommend}">
|
||||||
|
推荐: {recommend}
|
||||||
|
</span>
|
||||||
|
</header>
|
||||||
|
|
||||||
|
<div class="item-context" data-show="{hasContext}">
|
||||||
|
{context}
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div class="item-location" data-show="{hasLocation}">
|
||||||
|
位置: {file}:{start}-{end}
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div class="options-list">
|
||||||
|
<!-- 选项列表 -->
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div class="item-note">
|
||||||
|
<label for="note-{id}">备注（可选）:</label>
|
||||||
|
<textarea id="note-{id}" placeholder="添加补充说明..."></textarea>
|
||||||
|
</div>
|
||||||
|
</article>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 选项模板
|
||||||
|
|
||||||
|
```html
|
||||||
|
<label class="option-item" data-value="{value}" data-recommended="{isRecommended}">
|
||||||
|
<input type="radio" name="item-{itemId}" value="{value}">
|
||||||
|
<div class="option-content">
|
||||||
|
<div class="option-header">
|
||||||
|
<span class="option-label">{label}</span>
|
||||||
|
<span class="option-score" data-show="{hasScore}">
|
||||||
|
评分: {score}
|
||||||
|
</span>
|
||||||
|
</div>
|
||||||
|
<div class="option-details" data-show="{hasDetails}">
|
||||||
|
<div class="option-pros" data-show="{hasPros}">
|
||||||
|
<strong>优点:</strong> {pros}
|
||||||
|
</div>
|
||||||
|
<div class="option-cons" data-show="{hasCons}">
|
||||||
|
<strong>缺点:</strong> {cons}
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</label>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 四、CSS 样式规范
|
||||||
|
|
||||||
|
### 4.1 设计变量
|
||||||
|
|
||||||
|
```css
|
||||||
|
:root {
|
||||||
|
/* 颜色 */
|
||||||
|
--color-primary: #2563eb;
|
||||||
|
--color-primary-hover: #1d4ed8;
|
||||||
|
--color-success: #16a34a;
|
||||||
|
--color-warning: #ca8a04;
|
||||||
|
--color-error: #dc2626;
|
||||||
|
--color-text: #1f2937;
|
||||||
|
--color-text-secondary: #6b7280;
|
||||||
|
--color-border: #e5e7eb;
|
||||||
|
--color-background: #f9fafb;
|
||||||
|
--color-card: #ffffff;
|
||||||
|
|
||||||
|
/* 间距 */
|
||||||
|
--spacing-xs: 4px;
|
||||||
|
--spacing-sm: 8px;
|
||||||
|
--spacing-md: 16px;
|
||||||
|
--spacing-lg: 24px;
|
||||||
|
--spacing-xl: 32px;
|
||||||
|
|
||||||
|
/* 圆角 */
|
||||||
|
--radius-sm: 4px;
|
||||||
|
--radius-md: 8px;
|
||||||
|
--radius-lg: 12px;
|
||||||
|
|
||||||
|
/* 阴影 */
|
||||||
|
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
|
||||||
|
--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
|
||||||
|
|
||||||
|
/* 字体 */
|
||||||
|
--font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
|
||||||
|
--font-size-sm: 14px;
|
||||||
|
--font-size-md: 16px;
|
||||||
|
--font-size-lg: 18px;
|
||||||
|
--font-size-xl: 24px;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 关键样式类
|
||||||
|
|
||||||
|
| 类名 | 用途 |
|
||||||
|
|------|------|
|
||||||
|
| `.container` | 页面容器，最大宽度 800px，居中 |
|
||||||
|
| `.header` | 页面头部 |
|
||||||
|
| `.item-card` | 待定项卡片 |
|
||||||
|
| `.item-card.completed` | 已选择的卡片（边框高亮） |
|
||||||
|
| `.option-item` | 选项容器 |
|
||||||
|
| `.option-item.selected` | 已选中的选项（背景高亮） |
|
||||||
|
| `.option-item[data-recommended="true"]` | 推荐选项（特殊标记） |
|
||||||
|
| `.submit-btn` | 提交按钮 |
|
||||||
|
| `.submit-btn:disabled` | 禁用状态（未完成所有选择） |
|
||||||
|
| `.success-overlay` | 提交成功遮罩 |
|
||||||
|
|
||||||
|
### 4.3 响应式设计
|
||||||
|
|
||||||
|
虽然主要面向桌面浏览器，但应保证基本的响应式支持：
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* 小屏幕适配 */
|
||||||
|
@media (max-width: 640px) {
|
||||||
|
.container {
|
||||||
|
padding: var(--spacing-sm);
|
||||||
|
}
|
||||||
|
|
||||||
|
.item-card {
|
||||||
|
padding: var(--spacing-md);
|
||||||
|
}
|
||||||
|
|
||||||
|
.option-details {
|
||||||
|
flex-direction: column;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 五、JavaScript 交互逻辑
|
||||||
|
|
||||||
|
### 5.1 应用状态
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const AppState = {
|
||||||
|
task: "", // 任务名称
|
||||||
|
source: "", // 来源文档
|
||||||
|
items: [], // 待定项列表
|
||||||
|
decisions: {}, // 当前决策 { itemId: chosenValue }
|
||||||
|
notes: {}, // 用户备注 { itemId: noteText }
|
||||||
|
isSubmitting: false // 提交中标志
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 核心函数
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
/**
|
||||||
|
* 初始化应用
|
||||||
|
* 1. 从 API 加载数据
|
||||||
|
* 2. 渲染界面
|
||||||
|
* 3. 绑定事件
|
||||||
|
*/
|
||||||
|
async function init(): void
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 加载待定项数据
|
||||||
|
* GET /api/items
|
||||||
|
*/
|
||||||
|
async function loadItems(): DecideInput
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 渲染待定项列表
|
||||||
|
*/
|
||||||
|
function renderItems(data: DecideInput): void
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 渲染单个待定项卡片
|
||||||
|
*/
|
||||||
|
function renderItemCard(item: DecideItem): HTMLElement
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 渲染选项列表
|
||||||
|
*/
|
||||||
|
function renderOptions(item: DecideItem): HTMLElement
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 处理选项选择
|
||||||
|
*/
|
||||||
|
function handleOptionSelect(itemId: number, value: string): void
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 处理备注输入
|
||||||
|
*/
|
||||||
|
function handleNoteInput(itemId: number, note: string): void
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 更新进度显示
|
||||||
|
*/
|
||||||
|
function updateProgress(): void
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 检查是否可以提交
|
||||||
|
*/
|
||||||
|
function canSubmit(): boolean
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 提交决策
|
||||||
|
* POST /api/submit
|
||||||
|
*/
|
||||||
|
async function submitDecisions(): void
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 显示成功提示
|
||||||
|
*/
|
||||||
|
function showSuccess(): void
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 显示错误提示
|
||||||
|
*/
|
||||||
|
function showError(message: string): void
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.3 事件绑定
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// 页面加载完成后初始化
|
||||||
|
document.addEventListener('DOMContentLoaded', init);
|
||||||
|
|
||||||
|
// 选项选择事件（事件委托）
|
||||||
|
document.getElementById('items-container').addEventListener('change', (e) => {
|
||||||
|
if (e.target.type === 'radio') {
|
||||||
|
const itemId = parseInt(e.target.name.replace('item-', ''));
|
||||||
|
const value = e.target.value;
|
||||||
|
handleOptionSelect(itemId, value);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// 备注输入事件（事件委托）
|
||||||
|
document.getElementById('items-container').addEventListener('input', (e) => {
|
||||||
|
if (e.target.tagName === 'TEXTAREA') {
|
||||||
|
const itemId = parseInt(e.target.id.replace('note-', ''));
|
||||||
|
handleNoteInput(itemId, e.target.value);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// 提交按钮点击
|
||||||
|
document.getElementById('submit-btn').addEventListener('click', submitDecisions);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.4 交互流程
|
||||||
|
|
||||||
|
```
|
||||||
|
@startuml
|
||||||
|
skinparam defaultFontName "PingFang SC"
|
||||||
|
|
||||||
|
start
|
||||||
|
|
||||||
|
:页面加载;
|
||||||
|
|
||||||
|
:调用 init();
|
||||||
|
|
||||||
|
:GET /api/items;
|
||||||
|
|
||||||
|
if (加载成功?) then (是)
|
||||||
|
:渲染待定项列表;
|
||||||
|
:绑定事件监听;
|
||||||
|
else (否)
|
||||||
|
:显示错误信息;
|
||||||
|
stop
|
||||||
|
endif
|
||||||
|
|
||||||
|
repeat
|
||||||
|
:用户操作;
|
||||||
|
switch (操作类型)
|
||||||
|
case (选择选项)
|
||||||
|
:更新 decisions;
|
||||||
|
:高亮选中选项;
|
||||||
|
:更新进度;
|
||||||
|
case (输入备注)
|
||||||
|
:更新 notes;
|
||||||
|
case (点击提交)
|
||||||
|
if (所有项已选择?) then (是)
|
||||||
|
:禁用提交按钮;
|
||||||
|
:POST /api/submit;
|
||||||
|
if (提交成功?) then (是)
|
||||||
|
:显示成功提示;
|
||||||
|
stop
|
||||||
|
else (否)
|
||||||
|
:显示错误信息;
|
||||||
|
:恢复提交按钮;
|
||||||
|
endif
|
||||||
|
else (否)
|
||||||
|
:提示完成所有选择;
|
||||||
|
endif
|
||||||
|
endswitch
|
||||||
|
repeat while (继续操作?)
|
||||||
|
|
||||||
|
stop
|
||||||
|
@enduml
|
||||||
|
```
|
||||||
|
|
||||||
|
## 六、错误处理
|
||||||
|
|
||||||
|
### 6.1 加载错误
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
async function loadItems() {
|
||||||
|
try {
|
||||||
|
const response = await fetch('/api/items');
|
||||||
|
if (!response.ok) {
|
||||||
|
throw new Error(`HTTP ${response.status}`);
|
||||||
|
}
|
||||||
|
return await response.json();
|
||||||
|
} catch (error) {
|
||||||
|
showError('无法加载待定项数据，请刷新页面重试');
|
||||||
|
throw error;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.2 提交错误
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
async function submitDecisions() {
|
||||||
|
try {
|
||||||
|
const response = await fetch('/api/submit', {
|
||||||
|
method: 'POST',
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
body: JSON.stringify(buildDecisionData())
|
||||||
|
});
|
||||||
|
|
||||||
|
if (!response.ok) {
|
||||||
|
const error = await response.json();
|
||||||
|
throw new Error(error.detail || '提交失败');
|
||||||
|
}
|
||||||
|
|
||||||
|
showSuccess();
|
||||||
|
} catch (error) {
|
||||||
|
showError(`提交失败: ${error.message}`);
|
||||||
|
AppState.isSubmitting = false;
|
||||||
|
updateSubmitButton();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.3 错误提示样式
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="error-toast" id="error-toast" hidden>
|
||||||
|
<span class="error-icon">✗</span>
|
||||||
|
<span class="error-message" id="error-message"></span>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 七、无障碍支持
|
||||||
|
|
||||||
|
### 7.1 语义化 HTML
|
||||||
|
|
||||||
|
- 使用 `<header>`, `<main>`, `<footer>`, `<article>` 等语义标签
|
||||||
|
- 使用 `<label>` 关联表单控件
|
||||||
|
- 使用 `<fieldset>` 和 `<legend>` 组织选项组
|
||||||
|
|
||||||
|
### 7.2 键盘导航
|
||||||
|
|
||||||
|
- 所有交互元素可通过 Tab 键访问
|
||||||
|
- 选项可通过方向键切换
|
||||||
|
- Enter 键可触发提交
|
||||||
|
|
||||||
|
### 7.3 ARIA 属性
|
||||||
|
|
||||||
|
```html
|
||||||
|
<main role="main" aria-label="待定项列表">
|
||||||
|
<article role="group" aria-labelledby="item-title-1">
|
||||||
|
<h2 id="item-title-1">...</h2>
|
||||||
|
<div role="radiogroup" aria-label="选项">
|
||||||
|
...
|
||||||
|
</div>
|
||||||
|
</article>
|
||||||
|
</main>
|
||||||
|
|
||||||
|
<button aria-disabled="true" aria-describedby="submit-hint">
|
||||||
|
提交决策
|
||||||
|
</button>
|
||||||
|
<span id="submit-hint" class="sr-only">
|
||||||
|
请先完成所有待定项的选择
|
||||||
|
</span>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 八、浏览器兼容性
|
||||||
|
|
||||||
|
### 8.1 目标浏览器
|
||||||
|
|
||||||
|
| 浏览器 | 最低版本 |
|
||||||
|
|--------|----------|
|
||||||
|
| Chrome | 80+ |
|
||||||
|
| Firefox | 75+ |
|
||||||
|
| Safari | 13+ |
|
||||||
|
| Edge | 80+ |
|
||||||
|
|
||||||
|
### 8.2 避免使用的特性
|
||||||
|
|
||||||
|
- CSS Grid 子网格（subgrid）
|
||||||
|
- CSS 容器查询（container queries）
|
||||||
|
- JavaScript 可选链操作符（?.）在旧版本中不支持
|
||||||
|
- Top-level await
|
||||||
|
|
||||||
|
### 8.3 Polyfill 策略
|
||||||
|
|
||||||
|
不引入 polyfill，通过避免新特性保证兼容性。
|
||||||
|
|
||||||
|
## 九、文件清单
|
||||||
|
|
||||||
|
```
|
||||||
|
aide/decide/web/
|
||||||
|
├── index.html # 主页面
|
||||||
|
├── style.css # 样式文件
|
||||||
|
└── app.js # 交互逻辑
|
||||||
|
```
|
||||||
|
|
||||||
|
## 十、相关文档
|
||||||
|
|
||||||
|
- [decide 详细设计入口](README.md)
|
||||||
|
- [HTTP 服务设计](server.md)
|
||||||
|
- [数据格式文档](../../formats/data.md)
|
||||||
@@ -1,7 +1,8 @@
|
|||||||
1. 首先阅读 @statements/optimize.md，还有 @README.md 并根据其指引了解跟aide flow有关的所有信息
|
1. 首先阅读 @statements/optimize.md，还有 @README.md 并根据其指引了解跟aide decide有关的所有信息
|
||||||
2. 我想对aide flow开始详细设计，我将在完成设计后将所有设计文档打包交给其他开发人员进行开发，
|
2. 对aide decide开始详细设计，我将在完成设计后将所有设计文档打包交给其他开发人员进行开发，
|
||||||
|
- 设计文档中要有一个用于指导接手人员的入口文档，其中要说明：需要了解哪些信息、需要做什么事
|
||||||
|
|
||||||
对开发文档完善程度的预期是：可以仅靠整套文档和可能含有的其他附属文件的内容，以此为确定目标和完整指导，开始目标程序的实际开发工作，直到构建产出程序和通过测试运行
|
对开发文档完善程度的预期是：可以仅靠整套文档和可能含有的其他附属文件的内容（我将会打包aide-program目录），以此为确定目标和完整指导（aide-program/docs/ 目录下的相关文档），开始目标程序的实际开发工作，直到构建产出程序和通过测试运行（运行aide decide -h 及其一系列命令与参数）
|
||||||
|
|
||||||
切记，非常重要：开发文档中不允许给出代码片段、实现代码，最多只能出现类型与数据结构伪代码原型、方法签名、业务逻辑流程的plantuml流程图、API约定
|
切记，非常重要：开发文档中不允许给出代码片段、实现代码，最多只能出现类型与数据结构伪代码原型、方法签名、业务逻辑流程的plantuml流程图、API约定
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user