# 📋 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 风险治理流程

```
风险识别 → 风险评估 → 制定措施 → 实施监控 → 定期复盘
     ↑                                          │
     └──────────────────────────────────────────┘
```