129 lines
6.3 KiB
Markdown
129 lines
6.3 KiB
Markdown
# 代码开发规范
|
|
|
|
## 1. 目标
|
|
|
|
本规范保证代码对普通开发者可连续阅读、对关键业务可解释、对历史版本可维护。规范适用于 Vue 3 前端、NestJS 后端、调度器、RabbitMQ Worker、数据适配器、规则引擎和 AI 分析模块。
|
|
|
|
## 2. 技术基线
|
|
|
|
- 前端：Vue 3、Vite、TypeScript、Dart Sass、Naive UI。
|
|
- 后端：NestJS、TypeScript。
|
|
- 数据库：MySQL；缓存：Redis；消息队列：RabbitMQ。
|
|
- 图表：Lightweight Charts负责K线和分时，ECharts负责热力图、分布和资金趋势。
|
|
- AI：由服务端调用兼容 OpenAI 格式的付费 API，密钥不得下发浏览器。
|
|
|
|
依赖版本必须由锁文件固定。引入新依赖前应说明用途、替代方案、体积或运行成本以及退出方案。
|
|
|
|
## 3. 文件组织与拆分尺度
|
|
|
|
代码按业务能力组织，而不是把每个函数、类型和常量拆成独立文件。
|
|
|
|
### 应当拆分
|
|
|
|
- 文件同时承担两个可独立变化的业务职责。
|
|
- 模块形成稳定复用边界，且确实被多个调用方使用。
|
|
- 单个文件已经难以在一次正常阅读中理解完整流程。
|
|
- 外部系统适配、持久化、消息传输与纯业务计算需要隔离测试。
|
|
|
|
### 不应拆分
|
|
|
|
- 只为减少行数创建单函数文件。
|
|
- 将同一业务流程拆成大量需要来回跳转的薄包装。
|
|
- 为尚未出现的复用场景提前抽象。
|
|
- 为形式上的“分层”添加不产生业务价值的转发层。
|
|
|
|
Vue 页面可以包含与页面强绑定的小型展示逻辑；当子区域拥有独立状态、独立测试价值或被复用时再提取组件。NestJS 模块应让入口、服务和领域计算的调用关系容易跟读。
|
|
|
|
## 4. 命名与语言
|
|
|
|
- 文件、变量、函数、类型和数据库字段使用清晰英文命名。
|
|
- 产品文案、业务日志、错误说明、代码注释和提交摘要优先使用中文。
|
|
- 禁止 `data1`、`temp2`、`handleThing` 等缺乏语义的命名。
|
|
- A 股领域词汇使用统一词典，例如 `limitUpCount`、`brokenBoardRate`、`marketBreadth`。
|
|
- 时间字段必须体现语义，例如 `tradeDate`、`snapshotAt`、`sourceUpdatedAt`，不得统称 `time`。
|
|
|
|
## 5. 注释规范
|
|
|
|
代码必须写详细但有信息价值的中文注释。注释解释“为什么、口径、限制和风险”，不复述语法。
|
|
|
|
### 必须注释
|
|
|
|
- 对外导出的公共接口、类型和关键函数。
|
|
- 涨跌停、复权、停牌、午间休市等 A 股特殊规则。
|
|
- 指标公式、阈值来源、单位、数据日期和缺失值处理。
|
|
- RabbitMQ 的幂等、重试、死信和消息顺序假设。
|
|
- Redis 与 MySQL 一致性边界和缓存失效策略。
|
|
- AI 输入裁剪、事实约束、降级和成本控制逻辑。
|
|
- 看似可以简化但因兼容性或历史原因必须保留的实现。
|
|
- 异常恢复、降级策略和安全边界。
|
|
|
|
### 禁止注释
|
|
|
|
```ts
|
|
// 将 count 加一
|
|
count += 1;
|
|
```
|
|
|
|
此类注释没有提供代码之外的信息。代码变更时，注释必须同步更新；失真的注释视为缺陷。
|
|
|
|
## 6. 类型与数据契约
|
|
|
|
- 禁止无理由使用 `any`；外部输入先以 `unknown` 接收并校验。
|
|
- HTTP API 使用版本化 OpenAPI 契约。
|
|
- RabbitMQ 事件包含 `eventId`、`eventType`、`schemaVersion`、`occurredAt`、`tradeDate`、`traceId` 和 `idempotencyKey`。
|
|
- 金额、成交额和比率必须明确单位，避免同一字段混用元、万元、亿元或百分比小数。
|
|
- 数据来源、采集时间、交易日期、完整性和口径版本必须可追溯。
|
|
|
|
## 7. 错误处理与日志
|
|
|
|
- 不吞异常，不使用空 `catch`。
|
|
- 对外错误不泄露密钥、内部地址和原始上游响应。
|
|
- 日志使用结构化字段，至少包含 `traceId`、任务类型、交易日期和数据源。
|
|
- 免费数据源失败时保留最后有效快照，并明确标记陈旧，禁止伪装实时数据。
|
|
- AI 失败不得影响规则分析和基础行情展示。
|
|
|
|
## 8. 前端规范
|
|
|
|
- 页面不得直接访问第三方行情源、Redis、RabbitMQ 或 AI 服务。
|
|
- 全局服务器状态使用 TanStack Vue Query，本地界面偏好使用 Pinia或轻量组合式函数。
|
|
- Sass token集中管理颜色、间距、圆角、字号和断点。
|
|
- A 股默认红涨绿跌，但状态必须同时提供文字或形状，不能只依赖颜色。
|
|
- 图表必须标注单位、时间范围、数据日期和更新时间。
|
|
- 所有核心交互覆盖加载、空、部分数据、错误和过期状态。
|
|
|
|
## 9. 后端与任务规范
|
|
|
|
- API、Scheduler和Worker作为独立进程维护，不在请求期间临时抓取全市场数据。
|
|
- Scheduler只决定何时投递；RabbitMQ负责任务传输；Worker负责执行；MySQL负责事实记录；Redis负责当前快照和短期状态。
|
|
- 消费者必须幂等，消息确认只能发生在持久化或可验证处理完成后。
|
|
- 免费数据源通过 Adapter 统一为内部模型，上层不得依赖供应商原始字段。
|
|
|
|
## 10. 测试要求
|
|
|
|
- 功能和缺陷修复遵循测试先行：先看到测试因缺少行为而失败，再实现最小代码。
|
|
- 纯规则和指标计算使用单元测试，期望值必须手工推导。
|
|
- 数据源 Adapter 使用契约测试和固定样本。
|
|
- HTTP 与 RabbitMQ 使用契约测试。
|
|
- 关键页面使用 Playwright流程测试和视觉截图对比。
|
|
- 合并前必须通过类型检查、测试、构建和适用的视觉验证。
|
|
|
|
## 11. 安全要求
|
|
|
|
- 禁止提交 `.env`、API Key、密码、真实账号和生产数据。
|
|
- AI 密钥、数据源凭证和支付凭证仅存在服务端密钥管理中。
|
|
- SQL必须参数化；外部输入必须在边界处校验。
|
|
- 日志和异常报告必须脱敏。
|
|
|
|
## 12. 代码 Review 要求
|
|
|
|
开发者完成自测不等于 Review 完成。审查者必须从功能 PRD、设计和 Git diff 出发，检查：
|
|
|
|
- 业务行为是否真正满足验收标准，是否存在遗漏分支。
|
|
- 类型、数据口径、缓存、消息、事务和异常恢复是否正确。
|
|
- 是否引入安全、性能、并发、幂等或数据一致性风险。
|
|
- 测试是否能捕获真实回归，而非只验证 Mock 或实现细节。
|
|
- 中文注释是否解释关键原因、口径和限制，是否存在失真注释。
|
|
- 文件拆分是否便于常规阅读，是否出现过度抽象或巨型多职责文件。
|
|
|
|
Critical 和 Important 问题必须修复并复审。Minor 问题可以延期，但必须写明理由和后续功能编号。
|