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：
```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)
- 记录系统风险、缓解措施与负责人。