64 lines
2.1 KiB
Markdown
64 lines
2.1 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**: `[FE/BE/EX]_[序号]` (FE: 前端, BE: 后端, EX: 插件)。
|
||
- **验收**: 功能测试通过、符合规范、文档同步更新。
|
||
|
||
### 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)
|
||
- 记录系统风险、缓解措施与负责人。
|