refactor: 优化代码结构并修复类型问题

- 移除未使用的TabPane组件 - 修复类型定义和导入方式 - 优化mock数据源的环境变量判断逻辑 - 更新文档结构并归档旧文件 - 添加新的UI组件和Memo组件 - 调整API路径和响应处理
2026-03-23 12:41:35 +08:00
parent a037843851
commit 2b86715c09
363 changed files with 39305 additions and 40622 deletions
--- a/docs/ARCHIVE/00_Business/Governance_Standards.md
+++ b/docs/ARCHIVE/00_Business/Governance_Standards.md
@@ -0,0 +1,326 @@
+# 📋 Governance & Standards (Crawlful Hub)
+
+> **定位**：Crawlful Hub 治理与开发规范 - 包含开发风格、协作协议、任务规格及运维治理。
+> **更新日期**: 2026-03-17
+
+---
+
+## 1. 开发规范 (Development Standards)
+
+### 1.1 核心准则
+- **职责单一**: 一个文件只包含一个类或一组高度相关的函数。
+- **Zero-Mock**: 严禁在生产代码中使用硬编码的模拟数据。详见 [Mock数据规范](../../.trae/rules/project-specific-rules.md#11-mock数据规范ai上下文安全)
+- **契约优先**: 接口定义应先于实现。
+- **TypeScript 严格模式**: 详见 [TypeScript 编译规约](../01_Architecture/13_TypeScript_Standards.md) 和 [项目规则 - 第12章](../../.trae/rules/project-specific-rules.md#12-typescript-编译与类型安全)
+
+### 1.2 代码风格与规模限制
+- **命名**: 文件使用 `kebab-case`，组件 `PascalCase`，变量 `camelCase`。
+- **限制**: 单文件 ≤ 1500 行，单函数 ≤ 120 行，UI 组件 ≤ 300 行。
+
+---
+
+## 2. 任务规格与代码注释 (Task & JSDoc)
+
+### 2.1 任务规格模板 (Task Template)
+- **ID**: `[模块]-[子模块][序号]` (如 `BE-P001`, `FE-O001`, `PL-C001`)
+  - 模块: FE(前端), BE(后端), PL(插件), AI(AI), DT(数据), OP(运维)
+  - 子模块: P(商品), O(订单), F(财务), I(库存), C(采集), A(广告) 等
+- **验收**: 功能测试通过、符合规范、文档同步更新。
+
+### 2.2 任务完成时间标记规范
+
+#### 2.2.1 表格结构
+所有任务表必须包含 "完成时间" 列，表头格式如下：
+
+```markdown
+| Task ID | 闭环关联 | 任务描述 | 输入 | 输出 | 触发条件 | 状态 | 优先级 | 依赖 | 预计耗时 | 负责人 | 完成时间 |
+```
+
+#### 2.2.2 完成时间格式
+- 已完成任务的完成时间统一格式为 `YYYY-MM-DD`
+- 未完成任务的完成时间字段为空
+- 历史已完成任务的完成时间统一设置为项目基准日期
+
+#### 2.2.3 状态标记
+- 已完成任务状态标记为 `✅ completed` 或 `✅ 已完成`
+- 未完成任务状态标记为 `pending` 或其他未完成状态
+
+#### 2.2.4 操作流程
+1. **添加完成时间列**：为所有任务表添加 "完成时间" 列
+2. **标记已完成任务**：为所有状态为已完成的任务添加完成时间
+3. **保持未完成任务**：未完成任务的完成时间字段保持为空
+4. **新增任务处理**：新添加的任务，完成后及时添加完成时间
+
+#### 2.2.5 示例
+
+```markdown
+| Task ID | 闭环关联 | 任务描述 | 输入 | 输出 | 触发条件 | 状态 | 优先级 | 依赖 | 预计耗时 | 负责人 | 完成时间 |
+| ------- | -------- | -------- | ---- | ---- | -------- | ---- | ------ | ---- | -------- | ------ | -------- |
+| FE-P001 | 商品刊登闭环 | 渲染商品列表页面 | 用户ID, 筛选条件 | 商品列表数据 | 页面加载 | ✅ completed | P1 | - | 4h | AI-Frontend-1 | 2026-03-20 |
+| FE-P002 | 商品刊登闭环 | 渲染商品详情页面 | 商品ID | 商品详情数据 | 点击商品 | ✅ completed | P1 | FE-P001 | 3h | AI-Backend-9 | 2026-03-20 |
+| BE-P001 | 商品刊登闭环 | 商品数据获取接口 | 商品ID | 商品数据 | API请求 | pending | P1 | - | 5h | AI-Backend-1 | |
+```
+
+### 2.3 任务文档标准结构
+
+任务文档应遵循以下标准章节结构：
+
+```markdown
+# [模块名称]任务
+
+## 任务列表
+[任务表格]
+
+## 相关闭环
+[相关闭环列表]
+
+## 依赖关系
+[依赖关系描述，统一使用箭头图示]
+
+## 数据库表结构
+[表结构定义，backend任务必填]
+
+## API端点
+[API端点定义，backend任务必填]
+
+## 验收标准
+[验收标准列表]
+
+## 测试要求
+[测试用例要求]
+
+## 风险提示
+[风险识别和应对措施]
+```
+
+### 2.4 代码注释 (JSDoc)
+每个服务类必须包含完整的 JSDoc，明确标注任务 ID：
+```typescript
+/**
+ * [BE_60] 订单自动对账服务 (Order Reconciliation)
+ * @description 核心逻辑：比对平台结算单与系统订单差异。
+ * @version 1.0
+ */
+export class ReconciliationService { ... }
+```
+
+---
+
+## 3. 协作协议 (Collaboration Protocol)
+
+### 3.1 核心原则
+- **原子性认领**: 认领前必须先修改状态，防止并发冲突。
+- **超时释放**: 2 小时未更新进度，任务自动释放。
+- **状态定义**: ⏳ `PENDING` (待办), 🔒 `CLAIMED` (已认领), 🚧 `IN_PROGRESS` (进行中), ✅ `COMPLETED` (已完成)。
+
+### 3.2 任务包领取机制
+
+> **详细规范**: 详见 [项目规则 - 第7章](../../.trae/rules/project-specific-rules.md#7-ai-协作协议)
+
+- **优先领取任务包**: 必须优先领取同一闭环的完整任务链
+- **最小粒度**: 单次领取不少于 2 个相关任务
+- **依赖自包含**: 领取的任务包内依赖必须闭环
+
+### 3.3 协作流程
+1. **检查**: 确认任务状态为 `pending`。
+2. **锁定**: 修改状态为 `claimed [负责人] @ HH:MM`。
+3. **归档**: 完成后更新看板与相关文档。
+
+---
+
+## 4. 运维治理与风险 (Ops & Governance)
+
+### 4.1 上线前检查 (Deployment Checklist)
+- 数据库表初始化 (cf_ 前缀)。
+- 核心逻辑闭环、通过代码校验。
+- 产出配套的最小冒烟测试。
+
+### 4.2 风险登记 (Risk Registry)
+- 记录系统风险、缓解措施与负责人。
+
+---
+
+## 5. AI决策角色与权限（AI Decision Roles & Permissions）
+
+> **说明**：定义AI决策系统中各角色的权限边界，确保"AI主导决策 + 人类验证"的安全可控。
+
+### 5.1 角色定义
+
+| 角色 | 权限 | 职责 | 备注 |
+|------|------|------|------|
+| **AI Agent** | 决策生成、数据分析、风险评估 | 输出建议，带置信度 | 无执行权限 |
+| **人类操作者** | 审核/修改/确认 | 前期高干预，后期可降低 | 按权限等级操作 |
+| **系统执行层** | 自动化操作执行 | 仅执行经过确认的操作 | 幂等性保证 |
+| **日志管理系统** | 全链路记录 | 可回溯，每条操作打时间戳 | 只读权限 |
+
+### 5.2 人类操作者权限等级
+
+| 等级 | 角色 | 可操作范围 | 审核权限 |
+|------|------|------------|----------|
+| **L1** | OPERATOR | 查看、确认低风险操作 | 无 |
+| **L2** | MANAGER | 查看、确认、修改中低风险操作 | 审核OPERATOR操作 |
+| **L3** | FINANCE | 查看、确认、修改所有财务相关操作 | 审核财务操作 |
+| **L4** | ADMIN | 全部权限，包括配置AI阈值 | 审核所有操作 |
+
+### 5.3 操作风险等级与权限映射
+
+| 风险等级 | 操作类型 | 最低审核权限 | 自动执行 |
+|----------|----------|--------------|----------|
+| **低风险** | 库存预警、数据同步 | OPERATOR | ✅ 允许 |
+| **中风险** | 定价调整、广告投放 | MANAGER | ✅ 允许（高置信度） |
+| **高风险** | 退款审批、合同签订 | FINANCE | ❌ 禁止 |
+| **极高风险** | 大额转账、系统配置 | ADMIN | ❌ 禁止 |
+
+### 5.4 AI决策权限控制
+
+```typescript
+interface AIDecisionPermission {
+  module: string;                 // 模块名称
+  action: string;                 // 操作类型
+  risk_level: 'low' | 'medium' | 'high' | 'critical';
+  min_reviewer_role: 'OPERATOR' | 'MANAGER' | 'FINANCE' | 'ADMIN';
+  auto_execute: boolean;          // 是否允许自动执行
+  auto_execute_confidence: number; // 自动执行置信度阈值
+  require_dual_approval: boolean;  // 是否需要双人审批
+}
+```
+
+### 5.5 权限校验流程
+
+```
+1. AI生成建议 → 系统判断风险等级
+2. 根据风险等级 → 确定最低审核权限
+3. 操作者提交审核 → 校验操作者权限
+4. 权限通过 → 执行操作 → 记录日志
+5. 权限不足 → 拒绝操作 → 记录异常日志
+```
+
+### 5.6 特殊场景处理
+
+| 场景 | 处理方式 | 说明 |
+|------|----------|------|
+| **大额退款** | 双人审批 | ADMIN + FINANCE 同时确认 |
+| **紧急定价** | 快速通道 | MANAGER确认后立即执行，事后补录 |
+| **批量操作** | 批量审批 | 单次审批上限100条，超出需ADMIN |
+| **跨店铺操作** | 店铺权限校验 | 只能操作有权限的店铺 |
+
+### 5.7 审计与追溯
+
+- **操作日志**：所有AI建议、人类审核、系统执行均记录
+- **权限变更日志**：角色权限变更需ADMIN审批并记录
+- **异常告警**：权限越界、异常操作实时告警
+- **定期审计**：每月进行权限审计，清理过期权限
+
+---
+
+## 6. 自动化程度演进（Automation Evolution）
+
+> **说明**：定义AI决策系统从"人工主导"到"AI主导"的渐进式演进路径。
+
+### 6.1 演进阶段
+
+| 阶段 | 时间 | AI角色 | 人类角色 | 目标 |
+|------|------|--------|----------|------|
+| **阶段1** | 1-3月 | 建议生成 | 全部确认 | 建立信任 |
+| **阶段2** | 3-6月 | 低风险自动 | 高风险确认 | 效率提升 |
+| **阶段3** | 6-12月 | 大部分自动 | 异常介入 | 规模化 |
+| **阶段4** | 12月+ | 全链路决策 | 仅监控 | 智能化 |
+
+### 6.2 阶段准入条件
+
+| 阶段 | 准入条件 |
+|------|----------|
+| **阶段1→2** | AI建议采纳率 > 80%，决策准确率 > 85% |
+| **阶段2→3** | 自动执行成功率 > 95%，异常率 < 5% |
+| **阶段3→4** | 人工干预率 < 10%，系统稳定性 > 99.9% |
+
+---
+
+*本治理规范遵循 Crawlful Hub 项目规则，所有开发活动必须遵守逻辑集中化原则。*
+
+---
+
+## 7. 商品中心风险评估（Product Center Risk Assessment）
+
+> **说明**：商品中心重构涉及核心业务，需进行全面风险评估和应对措施规划。
+
+### 7.1 风险等级分类
+
+| 等级 | 风险类型 | 影响范围 | 处理优先级 |
+|------|----------|----------|------------|
+| **严重** | 数据丢失、业务中断 | 全系统 | 立即处理 |
+| **高** | 功能异常、性能下降 | 核心功能 | 24小时内 |
+| **中** | 部分功能受限 | 非核心功能 | 一周内 |
+| **低** | 用户体验影响 | 边缘场景 | 迭代优化 |
+
+### 7.2 数据迁移风险
+
+| 风险项 | 风险等级 | 影响描述 | 应对措施 |
+|--------|----------|----------|----------|
+| **数据丢失** | 严重 | 迁移过程中数据丢失 | 全量备份、分批迁移、数据校验 |
+| **数据不一致** | 高 | 新旧数据映射错误 | 双写验证、一致性检查脚本 |
+| **迁移超时** | 中 | 大数据量迁移超时 | 分批处理、增量迁移 |
+| **回滚困难** | 高 | 迁移失败后无法回滚 | 保留原表、版本化迁移脚本 |
+
+### 7.3 业务连续性风险
+
+| 风险项 | 风险等级 | 影响描述 | 应对措施 |
+|--------|----------|----------|----------|
+| **服务中断** | 严重 | 商品管理功能不可用 | 灰度发布、蓝绿部署 |
+| **价格错误** | 高 | 价格计算错误导致损失 | 价格校验、人工审核机制 |
+| **库存不同步** | 高 | 超卖或库存积压 | 实时同步、库存预警 |
+| **授权失效** | 高 | 店铺授权过期导致无法操作 | 自动刷新、过期预警 |
+
+### 7.4 技术风险
+
+| 风险项 | 风险等级 | 影响描述 | 应对措施 |
+|--------|----------|----------|----------|
+| **性能下降** | 中 | 三层模型查询性能下降 | 索引优化、缓存策略 |
+| **API兼容性** | 中 | 旧API与新模型不兼容 | 版本化API、适配层 |
+| **并发冲突** | 中 | 高并发下数据冲突 | 乐观锁、分布式锁 |
+| **第三方依赖** | 低 | 平台API变更 | 抽象层封装、降级策略 |
+
+### 7.5 应急预案
+
+#### 7.5.1 数据回滚方案
+
+```sql
+-- 1. 停止写入操作
+-- 2. 从备份恢复原表
+-- 3. 重放增量数据
+-- 4. 验证数据一致性
+-- 5. 切换服务
+```
+
+#### 7.5.2 服务降级方案
+
+| 降级级别 | 触发条件 | 降级措施 |
+|----------|----------|----------|
+| **L1** | 性能下降30% | 禁用非核心功能 |
+| **L2** | 性能下降50% | 只读模式 |
+| **L3** | 服务不可用 | 静态页面提示 |
+
+#### 7.5.3 紧急联系人
+
+| 角色 | 职责 | 联系方式 |
+|------|------|----------|
+| **技术负责人** | 技术决策、资源协调 | - |
+| **业务负责人** | 业务决策、用户沟通 | - |
+| **运维负责人** | 系统监控、应急响应 | - |
+
+### 7.6 风险监控指标
+
+| 指标 | 正常范围 | 预警阈值 | 告警阈值 |
+|------|----------|----------|----------|
+| **API响应时间** | <200ms | >500ms | >1000ms |
+| **错误率** | <1% | >3% | >5% |
+| **数据一致性** | 100% | <99% | <95% |
+| **服务可用性** | >99.9% | <99.5% | <99% |
+
+### 7.7 风险治理流程
+
+```
+风险识别 → 风险评估 → 制定措施 → 实施监控 → 定期复盘
+     ↑                                          │
+     └──────────────────────────────────────────┘
+```