# 📋 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 代码注释 (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 项目规则，所有开发活动必须遵守逻辑集中化原则。*