makemd/docs/00_Business/Governance_Standards.md

📋 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：

/**
 * [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决策权限控制

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 项目规则，所有开发活动必须遵守逻辑集中化原则。