wurenzhi
0dac26d781
refactor: 重构页面组件移除冗余Layout组件 feat: 实现WebSocket和事件总线系统 feat: 添加队列和调度系统 docs: 更新架构文档和服务映射 style: 清理重复接口定义使用数据源 chore: 更新依赖项配置 feat: 添加运行时系统和领域引导 ci: 配置ESLint边界检查规则 build: 添加Redis和WebSocket依赖 test: 添加MSW浏览器环境入口 perf: 优化数据获取逻辑使用统一数据源 fix: 修复类型定义和状态管理问题
166 lines
6.3 KiB
Markdown
166 lines
6.3 KiB
Markdown
# 📋 Governance & Standards (Crawlful Hub)
|
||
|
||
> **定位**：Crawlful Hub 治理与开发规范 - 包含开发风格、协作协议、任务规格及运维治理。
|
||
> **更新日期**: 2026-03-17
|
||
|
||
---
|
||
|
||
## 1. 开发规范 (Development Standards)
|
||
|
||
### 1.1 核心准则
|
||
- **职责单一**: 一个文件只包含一个类或一组高度相关的函数。
|
||
- **Zero-Mock**: 严禁在生产代码中使用硬编码的模拟数据。
|
||
- **契约优先**: 接口定义应先于实现。
|
||
|
||
### 1.2 代码风格与规模限制
|
||
- **命名**: 文件使用 `kebab-case`，组件 `PascalCase`，变量 `camelCase`。
|
||
- **严格模式**: 开启 TypeScript `strict: true`，严禁使用 `any`。
|
||
- **限制**: 单文件 ≤ 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 协作流程
|
||
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 项目规则，所有开发活动必须遵守逻辑集中化原则。*
|