refactor: 整理项目根目录结构

整理内容: - 删除 60+ 临时测试输出文件 (*.txt) - 移动二进制文件到 bin/ 目录 - 移动 Shell 脚本到 scripts/ 目录 - scripts/dev/: check_gitea.sh, check_sub2api.sh, run_tests.sh - scripts/deploy/: deploy_*.sh, simple_deploy.sh - scripts/ops/: fix_nginx.sh, fix_ssl.sh, install_docker.sh - scripts/test/: test_*.sh, test_*.bat - 移动批处理文件到 scripts/ - 移动 Python 脚本到 tools/ - 清理临时日志文件保留根目录必要文件: - go.mod, go.sum, go.work - Makefile, docker-compose.yml - .env.example, .gitignore - README.md, AGENTS.md, DEPLOY_GUIDE.md 验证: go build ./... && go test ./... 通过
2026-04-07 18:10:36 +08:00
parent 5dbb530b76
commit 5b6bd93179
152 changed files with 8775 additions and 4084 deletions
--- a/docs/team/PRODUCTION_CHECKLIST.md
+++ b/docs/team/PRODUCTION_CHECKLIST.md
@@ -1,10 +1,42 @@
 # 生产级发布清单

-版本：2.0  
-更新时间：2026-03-25
+版本：3.0  
+更新时间：2026-04-02

 本清单用于发布前、发布后和对外表述前的最后核查。

+## 0. PR 提交前检查（必须通过）
+
+### 0.1 分支与提交
+
+- [ ] 功能分支从 `main` 最新状态拉取
+- [ ] 每个提交是可独立验证的最小单元
+- [ ] 提交信息格式：`类型: 简短描述`
+
+### 0.2 代码审查
+
+- [ ] 至少 1 人完成代码审查
+- [ ] 所有 🔴 阻塞问题已修复
+- [ ] 所有 🟡 建议问题已有修复计划
+
+### 0.3 验证矩阵
+
+- [ ] 后端：`go test ./... -count=1` 通过
+- [ ] 后端：`go vet ./...` 通过
+- [ ] 后端：`go build ./cmd/server` 通过
+- [ ] 前端：`npm.cmd run lint` 通过
+- [ ] 前端：`npm.cmd run build` 通过
+- [ ] 前端：`npm.cmd run test -- --run` 全绿（如改动前端代码）
+- [ ] 真实浏览器 E2E：`npm.cmd run e2e:full:win` 通过（如涉及认证/导航/主流程）
+
+### 0.4 文档
+
+- [ ] PR 描述包含变更目的、验证命令及结果、影响范围
+- [ ] API 文档已更新（如改动 API）
+- [ ] `docs/status/REAL_PROJECT_STATUS.md` 已同步更新（如改变真实结论）
+
+---
+
 ## 1. 发布前必须完成

 ### 1.1 代码与构建
--- a/docs/team/PROJECT_EXPERIENCE_SUMMARY.md
+++ b/docs/team/PROJECT_EXPERIENCE_SUMMARY.md
@@ -74,10 +74,80 @@

 ## 10. 接下来仍然属于真实缺口的部分

-以下不是“代码没写完”，而是仍未形成完整外部交付证据：
+以下不是"代码没写完"，而是仍未形成完整外部交付证据：

 - 真实第三方 OAuth live browser validation
 - 外部 Secrets Manager / KMS 证据
 - 多环境 CI/CD 密钥分发证据
 - 跨历史版本 schema downgrade 回滚证据
 - 完整 OS 级自动化证据
+
+## 11. 多智能体并行是提效的关键路径
+
+- 2026-04-02 起，引入 Gitea 远程仓库作为协作基线。
+- 后续迭代采用多智能体并行模式：
+  - 方案对比阶段：多个智能体并行输出不同方案，由决策者选择最优解。
+  - 实现阶段：无依赖的任务并行执行，有依赖的任务按拓扑序执行。
+  - 验证阶段：后端测试、前端 lint/build、E2E 测试并行执行。
+- 经验教训：
+  - 任务拆分必须明确依赖关系，否则并行执行会互相阻塞。
+  - 多个智能体修改同一文件时，必须在任务拆分阶段识别并协调。
+  - 验证阶段并行执行可以显著缩短反馈周期。
+
+## 12. 方案对比能避免走弯路
+
+- 新增核心功能或架构变更时，必须先做方案对比。
+- 对比维度：实现复杂度、性能影响、可维护性、与现有架构的兼容性、测试难度。
+- 选定的方案必须记录决策原因，被否决的方案必须记录否决原因。
+- 经验教训：
+  - 不经过方案对比直接实现，容易在后期发现更优方案，导致返工。
+  - 对比记录是团队知识沉淀的重要组成部分。
+
+## 13. 快速迭代的核心是小步验证
+
+- 每个迭代周期不超过 2 小时。
+- 每个迭代完成后立即执行验证矩阵。
+- 如果验证失败，立即回滚到上一个可用状态。
+- 阻塞超过 30 分钟必须上报并寻求协助。
+- 经验教训：
+  - 大步提交会增加回滚成本和排查难度。
+  - 快速验证能尽早发现设计断链和实现偏差。
+  - 持续验证比最终验证更可靠。
+
+## 14. 测试全面性决定上线信心
+
+- 新增代码必须有对应测试。
+- 修复 bug 必须有回归测试。
+- 安全敏感代码必须有边界条件测试。
+- 经验教训：
+  - 没有测试的代码变更是定时炸弹。
+  - 回归测试能防止已修复的问题再次出现。
+  - 边界条件测试能发现最隐蔽的缺陷。
+
+## 15. 虚假测试比没有测试更危险
+
+- 虚假测试会给人"已通过"的错觉，推迟问题暴露时间并放大排查成本。
+- 项目中发现过的虚假测试模式：
+  - 使用 mock 响应替代真实 API 调用进行 E2E 验证
+  - 在测试中硬编码预期结果而不走真实业务链路
+  - 跳过认证、权限校验等安全环节直接断言页面状态
+  - 在测试中使用 `context.Background()` 绕过上下文治理
+- 结论：
+  - E2E 测试必须启动真实后端进程和前端服务器
+  - 必须通过真实浏览器（CDP 协议）执行用户操作
+  - 必须验证真实 API 响应和真实数据库状态变化
+  - 当前项目的真实 E2E 路径是 `cd frontend/admin && npm.cmd run e2e:full:win`
+
+## 16. 浏览器自动化工具是 E2E 能力的延伸
+
+- Playwright CDP E2E 已经覆盖管理员引导、注册、邮箱激活、登录、认证工作流、响应式布局、桌面/移动端导航。
+- 但仍有一些复杂交互场景未被覆盖：
+  - 设备信任管理
+  - 批量操作
+  - 系统设置页
+  - 管理员管理页
+  - 登录日志导出
+- 未来应引入 `agent-browser`（bb browse）等浏览器自动化工具：
+  - 补充 Playwright 未覆盖的交互场景
+  - 增加复杂业务流程的端到端验证
+  - 提供更灵活的用户操作模拟能力
--- a/docs/team/QUALITY_STANDARD.md
+++ b/docs/team/QUALITY_STANDARD.md
@@ -1,18 +1,19 @@
 # 项目工程规则

-版本：2.0  
-更新时间：2026-03-25
+版本：3.0  
+更新时间：2026-04-02

 本规则是当前项目的真实工程约束，不是泛化建议。

 ## 1. 基本原则

- 结论必须可验证，不能靠口头“已完成”。
+- 结论必须可验证，不能靠口头"已完成"。
 - 优先真实闭环，拒绝 fake success、临时掩盖和只过局部样例。
 - 任何上线结论都必须区分：
  - 浏览器级真实验证
  - OS 级自动化
  - 外部交付治理证据
+- 迭代速度优先，但速度不牺牲质量：快速验证、快速反馈、快速修正。

 ## 2. 后端规则

@@ -50,7 +51,7 @@

 ### 3.1 浏览器行为

- 原生弹窗和 popup 不是“可以接受的小问题”，而是验收失败信号。
+- 原生弹窗和 popup 不是"可以接受的小问题"，而是验收失败信号。
 - 必须阻断并记录：
  - `alert`
  - `confirm`
@@ -105,16 +106,151 @@ npm.cmd run e2e:full:win
 - `window` 防线
 - 用户主流程

-## 5. 文档规则
+### 4.4 测试覆盖要求
+
+- 新增代码必须有对应测试。
+- 修复 bug 必须有回归测试。
+- 安全敏感代码必须有边界条件测试。
+- 每个函数/方法必须有对应的单元测试。
+- 跨模块交互必须有集成测试。
+- 用户主流程必须有真实浏览器 E2E 测试。
+
+### 4.5 防虚假测试规则
+
+- 禁止使用 mock 响应替代真实 API 调用进行 E2E 验证。
+- 禁止在测试中硬编码预期结果而不走真实业务链路。
+- 禁止跳过认证、权限校验等安全环节直接断言页面状态。
+- 禁止在测试中使用 `context.Background()` 绕过上下文治理。
+- 禁止在测试中注入假数据后直接断言页面显示而不验证后端存储。
+- 禁止用 `smoke` 脚本的结果替代主验收路径。
+
+### 4.6 E2E 测试架构要求
+
+- E2E 测试必须：
+  - 启动真实后端进程（隔离测试数据库）
+  - 启动真实前端开发服务器
+  - 通过真实浏览器（CDP 协议）执行用户操作
+  - 验证真实 API 响应（非 mock）
+  - 验证真实数据库状态变化
+- 当前项目的真实 E2E 路径：
+  - Playwright CDP E2E：`cd frontend/admin && npm.cmd run e2e:full:win`
+  - 覆盖场景：管理员引导、注册、邮箱激活、登录、认证工作流、响应式布局、桌面/移动端导航
+- E2E 测试架构组件：
+  - Playwright CDP 协议连接真实浏览器
+  - 隔离测试数据库（临时 SQLite 文件）
+  - 本地 SMTP 捕获服务（验证邮件发送）
+  - 信号收集器（console errors、dialogs、popups、request failures、401 responses）
+  - 多视口验证（desktop 1440x960、tablet 820x1180、mobile 390x844）
+- 未来增强方向：
+  - 引入 `agent-browser`（bb browse）等浏览器自动化工具，补充 Playwright 未覆盖的交互场景
+  - 增加复杂业务流程的端到端验证（如设备信任、批量操作、系统设置等）
+
+## 5. 方案对比机制
+
+### 5.1 何时需要方案对比
+
+- 新增核心功能或架构变更时。
+- 存在多种可行实现路径时。
+- 性能优化涉及重大权衡时。
+
+### 5.2 对比维度
+
+- 实现复杂度（人天/智能体时）
+- 性能影响
+- 可维护性
+- 与现有架构的兼容性
+- 测试难度
+
+### 5.3 决策记录
+
+- 选定的方案必须记录决策原因。
+- 被否决的方案必须记录否决原因。
+- 决策记录写入 PR 描述或 `docs/decisions/` 目录。
+
+## 6. 文档规则

 - 真实状态变化后必须更新 `docs/status/REAL_PROJECT_STATUS.md`。
 - 团队长期规则变化后必须更新本文件和 `docs/team/PRODUCTION_CHECKLIST.md`。
 - 形成阶段性经验后必须沉淀到 `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`。
+- 新增架构决策时，写入 `docs/decisions/` 目录。

-## 6. 禁止项
+## 7. Gitea 协作规则

- 禁止“只跑单个用例就宣布收口”。
- 禁止“因为环境受限就把诊断脚本包装成主验收路径”。
- 禁止“为了通过测试保留运行时 mock provider”。
- 禁止“服务层通过具体仓储断言完成业务”。
- 禁止“因为终端乱码就把乱码字面量继续扩散到业务逻辑”。
+### 7.1 分支策略
+
+- `main` 分支：始终可构建、可测试通过，是唯一的发布基线。
+- `feature/<简短描述>`：功能分支，每个独立功能一个分支。
+- `fix/<简短描述>`：修复分支，每个独立修复一个分支。
+- 禁止直接推送到 `main`，所有变更必须通过 PR 合并。
+
+### 7.2 PR 规范
+
+- 每个 PR 只包含一个逻辑变更。
+- PR 描述必须包含：
+  - 变更目的（1-2 句）
+  - 验证命令及结果
+  - 影响范围（后端/前端/文档）
+- PR 合并前必须通过最低验证矩阵。
+
+### 7.3 提交规范
+
+- 提交信息格式：`类型: 简短描述`
+  - 类型：`feat`、`fix`、`test`、`docs`、`refactor`、`chore`
+- 每次提交应该是可独立验证的最小单元。
+
+## 8. 多智能体并行工作流
+
+### 8.1 任务拆分原则
+
+- 每个任务必须是独立的、可并行执行的单元。
+- 任务之间如果有依赖，必须明确标注依赖关系和执行顺序。
+- 前后端分离的任务优先并行执行。
+
+### 8.2 并行执行模式
+
+- **方案对比阶段**：多个智能体并行输出不同方案，由决策者选择最优解。
+- **实现阶段**：无依赖的任务并行执行，有依赖的任务按拓扑序执行。
+- **验证阶段**：后端测试、前端 lint/build、E2E 测试并行执行。
+
+### 8.3 智能体分工
+
+- **规划智能体**：负责任务拆分、依赖分析、方案对比。
+- **实现智能体**：负责编码，每个智能体负责一个独立任务。
+- **验证智能体**：负责测试执行、结果验证、报告生成。
+- **审查智能体**：负责代码审查、安全审查、性能审查。
+
+### 8.4 冲突解决
+
+- 多个智能体修改同一文件时，必须在任务拆分阶段识别并协调。
+- 如果发生合并冲突，优先保留功能完整的版本，手动合并差异。
+
+## 9. 快速迭代规则
+
+### 9.1 迭代节奏
+
+- 小步快跑：每个迭代周期不超过 2 小时。
+- 持续验证：每个迭代完成后立即执行验证矩阵。
+- 快速回滚：如果验证失败，立即回滚到上一个可用状态。
+
+### 9.2 阻塞处理
+
+- 遇到阻塞时，立即记录阻塞原因和影响范围。
+- 优先寻找替代方案，而不是等待阻塞解除。
+- 阻塞超过 30 分钟必须上报并寻求协助。
+
+### 9.3 知识沉淀
+
+- 每次解决的问题必须记录解决方案。
+- 每次踩过的坑必须记录避免方法。
+- 每次验证通过的命令必须记录执行结果。
+
+## 10. 禁止项
+
+- 禁止"只跑单个用例就宣布收口"。
+- 禁止"因为环境受限就把诊断脚本包装成主验收路径"。
+- 禁止"为了通过测试保留运行时 mock provider"。
+- 禁止"服务层通过具体仓储断言完成业务"。
+- 禁止"因为终端乱码就把乱码字面量继续扩散到业务逻辑"。
+- 禁止"用 mock 响应替代真实 API 调用进行 E2E 验证"。
+- 禁止"在测试中硬编码预期结果而不走真实业务链路"。
+- 禁止"跳过认证、权限校验等安全环节直接断言页面状态"。
--- a/docs/team/WORKFLOW.md
+++ b/docs/team/WORKFLOW.md
@@ -0,0 +1,281 @@
+# 多智能体并行协作工作流
+
+版本：1.0  
+更新时间：2026-04-02
+
+本文档描述基于 Gitea 远程仓库的多智能体并行协作工作流。
+
+## 1. 工作流总览
+
+```
+需求/问题 → 规划智能体 → 任务拆分 → 方案对比(可选) → 并行实现 → 并行验证 → PR合并 → 文档同步
+```
+
+## 2. 角色定义
+
+### 2.1 规划智能体 (Planner)
+
+- **职责**：需求分析、任务拆分、依赖识别、方案对比组织
+- **输出**：任务清单、依赖图、方案对比报告（如需要）
+- **触发条件**：收到新功能需求或复杂问题
+
+### 2.2 实现智能体 (Implementer)
+
+- **职责**：编码实现、单元测试编写
+- **输出**：代码变更、测试用例
+- **触发条件**：收到明确的任务描述和验收标准
+
+### 2.3 验证智能体 (Verifier)
+
+- **职责**：执行验证矩阵、生成验证报告
+- **输出**：验证报告（通过/失败/阻塞）
+- **触发条件**：实现智能体完成编码后
+
+### 2.4 审查智能体 (Reviewer)
+
+- **职责**：代码审查、安全审查、性能审查
+- **输出**：审查报告（问题清单+优先级）
+- **触发条件**：PR 创建后
+
+## 3. 任务拆分规则
+
+### 3.1 拆分原则
+
+- 每个任务必须是独立的、可并行执行的单元
+- 任务粒度：每个任务应在 30-120 分钟内可完成
+- 前后端分离的任务必须拆分为独立任务
+- 数据库变更必须单独作为一个任务
+
+### 3.2 依赖标注
+
+- 任务之间如果有依赖，必须明确标注：
+  - `依赖: TASK-XXX`
+  - 执行顺序：`先执行 TASK-XXX，再执行 TASK-YYY`
+- 无依赖的任务标记为 `独立`
+
+### 3.3 任务模板
+
+```markdown
+### TASK-XXX: 任务名称
+**优先级**: P0/P1/P2  
+**工作量**: S(1h)/M(2h)/L(4h)  
+**依赖**: 无 / TASK-XXX  
+**负责人**: 实现智能体-A  
+
+**任务描述**:
+- 要做什么
+- 为什么做
+
+**验收标准**:
+- [ ] 标准1
+- [ ] 标准2
+
+**验证命令**:
+- 命令1
+- 命令2
+```
+
+## 4. 方案对比流程
+
+### 4.1 触发条件
+
+- 新增核心功能
+- 架构变更
+- 存在多种可行实现路径
+- 性能优化涉及重大权衡
+
+### 4.2 对比流程
+
+1. 规划智能体识别需要方案对比的任务
+2. 分配 2-3 个智能体并行输出不同方案
+3. 每个方案必须包含：
+   - 实现思路
+   - 优缺点分析
+   - 预估工作量
+   - 风险评估
+4. 决策者根据对比维度选择最优方案
+5. 记录决策原因和否决原因
+
+### 4.3 对比维度
+
+| 维度 | 说明 |
+|------|------|
+| 实现复杂度 | 人天/智能体时 |
+| 性能影响 | 对现有性能的影响 |
+| 可维护性 | 后续维护成本 |
+| 架构兼容性 | 与现有架构的匹配度 |
+| 测试难度 | 测试覆盖的难易程度 |
+
+## 5. 并行实现模式
+
+### 5.1 无依赖并行
+
+```
+TASK-A (前端) ──┐
+                ├── 并行执行
+TASK-B (后端) ──┘
+```
+
+### 5.2 有依赖串行
+
+```
+TASK-A (后端API) ──→ TASK-B (前端对接)
+```
+
+### 5.3 混合模式
+
+```
+TASK-A (数据模型) ──┬─→ TASK-B (后端Service) ──┐
+                    │                           ├── TASK-E (集成测试)
+                    └─→ TASK-C (前端页面) ──────┘
+                    │
+TASK-D (独立任务) ──┘
+```
+
+## 6. 冲突解决机制
+
+### 6.1 文件冲突预防
+
+- 任务拆分阶段识别可能被多个任务修改的文件
+- 协调修改顺序或分配不同的修改区域
+- 共享文件（如路由配置、类型定义）由单一智能体统一修改
+
+### 6.2 合并冲突处理
+
+- 优先保留功能完整的版本
+- 手动合并差异，不自动解决
+- 合并后必须重新运行验证矩阵
+
+## 7. 验证策略
+
+### 7.1 本地验证（实现智能体）
+
+- 每次提交前运行受影响的最小测试集
+- 确保代码可编译、lint 通过
+
+### 7.2 并行验证（验证智能体）
+
+- 后端测试、前端 lint/build、E2E 测试并行执行
+- 生成统一的验证报告
+
+### 7.3 PR 验证（审查智能体）
+
+- 代码审查
+- 安全审查
+- 性能审查
+- 生成审查报告
+
+## 7. E2E 测试流程
+
+### 7.1 E2E 测试架构
+
+- **Playwright CDP E2E**（主验收路径）：
+  - 命令：`cd frontend/admin && npm.cmd run e2e:full:win`
+  - 协议：Playwright 通过 CDP 连接真实浏览器
+  - 数据库：隔离测试数据库（临时 SQLite 文件）
+  - 邮件：本地 SMTP 捕获服务（验证邮件发送）
+  - 信号收集：console errors、dialogs、popups、request failures、401 responses
+  - 多视口：desktop 1440x960、tablet 820x1180、mobile 390x844
+- **覆盖场景**：
+  - 管理员引导（admin-bootstrap）
+  - 公开注册（public-registration）
+  - 邮箱激活（email-activation）
+  - 登录表面验证（login-surface）
+  - 认证工作流（auth-workflow）
+  - 响应式登录（responsive-login）
+  - 桌面/移动端导航（desktop-mobile-navigation）
+
+### 7.2 E2E 测试规则
+
+- 必须启动真实后端进程（隔离测试数据库）
+- 必须启动真实前端开发服务器
+- 必须通过真实浏览器（CDP 协议）执行用户操作
+- 必须验证真实 API 响应（非 mock）
+- 必须验证真实数据库状态变化
+- 禁止使用 mock 响应替代真实 API 调用
+- 禁止在测试中硬编码预期结果而不走真实业务链路
+- 禁止跳过认证、权限校验等安全环节直接断言页面状态
+
+### 7.3 未来 E2E 增强方向
+
+- 引入 `agent-browser`（bb browse）等浏览器自动化工具
+- 补充 Playwright 未覆盖的交互场景：
+  - 设备信任管理
+  - 批量操作
+  - 系统设置页
+  - 管理员管理页
+  - 登录日志导出
+- 增加复杂业务流程的端到端验证
+
+## 8. 文档同步规则
+
+### 8.1 必须更新的文档
+
+| 变更类型 | 必须更新的文档 |
+|----------|----------------|
+| 功能变更 | `docs/status/REAL_PROJECT_STATUS.md` |
+| API 变更 | `docs/API.md` |
+| 规则变更 | `docs/team/QUALITY_STANDARD.md` |
+| 经验沉淀 | `docs/team/PROJECT_EXPERIENCE_SUMMARY.md` |
+| 架构决策 | `docs/decisions/` |
+
+### 8.2 文档更新时机
+
+- 代码合并后立即更新相关文档
+- 文档更新作为 PR 的一部分
+
+## 9. 迭代节奏
+
+### 9.1 迭代周期
+
+- 每个迭代周期不超过 2 小时
+- 小步快跑，持续验证
+
+### 9.2 迭代流程
+
+1. **规划阶段**（10-15 分钟）
+   - 任务拆分
+   - 依赖分析
+   - 智能体分配
+
+2. **实现阶段**（60-90 分钟）
+   - 并行编码
+   - 本地验证
+
+3. **验证阶段**（15-30 分钟）
+   - 并行验证
+   - 代码审查
+   - PR 合并
+
+4. **总结阶段**（5-10 分钟）
+   - 文档同步
+   - 经验沉淀
+
+## 10. 阻塞处理
+
+### 10.1 阻塞识别
+
+- 智能体无法继续执行任务
+- 验证持续失败
+- 依赖任务未完成
+
+### 10.2 阻塞处理流程
+
+1. 记录阻塞原因和影响范围
+2. 寻找替代方案
+3. 阻塞超过 30 分钟上报
+4. 调整任务优先级或拆分方式
+
+## 11. 知识沉淀
+
+### 11.1 必须记录的内容
+
+- 解决方案（每次解决的问题）
+- 避免方法（每次踩过的坑）
+- 验证结果（每次验证通过的命令）
+
+### 11.2 沉淀位置
+
+- 短期经验：`docs/sprints/`
+- 长期经验：`docs/team/PROJECT_EXPERIENCE_SUMMARY.md`
+- 架构决策：`docs/decisions/`