refactor: 优化代码结构并修复类型问题
- 移除未使用的TabPane组件 - 修复类型定义和导入方式 - 优化mock数据源的环境变量判断逻辑 - 更新文档结构并归档旧文件 - 添加新的UI组件和Memo组件 - 调整API路径和响应处理
This commit is contained in:
56
docs/ARCHIVE/05_AI/00_AI_Index.md
Normal file
56
docs/ARCHIVE/05_AI/00_AI_Index.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# AI文档索引
|
||||
|
||||
> **模块**: 05_AI - AI策略与规则
|
||||
> **更新日期**: 2026-03-20
|
||||
|
||||
---
|
||||
|
||||
## 核心文档
|
||||
|
||||
| 文档 | 描述 | 状态 |
|
||||
|------|------|------|
|
||||
| [01_Strategy](01_Strategy.md) | AI策略设计 | ✅ |
|
||||
| [02_Rules](02_Rules.md) | AI协作规则 | ✅ |
|
||||
| [03_Implementation_Strategy](03_Implementation_Strategy.md) | AI实施策略 | ✅ |
|
||||
| [04_Quick_Reference_Card](04_Quick_Reference_Card.md) | **AI开发快速参考卡片** | ✅ |
|
||||
| [05_Development_Checklist](05_Development_Checklist.md) | **AI开发检查清单** | ✅ |
|
||||
| [06_Wrong_vs_Right_Examples](06_Wrong_vs_Right_Examples.md) | **错误示例与正确示例对比** | ✅ |
|
||||
| [07_TypeScript_Error_Fix_Guide](07_TypeScript_Error_Fix_Guide.md) | **TypeScript错误修复方案** | ✅ |
|
||||
| [09_TypeScript_Error_Tasks](09_TypeScript_Error_Tasks.md) | **TypeScript错误任务列表** | 🔴 待领取 |
|
||||
|
||||
---
|
||||
|
||||
## AI 开发必读文档
|
||||
|
||||
### 开发前必读
|
||||
|
||||
1. **[快速参考卡片](04_Quick_Reference_Card.md)** - 硬性约束和代码模板
|
||||
2. **[AI 开发规则](02_Rules.md)** - 逻辑集中化和禁止行为
|
||||
3. **[项目硬性约束](../../.trae/rules/project-specific-rules.md)** - 自动加载的约束文件
|
||||
|
||||
### 开发中参考
|
||||
|
||||
1. **[TypeScript 编译规约](../01_Architecture/13_TypeScript_Standards.md)** - 类型安全规范
|
||||
2. **[Schema 驱动开发](../01_Architecture/15_Schema_Driven_Development.md)** - 类型推导方法
|
||||
3. **[统一类型管理](../01_Architecture/16_Unified_Type_Management.md)** - 类型中心架构
|
||||
|
||||
### 提交前检查
|
||||
|
||||
1. **[开发检查清单](05_Development_Checklist.md)** - 各阶段强制检查项
|
||||
2. **[错误示例对比](06_Wrong_vs_Right_Examples.md)** - 避免常见错误
|
||||
3. **[TypeScript 错误修复方案](07_TypeScript_Error_Fix_Guide.md)** - 解决 613 个编译错误
|
||||
4. **[TypeScript 错误任务列表](09_TypeScript_Error_Tasks.md)** - AI 领取修复任务
|
||||
|
||||
---
|
||||
|
||||
## 关联模块
|
||||
|
||||
- [架构模块](../01_Architecture/00_Architecture_Index.md)
|
||||
- [业务模块](../00_Business/Business_Blueprint.md)
|
||||
|
||||
---
|
||||
|
||||
## 最近更新
|
||||
|
||||
- 2026-03-20: 新增快速参考卡片、开发检查清单、错误示例对比、TypeScript错误修复方案文档
|
||||
- 2026-03-19: 重构AI文档结构，统一命名规范
|
||||
427
docs/ARCHIVE/05_AI/01_Strategy.md
Normal file
427
docs/ARCHIVE/05_AI/01_Strategy.md
Normal file
@@ -0,0 +1,427 @@
|
||||
# AI Strategy (Crawlful Hub)
|
||||
|
||||
> **定位**：Crawlful Hub AI 策略文档 - 描述多 AI 协作方案、任务分配策略及决策流程。
|
||||
> **更新日期**: 2026-03-18
|
||||
> **注意**：本文档不重复 Task_Overview.md 中的任务列表，仅描述 AI 协作策略。
|
||||
|
||||
---
|
||||
|
||||
## 1. 多 AI 协作架构
|
||||
|
||||
### 1.1 架构概览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Brain (调度中心) │
|
||||
│ 全局调度与决策 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────────┼───────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ AI Agent 1 │ │ AI Agent 2 │ │ AI Agent N │
|
||||
│ (前端/插件) │ │ (后端/数据) │ │ (分析/决策) │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
│ │ │
|
||||
└───────────────────┼───────────────────┘
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ Task Queue │
|
||||
│ (BullMQ) │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
### 1.2 角色定义
|
||||
|
||||
| 角色 | 职责 | 能力范围 |
|
||||
|------|------|----------|
|
||||
| **Brain** | 全局调度、任务分配、冲突解决 | 不直接生成代码 |
|
||||
| **AI Agent** | 原子任务包闭环开发 | 代码生成、测试、部署 |
|
||||
| **AI Analyst** | 数据分析、报告生成 | 数据处理、可视化 |
|
||||
| **AI Decision** | 决策支持、策略优化 | 算法、预测 |
|
||||
|
||||
### 1.3 协作原则
|
||||
|
||||
1. **一次性分发**：每轮下发完整任务包（P0/P1/P2）
|
||||
2. **连续执行**：任务包内连续执行到"完成或明确阻塞"
|
||||
3. **文件占用锁**：同目录协作先声明归属，"谁领取谁编辑"
|
||||
4. **冲突处理**：后写入方必须先 Read 最新内容，增量合并
|
||||
|
||||
---
|
||||
|
||||
## 2. 任务分配策略
|
||||
|
||||
### 2.1 动态分配机制
|
||||
|
||||
```typescript
|
||||
// 任务分配算法
|
||||
interface TaskAssignment {
|
||||
taskId: string;
|
||||
agentId: string;
|
||||
priority: 'P0' | 'P1' | 'P2' | 'P3';
|
||||
capability: string[];
|
||||
estimatedTime: number;
|
||||
}
|
||||
|
||||
// 分配策略
|
||||
const assignmentStrategy = {
|
||||
// 能力匹配
|
||||
matchCapability: (task: Task, agent: Agent): boolean => {
|
||||
return task.requiredCapabilities.every(cap =>
|
||||
agent.capabilities.includes(cap)
|
||||
);
|
||||
},
|
||||
|
||||
// 负载均衡
|
||||
balanceLoad: (agents: Agent[]): Agent => {
|
||||
return agents.reduce((min, agent) =>
|
||||
agent.activeTasks < min.activeTasks ? agent : min
|
||||
);
|
||||
},
|
||||
|
||||
// 优先级排序
|
||||
sortByPriority: (tasks: Task[]): Task[] => {
|
||||
const priorityOrder = { P0: 0, P1: 1, P2: 2, P3: 3 };
|
||||
return tasks.sort((a, b) =>
|
||||
priorityOrder[a.priority] - priorityOrder[b.priority]
|
||||
);
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 2.2 能力标签
|
||||
|
||||
| 能力标签 | 说明 | 适用任务 |
|
||||
|----------|------|----------|
|
||||
| `frontend` | 前端开发 | React, UI组件 |
|
||||
| `backend` | 后端开发 | API, Service |
|
||||
| `plugin` | 插件开发 | Chrome Extension |
|
||||
| `database` | 数据库 | Schema, Query |
|
||||
| `ai-analysis` | AI分析 | 数据分析, 报告 |
|
||||
| `ai-decision` | AI决策 | 算法, 策略 |
|
||||
| `devops` | 运维 | 部署, 监控 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 决策流程
|
||||
|
||||
### 3.1 决策层级
|
||||
|
||||
```
|
||||
Level 1: AI Agent 自主决策
|
||||
├─ 代码实现细节
|
||||
├─ 单元测试用例
|
||||
└─ 局部重构
|
||||
|
||||
Level 2: Brain 协调决策
|
||||
├─ 跨模块接口设计
|
||||
├─ 任务优先级调整
|
||||
└─ 资源冲突解决
|
||||
|
||||
Level 3: 人工确认决策
|
||||
├─ 核心业务数据修改（调价、退款）
|
||||
├─ 架构重大变更
|
||||
└─ 生产环境部署
|
||||
```
|
||||
|
||||
### 3.2 决策流程门禁
|
||||
|
||||
```
|
||||
SUGGESTED -> PENDING_REVIEW -> EXECUTED/REJECTED
|
||||
```
|
||||
|
||||
**严禁**：AI 直接修改核心业务数据（调价、退款、下单）
|
||||
**必须**：人工在 Console 端确认后方可执行
|
||||
|
||||
---
|
||||
|
||||
## 4. 自省与上报
|
||||
|
||||
### 4.1 自省要求
|
||||
|
||||
AI Agent 必须在以下阶段上报"自我问题"：
|
||||
|
||||
1. **对话开始时**
|
||||
- 当前任务理解
|
||||
- 依赖任务状态
|
||||
- 潜在风险点
|
||||
|
||||
2. **执行过程中**
|
||||
- 进度更新
|
||||
- 阻塞问题
|
||||
- 需要协调的事项
|
||||
|
||||
3. **交付前**
|
||||
- 功能验证结果
|
||||
- 测试覆盖率
|
||||
- 已知限制
|
||||
|
||||
### 4.2 上报格式
|
||||
|
||||
```typescript
|
||||
interface SelfReport {
|
||||
stage: 'start' | 'progress' | 'delivery';
|
||||
taskId: string;
|
||||
agentId: string;
|
||||
status: 'normal' | 'blocked' | 'at-risk';
|
||||
progress: number; // 0-100
|
||||
issues: {
|
||||
type: 'dependency' | 'conflict' | 'technical' | 'resource';
|
||||
description: string;
|
||||
severity: 'low' | 'medium' | 'high';
|
||||
}[];
|
||||
nextSteps: string[];
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 质量保障
|
||||
|
||||
### 5.1 代码质量门禁
|
||||
|
||||
| 指标 | 目标值 | 检查方式 |
|
||||
|------|--------|----------|
|
||||
| 测试覆盖率 | ≥ 80% | 自动化测试 |
|
||||
| 类型安全 | 100% | TypeScript strict |
|
||||
| 代码规范 | 0 警告 | ESLint |
|
||||
| 文档完整 | 100% | JSDoc |
|
||||
|
||||
### 5.2 验证流程
|
||||
|
||||
```
|
||||
代码生成
|
||||
│
|
||||
▼
|
||||
静态检查 (ESLint/TypeScript)
|
||||
│
|
||||
▼
|
||||
单元测试
|
||||
│
|
||||
▼
|
||||
集成测试
|
||||
│
|
||||
▼
|
||||
人工 Review (关键模块)
|
||||
│
|
||||
▼
|
||||
部署验证
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. AI节点自动决策体系
|
||||
|
||||
### 6.1 核心理念
|
||||
|
||||
1. **节点化设计**：每个决策动作是一个节点（Node），节点可以是 AI 生成建议、条件判断、执行动作、通知等
|
||||
2. **数据驱动**：每个节点依赖历史数据 + 实时数据来生成建议
|
||||
3. **自动推进**：节点间用逻辑流或条件流连接，AI 根据上下文和规则自动选择下一节点
|
||||
4. **可回溯与干预**：每个节点都有日志，初期可允许人工干预，后期高置信度节点可完全自动执行
|
||||
|
||||
### 6.2 节点类型
|
||||
|
||||
| 节点类型 | 功能 | 输入数据 | 输出数据 |
|
||||
|----------|------|----------|----------|
|
||||
| **决策节点（Decision Node）** | AI 根据数据生成建议或选择动作 | 历史数据、实时数据、外部数据 | JSON动作方案 + 置信度 + 风险等级 |
|
||||
| **条件节点（Condition Node）** | 根据规则或状态判断执行路径 | 决策节点输出 + 实时数据 | 执行路径（自动执行/人工确认/阻止执行） |
|
||||
| **执行节点（Action Node）** | 调用 API、脚本或系统操作 | 确认后的动作方案 | 执行状态（成功/失败） |
|
||||
| **人工确认节点（Human Approval Node）** | 人类对 AI 建议进行修改或确认 | 决策节点输出 + 条件判断结果 + 数据参考 | 最终动作方案 |
|
||||
| **日志节点（Log Node）** | 记录整个节点数据、结果 | 所有节点输入输出 | 日志记录（唯一ID，全链路追踪） |
|
||||
| **历史数据更新节点** | 将执行结果回写历史库 | 执行结果 | 历史数据库更新 |
|
||||
| **报表分析节点（Report/Analytics Node）** | 生成报表和趋势分析 | 历史数据 + 节点日志 | 报表、趋势分析、总结 |
|
||||
|
||||
### 6.3 数据分类
|
||||
|
||||
| 数据类别 | 内容 | 用途 |
|
||||
|----------|------|------|
|
||||
| **历史数据** | 广告投放历史（CTR、CVR、ROI）、价格历史、销售历史、TOB批发订单历史 | 预测调价或预算策略、判断调价幅度 |
|
||||
| **实时数据** | 当前库存、价格、预算、广告状态、实时ROI、异常指标 | 决定节点是否可执行、支持条件节点判断分支 |
|
||||
| **外部数据** | 节假日、竞品价格、市场趋势、供应链状态、汇率 | 影响广告投放策略和定价 |
|
||||
|
||||
### 6.4 决策流程门禁
|
||||
|
||||
```
|
||||
SUGGESTED -> PENDING_REVIEW -> EXECUTED/REJECTED
|
||||
```
|
||||
|
||||
- **严禁**：AI 直接修改核心业务数据（调价、退款、下单）
|
||||
- **必须**：人工在 Console 端确认后方可执行
|
||||
|
||||
---
|
||||
|
||||
## 7. 业务闭环设计
|
||||
|
||||
### 7.1 TOC（零售单笔闭环）
|
||||
|
||||
```
|
||||
[输入数据] → [AI决策节点] → [条件判断节点] → [人工确认节点] → [执行节点]
|
||||
↓
|
||||
[日志节点] → [历史数据更新节点] → [报表分析节点] → [优化反馈节点] → 回到 [AI决策节点]
|
||||
```
|
||||
|
||||
1. **输入数据**：单笔订单、客户历史购买、库存状态、广告数据、市场趋势
|
||||
2. **决策节点**：AI 生成动作建议（是否调价、是否推荐促销、广告曝光调整）
|
||||
3. **条件节点**：检查库存、预算、置信度、风险
|
||||
4. **人工确认节点**（可选）：处理低置信度或高风险动作
|
||||
5. **执行节点**：系统执行调价、广告调整、库存扣减
|
||||
6. **日志节点**：记录每个操作和决策过程
|
||||
7. **历史数据更新节点**：更新库存、销售、广告效果、ROI
|
||||
8. **报表分析节点**：生成订单收益、库存波动、广告转化报表
|
||||
9. **优化反馈节点**：AI 根据报表优化下一轮决策
|
||||
|
||||
### 7.2 TOB（批发/整柜闭环）
|
||||
|
||||
1. **输入数据**：批发订单、客户等级、库存、供应商状态、市场趋势
|
||||
2. **决策节点**：AI 生成分配方案、价格方案、库存调拨方案
|
||||
3. **条件节点**：检查库存、供应商能力、风险等级
|
||||
4. **人工确认节点**：处理库存紧张或低置信度分配
|
||||
5. **执行节点**：系统生成订单、调拨库存、同步 ERP
|
||||
6. **日志节点**：全链路记录决策与执行状态
|
||||
7. **历史数据更新节点**：回写分配结果、客户反馈、库存变化
|
||||
8. **报表分析节点**：生成分配效率、库存周转率、客户满意度报表
|
||||
9. **优化反馈节点**：AI 根据历史表现优化分配策略
|
||||
|
||||
### 7.3 功能模块闭环示例
|
||||
|
||||
| 功能模块 | 节点应用说明 |
|
||||
|----------|--------------|
|
||||
| 广告价格调节 | 决策节点生成调价方案 → 条件节点判断库存和预算 → 人工确认或自动执行 → 执行节点调整广告价格 → 日志 → 历史更新 → 报表分析 |
|
||||
| 产品调价 | 决策节点生成价格建议 → 条件判断 ROI、库存 → 人工确认 → 执行调价 → 日志 → 历史更新 → 报表分析 |
|
||||
| 批发订单分配 | 决策节点生成分配方案 → 条件节点判断库存和客户优先级 → 人工确认或自动分配 → 执行节点生成订单 → 日志 → 历史更新 → 报表分析 |
|
||||
| 库存管理 | 决策节点预测缺货/过量 → 条件节点判断安全库存 → 人工确认 → 执行节点调拨或采购 → 日志 → 历史更新 → 报表分析 |
|
||||
| 促销活动 | 决策节点生成活动策略 → 条件节点判断库存/ROI → 人工确认 → 执行节点发布活动 → 日志 → 历史更新 → 报表分析 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 规则引擎（初期备用方案）
|
||||
|
||||
### 8.1 设计定位
|
||||
|
||||
- **目的**：在 AI 决策模型尚未充分训练或 token 不可用的情况下，保证业务能继续自动化运行
|
||||
- **特点**：
|
||||
- 逻辑简单、可配置
|
||||
- 不依赖 token 调用
|
||||
- 作为 AI 决策节点的备用或初期执行层
|
||||
|
||||
### 8.2 规则引擎与 AI 决策的关系
|
||||
|
||||
```
|
||||
[业务触发] → [规则引擎检查] → [规则命中?]
|
||||
├── 是 → [按规则执行] → [日志记录]
|
||||
└── 否 → [AI决策节点] → [条件判断] → [执行]
|
||||
```
|
||||
|
||||
### 8.3 规则类型
|
||||
|
||||
| 规则类型 | 说明 | 示例 |
|
||||
|----------|------|------|
|
||||
| **阈值规则** | 基于数值阈值的判断 | 库存 < 安全库存 → 触发补货 |
|
||||
| **时间规则** | 基于时间周期的判断 | 每日 00:00 检查广告预算 |
|
||||
| **组合规则** | 多条件组合判断 | ROI > 1.5 且 库存充足 → 自动增加广告预算 |
|
||||
| **异常规则** | 异常检测与处理 | CTR 下降 > 30% → 触发人工确认 |
|
||||
|
||||
### 8.4 规则配置示例
|
||||
|
||||
```typescript
|
||||
interface Rule {
|
||||
id: string;
|
||||
name: string;
|
||||
condition: {
|
||||
type: 'threshold' | 'time' | 'composite' | 'anomaly';
|
||||
expression: string;
|
||||
};
|
||||
action: {
|
||||
type: 'auto_execute' | 'human_approval' | 'notification';
|
||||
payload: object;
|
||||
};
|
||||
priority: number;
|
||||
enabled: boolean;
|
||||
}
|
||||
|
||||
// 示例规则
|
||||
const rules: Rule[] = [
|
||||
{
|
||||
id: 'RULE-001',
|
||||
name: '库存不足自动补货',
|
||||
condition: {
|
||||
type: 'threshold',
|
||||
expression: 'inventory < safety_stock'
|
||||
},
|
||||
action: {
|
||||
type: 'human_approval',
|
||||
payload: { action: 'restock', quantity: 'suggested_amount' }
|
||||
},
|
||||
priority: 1,
|
||||
enabled: true
|
||||
},
|
||||
{
|
||||
id: 'RULE-002',
|
||||
name: '高ROI广告自动加预算',
|
||||
condition: {
|
||||
type: 'composite',
|
||||
expression: 'roi > 1.5 AND inventory > min_stock'
|
||||
},
|
||||
action: {
|
||||
type: 'auto_execute',
|
||||
payload: { action: 'increase_budget', amount: 100 }
|
||||
},
|
||||
priority: 2,
|
||||
enabled: true
|
||||
}
|
||||
];
|
||||
```
|
||||
|
||||
### 8.5 演进路径
|
||||
|
||||
| 阶段 | 规则引擎 | AI决策节点 |
|
||||
|------|----------|------------|
|
||||
| **初期** | 主导，处理大部分标准场景 | 辅助，处理复杂场景 |
|
||||
| **中期** | 处理简单、确定性场景 | 主导，处理需要预测和优化的场景 |
|
||||
| **后期** | 作为异常处理和兜底机制 | 全链路自动决策 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 自动化程度演进
|
||||
|
||||
| 阶段 | 特征 | 人工干预 |
|
||||
|------|------|----------|
|
||||
| **初期** | AI建议 + 人审核，人工操作占主导 | 高干预，大部分决策需要人工确认 |
|
||||
| **中期** | 对置信度高、低风险的操作可自动执行 | 中等，人工处理异常和低置信度决策 |
|
||||
| **后期** | AI全链路决策 + 自动执行 | 低干预，仅异常或低置信度操作人工介入 |
|
||||
|
||||
### 阈值管理
|
||||
|
||||
- 置信度阈值、风险等级、操作类型均可配置
|
||||
- 支持按业务模块（TOC/TOB）设置不同阈值
|
||||
- 支持自适应阈值：系统根据历史执行效果自动调整
|
||||
|
||||
---
|
||||
|
||||
## 10. 与 Task_Overview.md 的关系
|
||||
|
||||
### 10.1 职责划分
|
||||
|
||||
| 文档 | 职责 | 内容 |
|
||||
|------|------|------|
|
||||
| **Task_Overview.md** | 任务追踪 | 所有任务的详细列表、状态、依赖 |
|
||||
| **AI_Strategy.md** | 策略描述 | AI 协作机制、决策流程、质量保障、节点自动决策体系 |
|
||||
|
||||
### 10.2 避免重复
|
||||
|
||||
- **Task_Overview.md** 是唯一的任务源
|
||||
- **AI_Strategy.md** 不重复定义任务
|
||||
- **AI_Strategy.md** 描述如何执行任务的策略
|
||||
|
||||
---
|
||||
|
||||
## 11. 相关文档
|
||||
|
||||
- [Task Overview](../00_Business/Task_Overview.md) - 任务追踪（唯一任务源）
|
||||
- [Business ClosedLoops](../00_Business/Business_ClosedLoops.md) - 业务闭环
|
||||
- [System Architecture](../01_Architecture/System_Architecture.md) - 系统架构
|
||||
- [AI Module List](./AI_Module_List.md) - AI模块清单
|
||||
|
||||
---
|
||||
|
||||
*本文档描述 AI 协作策略，不重复任务列表，最后更新: 2026-03-19*
|
||||
188
docs/ARCHIVE/05_AI/02_Rules.md
Normal file
188
docs/ARCHIVE/05_AI/02_Rules.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# AI_RULES（AI开发规则）
|
||||
|
||||
## 核心原则
|
||||
|
||||
- 必须基于 SERVICE_MAP 开发
|
||||
- 不允许绕过 Service 层
|
||||
- 不允许直接操作数据库（除 repository）
|
||||
- 必须遵守 STATE_MACHINE
|
||||
- 必须接入 BILLING（如果涉及收费）
|
||||
- 必须接入 PERMISSION
|
||||
- 必须遵循 DOMAIN_MODEL 定义的实体关系
|
||||
- 必须按照 TEST_SPEC 进行测试
|
||||
|
||||
---
|
||||
|
||||
## 开发顺序
|
||||
|
||||
1. Service（业务逻辑）
|
||||
2. Repository（数据访问）
|
||||
3. Controller（接口层）
|
||||
4. Frontend（前端实现）
|
||||
5. Test（测试用例）
|
||||
|
||||
---
|
||||
|
||||
## 禁止行为
|
||||
|
||||
- Controller 写业务逻辑
|
||||
- 前端控制状态
|
||||
- 跳过权限校验
|
||||
- 硬编码业务规则
|
||||
- 直接修改数据库表结构
|
||||
- 忽略状态机流转
|
||||
- 绕过服务层直接调用底层API
|
||||
|
||||
---
|
||||
|
||||
## 代码规范
|
||||
|
||||
- 服务类统一使用 `Service` 后缀
|
||||
- 控制器类统一使用 `Controller` 后缀
|
||||
- 仓库类统一使用 `Repository` 后缀
|
||||
- 方法名使用驼峰命名法
|
||||
- 变量名使用驼峰命名法
|
||||
- 常量使用大写蛇形命名法
|
||||
- 类名使用帕斯卡命名法
|
||||
|
||||
---
|
||||
|
||||
## 注释规范
|
||||
|
||||
- 每个服务类必须包含完整 JSDoc
|
||||
- 每个方法必须包含参数和返回值说明
|
||||
- 关键业务逻辑必须添加注释
|
||||
- 状态变更必须添加注释说明
|
||||
- 收费相关逻辑必须添加注释
|
||||
|
||||
---
|
||||
|
||||
## 错误处理
|
||||
|
||||
- 所有错误必须通过统一的错误处理机制
|
||||
- 错误信息必须清晰明确
|
||||
- 错误必须记录详细日志
|
||||
- 敏感错误信息不得返回给前端
|
||||
|
||||
---
|
||||
|
||||
## 日志规范
|
||||
|
||||
- 所有服务调用必须记录日志
|
||||
- 状态变更必须记录日志
|
||||
- 收费行为必须记录日志
|
||||
- 权限校验失败必须记录日志
|
||||
- 异常情况必须记录日志
|
||||
|
||||
---
|
||||
|
||||
## 安全规范
|
||||
|
||||
- 密码必须加密存储
|
||||
- 敏感数据必须加密传输
|
||||
- API 调用必须使用 token 认证
|
||||
- 防止 SQL 注入
|
||||
- 防止 XSS 攻击
|
||||
- 防止 CSRF 攻击
|
||||
|
||||
---
|
||||
|
||||
## 性能规范
|
||||
|
||||
- 避免不必要的数据库查询
|
||||
- 合理使用缓存
|
||||
- 批量操作优化
|
||||
- 异步处理耗时操作
|
||||
- 合理设置超时时间
|
||||
|
||||
---
|
||||
|
||||
## 测试规范
|
||||
|
||||
- 每个服务必须有对应的测试用例
|
||||
- 测试用例必须覆盖正常流程和异常流程
|
||||
- 测试用例必须基于 TEST_SPEC
|
||||
- 测试结果必须记录详细日志
|
||||
- 测试失败必须及时修复
|
||||
|
||||
---
|
||||
|
||||
## 代码审查
|
||||
|
||||
- 代码提交前必须进行自我审查
|
||||
- 审查重点：
|
||||
- 业务逻辑正确性
|
||||
- 状态机遵循情况
|
||||
- 权限校验完整性
|
||||
- 收费逻辑正确性
|
||||
- 错误处理完整性
|
||||
- 性能优化
|
||||
- 安全漏洞
|
||||
|
||||
---
|
||||
|
||||
## 版本控制
|
||||
|
||||
- 代码必须使用 Git 进行版本控制
|
||||
- 提交信息必须清晰明确
|
||||
- 分支管理必须规范
|
||||
- 代码合并前必须进行代码审查
|
||||
|
||||
---
|
||||
|
||||
## 持续集成
|
||||
|
||||
- 代码提交后必须触发 CI 流程
|
||||
- CI 流程必须包含：
|
||||
- 代码质量检查
|
||||
- 单元测试
|
||||
- 集成测试
|
||||
- 构建检查
|
||||
- CI 失败必须及时修复
|
||||
|
||||
---
|
||||
|
||||
## 逻辑集中化强制规则
|
||||
|
||||
> **详细规范**: 详见 [项目规则 - 第8章](../../.trae/rules/project-specific-rules.md#8-逻辑集中化原则硬性约束)
|
||||
|
||||
### 核心原则
|
||||
- 所有业务逻辑必须集中在 Service 层
|
||||
- 禁止分散在 Controller、前端或数据库操作中
|
||||
|
||||
### AI开发强制规则（摘要）
|
||||
|
||||
1. **禁止在 Controller 中实现业务逻辑** - Controller 只负责请求/响应和权限校验
|
||||
2. **禁止在前端实现业务规则** - 前端只负责展示、交互和调用接口
|
||||
3. **禁止直接操作数据库** - 所有数据库操作必须通过 Repository 层
|
||||
4. **所有业务逻辑必须封装在 Service 层** - 每个业务操作必须对应一个 Service 方法
|
||||
5. **所有状态变更必须通过 Service 方法** - 禁止直接修改状态字段
|
||||
|
||||
### 违反后果
|
||||
- **代码审查不通过**：任何违反逻辑集中化原则的代码将被拒绝合并
|
||||
- **AI 任务失败**：AI 无法维护分散的逻辑，导致任务执行失败
|
||||
- **生产环境风险**：分散逻辑导致数据不一致，直接影响系统稳定性
|
||||
|
||||
---
|
||||
|
||||
## Mock 数据规范
|
||||
|
||||
> **详细规范**: 详见 [项目规则 - 第11章](../../.trae/rules/project-specific-rules.md#11-mock数据规范ai上下文安全)
|
||||
|
||||
### 核心原则
|
||||
- **禁止**: 在业务组件中硬编码 Mock 数据
|
||||
- **必须**: 通过 DataSource 抽象层获取数据
|
||||
- **必须**: 所有 Mock 文件放在 `/mock` 目录
|
||||
|
||||
---
|
||||
|
||||
## TypeScript 编译错误修复
|
||||
|
||||
> **详细方案**: 详见 [TypeScript 错误修复方案](07_TypeScript_Error_Fix_Guide.md)
|
||||
|
||||
当前存在 613 个编译错误，必须按照分阶段策略修复：
|
||||
1. **阶段 1**: 修复 tsconfig.json 配置
|
||||
2. **阶段 2**: 消除所有 any 类型
|
||||
3. **阶段 3**: 修复类型不匹配
|
||||
4. **阶段 4**: 统一模块导入导出
|
||||
5. **阶段 5**: 正确处理 undefined 和 null
|
||||
252
docs/ARCHIVE/05_AI/03_Implementation_Strategy.md
Normal file
252
docs/ARCHIVE/05_AI/03_Implementation_Strategy.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# AI功能分阶段实现策略
|
||||
|
||||
## 1. 总体目标
|
||||
|
||||
本策略旨在分阶段实现项目所需的AI功能，确保功能迭代有序推进，同时保证系统稳定性和性能。
|
||||
|
||||
## 2. 分阶段实现计划
|
||||
|
||||
### 2.1 第一阶段：核心AI功能优化（1-2周）
|
||||
|
||||
**目标**：优化已实现的核心AI功能，提升性能和可靠性。
|
||||
|
||||
**技术栈**：
|
||||
- TypeScript
|
||||
- OpenAI API (GPT-4o)
|
||||
- Redis 缓存
|
||||
- Express.js
|
||||
|
||||
**具体任务**：
|
||||
1. **优化AIService中的API调用**
|
||||
- 实现API调用的重试机制
|
||||
- 添加请求超时控制
|
||||
- 实现批量API调用，减少网络请求次数
|
||||
|
||||
2. **优化缓存策略**
|
||||
- 改进CoreEngineService中的缓存键生成算法
|
||||
- 实现缓存过期策略
|
||||
- 增加缓存命中率监控
|
||||
|
||||
3. **提升多模态处理性能**
|
||||
- 优化图像处理流程
|
||||
- 实现图像压缩和预处理
|
||||
- 减少API调用延迟
|
||||
|
||||
**性能指标**：
|
||||
- API响应时间 < 2秒
|
||||
- 缓存命中率 > 80%
|
||||
- 错误率 < 1%
|
||||
|
||||
**验收标准**：
|
||||
- 所有核心AI功能正常运行
|
||||
- 性能指标达标
|
||||
- 代码通过TypeScript编译
|
||||
- 无运行时错误
|
||||
|
||||
### 2.2 第二阶段：扩展AI功能（2-3周）
|
||||
|
||||
**目标**：实现缺失的重要AI功能，扩展系统能力。
|
||||
|
||||
**技术栈**：
|
||||
- TypeScript
|
||||
- OpenAI API (GPT-4o)
|
||||
- TensorFlow.js (可选)
|
||||
- Redis 缓存
|
||||
|
||||
**具体任务**：
|
||||
1. **实现视频自动切片与卖点提取**
|
||||
- 视频内容分析
|
||||
- 自动识别关键帧
|
||||
- 生成卖点描述
|
||||
|
||||
2. **实现风格自动对齐**
|
||||
- 分析商品图像风格
|
||||
- 生成风格一致的营销素材
|
||||
- 应用于商品列表和详情页
|
||||
|
||||
3. **增强语义漂移检测**
|
||||
- 优化语义漂移算法
|
||||
- 实现自动修正机制
|
||||
- 提供可视化分析工具
|
||||
|
||||
**性能指标**：
|
||||
- 视频处理时间 < 10秒/分钟
|
||||
- 风格对齐准确率 > 90%
|
||||
- 语义漂移检测准确率 > 85%
|
||||
|
||||
**验收标准**：
|
||||
- 新功能通过功能测试
|
||||
- 性能指标达标
|
||||
- 代码质量符合规范
|
||||
- 文档完善
|
||||
|
||||
### 2.3 第三阶段：高级AI功能（3-4周）
|
||||
|
||||
**目标**：实现高级AI功能，提升系统智能化水平。
|
||||
|
||||
**技术栈**：
|
||||
- TypeScript
|
||||
- OpenAI API (GPT-4o)
|
||||
- 联邦学习框架
|
||||
- 图神经网络 (可选)
|
||||
|
||||
**具体任务**：
|
||||
1. **实现联邦学习模型**
|
||||
- 设计联邦学习架构
|
||||
- 实现模型训练和聚合
|
||||
- 提供模型性能监控
|
||||
|
||||
2. **增强AGI功能**
|
||||
- 实现多任务协同
|
||||
- 提升决策能力
|
||||
- 实现自主学习机制
|
||||
|
||||
3. **安全相关AI功能**
|
||||
- 增强侵权风险检测
|
||||
- 实现内容安全审核
|
||||
- 提供安全风险评估
|
||||
|
||||
**性能指标**：
|
||||
- 联邦学习模型准确率 > 95%
|
||||
- AGI任务完成率 > 90%
|
||||
- 安全检测准确率 > 98%
|
||||
|
||||
**验收标准**：
|
||||
- 高级功能通过集成测试
|
||||
- 性能指标达标
|
||||
- 系统稳定性良好
|
||||
- 文档和测试覆盖完整
|
||||
|
||||
## 3. 技术实现要点
|
||||
|
||||
### 3.1 代码结构优化
|
||||
|
||||
1. **模块化设计**
|
||||
- 将AI功能按模块划分
|
||||
- 实现松耦合的服务架构
|
||||
- 提供统一的API接口
|
||||
|
||||
2. **性能优化**
|
||||
- 实现异步处理
|
||||
- 优化内存使用
|
||||
- 减少网络延迟
|
||||
|
||||
3. **可靠性保障**
|
||||
- 实现错误处理和重试机制
|
||||
- 提供降级方案
|
||||
- 增加监控和日志
|
||||
|
||||
### 3.2 数据管理
|
||||
|
||||
1. **数据预处理**
|
||||
- 实现数据清洗和标准化
|
||||
- 优化数据存储结构
|
||||
- 提供数据质量监控
|
||||
|
||||
2. **模型管理**
|
||||
- 实现模型版本控制
|
||||
- 提供模型性能评估
|
||||
- 支持模型部署和回滚
|
||||
|
||||
### 3.3 安全性
|
||||
|
||||
1. **API安全**
|
||||
- 实现API密钥管理
|
||||
- 提供请求频率限制
|
||||
- 增加安全审计日志
|
||||
|
||||
2. **数据安全**
|
||||
- 实现数据加密
|
||||
- 提供访问控制
|
||||
- 符合数据隐私法规
|
||||
|
||||
## 4. 风险评估与应对策略
|
||||
|
||||
### 4.1 技术风险
|
||||
|
||||
1. **API调用限制**
|
||||
- 风险：OpenAI API调用频率限制
|
||||
- 应对：实现请求队列和节流机制
|
||||
|
||||
2. **模型性能**
|
||||
- 风险：模型预测准确性不足
|
||||
- 应对：持续模型评估和优化
|
||||
|
||||
3. **系统稳定性**
|
||||
- 风险：AI功能可能影响系统稳定性
|
||||
- 应对：实现隔离机制和监控
|
||||
|
||||
### 4.2 业务风险
|
||||
|
||||
1. **功能效果**
|
||||
- 风险：AI功能可能不符合业务预期
|
||||
- 应对：持续业务反馈和调整
|
||||
|
||||
2. **成本控制**
|
||||
- 风险：API调用成本可能过高
|
||||
- 应对：实现成本监控和优化
|
||||
|
||||
3. **合规性**
|
||||
- 风险：AI功能可能涉及合规问题
|
||||
- 应对：遵守相关法规和最佳实践
|
||||
|
||||
## 5. 实施计划
|
||||
|
||||
### 5.1 资源需求
|
||||
|
||||
1. **人力资源**
|
||||
- 前端开发：1人
|
||||
- 后端开发：2人
|
||||
- AI专家：1人
|
||||
|
||||
2. **硬件资源**
|
||||
- 开发服务器：2台
|
||||
- 测试环境：1套
|
||||
- 生产环境：按需扩展
|
||||
|
||||
### 5.2 时间规划
|
||||
|
||||
| 阶段 | 时间 | 主要任务 |
|
||||
|------|------|----------|
|
||||
| 第一阶段 | 1-2周 | 核心AI功能优化 |
|
||||
| 第二阶段 | 2-3周 | 扩展AI功能 |
|
||||
| 第三阶段 | 3-4周 | 高级AI功能 |
|
||||
| 测试与部署 | 1周 | 系统测试和部署 |
|
||||
|
||||
### 5.3 质量保证
|
||||
|
||||
1. **测试策略**
|
||||
- 单元测试：覆盖核心功能
|
||||
- 集成测试：验证模块间交互
|
||||
- 性能测试：确保性能指标达标
|
||||
|
||||
2. **代码审查**
|
||||
- 代码质量检查
|
||||
- 安全漏洞扫描
|
||||
- 性能瓶颈分析
|
||||
|
||||
3. **监控与维护**
|
||||
- 实时监控系统运行状态
|
||||
- 定期性能评估
|
||||
- 及时响应和修复问题
|
||||
|
||||
## 6. 预期成果
|
||||
|
||||
1. **功能成果**
|
||||
- 优化后的核心AI功能
|
||||
- 新增的扩展AI功能
|
||||
- 实现的高级AI功能
|
||||
|
||||
2. **性能成果**
|
||||
- 提升的系统响应速度
|
||||
- 降低的API调用成本
|
||||
- 提高的系统稳定性
|
||||
|
||||
3. **业务成果**
|
||||
- 增强的用户体验
|
||||
- 提升的业务效率
|
||||
- 增加的竞争优势
|
||||
|
||||
## 7. 结论
|
||||
|
||||
本分阶段实现策略旨在有序推进AI功能的开发和优化，确保系统稳定性和性能的同时，满足业务需求。通过明确的目标、技术栈选择、性能指标和验收标准，确保功能迭代的质量和效率。
|
||||
342
docs/ARCHIVE/05_AI/04_Quick_Reference_Card.md
Normal file
342
docs/ARCHIVE/05_AI/04_Quick_Reference_Card.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# AI 开发快速参考卡片（AI Development Quick Reference Card）
|
||||
|
||||
> **模块**: 05_AI - AI 开发快速参考
|
||||
> **更新日期**: 2026-03-20
|
||||
> **用途**: AI 开发时快速查阅的关键约束和规范
|
||||
|
||||
---
|
||||
|
||||
## 🔴 硬性约束（必须遵守）
|
||||
|
||||
### 1. TypeScript 类型安全
|
||||
|
||||
| 约束 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| ❌ **禁止 any** | 使用 `unknown` + 类型守卫 | `function handle(data: unknown)` |
|
||||
| ✅ **函数返回类型** | 所有函数必须声明返回类型 | `function getUser(): User` |
|
||||
| ✅ **API 类型定义** | 所有 API 必须定义类型 | `axios.get<ApiResponse<User>>('/api')` |
|
||||
| ✅ **Schema 驱动** | 类型从 Schema 推导 | `type User = z.infer<typeof UserSchema>` |
|
||||
|
||||
### 2. 逻辑集中化
|
||||
|
||||
| 层级 | 职责 | 禁止行为 |
|
||||
|------|------|----------|
|
||||
| **Controller** | 请求/响应 + 权限校验 | ❌ 业务逻辑 |
|
||||
| **Service** | 业务逻辑 + 状态流转 | ✅ 核心逻辑 |
|
||||
| **Repository** | 数据库 CRUD | ❌ 业务逻辑 |
|
||||
|
||||
### 3. 数据安全
|
||||
|
||||
| 约束 | 说明 |
|
||||
|------|------|
|
||||
| **表前缀** | 所有表必须以 `cf_` 开头 |
|
||||
| **金额字段** | 必须使用 `decimal(10,2)` |
|
||||
| **五元组** | tenantId, shopId, taskId, traceId, businessType |
|
||||
|
||||
### 4. 业务红线
|
||||
|
||||
| 场景 | 规则 |
|
||||
|------|------|
|
||||
| **B2B 利润率** | < 15% → 禁止报价 |
|
||||
| **B2C 利润率** | < 20% → 触发风控预警 |
|
||||
| **决策流程** | SUGGESTED → PENDING_REVIEW → EXECUTED/REJECTED |
|
||||
|
||||
---
|
||||
|
||||
## 🟡 开发流程
|
||||
|
||||
### 标准开发顺序
|
||||
|
||||
```
|
||||
1. Service（业务逻辑）
|
||||
↓
|
||||
2. Repository（数据访问）
|
||||
↓
|
||||
3. Controller（接口层）
|
||||
↓
|
||||
4. Frontend（前端实现）
|
||||
↓
|
||||
5. Test（测试用例）
|
||||
```
|
||||
|
||||
### 类型转换流程
|
||||
|
||||
```
|
||||
API 返回数据
|
||||
↓
|
||||
Schema 验证（zod）
|
||||
↓
|
||||
DTO 转换
|
||||
↓
|
||||
Domain 模型
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🟢 代码模板
|
||||
|
||||
### Service 层模板
|
||||
|
||||
```typescript
|
||||
import { z } from 'zod'
|
||||
import { User, UserDTO } from '@/types'
|
||||
import { UserSchema } from '@/types/domain/User.schema'
|
||||
|
||||
export class UserService {
|
||||
constructor(
|
||||
private readonly userRepository: UserRepository
|
||||
) {}
|
||||
|
||||
/**
|
||||
* 创建用户
|
||||
* [BE-U001] 用户创建服务
|
||||
*/
|
||||
async createUser(request: CreateUserRequest): Promise<UserDTO> {
|
||||
// 1. 验证请求数据
|
||||
const validatedRequest = CreateUserRequestSchema.parse(request)
|
||||
|
||||
// 2. 创建领域模型
|
||||
const user = UserSchema.parse({
|
||||
id: crypto.randomUUID(),
|
||||
username: validatedRequest.username,
|
||||
email: validatedRequest.email,
|
||||
role: validatedRequest.role,
|
||||
status: 'ACTIVE',
|
||||
createdAt: new Date(),
|
||||
updatedAt: new Date()
|
||||
})
|
||||
|
||||
// 3. 保存到数据库
|
||||
const savedUser = await this.userRepository.create(user)
|
||||
|
||||
// 4. 转换为 DTO
|
||||
return toUserDTO(savedUser)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Controller 层模板
|
||||
|
||||
```typescript
|
||||
import { Request, Response } from 'express'
|
||||
import { CreateUserRequest, CreateUserResponse } from '@/types'
|
||||
import { createSuccessResponse, createErrorResponse } from '@/types/shared/Response'
|
||||
|
||||
export class UserController {
|
||||
constructor(private readonly userService: UserService) {}
|
||||
|
||||
async createUser(req: Request, res: Response): Promise<void> {
|
||||
try {
|
||||
const request: CreateUserRequest = CreateUserRequestSchema.parse(req.body)
|
||||
const userDTO = await this.userService.createUser(request)
|
||||
|
||||
const response = createSuccessResponse({
|
||||
id: userDTO.id,
|
||||
username: userDTO.username,
|
||||
email: userDTO.email,
|
||||
role: userDTO.role,
|
||||
createdAt: userDTO.createdAt
|
||||
})
|
||||
|
||||
res.json(response)
|
||||
} catch (error) {
|
||||
const response = createErrorResponse(
|
||||
'INTERNAL_ERROR',
|
||||
error instanceof Error ? error.message : 'Unknown error'
|
||||
)
|
||||
res.status(500).json(response)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Schema 定义模板
|
||||
|
||||
```typescript
|
||||
import { z } from 'zod'
|
||||
|
||||
export const UserSchema = z.object({
|
||||
id: z.string().uuid(),
|
||||
username: z.string().min(3).max(50),
|
||||
email: z.string().email(),
|
||||
role: z.enum(['ADMIN', 'MANAGER', 'OPERATOR']),
|
||||
status: z.enum(['ACTIVE', 'INACTIVE']).default('ACTIVE'),
|
||||
createdAt: z.date(),
|
||||
updatedAt: z.date()
|
||||
})
|
||||
|
||||
export type User = z.infer<typeof UserSchema>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔵 常见错误对比
|
||||
|
||||
### ❌ 错误示例 vs ✅ 正确示例
|
||||
|
||||
#### 1. 类型定义
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：使用 any
|
||||
function handle(data: any) {
|
||||
return data.name
|
||||
}
|
||||
|
||||
// ✅ 正确：使用 unknown + 类型守卫
|
||||
function handle(data: unknown) {
|
||||
if (typeof data === 'object' && data !== null && 'name' in data) {
|
||||
return (data as { name: string }).name
|
||||
}
|
||||
throw new Error('Invalid data')
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 函数返回类型
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：未声明返回类型
|
||||
function getUser(userId: string) {
|
||||
return userRepository.findById(userId)
|
||||
}
|
||||
|
||||
// ✅ 正确：声明返回类型
|
||||
function getUser(userId: string): Promise<User | null> {
|
||||
return userRepository.findById(userId)
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. API 调用
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：未定义类型
|
||||
const response = await axios.get('/api/users')
|
||||
|
||||
// ✅ 正确：定义类型
|
||||
const response = await axios.get<ApiResponse<User[]>>('/api/users')
|
||||
const users = response.data.data
|
||||
```
|
||||
|
||||
#### 4. 业务逻辑位置
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：Controller 中写业务逻辑
|
||||
async createUser(req: Request, res: Response) {
|
||||
const { username, email } = req.body
|
||||
if (!username || !email) {
|
||||
return res.status(400).json({ error: 'Missing fields' })
|
||||
}
|
||||
const user = await this.userRepository.create({ username, email })
|
||||
res.json(user)
|
||||
}
|
||||
|
||||
// ✅ 正确：Controller 只负责请求/响应
|
||||
async createUser(req: Request, res: Response) {
|
||||
try {
|
||||
const userDTO = await this.userService.createUser(req.body)
|
||||
res.json(createSuccessResponse(userDTO))
|
||||
} catch (error) {
|
||||
res.status(500).json(createErrorResponse('ERROR', error.message))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. 类型定义方式
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：手动定义类型
|
||||
interface User {
|
||||
id: string
|
||||
name: string
|
||||
email: string
|
||||
}
|
||||
|
||||
// ✅ 正确：从 Schema 推导类型
|
||||
const UserSchema = z.object({
|
||||
id: z.string().uuid(),
|
||||
name: z.string(),
|
||||
email: z.string().email()
|
||||
})
|
||||
|
||||
type User = z.infer<typeof UserSchema>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🟣 检查清单
|
||||
|
||||
### 开发前检查
|
||||
|
||||
- [ ] 已阅读相关业务文档
|
||||
- [ ] 已理解状态机流转
|
||||
- [ ] 已确认任务依赖关系
|
||||
- [ ] 已声明文件占用
|
||||
|
||||
### 开发中检查
|
||||
|
||||
- [ ] 所有函数已声明返回类型
|
||||
- [ ] 所有 API 调用已定义类型
|
||||
- [ ] 业务逻辑在 Service 层
|
||||
- [ ] 类型从 Schema 推导
|
||||
- [ ] 所有类型从 `/types` 导入
|
||||
|
||||
### 提交前检查
|
||||
|
||||
- [ ] `tsc --noEmit` 无错误
|
||||
- [ ] `eslint` 无错误
|
||||
- [ ] 单元测试通过
|
||||
- [ ] 五元组已填写
|
||||
- [ ] JSDoc 注释完整
|
||||
|
||||
---
|
||||
|
||||
## 🟤 快速导航
|
||||
|
||||
| 文档 | 路径 |
|
||||
|------|------|
|
||||
| **TypeScript 编译规约** | `docs/01_Architecture/13_TypeScript_Standards.md` |
|
||||
| **代码质量规范** | `docs/01_Architecture/14_Code_Quality_Standards.md` |
|
||||
| **Schema 驱动开发** | `docs/01_Architecture/15_Schema_Driven_Development.md` |
|
||||
| **统一类型管理** | `docs/01_Architecture/16_Unified_Type_Management.md` |
|
||||
| **AI 开发规则** | `docs/05_AI/02_Rules.md` |
|
||||
| **项目硬性约束** | `.trae/rules/project-specific-rules.md` |
|
||||
|
||||
---
|
||||
|
||||
## 🟠 紧急情况处理
|
||||
|
||||
### 编译错误
|
||||
|
||||
```bash
|
||||
# 1. 检查类型错误
|
||||
npm run typecheck
|
||||
|
||||
# 2. 修复 ESLint 错误
|
||||
npm run lint:fix
|
||||
|
||||
# 3. 重新编译
|
||||
npm run build
|
||||
```
|
||||
|
||||
### 类型错误
|
||||
|
||||
```typescript
|
||||
// 快速修复：使用类型守卫
|
||||
if (isUser(data)) {
|
||||
// TypeScript 知道 data 是 User 类型
|
||||
}
|
||||
|
||||
// 快速修复：使用 Schema 验证
|
||||
const user = UserSchema.parse(data)
|
||||
```
|
||||
|
||||
### 业务逻辑错误
|
||||
|
||||
```typescript
|
||||
// 检查：业务逻辑是否在 Service 层
|
||||
// 检查：状态流转是否遵循状态机
|
||||
// 检查：权限校验是否完整
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*本卡片仅供快速参考，详细规范请查阅完整文档。*
|
||||
359
docs/ARCHIVE/05_AI/05_Development_Checklist.md
Normal file
359
docs/ARCHIVE/05_AI/05_Development_Checklist.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# AI 开发检查清单（AI Development Checklist）
|
||||
|
||||
> **模块**: 05_AI - AI 开发检查清单
|
||||
> **更新日期**: 2026-03-20
|
||||
> **用途**: AI 开发各阶段的强制检查项
|
||||
|
||||
---
|
||||
|
||||
## 📋 使用说明
|
||||
|
||||
AI 在开发过程中必须在以下阶段执行检查清单：
|
||||
|
||||
1. **开发前** - 任务领取和规划阶段
|
||||
2. **开发中** - 编码实现阶段
|
||||
3. **提交前** - 代码提交前验证
|
||||
4. **交付后** - 任务完成确认
|
||||
|
||||
---
|
||||
|
||||
## 🔵 开发前检查清单（Pre-Development Checklist）
|
||||
|
||||
### 1. 任务理解
|
||||
|
||||
- [ ] **已阅读任务文档**
|
||||
- 任务 ID 和描述
|
||||
- 验收标准
|
||||
- 依赖关系
|
||||
|
||||
- [ ] **已理解业务逻辑**
|
||||
- 业务闭环流程
|
||||
- 状态机流转
|
||||
- 权限要求
|
||||
|
||||
- [ ] **已确认技术方案**
|
||||
- 技术栈选择
|
||||
- 架构设计
|
||||
- 接口定义
|
||||
|
||||
### 2. 文档查阅
|
||||
|
||||
- [ ] **已查阅相关文档**
|
||||
- [ ] `.trae/rules/project-specific-rules.md` - 硬性约束
|
||||
- [ ] `docs/05_AI/02_Rules.md` - AI 开发规则
|
||||
- [ ] `docs/05_AI/04_Quick_Reference_Card.md` - 快速参考
|
||||
- [ ] `docs/01_Architecture/13_TypeScript_Standards.md` - TypeScript 规范
|
||||
- [ ] `docs/01_Architecture/15_Schema_Driven_Development.md` - Schema 驱动
|
||||
|
||||
- [ ] **已理解领域模型**
|
||||
- 实体关系
|
||||
- 数据模型
|
||||
- 业务规则
|
||||
|
||||
### 3. 任务领取
|
||||
|
||||
- [ ] **已检查任务状态**
|
||||
- 任务状态为 `pending`
|
||||
- 无其他 Agent 占用
|
||||
|
||||
- [ ] **已声明占用**
|
||||
- 在 Task_Overview.md 声明占用
|
||||
- 声明涉及文件
|
||||
- 声明预计完成时间
|
||||
|
||||
- [ ] **已领取完整任务包**
|
||||
- 领取同一闭环的完整任务链
|
||||
- 最小粒度不少于 2 个相关任务
|
||||
|
||||
---
|
||||
|
||||
## 🟢 开发中检查清单（During Development Checklist）
|
||||
|
||||
### 1. TypeScript 类型安全
|
||||
|
||||
- [ ] **类型定义**
|
||||
- [ ] 所有函数已声明返回类型
|
||||
- [ ] 所有变量已声明类型
|
||||
- [ ] 所有参数已声明类型
|
||||
- [ ] 禁止使用 `any` 类型
|
||||
|
||||
- [ ] **Schema 驱动**
|
||||
- [ ] 类型从 Schema（zod）推导
|
||||
- [ ] 所有外部数据经过 Schema 验证
|
||||
- [ ] 类型守卫已实现
|
||||
|
||||
- [ ] **类型导入**
|
||||
- [ ] 所有类型从 `/types` 目录导入
|
||||
- [ ] 禁止各模块重复定义类型
|
||||
|
||||
### 2. 逻辑集中化
|
||||
|
||||
- [ ] **Service 层**
|
||||
- [ ] 所有业务逻辑在 Service 层
|
||||
- [ ] 状态流转在 Service 层
|
||||
- [ ] 多模块协同在 Service 层
|
||||
|
||||
- [ ] **Controller 层**
|
||||
- [ ] 只负责请求/响应
|
||||
- [ ] 只负责权限校验
|
||||
- [ ] 无业务逻辑
|
||||
|
||||
- [ ] **Repository 层**
|
||||
- [ ] 只负责数据库 CRUD
|
||||
- [ ] 无业务逻辑
|
||||
|
||||
### 3. 数据安全
|
||||
|
||||
- [ ] **数据库**
|
||||
- [ ] 表名以 `cf_` 开头
|
||||
- [ ] 金额字段使用 `decimal(10,2)`
|
||||
- [ ] 复杂查询通过 `EXPLAIN` 校验
|
||||
|
||||
- [ ] **五元组**
|
||||
- [ ] tenantId 已填写
|
||||
- [ ] shopId 已填写
|
||||
- [ ] taskId 已填写
|
||||
- [ ] traceId 已填写
|
||||
- [ ] businessType 已填写
|
||||
|
||||
### 4. 业务规则
|
||||
|
||||
- [ ] **状态机**
|
||||
- [ ] 状态流转遵循 STATE_MACHINE
|
||||
- [ ] 非法状态流转已拦截
|
||||
|
||||
- [ ] **权限校验**
|
||||
- [ ] 使用 `authorize()` 中间件
|
||||
- [ ] 数据隔离已实现
|
||||
|
||||
- [ ] **利润红线**
|
||||
- [ ] B2B 利润率 ≥ 15%
|
||||
- [ ] B2C 利润率 ≥ 20%
|
||||
|
||||
### 5. 代码质量
|
||||
|
||||
- [ ] **命名规范**
|
||||
- [ ] 服务类使用 `Service` 后缀
|
||||
- [ ] 控制器类使用 `Controller` 后缀
|
||||
- [ ] 仓库类使用 `Repository` 后缀
|
||||
|
||||
- [ ] **注释规范**
|
||||
- [ ] 每个服务类包含完整 JSDoc
|
||||
- [ ] 每个方法包含参数和返回值说明
|
||||
- [ ] 关键业务逻辑已添加注释
|
||||
- [ ] 任务 ID 已标注
|
||||
|
||||
- [ ] **文件规模**
|
||||
- [ ] 单文件 ≤ 1500 行
|
||||
- [ ] 单函数 ≤ 120 行
|
||||
- [ ] UI 组件 ≤ 300 行
|
||||
|
||||
---
|
||||
|
||||
## 🟡 提交前检查清单（Pre-Commit Checklist）
|
||||
|
||||
### 1. 编译检查
|
||||
|
||||
- [ ] **TypeScript 编译**
|
||||
```bash
|
||||
npm run typecheck
|
||||
```
|
||||
- [ ] 无类型错误
|
||||
- [ ] 无编译警告
|
||||
|
||||
- [ ] **ESLint 检查**
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
- [ ] 无 ESLint 错误
|
||||
- [ ] 已修复可自动修复的问题
|
||||
|
||||
### 2. 测试检查
|
||||
|
||||
- [ ] **单元测试**
|
||||
```bash
|
||||
npm run test
|
||||
```
|
||||
- [ ] 所有测试通过
|
||||
- [ ] 测试覆盖率达标
|
||||
|
||||
- [ ] **集成测试**
|
||||
- [ ] 核心流程测试通过
|
||||
- [ ] 异常流程测试通过
|
||||
|
||||
### 3. 代码审查
|
||||
|
||||
- [ ] **自我审查**
|
||||
- [ ] 业务逻辑正确性
|
||||
- [ ] 状态机遵循情况
|
||||
- [ ] 权限校验完整性
|
||||
- [ ] 错误处理完整性
|
||||
- [ ] 性能优化
|
||||
- [ ] 安全漏洞
|
||||
|
||||
- [ ] **类型安全审查**
|
||||
- [ ] 无 `any` 类型
|
||||
- [ ] 所有函数有返回类型
|
||||
- [ ] 所有 API 有类型定义
|
||||
- [ ] 类型从 Schema 推导
|
||||
|
||||
### 4. 文档同步
|
||||
|
||||
- [ ] **文档更新**
|
||||
- [ ] API 文档已更新
|
||||
- [ ] 数据库文档已更新
|
||||
- [ ] 任务状态已更新
|
||||
|
||||
---
|
||||
|
||||
## 🟠 交付后检查清单（Post-Delivery Checklist）
|
||||
|
||||
### 1. 任务完成确认
|
||||
|
||||
- [ ] **功能验证**
|
||||
- [ ] 功能测试通过
|
||||
- [ ] 符合验收标准
|
||||
- [ ] 无回归问题
|
||||
|
||||
- [ ] **文档同步**
|
||||
- [ ] 任务状态更新为 `completed`
|
||||
- [ ] 相关文档已更新
|
||||
- [ ] 注释和 JSDoc 完整
|
||||
|
||||
### 2. 资源释放
|
||||
|
||||
- [ ] **占用释放**
|
||||
- [ ] Task_Overview.md 占用声明已清除
|
||||
- [ ] 文件占用已释放
|
||||
|
||||
- [ ] **知识沉淀**
|
||||
- [ ] 遇到的问题已记录
|
||||
- [ ] 解决方案已文档化
|
||||
|
||||
### 3. 质量确认
|
||||
|
||||
- [ ] **代码质量**
|
||||
- [ ] `GetDiagnostics` 无错误
|
||||
- [ ] 代码审查通过
|
||||
- [ ] 测试覆盖率达标
|
||||
|
||||
- [ ] **部署标准**
|
||||
- [ ] 数据库表已初始化
|
||||
- [ ] 核心逻辑已闭环
|
||||
- [ ] 最小冒烟测试已补充
|
||||
|
||||
---
|
||||
|
||||
## 🔴 禁止行为清单（Forbidden Actions）
|
||||
|
||||
### TypeScript 相关
|
||||
|
||||
- ❌ 使用 `any` 类型
|
||||
- ❌ 函数不声明返回类型
|
||||
- ❌ API 调用不定义类型
|
||||
- ❌ 手动定义类型（不从 Schema 推导）
|
||||
- ❌ 各模块重复定义类型
|
||||
|
||||
### 架构相关
|
||||
|
||||
- ❌ Controller 中写业务逻辑
|
||||
- ❌ 前端直接写业务规则
|
||||
- ❌ 直接操作数据库（不通过 Repository）
|
||||
- ❌ 跨 Domain 直接操作数据库模型
|
||||
- ❌ 跳过权限校验
|
||||
|
||||
### 数据相关
|
||||
|
||||
- ❌ 表名不以 `cf_` 开头
|
||||
- ❌ 金额字段使用 float/double
|
||||
- ❌ 代码中执行 `DROP/TRUNCATE`
|
||||
- ❌ 五元组未填写
|
||||
|
||||
### 业务相关
|
||||
|
||||
- ❌ Agent 直接修改核心业务数据
|
||||
- ❌ B2B 利润率 < 15% 报价
|
||||
- ❌ B2C 利润率 < 20% 无预警
|
||||
- ❌ 非法状态流转
|
||||
|
||||
### 协作相关
|
||||
|
||||
- ❌ 单独领取任务包内的部分任务
|
||||
- ❌ 不声明占用直接开始开发
|
||||
- ❌ 跨模块同时占用多个任务包
|
||||
- ❌ 占用超过 24 小时未释放
|
||||
|
||||
---
|
||||
|
||||
## 🟣 快速检查命令
|
||||
|
||||
```bash
|
||||
# TypeScript 类型检查
|
||||
npm run typecheck
|
||||
|
||||
# ESLint 检查
|
||||
npm run lint
|
||||
|
||||
# ESLint 自动修复
|
||||
npm run lint:fix
|
||||
|
||||
# 单元测试
|
||||
npm run test
|
||||
|
||||
# 测试覆盖率
|
||||
npm run test:coverage
|
||||
|
||||
# 完整验证
|
||||
npm run validate
|
||||
|
||||
# 构建
|
||||
npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 检查清单执行记录
|
||||
|
||||
AI 在每个阶段完成后，应记录检查清单执行情况：
|
||||
|
||||
```markdown
|
||||
## 检查清单执行记录
|
||||
|
||||
**任务 ID**: BE-U001
|
||||
**Agent**: AI-Backend-1
|
||||
**开始时间**: 2026-03-20 10:00
|
||||
|
||||
### 开发前检查
|
||||
- [x] 已阅读任务文档
|
||||
- [x] 已理解业务逻辑
|
||||
- [x] 已声明占用
|
||||
- 执行时间: 2026-03-20 10:05
|
||||
|
||||
### 开发中检查
|
||||
- [x] TypeScript 类型安全
|
||||
- [x] 逻辑集中化
|
||||
- [x] 数据安全
|
||||
- [x] 业务规则
|
||||
- [x] 代码质量
|
||||
- 执行时间: 2026-03-20 12:00
|
||||
|
||||
### 提交前检查
|
||||
- [x] TypeScript 编译
|
||||
- [x] ESLint 检查
|
||||
- [x] 单元测试
|
||||
- [x] 代码审查
|
||||
- 执行时间: 2026-03-20 13:00
|
||||
|
||||
### 交付后检查
|
||||
- [x] 功能验证
|
||||
- [x] 文档同步
|
||||
- [x] 资源释放
|
||||
- 执行时间: 2026-03-20 14:00
|
||||
|
||||
**完成时间**: 2026-03-20 14:00
|
||||
**状态**: ✅ 完成
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*本检查清单为强制执行项，AI 必须在每个阶段完成所有检查。*
|
||||
962
docs/ARCHIVE/05_AI/06_Wrong_vs_Right_Examples.md
Normal file
962
docs/ARCHIVE/05_AI/06_Wrong_vs_Right_Examples.md
Normal file
@@ -0,0 +1,962 @@
|
||||
# 错误示例与正确示例对比（Wrong vs Right Examples）
|
||||
|
||||
> **模块**: 05_AI - 错误示例与正确示例对比
|
||||
> **更新日期**: 2026-03-20
|
||||
> **用途**: 帮助 AI 快速识别错误代码模式并避免重复犯错
|
||||
|
||||
---
|
||||
|
||||
## 📋 使用说明
|
||||
|
||||
本文档通过对比错误示例和正确示例，帮助 AI：
|
||||
|
||||
1. **快速识别错误模式**
|
||||
2. **理解正确实现方式**
|
||||
3. **避免重复犯错**
|
||||
4. **提高代码质量**
|
||||
|
||||
---
|
||||
|
||||
## 1️⃣ TypeScript 类型安全
|
||||
|
||||
### 1.1 禁止 any 类型
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：使用 any 类型
|
||||
function handleData(data: any) {
|
||||
return data.name
|
||||
}
|
||||
|
||||
function processUser(user: any) {
|
||||
console.log(user.email)
|
||||
return user.id
|
||||
}
|
||||
|
||||
const userData: any = fetchUser()
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：使用 unknown + 类型守卫
|
||||
function handleData(data: unknown) {
|
||||
if (typeof data === 'object' && data !== null && 'name' in data) {
|
||||
return (data as { name: string }).name
|
||||
}
|
||||
throw new Error('Invalid data')
|
||||
}
|
||||
|
||||
// 正确：使用类型守卫函数
|
||||
function isUser(data: unknown): data is User {
|
||||
return (
|
||||
typeof data === 'object' &&
|
||||
data !== null &&
|
||||
'id' in data &&
|
||||
'email' in data &&
|
||||
typeof (data as User).id === 'string' &&
|
||||
typeof (data as User).email === 'string'
|
||||
)
|
||||
}
|
||||
|
||||
function processUser(data: unknown) {
|
||||
if (isUser(data)) {
|
||||
console.log(data.email)
|
||||
return data.id
|
||||
}
|
||||
throw new Error('Invalid user data')
|
||||
}
|
||||
|
||||
// 正确：使用 Schema 验证
|
||||
const userData = UserSchema.parse(fetchUser())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.2 函数必须声明返回类型
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：未声明返回类型
|
||||
function getUser(userId: string) {
|
||||
return userRepository.findById(userId)
|
||||
}
|
||||
|
||||
function calculateTotal(items: Item[]) {
|
||||
return items.reduce((sum, item) => sum + item.price, 0)
|
||||
}
|
||||
|
||||
async function fetchData(url: string) {
|
||||
const response = await fetch(url)
|
||||
return response.json()
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：声明返回类型
|
||||
function getUser(userId: string): Promise<User | null> {
|
||||
return userRepository.findById(userId)
|
||||
}
|
||||
|
||||
function calculateTotal(items: Item[]): number {
|
||||
return items.reduce((sum, item) => sum + item.price, 0)
|
||||
}
|
||||
|
||||
async function fetchData<T>(url: string): Promise<T> {
|
||||
const response = await fetch(url)
|
||||
return response.json() as Promise<T>
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.3 API 必须定义类型
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：未定义类型
|
||||
const response = await axios.get('/api/users')
|
||||
const users = response.data
|
||||
|
||||
const createResponse = await axios.post('/api/users', userData)
|
||||
|
||||
const product = await fetch('/api/products/123').then(res => res.json())
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：定义请求和响应类型
|
||||
interface ApiResponse<T> {
|
||||
success: boolean
|
||||
data: T
|
||||
message?: string
|
||||
}
|
||||
|
||||
interface User {
|
||||
id: string
|
||||
name: string
|
||||
email: string
|
||||
}
|
||||
|
||||
const response = await axios.get<ApiResponse<User[]>>('/api/users')
|
||||
const users = response.data.data
|
||||
|
||||
const createResponse = await axios.post<ApiResponse<User>>('/api/users', userData)
|
||||
|
||||
const product = await fetch('/api/products/123')
|
||||
.then(res => res.json() as Promise<ApiResponse<Product>>)
|
||||
.then(data => data.data)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.4 类型从 Schema 推导
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：手动定义类型
|
||||
interface User {
|
||||
id: string
|
||||
name: string
|
||||
email: string
|
||||
age: number
|
||||
}
|
||||
|
||||
interface Product {
|
||||
id: string
|
||||
name: string
|
||||
price: number
|
||||
}
|
||||
|
||||
// 错误：类型和 Schema 不一致
|
||||
const UserSchema = z.object({
|
||||
id: z.string(),
|
||||
name: z.string(),
|
||||
email: z.string().email()
|
||||
// 缺少 age 字段
|
||||
})
|
||||
|
||||
type User = z.infer<typeof UserSchema>
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：从 Schema 推导类型
|
||||
import { z } from 'zod'
|
||||
|
||||
const UserSchema = z.object({
|
||||
id: z.string().uuid(),
|
||||
name: z.string().min(1).max(100),
|
||||
email: z.string().email(),
|
||||
age: z.number().int().positive()
|
||||
})
|
||||
|
||||
type User = z.infer<typeof UserSchema>
|
||||
|
||||
const ProductSchema = z.object({
|
||||
id: z.string().uuid(),
|
||||
name: z.string().min(1).max(200),
|
||||
price: z.number().positive()
|
||||
})
|
||||
|
||||
type Product = z.infer<typeof ProductSchema>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.5 统一类型中心
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：各模块重复定义类型
|
||||
// dashboard/src/pages/User/User.tsx
|
||||
interface User {
|
||||
id: string
|
||||
name: string
|
||||
}
|
||||
|
||||
// server/src/models/User.ts
|
||||
interface User {
|
||||
id: string
|
||||
name: string
|
||||
email: string
|
||||
}
|
||||
|
||||
// extension/src/types/User.ts
|
||||
interface User {
|
||||
id: string
|
||||
name: string
|
||||
email: string
|
||||
role: string
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：从类型中心导入
|
||||
// types/domain/User.ts
|
||||
export const UserSchema = z.object({
|
||||
id: z.string().uuid(),
|
||||
name: z.string(),
|
||||
email: z.string().email(),
|
||||
role: z.enum(['ADMIN', 'MANAGER', 'OPERATOR'])
|
||||
})
|
||||
|
||||
export type User = z.infer<typeof UserSchema>
|
||||
|
||||
// dashboard/src/pages/User/User.tsx
|
||||
import { User } from '@/types/domain/User'
|
||||
|
||||
// server/src/models/User.ts
|
||||
import { User } from '@/types/domain/User'
|
||||
|
||||
// node-agent/src/index.ts
|
||||
import { User } from '@/types/domain/User'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2️⃣ 逻辑集中化
|
||||
|
||||
### 2.1 Controller 层职责
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：Controller 中写业务逻辑
|
||||
export class UserController {
|
||||
async createUser(req: Request, res: Response) {
|
||||
const { username, email, password } = req.body
|
||||
|
||||
// 业务逻辑在 Controller 中
|
||||
if (!username || !email || !password) {
|
||||
return res.status(400).json({ error: 'Missing fields' })
|
||||
}
|
||||
|
||||
if (password.length < 8) {
|
||||
return res.status(400).json({ error: 'Password too short' })
|
||||
}
|
||||
|
||||
const hashedPassword = await bcrypt.hash(password, 10)
|
||||
|
||||
const user = await this.userRepository.create({
|
||||
username,
|
||||
email,
|
||||
passwordHash: hashedPassword,
|
||||
role: 'OPERATOR',
|
||||
status: 'ACTIVE'
|
||||
})
|
||||
|
||||
res.json(user)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：Controller 只负责请求/响应
|
||||
export class UserController {
|
||||
constructor(private readonly userService: UserService) {}
|
||||
|
||||
async createUser(req: Request, res: Response) {
|
||||
try {
|
||||
const userDTO = await this.userService.createUser(req.body)
|
||||
res.json(createSuccessResponse(userDTO))
|
||||
} catch (error) {
|
||||
if (error instanceof ValidationError) {
|
||||
res.status(400).json(createErrorResponse('VALIDATION_ERROR', error.message))
|
||||
} else {
|
||||
res.status(500).json(createErrorResponse('INTERNAL_ERROR', error.message))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 业务逻辑在 Service 层
|
||||
export class UserService {
|
||||
async createUser(request: CreateUserRequest): Promise<UserDTO> {
|
||||
// 1. 验证请求数据
|
||||
const validatedRequest = CreateUserRequestSchema.parse(request)
|
||||
|
||||
// 2. 业务逻辑处理
|
||||
const hashedPassword = await this.hashPassword(validatedRequest.password)
|
||||
|
||||
// 3. 创建领域模型
|
||||
const user = UserSchema.parse({
|
||||
id: crypto.randomUUID(),
|
||||
username: validatedRequest.username,
|
||||
email: validatedRequest.email,
|
||||
passwordHash: hashedPassword,
|
||||
role: validatedRequest.role || 'OPERATOR',
|
||||
status: 'ACTIVE',
|
||||
createdAt: new Date(),
|
||||
updatedAt: new Date()
|
||||
})
|
||||
|
||||
// 4. 保存到数据库
|
||||
const savedUser = await this.userRepository.create(user)
|
||||
|
||||
// 5. 转换为 DTO
|
||||
return toUserDTO(savedUser)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.2 前端业务规则
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：前端直接写业务规则
|
||||
function ProductCard({ product }: { product: Product }) {
|
||||
// 业务规则在前端
|
||||
const profitMargin = (product.price - product.cost) / product.price
|
||||
|
||||
// 业务判断在前端
|
||||
const canSell = profitMargin >= 0.15
|
||||
|
||||
// 状态判断在前端
|
||||
const statusText = product.status === 'ACTIVE' ? '可售' : '不可售'
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h3>{product.name}</h3>
|
||||
<p>利润率: {(profitMargin * 100).toFixed(2)}%</p>
|
||||
<p>状态: {statusText}</p>
|
||||
{canSell && <button>购买</button>}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：前端只负责展示
|
||||
function ProductCard({ product }: { product: ProductDTO }) {
|
||||
return (
|
||||
<div>
|
||||
<h3>{product.name}</h3>
|
||||
<p>利润率: {product.profitMargin}%</p>
|
||||
<p>状态: {product.statusText}</p>
|
||||
{product.canSell && <button onClick={() => handleBuy(product)}>购买</button>}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
// 业务规则在 Service 层
|
||||
export class ProductService {
|
||||
async getProduct(id: string): Promise<ProductDTO> {
|
||||
const product = await this.productRepository.findById(id)
|
||||
|
||||
if (!product) {
|
||||
throw new NotFoundError('Product', id)
|
||||
}
|
||||
|
||||
// 业务规则计算
|
||||
const profitMargin = this.calculateProfitMargin(product)
|
||||
const canSell = this.checkProfitMargin(profitMargin, product.businessType)
|
||||
const statusText = this.getStatusText(product.status)
|
||||
|
||||
return {
|
||||
...product,
|
||||
profitMargin: (profitMargin * 100).toFixed(2),
|
||||
canSell,
|
||||
statusText
|
||||
}
|
||||
}
|
||||
|
||||
private calculateProfitMargin(product: Product): number {
|
||||
return (product.price - product.cost) / product.price
|
||||
}
|
||||
|
||||
private checkProfitMargin(margin: number, businessType: 'B2B' | 'B2C'): boolean {
|
||||
const threshold = businessType === 'B2B' ? 0.15 : 0.20
|
||||
return margin >= threshold
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.3 数据库操作
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：直接操作数据库
|
||||
export class UserController {
|
||||
async getUser(req: Request, res: Response) {
|
||||
// 直接使用数据库连接
|
||||
const user = await db('users').where({ id: req.params.id }).first()
|
||||
res.json(user)
|
||||
}
|
||||
}
|
||||
|
||||
// 错误：跨模块直接操作数据库
|
||||
export class OrderService {
|
||||
async createOrder(orderData: OrderData) {
|
||||
// 直接操作商品表
|
||||
const product = await db('products').where({ id: orderData.productId }).first()
|
||||
|
||||
// 直接更新库存
|
||||
await db('inventory').where({ product_id: orderData.productId }).decrement('quantity', orderData.quantity)
|
||||
|
||||
// 直接创建订单
|
||||
const order = await db('orders').insert(orderData)
|
||||
|
||||
return order
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：通过 Repository 层操作数据库
|
||||
export class UserController {
|
||||
constructor(
|
||||
private readonly userService: UserService
|
||||
) {}
|
||||
|
||||
async getUser(req: Request, res: Response) {
|
||||
const user = await this.userService.getUser(req.params.id)
|
||||
res.json(createSuccessResponse(user))
|
||||
}
|
||||
}
|
||||
|
||||
// 正确：通过 Service 层协调多模块
|
||||
export class OrderService {
|
||||
constructor(
|
||||
private readonly orderRepository: OrderRepository,
|
||||
private readonly productService: ProductService,
|
||||
private readonly inventoryService: InventoryService
|
||||
) {}
|
||||
|
||||
async createOrder(orderData: OrderData): Promise<Order> {
|
||||
// 通过 Service 获取商品信息
|
||||
const product = await this.productService.getProduct(orderData.productId)
|
||||
|
||||
// 通过 Service 更新库存
|
||||
await this.inventoryService.decreaseStock(orderData.productId, orderData.quantity)
|
||||
|
||||
// 通过 Repository 创建订单
|
||||
const order = await this.orderRepository.create(orderData)
|
||||
|
||||
return order
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3️⃣ 数据安全
|
||||
|
||||
### 3.1 表命名规范
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：表名不以 cf_ 开头
|
||||
await db.schema.createTable('users', (table) => {
|
||||
table.string('id').primary()
|
||||
table.string('name')
|
||||
table.string('email')
|
||||
})
|
||||
|
||||
await db.schema.createTable('products', (table) => {
|
||||
table.string('id').primary()
|
||||
table.string('name')
|
||||
table.decimal('price')
|
||||
})
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：表名以 cf_ 开头
|
||||
await db.schema.createTable('cf_users', (table) => {
|
||||
table.string('id').primary()
|
||||
table.string('name')
|
||||
table.string('email')
|
||||
})
|
||||
|
||||
await db.schema.createTable('cf_products', (table) => {
|
||||
table.string('id').primary()
|
||||
table.string('name')
|
||||
table.decimal('price', 10, 2) // 金额字段使用 decimal(10,2)
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.2 金额字段
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：金额字段使用 float/double
|
||||
await db.schema.createTable('cf_orders', (table) => {
|
||||
table.string('id').primary()
|
||||
table.float('total_amount') // 错误
|
||||
table.double('subtotal') // 错误
|
||||
})
|
||||
|
||||
// 错误：金额计算使用浮点数
|
||||
const total = 10.5 + 20.3 // 30.800000000000004
|
||||
const price = product.price * 1.1 // 浮点数精度问题
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：金额字段使用 decimal(10,2)
|
||||
await db.schema.createTable('cf_orders', (table) => {
|
||||
table.string('id').primary()
|
||||
table.decimal('total_amount', 10, 2) // 正确
|
||||
table.decimal('subtotal', 10, 2) // 正确
|
||||
})
|
||||
|
||||
// 正确：金额计算使用整数（分）或 decimal
|
||||
const total = Math.round((10.5 + 20.3) * 100) / 100 // 30.80
|
||||
const price = Math.round(product.price * 1.1 * 100) / 100
|
||||
|
||||
// 或使用 decimal.js
|
||||
import Decimal from 'decimal.js'
|
||||
const total = new Decimal(10.5).plus(20.3).toNumber() // 30.8
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.3 五元组
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：缺少五元组
|
||||
async function processOrder(orderId: string) {
|
||||
const order = await orderRepository.findById(orderId)
|
||||
await orderService.process(order)
|
||||
}
|
||||
|
||||
// 错误：五元组不完整
|
||||
const log = {
|
||||
orderId: '123',
|
||||
action: 'process',
|
||||
timestamp: new Date()
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：包含完整五元组
|
||||
interface TaskContext {
|
||||
tenantId: string
|
||||
shopId: string
|
||||
taskId: string
|
||||
traceId: string
|
||||
businessType: 'TOC' | 'TOB'
|
||||
}
|
||||
|
||||
async function processOrder(orderId: string, context: TaskContext) {
|
||||
const order = await orderRepository.findById(orderId)
|
||||
|
||||
// 记录日志时包含五元组
|
||||
logger.info('Processing order', {
|
||||
...context,
|
||||
orderId,
|
||||
action: 'process'
|
||||
})
|
||||
|
||||
await orderService.process(order, context)
|
||||
}
|
||||
|
||||
// 正确：五元组完整
|
||||
const log = {
|
||||
tenantId: 'tenant-123',
|
||||
shopId: 'shop-456',
|
||||
taskId: 'task-789',
|
||||
traceId: 'trace-abc',
|
||||
businessType: 'TOC',
|
||||
orderId: '123',
|
||||
action: 'process',
|
||||
timestamp: new Date()
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4️⃣ 业务规则
|
||||
|
||||
### 4.1 状态机流转
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：非法状态流转
|
||||
async function updateOrderStatus(orderId: string, newStatus: string) {
|
||||
const order = await orderRepository.findById(orderId)
|
||||
|
||||
// 直接修改状态，未检查流转规则
|
||||
order.status = newStatus
|
||||
await orderRepository.update(orderId, order)
|
||||
}
|
||||
|
||||
// 错误：跳过状态
|
||||
async function shipOrder(orderId: string) {
|
||||
const order = await orderRepository.findById(orderId)
|
||||
|
||||
// 从 PENDING 直接跳到 SHIPPED，跳过 PAID 和 PROCESSING
|
||||
order.status = 'SHIPPED'
|
||||
await orderRepository.update(orderId, order)
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：通过 Service 层遵循状态机
|
||||
export class OrderService {
|
||||
private readonly STATE_TRANSITIONS = {
|
||||
PENDING: ['PAID', 'CANCELLED'],
|
||||
PAID: ['PROCESSING', 'REFUNDED'],
|
||||
PROCESSING: ['SHIPPED', 'REFUNDED'],
|
||||
SHIPPED: ['COMPLETED', 'REFUNDED'],
|
||||
COMPLETED: [],
|
||||
CANCELLED: [],
|
||||
REFUNDED: []
|
||||
}
|
||||
|
||||
async updateOrderStatus(
|
||||
orderId: string,
|
||||
newStatus: OrderStatus,
|
||||
context: TaskContext
|
||||
): Promise<Order> {
|
||||
const order = await this.orderRepository.findById(orderId)
|
||||
|
||||
if (!order) {
|
||||
throw new NotFoundError('Order', orderId)
|
||||
}
|
||||
|
||||
// 检查状态流转是否合法
|
||||
if (!this.isValidTransition(order.status, newStatus)) {
|
||||
throw new Error(`Invalid state transition: ${order.status} -> ${newStatus}`)
|
||||
}
|
||||
|
||||
// 更新状态
|
||||
order.status = newStatus
|
||||
order.updatedAt = new Date()
|
||||
|
||||
const updatedOrder = await this.orderRepository.update(orderId, order)
|
||||
|
||||
// 记录状态变更日志
|
||||
logger.info('Order status updated', {
|
||||
...context,
|
||||
orderId,
|
||||
fromStatus: order.status,
|
||||
toStatus: newStatus
|
||||
})
|
||||
|
||||
return updatedOrder
|
||||
}
|
||||
|
||||
private isValidTransition(from: OrderStatus, to: OrderStatus): boolean {
|
||||
return this.STATE_TRANSITIONS[from]?.includes(to) || false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 权限校验
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：硬编码权限判断
|
||||
async function deleteUser(userId: string, req: Request) {
|
||||
const user = req.user
|
||||
|
||||
// 硬编码权限判断
|
||||
if (user.role !== 'ADMIN') {
|
||||
throw new Error('Permission denied')
|
||||
}
|
||||
|
||||
await userRepository.delete(userId)
|
||||
}
|
||||
|
||||
// 错误：跳过权限校验
|
||||
async function getAllUsers() {
|
||||
return await userRepository.findAll()
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：使用 authorize 中间件
|
||||
import { authorize } from '@/middleware/auth'
|
||||
|
||||
router.delete('/users/:id',
|
||||
authorize('user:delete'),
|
||||
userController.deleteUser
|
||||
)
|
||||
|
||||
// 正确：Controller 中调用 Service
|
||||
export class UserController {
|
||||
async deleteUser(req: Request, res: Response) {
|
||||
await this.userService.deleteUser(req.params.id)
|
||||
res.json(createSuccessResponse({ message: 'User deleted' }))
|
||||
}
|
||||
}
|
||||
|
||||
// 正确：Service 层实现权限逻辑
|
||||
export class UserService {
|
||||
async deleteUser(userId: string): Promise<void> {
|
||||
// 检查用户是否存在
|
||||
const user = await this.userRepository.findById(userId)
|
||||
if (!user) {
|
||||
throw new NotFoundError('User', userId)
|
||||
}
|
||||
|
||||
// 执行删除
|
||||
await this.userRepository.delete(userId)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.3 利润红线
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：未检查利润红线
|
||||
async function createQuote(productId: string, price: number) {
|
||||
const product = await productRepository.findById(productId)
|
||||
|
||||
// 未检查利润率
|
||||
const quote = await quoteRepository.create({
|
||||
productId,
|
||||
price,
|
||||
status: 'ACTIVE'
|
||||
})
|
||||
|
||||
return quote
|
||||
}
|
||||
|
||||
// 错误：仅用售价 - 采购价判断
|
||||
const profit = price - product.cost
|
||||
if (profit > 0) {
|
||||
// 允许报价
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：使用 PricingService 检查利润红线
|
||||
export class QuoteService {
|
||||
constructor(
|
||||
private readonly pricingService: PricingService,
|
||||
private readonly quoteRepository: QuoteRepository
|
||||
) {}
|
||||
|
||||
async createQuote(
|
||||
productId: string,
|
||||
price: number,
|
||||
businessType: 'B2B' | 'B2C'
|
||||
): Promise<Quote> {
|
||||
const product = await this.productRepository.findById(productId)
|
||||
|
||||
if (!product) {
|
||||
throw new NotFoundError('Product', productId)
|
||||
}
|
||||
|
||||
// 计算净利率（含平台费/物流/税费/汇率/售后/广告摊销）
|
||||
const profitMargin = await this.pricingService.calculateProfitMargin({
|
||||
price,
|
||||
cost: product.cost,
|
||||
platform: product.platform,
|
||||
businessType
|
||||
})
|
||||
|
||||
// 检查利润红线
|
||||
if (businessType === 'B2B' && profitMargin < 0.15) {
|
||||
throw new Error('B2B profit margin must be at least 15%')
|
||||
}
|
||||
|
||||
if (businessType === 'B2C' && profitMargin < 0.20) {
|
||||
// 触发风控预警
|
||||
await this.riskAlertService.createAlert({
|
||||
type: 'LOW_PROFIT_MARGIN',
|
||||
productId,
|
||||
profitMargin,
|
||||
threshold: 0.20
|
||||
})
|
||||
}
|
||||
|
||||
// 创建报价
|
||||
const quote = await this.quoteRepository.create({
|
||||
productId,
|
||||
price,
|
||||
profitMargin,
|
||||
status: 'ACTIVE'
|
||||
})
|
||||
|
||||
return quote
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5️⃣ Mock 数据
|
||||
|
||||
### 5.1 硬编码 Mock 数据
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 错误：在业务组件中硬编码 Mock 数据
|
||||
function ProductList() {
|
||||
const products = [
|
||||
{ id: 1, name: 'Mock商品1', price: 100 },
|
||||
{ id: 2, name: 'Mock商品2', price: 200 }
|
||||
]
|
||||
|
||||
return (
|
||||
<div>
|
||||
{products.map(p => (
|
||||
<div key={p.id}>{p.name}</div>
|
||||
))}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
// 错误：通过 if 判断切换 Mock/真实数据
|
||||
async function getProducts() {
|
||||
if (process.env.NODE_ENV === 'development') {
|
||||
return mockProducts
|
||||
}
|
||||
return await api.getProducts()
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 正确：通过 DataSource 抽象层
|
||||
// services/productDataSource.ts
|
||||
import { ProductDTOSchema, type ProductDTO } from '@/types'
|
||||
|
||||
export const productDataSource = {
|
||||
async list(): Promise<ProductDTO[]> {
|
||||
if (process.env.REACT_APP_USE_MOCK === 'true') {
|
||||
const { mockProducts } = await import('@/mock/data/product.mock')
|
||||
return mockProducts.map(p => ProductDTOSchema.parse(p))
|
||||
}
|
||||
|
||||
const response = await api.getProducts()
|
||||
return response.data.map(p => ProductDTOSchema.parse(p))
|
||||
}
|
||||
}
|
||||
|
||||
// components/ProductList.tsx
|
||||
function ProductList() {
|
||||
const { data: products } = useQuery({
|
||||
queryKey: ['products'],
|
||||
queryFn: () => productDataSource.list()
|
||||
})
|
||||
|
||||
return (
|
||||
<div>
|
||||
{products?.map(p => (
|
||||
<div key={p.id}>{p.name}</div>
|
||||
))}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
// mock/data/product.mock.ts
|
||||
/**
|
||||
* [MOCK] 商品 Mock 数据
|
||||
* AI注意: 这是Mock实现，不是真实业务逻辑
|
||||
* 仅在USE_MOCK=true时启用
|
||||
*/
|
||||
export const mockProducts = [
|
||||
{ id: '1', name: '商品1', price: 100 },
|
||||
{ id: '2', name: '商品2', price: 200 }
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 总结
|
||||
|
||||
| 类别 | 常见错误 | 正确做法 |
|
||||
|------|----------|----------|
|
||||
| **TypeScript** | 使用 any、不声明返回类型 | 使用 unknown + 类型守卫、声明返回类型 |
|
||||
| **逻辑集中化** | Controller 写业务逻辑 | 业务逻辑在 Service 层 |
|
||||
| **数据安全** | 表名无前缀、金额用 float | 表名 cf_ 前缀、金额用 decimal(10,2) |
|
||||
| **业务规则** | 非法状态流转、跳过权限校验 | 遵循状态机、使用 authorize 中间件 |
|
||||
| **Mock 数据** | 硬编码 Mock、if 判断切换 | DataSource 抽象层、环境变量控制 |
|
||||
|
||||
---
|
||||
|
||||
*本文档持续更新，帮助 AI 避免常见错误。*
|
||||
360
docs/ARCHIVE/05_AI/07_TypeScript_Error_Fix_Guide.md
Normal file
360
docs/ARCHIVE/05_AI/07_TypeScript_Error_Fix_Guide.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# TypeScript 编译错误修复方案（TypeScript Error Fix Guide）
|
||||
|
||||
> **模块**: 05_AI - TypeScript 编译错误修复方案
|
||||
> **更新日期**: 2026-03-20
|
||||
> **用途**: 解决 613 个 TypeScript 编译错误的完整方案
|
||||
|
||||
---
|
||||
|
||||
## 📊 错误现状
|
||||
|
||||
### 当前错误统计
|
||||
|
||||
```bash
|
||||
$ npx tsc --noEmit 2>&1 | Select-String -Pattern "^src/" | Measure-Object
|
||||
|
||||
Count: 613
|
||||
```
|
||||
|
||||
### 错误分布分析
|
||||
|
||||
| 错误类型 | 预估占比 | 严重程度 |
|
||||
|---------|---------|---------|
|
||||
| **类型不匹配** | 40% | 🔴 高 |
|
||||
| **类型丢失（any）** | 25% | 🔴 高 |
|
||||
| **模块导入/导出错误** | 15% | 🟡 中 |
|
||||
| **未处理的 undefined/null** | 10% | 🟡 中 |
|
||||
| **编译器配置问题** | 5% | 🟢 低 |
|
||||
| **文件/路径问题** | 5% | 🟢 低 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 修复策略
|
||||
|
||||
### 策略一：分阶段修复（推荐）
|
||||
|
||||
#### 阶段 1：修复编译器配置（优先级：🔴 最高）
|
||||
|
||||
**目标**：确保 tsconfig.json 配置正确
|
||||
|
||||
**步骤**：
|
||||
1. 检查 server/tsconfig.json 配置
|
||||
2. 检查 dashboard/tsconfig.json 配置
|
||||
3. 检查 node-agent/tsconfig.json 配置
|
||||
4. 统一配置标准
|
||||
|
||||
**预期效果**：减少 5% 错误（约 30 个）
|
||||
|
||||
#### 阶段 2：修复 any 类型（优先级：🔴 最高）
|
||||
|
||||
**目标**：消除所有 any 类型
|
||||
|
||||
**步骤**：
|
||||
1. 运行 `npx tsc --noEmit 2>&1 | Select-String "any"` 找到所有 any 相关错误
|
||||
2. 逐个文件修复，使用 unknown + 类型守卫
|
||||
3. 使用 ESLint 规则 `@typescript-eslint/no-explicit-any: error` 强制禁止
|
||||
|
||||
**预期效果**：减少 25% 错误（约 150 个）
|
||||
|
||||
#### 阶段 3：修复类型不匹配（优先级：🔴 高）
|
||||
|
||||
**目标**：确保所有类型声明正确
|
||||
|
||||
**步骤**：
|
||||
1. 运行 `npx tsc --noEmit 2>&1 | Select-String "Type"` 找到类型不匹配错误
|
||||
2. 检查函数参数和返回值类型
|
||||
3. 检查对象属性类型
|
||||
4. 使用 Schema 驱动类型定义
|
||||
|
||||
**预期效果**：减少 40% 错误（约 245 个）
|
||||
|
||||
#### 阶段 4：修复模块导入错误（优先级：🟡 中）
|
||||
|
||||
**目标**：确保模块导入导出正确
|
||||
|
||||
**步骤**：
|
||||
1. 运行 `npx tsc --noEmit 2>&1 | Select-String "module"` 找到模块错误
|
||||
2. 统一使用 ES 模块或 CommonJS
|
||||
3. 检查路径别名配置
|
||||
4. 修复循环依赖
|
||||
|
||||
**预期效果**：减少 15% 错误（约 92 个）
|
||||
|
||||
#### 阶段 5：修复 undefined/null 问题（优先级：🟡 中）
|
||||
|
||||
**目标**：正确处理 undefined 和 null
|
||||
|
||||
**步骤**：
|
||||
1. 运行 `npx tsc --noEmit 2>&1 | Select-String "undefined\|null"` 找到相关错误
|
||||
2. 使用可选链操作符 `?.`
|
||||
3. 使用空值合并操作符 `??`
|
||||
4. 添加类型守卫
|
||||
|
||||
**预期效果**：减少 10% 错误（约 61 个）
|
||||
|
||||
---
|
||||
|
||||
## 🔧 具体修复方案
|
||||
|
||||
### 1. 修复 any 类型
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
function handleData(data: any) {
|
||||
return data.name
|
||||
}
|
||||
|
||||
const user: any = fetchUser()
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
function handleData(data: unknown): string {
|
||||
if (typeof data === 'object' && data !== null && 'name' in data) {
|
||||
return String((data as { name: unknown }).name)
|
||||
}
|
||||
throw new Error('Invalid data')
|
||||
}
|
||||
|
||||
const user: User = UserSchema.parse(fetchUser())
|
||||
```
|
||||
|
||||
#### 批量修复脚本
|
||||
|
||||
```bash
|
||||
# 查找所有 any 类型使用
|
||||
grep -r ": any" server/src --include="*.ts" | wc -l
|
||||
|
||||
# 查找所有 any 类型使用（PowerShell）
|
||||
Get-ChildItem -Path server\src -Filter *.ts -Recurse | Select-String ": any" | Measure-Object
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 修复类型不匹配
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
function getUser(id: string) {
|
||||
return userRepository.findById(id) // 返回类型未声明
|
||||
}
|
||||
|
||||
const price = res.price * 100 // res.price 类型未知
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
function getUser(id: string): Promise<User | null> {
|
||||
return userRepository.findById(id)
|
||||
}
|
||||
|
||||
const price = Number(res.price) * 100 // 显式转换类型
|
||||
```
|
||||
|
||||
#### 类型修复检查清单
|
||||
|
||||
- [ ] 所有函数声明返回类型
|
||||
- [ ] 所有变量声明类型
|
||||
- [ ] 所有参数声明类型
|
||||
- [ ] 所有 API 调用定义类型
|
||||
- [ ] 所有对象属性声明类型
|
||||
|
||||
---
|
||||
|
||||
### 3. 修复模块导入错误
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
// 混用 ES 模块和 CommonJS
|
||||
import { something } from './module'
|
||||
const other = require('./other')
|
||||
|
||||
// 路径错误
|
||||
import { User } from '../types/User' // 实际路径是 @/types/User
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
// 统一使用 ES 模块
|
||||
import { something } from './module'
|
||||
import { other } from './other'
|
||||
|
||||
// 使用路径别名
|
||||
import { User } from '@/types/User'
|
||||
```
|
||||
|
||||
#### tsconfig.json 路径配置
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"baseUrl": ".",
|
||||
"paths": {
|
||||
"@/*": ["src/*"],
|
||||
"@types/*": ["src/types/*"],
|
||||
"@services/*": ["src/services/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 修复 undefined/null 问题
|
||||
|
||||
#### ❌ 错误示例
|
||||
|
||||
```typescript
|
||||
const name = user.name // user 可能为 null
|
||||
const value = obj[key] // obj[key] 可能为 undefined
|
||||
```
|
||||
|
||||
#### ✅ 正确示例
|
||||
|
||||
```typescript
|
||||
const name = user?.name ?? 'Unknown'
|
||||
const value = obj[key] ?? defaultValue
|
||||
|
||||
// 或使用类型守卫
|
||||
if (user !== null && user !== undefined) {
|
||||
const name = user.name
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 ESLint 强制约束
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
|
||||
```
|
||||
|
||||
### .eslintrc.js 配置
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
parser: '@typescript-eslint/parser',
|
||||
plugins: ['@typescript-eslint'],
|
||||
extends: [
|
||||
'eslint:recommended',
|
||||
'plugin:@typescript-eslint/recommended',
|
||||
'plugin:@typescript-eslint/recommended-requiring-type-checking'
|
||||
],
|
||||
parserOptions: {
|
||||
project: './tsconfig.json'
|
||||
},
|
||||
rules: {
|
||||
'@typescript-eslint/no-explicit-any': 'error',
|
||||
'@typescript-eslint/explicit-function-return-type': 'error',
|
||||
'@typescript-eslint/explicit-module-boundary-types': 'error',
|
||||
'@typescript-eslint/consistent-type-imports': 'error',
|
||||
'@typescript-eslint/no-unused-vars': 'error',
|
||||
'@typescript-eslint/no-non-null-assertion': 'warn',
|
||||
'@typescript-eslint/prefer-nullish-coalescing': 'error',
|
||||
'@typescript-eslint/prefer-optional-chain': 'error',
|
||||
'@typescript-eslint/strict-boolean-expressions': 'error'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 修复执行计划
|
||||
|
||||
### 第 1 周：配置与工具
|
||||
|
||||
| 任务 | 预计时间 | 负责人 |
|
||||
|------|---------|--------|
|
||||
| 检查并修复 tsconfig.json 配置 | 2h | AI |
|
||||
| 安装并配置 ESLint | 2h | AI |
|
||||
| 运行首次完整错误扫描 | 1h | AI |
|
||||
| 分类错误并制定优先级 | 2h | AI |
|
||||
|
||||
### 第 2 周：核心错误修复
|
||||
|
||||
| 任务 | 预计时间 | 负责人 |
|
||||
|------|---------|--------|
|
||||
| 修复 any 类型错误（约 150 个） | 8h | AI |
|
||||
| 修复类型不匹配错误（约 245 个） | 12h | AI |
|
||||
| 修复模块导入错误（约 92 个） | 4h | AI |
|
||||
|
||||
### 第 3 周：剩余错误修复
|
||||
|
||||
| 任务 | 预计时间 | 负责人 |
|
||||
|------|---------|--------|
|
||||
| 修复 undefined/null 错误（约 61 个） | 4h | AI |
|
||||
| 修复文件/路径错误（约 30 个） | 2h | AI |
|
||||
| 全面测试验证 | 4h | AI |
|
||||
|
||||
---
|
||||
|
||||
## 📊 进度追踪
|
||||
|
||||
### 错误修复进度表
|
||||
|
||||
| 阶段 | 目标错误数 | 已修复 | 进度 |
|
||||
|------|-----------|--------|------|
|
||||
| 阶段 1：配置修复 | 30 | 0 | 0% |
|
||||
| 阶段 2：any 类型 | 150 | 0 | 0% |
|
||||
| 阶段 3：类型不匹配 | 245 | 0 | 0% |
|
||||
| 阶段 4：模块导入 | 92 | 0 | 0% |
|
||||
| 阶段 5：undefined/null | 61 | 0 | 0% |
|
||||
| **总计** | **613** | **0** | **0%** |
|
||||
|
||||
### 每日检查命令
|
||||
|
||||
```bash
|
||||
# 检查剩余错误数
|
||||
npx tsc --noEmit 2>&1 | Select-String -Pattern "^src/" | Measure-Object
|
||||
|
||||
# 检查 any 类型错误
|
||||
npx tsc --noEmit 2>&1 | Select-String "any" | Measure-Object
|
||||
|
||||
# 检查类型错误
|
||||
npx tsc --noEmit 2>&1 | Select-String "Type" | Measure-Object
|
||||
|
||||
# 检查模块错误
|
||||
npx tsc --noEmit 2>&1 | Select-String "module" | Measure-Object
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
### 修复原则
|
||||
|
||||
1. **优先修复配置问题**：配置错误会导致连锁反应
|
||||
2. **批量修复相同类型错误**：提高效率
|
||||
3. **每次修复后运行测试**：确保不引入新错误
|
||||
4. **保持代码风格一致**：遵循项目规范
|
||||
5. **记录修复过程**：便于后续参考
|
||||
|
||||
### 禁止行为
|
||||
|
||||
- ❌ 使用 `// @ts-ignore` 忽略错误
|
||||
- ❌ 使用 `// @ts-nocheck` 禁用检查
|
||||
- ❌ 将类型改为 `any` 来"解决"错误
|
||||
- ❌ 不运行测试就提交修复
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [TypeScript 编译规约](../01_Architecture/13_TypeScript_Standards.md)
|
||||
- [代码质量规范](../01_Architecture/14_Code_Quality_Standards.md)
|
||||
- [Schema 驱动开发](../01_Architecture/15_Schema_Driven_Development.md)
|
||||
- [统一类型管理](../01_Architecture/16_Unified_Type_Management.md)
|
||||
- [AI 开发检查清单](05_Development_Checklist.md)
|
||||
- [错误示例对比](06_Wrong_vs_Right_Examples.md)
|
||||
|
||||
---
|
||||
|
||||
*本文档将随着错误修复进度持续更新。*
|
||||
376
docs/ARCHIVE/05_AI/08_Type_Migration_Guide.md
Normal file
376
docs/ARCHIVE/05_AI/08_Type_Migration_Guide.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# 类型导入迁移指南
|
||||
|
||||
> **目的**: 帮助开发者将旧的类型导入方式迁移到统一类型中心
|
||||
> **更新日期**: 2026-03-20
|
||||
|
||||
---
|
||||
|
||||
## 1. 迁移概览
|
||||
|
||||
### 1.1 迁移目标
|
||||
|
||||
```
|
||||
旧方式（分散） 新方式（统一）
|
||||
─────────────────────────────────────────────────────
|
||||
各模块独立定义类型 → 从类型中心导入
|
||||
手动维护类型一致性 → Schema 自动推导
|
||||
无运行时验证 → Zod 运行时验证
|
||||
```
|
||||
|
||||
### 1.2 迁移原则
|
||||
|
||||
1. **渐进式迁移**: 不要求一次性全部迁移
|
||||
2. **向后兼容**: 保留旧的类型导出路径
|
||||
3. **验证优先**: 迁移后必须通过类型检查
|
||||
|
||||
---
|
||||
|
||||
## 2. 后端迁移
|
||||
|
||||
### 2.1 旧导入方式
|
||||
|
||||
```typescript
|
||||
// ❌ 旧方式：从本地文件导入
|
||||
import { User } from '../models/User';
|
||||
import { Product } from '../models/Product';
|
||||
import { Order } from '../models/Order';
|
||||
|
||||
// ❌ 旧方式：在文件中直接定义
|
||||
interface CreateUserRequest {
|
||||
username: string;
|
||||
email: string;
|
||||
password: string;
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 新导入方式
|
||||
|
||||
```typescript
|
||||
// ✅ 新方式：从统一类型中心导入
|
||||
import { User, Product, Order } from '@shared/types';
|
||||
import { CreateUserDTO, UpdateUserDTO } from '@shared/types';
|
||||
import { CreateUserSchema } from '@shared/schemas';
|
||||
|
||||
// ✅ 新方式：使用 Schema 验证
|
||||
const validated = CreateUserSchema.parse(requestBody);
|
||||
```
|
||||
|
||||
### 2.3 迁移步骤
|
||||
|
||||
```bash
|
||||
# 1. 查找需要迁移的文件
|
||||
grep -r "from '../models" server/src --include="*.ts"
|
||||
|
||||
# 2. 替换导入语句
|
||||
# 将 '../models/User' 替换为 '@shared/types'
|
||||
|
||||
# 3. 运行类型检查
|
||||
cd server && npx tsc --noEmit
|
||||
|
||||
# 4. 修复类型错误
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 前端迁移
|
||||
|
||||
### 3.1 旧导入方式
|
||||
|
||||
```typescript
|
||||
// ❌ 旧方式：从本地 types 导入
|
||||
import { User } from '../types/user';
|
||||
import { Product } from '../types/product';
|
||||
|
||||
// ❌ 旧方式：在组件中定义类型
|
||||
interface UserCardProps {
|
||||
user: {
|
||||
id: string;
|
||||
name: string;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 新导入方式
|
||||
|
||||
```typescript
|
||||
// ✅ 新方式：从 server 类型中心导入
|
||||
import { User, Product } from '@shared/types';
|
||||
import { UserDTO, ProductDTO } from '@shared/types';
|
||||
|
||||
// ✅ 新方式：使用类型化的 Props
|
||||
import { User } from '@shared/types';
|
||||
|
||||
interface UserCardProps {
|
||||
user: User;
|
||||
onEdit?: (user: User) => void;
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 迁移步骤
|
||||
|
||||
```bash
|
||||
# 1. 查找需要迁移的文件
|
||||
grep -r "from '../types" dashboard/src --include="*.ts" --include="*.tsx"
|
||||
|
||||
# 2. 替换导入语句
|
||||
# 将 '../types/user' 替换为 '@shared/types'
|
||||
|
||||
# 3. 运行类型检查
|
||||
cd dashboard && npx tsc --noEmit
|
||||
|
||||
# 4. 修复类型错误
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 插件端迁移
|
||||
|
||||
### 4.1 旧导入方式
|
||||
|
||||
```typescript
|
||||
// ❌ 旧方式：在插件中重复定义类型
|
||||
interface Message {
|
||||
type: string;
|
||||
payload: any;
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 新导入方式
|
||||
|
||||
```typescript
|
||||
// ✅ 新方式：从 server 类型中心导入
|
||||
import { BaseMessage, MessageResponse } from '../../server/src/shared/types';
|
||||
import { BaseMessageSchema } from '../../server/src/shared/schemas';
|
||||
|
||||
// ✅ 新方式：使用 Schema 验证
|
||||
const validated = BaseMessageSchema.parse(message);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 常见迁移场景
|
||||
|
||||
### 5.1 类型扩展
|
||||
|
||||
```typescript
|
||||
// ❌ 旧方式：扩展本地类型
|
||||
interface User {
|
||||
id: string;
|
||||
name: string;
|
||||
}
|
||||
|
||||
interface UserWithRole extends User {
|
||||
role: string;
|
||||
}
|
||||
|
||||
// ✅ 新方式：从 Schema 扩展
|
||||
import { User } from '@shared/types';
|
||||
import { z } from 'zod';
|
||||
|
||||
const UserWithRoleSchema = UserSchema.extend({
|
||||
role: z.string()
|
||||
});
|
||||
|
||||
type UserWithRole = z.infer<typeof UserWithRoleSchema>;
|
||||
```
|
||||
|
||||
### 5.2 类型组合
|
||||
|
||||
```typescript
|
||||
// ❌ 旧方式：手动组合类型
|
||||
interface CreateUserRequest {
|
||||
username: string;
|
||||
email: string;
|
||||
}
|
||||
|
||||
interface UpdateUserRequest {
|
||||
username?: string;
|
||||
email?: string;
|
||||
}
|
||||
|
||||
// ✅ 新方式：使用 Schema 工具
|
||||
import { UserSchema } from '@shared/schemas';
|
||||
import { z } from 'zod';
|
||||
|
||||
const CreateUserSchema = UserSchema.pick({
|
||||
username: true,
|
||||
email: true,
|
||||
password: true
|
||||
});
|
||||
|
||||
const UpdateUserSchema = UserSchema.partial().pick({
|
||||
username: true,
|
||||
email: true
|
||||
});
|
||||
```
|
||||
|
||||
### 5.3 API 响应类型
|
||||
|
||||
```typescript
|
||||
// ❌ 旧方式：手动定义响应类型
|
||||
interface ApiResponse<T> {
|
||||
success: boolean;
|
||||
data?: T;
|
||||
error?: string;
|
||||
}
|
||||
|
||||
// ✅ 新方式：使用统一响应类型
|
||||
import { ApiResponse, PaginatedResult } from '@shared/types';
|
||||
import { SuccessResponseSchema, ErrorResponseSchema } from '@shared/schemas';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 迁移检查清单
|
||||
|
||||
### 6.1 后端检查
|
||||
|
||||
- [ ] 所有 Service 层使用 `@shared/types` 导入
|
||||
- [ ] 所有 Controller 层使用 `@shared/schemas` 验证
|
||||
- [ ] 所有 Model 层类型从 Schema 推导
|
||||
- [ ] 运行 `npx tsc --noEmit` 无错误
|
||||
|
||||
### 6.2 前端检查
|
||||
|
||||
- [ ] 所有组件使用 `@shared/types` 导入
|
||||
- [ ] 所有 API 调用使用类型化的 DTO
|
||||
- [ ] 所有 Props 使用类型中心定义
|
||||
- [ ] 运行 `npx tsc --noEmit` 无错误
|
||||
|
||||
### 6.3 插件端检查
|
||||
|
||||
- [ ] 所有消息类型从 server 导入
|
||||
- [ ] 所有消息使用 Schema 验证
|
||||
- [ ] 运行 `npx tsc --noEmit` 无错误
|
||||
|
||||
---
|
||||
|
||||
## 7. 迁移脚本
|
||||
|
||||
### 7.1 自动替换脚本
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# migrate-types.sh
|
||||
|
||||
# 后端迁移
|
||||
find server/src -name "*.ts" -type f -exec sed -i \
|
||||
-e "s|from '../models/User'|from '@shared/types'|g" \
|
||||
-e "s|from '../models/Product'|from '@shared/types'|g" \
|
||||
-e "s|from '../models/Order'|from '@shared/types'|g" \
|
||||
{} +
|
||||
|
||||
# 前端迁移
|
||||
find dashboard/src -name "*.ts" -o -name "*.tsx" -type f -exec sed -i \
|
||||
-e "s|from '../types/user'|from '@shared/types'|g" \
|
||||
-e "s|from '../types/product'|from '@shared/types'|g" \
|
||||
{} +
|
||||
|
||||
echo "Migration complete. Please run: npx tsc --noEmit"
|
||||
```
|
||||
|
||||
### 7.2 类型检查脚本
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# check-types.sh
|
||||
|
||||
echo "Checking server types..."
|
||||
cd server && npx tsc --noEmit --skipLibCheck
|
||||
SERVER_EXIT=$?
|
||||
|
||||
echo "Checking dashboard types..."
|
||||
cd ../dashboard && npx tsc --noEmit --skipLibCheck
|
||||
DASHBOARD_EXIT=$?
|
||||
|
||||
echo "Checking node-agent types..."
|
||||
cd ../node-agent && npx tsc --noEmit --skipLibCheck
|
||||
NODE_AGENT_EXIT=$?
|
||||
|
||||
if [ $SERVER_EXIT -ne 0 ] || [ $DASHBOARD_EXIT -ne 0 ] || [ $NODE_AGENT_EXIT -ne 0 ]; then
|
||||
echo "❌ Type check failed"
|
||||
exit 1
|
||||
else
|
||||
echo "✅ All type checks passed"
|
||||
exit 0
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 常见问题
|
||||
|
||||
### Q1: 导入路径报错怎么办？
|
||||
|
||||
**A**: 检查 `tsconfig.json` 中的 `paths` 配置是否正确：
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"paths": {
|
||||
"@shared/types": ["../server/src/shared/types"],
|
||||
"@shared/schemas": ["../server/src/shared/schemas"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Q2: 类型不匹配怎么办？
|
||||
|
||||
**A**: 确保使用 Schema 推导类型，而不是手动定义：
|
||||
|
||||
```typescript
|
||||
// ❌ 手动定义可能与 Schema 不一致
|
||||
interface User {
|
||||
id: string;
|
||||
name: string;
|
||||
}
|
||||
|
||||
// ✅ 从 Schema 推导，保证一致
|
||||
import { User } from '@shared/types';
|
||||
// User 类型来自 UserSchema
|
||||
```
|
||||
|
||||
### Q3: 运行时验证失败怎么办？
|
||||
|
||||
**A**: 使用 Schema 的 `parse` 或 `safeParse` 方法：
|
||||
|
||||
```typescript
|
||||
import { CreateUserSchema } from '@shared/schemas';
|
||||
|
||||
// 安全解析
|
||||
const result = CreateUserSchema.safeParse(data);
|
||||
if (!result.success) {
|
||||
console.error(result.error.issues);
|
||||
return;
|
||||
}
|
||||
const validated = result.data;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 版本兼容
|
||||
|
||||
### 9.1 向后兼容
|
||||
|
||||
旧的导入路径仍然可用，但建议迁移：
|
||||
|
||||
```typescript
|
||||
// 仍然可用（向后兼容）
|
||||
import { User } from '../types/domain/User';
|
||||
|
||||
// 推荐使用（新方式）
|
||||
import { User } from '@shared/types';
|
||||
```
|
||||
|
||||
### 9.2 废弃计划
|
||||
|
||||
| 版本 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 1.0.0 | 当前 | 新旧方式并存 |
|
||||
| 1.1.0 | 计划 | 标记旧方式为 deprecated |
|
||||
| 2.0.0 | 计划 | 移除旧的类型定义文件 |
|
||||
|
||||
---
|
||||
|
||||
*迁移完成后，请更新 `server/src/shared/types/version.ts` 中的版本号*
|
||||
359
docs/ARCHIVE/05_AI/09_TypeScript_Error_Tasks.md
Normal file
359
docs/ARCHIVE/05_AI/09_TypeScript_Error_Tasks.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# TypeScript 编译错误任务列表
|
||||
|
||||
> **创建日期**: 2026-03-20
|
||||
> **总错误数**: 783 行输出（约 600+ 个错误）
|
||||
> **状态**: 🔴 待领取
|
||||
|
||||
---
|
||||
|
||||
## 🔒 当前任务占用状态
|
||||
|
||||
| Agent | 任务ID | 涉及文件 | 开始时间 | 状态 |
|
||||
|-------|--------|----------|----------|------|
|
||||
| AI-Backend-1 | TS-ERR-001 | src/api/controllers/ImageRecognitionController.ts, src/api/controllers/NaturalLanguageProcessingController.ts, src/api/controllers/RecommendationController.ts, src/api/routes/operation-agent.ts, src/api/routes/product.ts, src/core/ai/MerchantAnalysisService.ts, src/core/ai/MerchantPredictionService.ts, src/core/ai/ReturnAnalysisService.ts, src/core/ai/ReturnOptimizationService.ts, src/core/ai/SettlementOptimizationService.ts | 2026-03-20 10:00 | ✅ 已完成 |
|
||||
| AI-Backend-2 | TS-QUERY-001 | src/api/controllers/OmnichannelController.ts, src/api/controllers/SettingsController.ts | 2026-03-20 14:00 | ✅ 已完成 |
|
||||
| AI-Backend-3 | TS-DTO-001 | src/api/dto/StoreBindingDto.ts | 2026-03-20 14:30 | ✅ 已完成 |
|
||||
| AI-Backend-4 | TS-TEST-001 | src/core/engine/CoreEngineService.test.ts | 2026-03-20 15:00 | ✅ 已完成 |
|
||||
| AI-Backend-1 | TS-STATE-001 | src/core/engine/DataStateMachine.ts, src/core/engine/OrderStateMachine.ts, src/core/engine/ProductStateMachine.ts | 2026-03-20 16:00 | ✅ 已完成 |
|
||||
| AI-Backend-1 | TS-TYPE-001 | src/core/engine/DataStateMachine.ts, src/core/engine/OrderStateMachine.ts | 2026-03-20 17:00 | ✅ 已完成 |
|
||||
| AI-Backend-2 | TS-WORKER-001 | src/workers/PlatformSyncWorker.ts | 2026-03-20 18:00 | ✅ 已完成 |
|
||||
|
||||
---
|
||||
|
||||
## <20>📊 错误分类统计
|
||||
|
||||
| 错误类型 | 错误码 | 数量 | 优先级 | 状态 |
|
||||
|---------|--------|------|--------|------|
|
||||
| **error is of type 'unknown'** | TS18046 | ~30 | 🔴 高 | ✅ 已完成 |
|
||||
| **string \| string[] 类型不匹配** | TS2345/TS2322 | ~60 | 🔴 高 | 🔒 进行中 |
|
||||
| **Property has no initializer** | TS2564 | 5 | 🟡 中 | ✅ 已完成 |
|
||||
| **Property does not exist** | TS2339 | ~10 | 🟡 中 | ✅ 已完成 |
|
||||
| **StateMachine not callable** | TS2348 | 3 | 🟡 中 | ✅ 已完成 |
|
||||
| **Type 'string[]' not assignable** | TS2322 | 2 | 🟡 中 | ✅ 已完成 |
|
||||
|
||||
---
|
||||
|
||||
## 🔴 任务包 1：error 类型修复（TS18046）
|
||||
|
||||
### 任务ID: TS-ERR-001
|
||||
|
||||
**错误描述**: `'error' is of type 'unknown'`
|
||||
|
||||
**涉及文件**:
|
||||
| 文件 | 行号 | 状态 |
|
||||
|------|------|------|
|
||||
| `src/api/controllers/ImageRecognitionController.ts` | 87, 122, 190 | ✅ |
|
||||
| `src/api/controllers/NaturalLanguageProcessingController.ts` | 88, 124, 210 | ✅ |
|
||||
| `src/api/controllers/RecommendationController.ts` | 92, 120, 161, 209, 224 | ✅ |
|
||||
| `src/api/routes/operation-agent.ts` | 31, 42 | ✅ |
|
||||
| `src/api/routes/product.ts` | 29, 40 | ✅ |
|
||||
| `src/core/ai/MerchantAnalysisService.ts` | 142, 186 | ✅ |
|
||||
| `src/core/ai/MerchantPredictionService.ts` | 85, 136 | ✅ |
|
||||
| `src/core/ai/ReturnAnalysisService.ts` | 101, 160 | ✅ |
|
||||
| `src/core/ai/ReturnOptimizationService.ts` | 97 | ✅ |
|
||||
| `src/core/ai/SettlementOptimizationService.ts` | 81, 157 | ✅ |
|
||||
|
||||
**修复方案**:
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
catch (error) {
|
||||
console.error(error.message)
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
catch (error: unknown) {
|
||||
if (error instanceof Error) {
|
||||
console.error(error.message)
|
||||
}
|
||||
}
|
||||
|
||||
// 或使用类型守卫
|
||||
catch (error) {
|
||||
const message = error instanceof Error ? error.message : String(error)
|
||||
console.error(message)
|
||||
}
|
||||
```
|
||||
|
||||
**领取模板**:
|
||||
```markdown
|
||||
### 🔒 任务领取声明
|
||||
**Agent**: [你的标识]
|
||||
**领取时间**: [YYYY-MM-DD HH:MM]
|
||||
**任务ID**: TS-ERR-001
|
||||
**涉及文件**: [列出你要修复的文件]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔴 任务包 2：req.query 类型修复（TS2345/TS2322）
|
||||
|
||||
### 任务ID: TS-QUERY-001
|
||||
|
||||
**错误描述**: `Argument of type 'string | string[]' is not assignable to parameter of type 'string'`
|
||||
|
||||
**涉及文件**:
|
||||
| 文件 | 错误数 | 状态 |
|
||||
|------|--------|------|
|
||||
| `src/api/controllers/OmnichannelController.ts` | ~25 | 🔒 |
|
||||
| `src/api/controllers/SettingsController.ts` | ~35 | 🔒 |
|
||||
|
||||
**修复方案**:
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
const id = req.query.id as string
|
||||
|
||||
// ✅ 正确 - 方案1：类型守卫
|
||||
const id = Array.isArray(req.query.id) ? req.query.id[0] : req.query.id
|
||||
|
||||
// ✅ 正确 - 方案2：工具函数
|
||||
function getQueryParam(value: string | string[] | undefined): string | undefined {
|
||||
if (Array.isArray(value)) return value[0]
|
||||
return value
|
||||
}
|
||||
|
||||
const id = getQueryParam(req.query.id)
|
||||
|
||||
// ✅ 正确 - 方案3：强制断言（确定不会是数组时）
|
||||
const id = req.query.id as string | undefined
|
||||
```
|
||||
|
||||
**领取模板**:
|
||||
```markdown
|
||||
### 🔒 任务领取声明
|
||||
**Agent**: [你的标识]
|
||||
**领取时间**: [YYYY-MM-DD HH:MM]
|
||||
**任务ID**: TS-QUERY-001
|
||||
**涉及文件**: [列出你要修复的文件]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🟡 任务包 3：DTO 属性初始化修复（TS2564）
|
||||
|
||||
### 任务ID: TS-DTO-001
|
||||
|
||||
**错误描述**: `Property 'xxx' has no initializer and is not definitely assigned in the constructor`
|
||||
|
||||
**涉及文件**:
|
||||
| 文件 | 行号 | 属性 | 状态 |
|
||||
|------|------|------|------|
|
||||
| `src/api/dto/StoreBindingDto.ts` | 2 | merchantId | ✅ |
|
||||
| `src/api/dto/StoreBindingDto.ts` | 3 | platform | ✅ |
|
||||
| `src/api/dto/StoreBindingDto.ts` | 4 | platformShopId | ✅ |
|
||||
| `src/api/dto/StoreBindingDto.ts` | 5 | name | ✅ |
|
||||
| `src/api/dto/StoreBindingDto.ts` | 7 | authInfo | ✅ |
|
||||
|
||||
**修复方案**:
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
class StoreBindingDto {
|
||||
merchantId: string
|
||||
platform: string
|
||||
}
|
||||
|
||||
// ✅ 正确 - 方案1：添加默认值
|
||||
class StoreBindingDto {
|
||||
merchantId: string = ''
|
||||
platform: string = ''
|
||||
}
|
||||
|
||||
// ✅ 正确 - 方案2：使用可选属性
|
||||
class StoreBindingDto {
|
||||
merchantId?: string
|
||||
platform?: string
|
||||
}
|
||||
|
||||
// ✅ 正确 - 方案3：使用 definite assignment assertion
|
||||
class StoreBindingDto {
|
||||
merchantId!: string
|
||||
platform!: string
|
||||
}
|
||||
```
|
||||
|
||||
**领取模板**:
|
||||
```markdown
|
||||
### 🔒 任务领取声明
|
||||
**Agent**: [你的标识]
|
||||
**领取时间**: [YYYY-MM-DD HH:MM]
|
||||
**任务ID**: TS-DTO-001
|
||||
**涉及文件**: src/api/dto/StoreBindingDto.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🟡 任务包 4：测试文件类型修复（TS2345/TS2339）
|
||||
|
||||
### 任务ID: TS-TEST-001
|
||||
|
||||
**错误描述**: 测试文件中的类型不匹配
|
||||
|
||||
**涉及文件**:
|
||||
| 文件 | 行号 | 错误类型 | 状态 |
|
||||
|------|------|---------|------|
|
||||
| `src/core/engine/CoreEngineService.test.ts` | 27, 82, 85 | 缺少 data 属性 | ✅ |
|
||||
| `src/core/engine/CoreEngineService.test.ts` | 30-33 | 属性不存在 | ✅ |
|
||||
|
||||
**修复方案**:
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
const request = { id: 'test', type: 'order' }
|
||||
const result = engine.process(request)
|
||||
expect(result.validated).toBe(true)
|
||||
|
||||
// ✅ 正确
|
||||
const request: BusinessRequest = {
|
||||
id: 'test',
|
||||
type: 'order',
|
||||
data: {} // 添加必需的 data 属性
|
||||
}
|
||||
const result = engine.process(request)
|
||||
expect(result.status.validated).toBe(true) // 使用正确的属性路径
|
||||
```
|
||||
|
||||
**领取模板**:
|
||||
```markdown
|
||||
### 🔒 任务领取声明
|
||||
**Agent**: [你的标识]
|
||||
**领取时间**: [YYYY-MM-DD HH:MM]
|
||||
**任务ID**: TS-TEST-001
|
||||
**涉及文件**: src/core/engine/CoreEngineService.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🟡 任务包 5：StateMachine 构造函数修复（TS2348）
|
||||
|
||||
### 任务ID: TS-STATE-001
|
||||
|
||||
**错误描述**: `Value of type 'typeof StateMachine' is not callable. Did you mean to include 'new'?`
|
||||
|
||||
**涉及文件**:
|
||||
| 文件 | 行号 | 状态 |
|
||||
|------|------|------|
|
||||
| `src/core/engine/DataStateMachine.ts` | 31 | ✅ |
|
||||
| `src/core/engine/OrderStateMachine.ts` | 31 | ✅ |
|
||||
| `src/core/engine/ProductStateMachine.ts` | 29 | ✅ |
|
||||
|
||||
**修复方案**:
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
const machine = StateMachine(initialState, config)
|
||||
|
||||
// ✅ 正确
|
||||
const machine = new StateMachine(initialState, config)
|
||||
```
|
||||
|
||||
**领取模板**:
|
||||
```markdown
|
||||
### 🔒 任务领取声明
|
||||
**Agent**: [你的标识]
|
||||
**领取时间**: [YYYY-MM-DD HH:MM]
|
||||
**任务ID**: TS-STATE-001
|
||||
**涉及文件**: [列出你要修复的文件]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🟡 任务包 6：状态类型数组修复（TS2322）
|
||||
|
||||
### 任务ID: TS-TYPE-001
|
||||
|
||||
**错误描述**: `Type 'string[]' is not assignable to type 'xxx[]'`
|
||||
|
||||
**涉及文件**:
|
||||
| 文件 | 行号 | 状态 |
|
||||
|------|------|------|
|
||||
| `src/core/engine/DataStateMachine.ts` | 131 | ✅ |
|
||||
| `src/core/engine/OrderStateMachine.ts` | 139 | ✅ |
|
||||
|
||||
**修复方案**:
|
||||
```typescript
|
||||
// ❌ 错误
|
||||
const events: string[] = ['RETRY', 'VALID', 'PROCESS']
|
||||
|
||||
// ✅ 正确
|
||||
type DataEvent = 'RETRY' | 'VALID' | 'VALIDATE' | 'INVALID' | 'PROCESS' | 'PROCESS_SUCCESS' | 'PROCESS_ERROR'
|
||||
const events: DataEvent[] = ['RETRY', 'VALID', 'PROCESS']
|
||||
|
||||
// 或使用 as const
|
||||
const events = ['RETRY', 'VALID', 'PROCESS'] as const
|
||||
```
|
||||
|
||||
**领取模板**:
|
||||
```markdown
|
||||
### 🔒 任务领取声明
|
||||
**Agent**: [你的标识]
|
||||
**领取时间**: [YYYY-MM-DD HH:MM]
|
||||
**任务ID**: TS-TYPE-001
|
||||
**涉及文件**: [列出你要修复的文件]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🟡 任务包 7：WorkerHub 属性修复（TS2339）
|
||||
|
||||
### 任务ID: TS-WORKER-001
|
||||
|
||||
**错误描述**: `Property 'addJob' does not exist on type 'typeof WorkerHub'`
|
||||
|
||||
**涉及文件**:
|
||||
| 文件 | 行号 | 状态 |
|
||||
|------|------|------|
|
||||
| `src/workers/PlatformSyncWorker.ts` | 288 | ✅ |
|
||||
|
||||
**修复方案**:
|
||||
```typescript
|
||||
// 需要检查 WorkerHub 类定义，确保 addJob 方法存在且为静态方法
|
||||
// 或修改为实例方法调用
|
||||
```
|
||||
|
||||
**领取模板**:
|
||||
```markdown
|
||||
### 🔒 任务领取声明
|
||||
**Agent**: [你的标识]
|
||||
**领取时间**: [YYYY-MM-DD HH:MM]
|
||||
**任务ID**: TS-WORKER-001
|
||||
**涉及文件**: src/workers/PlatformSyncWorker.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 任务领取规则
|
||||
|
||||
### 领取原则
|
||||
1. **优先领取任务包**：必须优先领取同一类型的完整任务包
|
||||
2. **最小粒度**：单次领取不少于 1 个任务包
|
||||
3. **文件锁定**：同一文件同时只能被一个 Agent 修改
|
||||
|
||||
### 领取流程
|
||||
1. 在本文档顶部更新 🔒 当前占用区
|
||||
2. 修改对应任务的状态为 🔒 进行中
|
||||
3. 完成后更新状态为 ✅ 已完成
|
||||
4. 释放文件占用
|
||||
|
||||
---
|
||||
|
||||
## 🔒 当前任务占用状态
|
||||
|
||||
| Agent | 任务ID | 涉及文件 | 开始时间 | 状态 |
|
||||
|-------|--------|----------|----------|------|
|
||||
| AI-Backend-1 | TS-TEST-002 | src/tests/integration/IntegrationTestCases.ts, src/tests/integration/plugin.integration.test.ts, src/tests/integration/tuple-tracing.test.ts, src/tests/qa/TestDatabaseInitializer.ts, src/tests/unit/UnitTestCases.ts | 2026-03-21 10:00 | 🔒 进行中 |
|
||||
|
||||
---
|
||||
|
||||
## 📈 修复进度
|
||||
|
||||
| 任务包 | 总数 | 已完成 | 进度 |
|
||||
|--------|------|--------|------|
|
||||
| TS-ERR-001 | ~30 | 30 | 100% |
|
||||
| TS-QUERY-001 | ~60 | 60 | 100% |
|
||||
| TS-DTO-001 | 5 | 5 | 100% |
|
||||
| TS-TEST-001 | 8 | 8 | 100% |
|
||||
| TS-STATE-001 | 3 | 3 | 100% |
|
||||
| TS-TYPE-001 | 2 | 2 | 100% |
|
||||
| TS-WORKER-001 | 1 | 1 | 100% |
|
||||
| **总计** | **~109** | **109** | **100%** |
|
||||
|
||||
---
|
||||
|
||||
*本文档将持续更新，记录修复进度。*
|
||||
Reference in New Issue
Block a user