makemd/docs/ARCHIVE/00_Business/Governance_Standards.md

📋 Governance & Standards (Crawlful Hub)

定位：Crawlful Hub 治理与开发规范 - 包含开发风格、协作协议、任务规格及运维治理。 更新日期: 2026-03-17

---

1. 开发规范 (Development Standards)

1.1 核心准则

• 职责单一: 一个文件只包含一个类或一组高度相关的函数。
• Zero-Mock: 严禁在生产代码中使用硬编码的模拟数据。详见 Mock数据规范
• 契约优先: 接口定义应先于实现。
• TypeScript 严格模式: 详见 TypeScript 编译规约 和 项目规则 - 第12章

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 表格结构

所有任务表必须包含 "完成时间" 列，表头格式如下：

| Task ID | 闭环关联 | 任务描述 | 输入 | 输出 | 触发条件 | 状态 | 优先级 | 依赖 | 预计耗时 | 负责人 | 完成时间 |

2.2.2 完成时间格式

• 已完成任务的完成时间统一格式为 YYYY-MM-DD
• 未完成任务的完成时间字段为空
• 历史已完成任务的完成时间统一设置为项目基准日期

2.2.3 状态标记

• 已完成任务状态标记为 ✅ completed 或 ✅ 已完成
• 未完成任务状态标记为 pending 或其他未完成状态

2.2.4 操作流程

1. 添加完成时间列：为所有任务表添加 "完成时间" 列
2. 标记已完成任务：为所有状态为已完成的任务添加完成时间
3. 保持未完成任务：未完成任务的完成时间字段保持为空
4. 新增任务处理：新添加的任务，完成后及时添加完成时间

2.2.5 示例

| 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 任务文档标准结构

任务文档应遵循以下标准章节结构：

# [模块名称]任务

## 任务列表
[任务表格]

## 相关闭环
[相关闭环列表]

## 依赖关系
[依赖关系描述，统一使用箭头图示]

## 数据库表结构
[表结构定义，backend任务必填]

## API端点
[API端点定义，backend任务必填]

## 验收标准
[验收标准列表]

## 测试要求
[测试用例要求]

## 风险提示
[风险识别和应对措施]

2.4 代码注释 (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 任务包领取机制

详细规范: 详见 项目规则 - 第7章

• 优先领取任务包: 必须优先领取同一闭环的完整任务链
• 最小粒度: 单次领取不少于 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决策权限控制

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 数据回滚方案

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

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