chore: 初始化项目与后端基础工程
This commit is contained in:
freedakgmail
@@ -0,0 +1,134 @@
|
||||
# AGENTS.md — AI 辅助开发协作规范
|
||||
|
||||
> 本文件定义 AI 辅助开发（Windsurf Cascade / 其他 AI Agent）在本项目中的协作规则。
|
||||
> 所有 AI Agent 必须同时遵守 `.windsurfrules`、`.windsurfrules.DEV-RULES` 和本文件。
|
||||
|
||||
---
|
||||
|
||||
## 1. 文档阅读顺序
|
||||
|
||||
开始任何开发任务前，AI Agent 必须按以下顺序阅读文档：
|
||||
|
||||
1. **`.windsurfrules`** — 精简规则，了解技术栈和禁止事项
|
||||
2. **`.windsurfrules.DEV-RULES` §0** — 文档骨架，了解项目文档结构
|
||||
3. **`pmdocs/2-task.md`** — 查看当前任务状态和进度
|
||||
4. **`pmdocs/1-prd-finance-v1.md`** — 了解要开发的功能需求
|
||||
5. **`pmdocs/changes/CHANGELOG.md`** — 查看需求变更历史
|
||||
6. **`run.md`** — 了解如何启动和测试
|
||||
7. 对应模块的现有代码 — 了解代码风格和模式
|
||||
|
||||
---
|
||||
|
||||
## 2. 代码修改原则
|
||||
|
||||
### 2.1 最小改动
|
||||
|
||||
- 优先最小化修改，不重写已有代码
|
||||
- 不删除与本次修改无关的代码和注释
|
||||
- 不创建随机文件，除非任务明确需要
|
||||
|
||||
### 2.2 遵循现有模式
|
||||
|
||||
- 后端：遵循模块三件套（Controller + Service + Table）模式
|
||||
- 前端：遵循现有页面结构（列表页/详情页/表单页模板）
|
||||
- 复用公共组件，禁止重复造轮子
|
||||
|
||||
### 2.3 同步更新文档
|
||||
|
||||
- 修改代码涉及行为变更 → 更新 `pmdocs/2-task.md` 任务状态
|
||||
- 修改 DB 结构 → 更新 `run.md` 数据库命令
|
||||
- 修改技术栈版本 → 更新 `run.md` §1 和 `.windsurfrules`
|
||||
- 新增/修改 API → 更新 `pmdocs/1-prd-finance-v1.md`（如有接口说明）
|
||||
|
||||
---
|
||||
|
||||
## 3. 任务管理
|
||||
|
||||
### 3.1 任务状态标记
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| `[ ]` | 未开始 |
|
||||
| `[~]` | 进行中 |
|
||||
| `[x]` | 已完成 |
|
||||
| `[!]` | 阻塞/有问题 |
|
||||
|
||||
### 3.2 任务编号
|
||||
|
||||
- `T1-W1-xx`：1期第1周第 xx 个任务
|
||||
- `T1-W2-xx`：1期第2周第 xx 个任务
|
||||
- `T2-W3-xx`：2期第3周第 xx 个任务
|
||||
|
||||
---
|
||||
|
||||
## 4. 测试纪律
|
||||
|
||||
- 修 bug 必先写复现测试
|
||||
- 禁止删测试、禁止 `@skip`/`it.only` 进 PR
|
||||
- 后端测试用真实 PostgreSQL（`ruchu_finance_test`），禁止 mock DB
|
||||
- 测试覆盖率目标：70% 单元 / 20% 集成 / 10% E2E
|
||||
|
||||
### 测试命令
|
||||
|
||||
```bash
|
||||
# 后端
|
||||
java -cp apps/api/gradle/wrapper/gradle-wrapper.jar org.gradle.wrapper.GradleWrapperMain -p apps/api test
|
||||
|
||||
# 前端单元
|
||||
cd apps/web && npm run test
|
||||
|
||||
# 前端 E2E
|
||||
cd apps/web && npm run test:e2e
|
||||
```
|
||||
|
||||
> ⚠️ `./gradlew` 脚本有 bug，用上述 `java -cp` 命令替代。
|
||||
|
||||
---
|
||||
|
||||
## 5. 提交规范
|
||||
|
||||
### 5.1 Git 提交信息
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
```
|
||||
|
||||
- **type**：`feat`(新功能) / `fix`(修复) / `refactor`(重构) / `docs`(文档) / `test`(测试) / `chore`(杂项)
|
||||
- **scope**：模块名（contracts/payments/refunds/commissions/exchanges/insurances/salaries/workers/customers/reconcile/dashboard/auth/users/roles/permissions）
|
||||
- **subject**：简短描述（中文）
|
||||
|
||||
示例：
|
||||
```
|
||||
feat(contracts): 合同列表页增加月份筛选
|
||||
fix(payments): 退款金额校验允许零元
|
||||
refactor(auth): 权限码从 user:manage 拆分为细粒度权限
|
||||
```
|
||||
|
||||
### 5.2 禁止提交
|
||||
|
||||
- 禁止提交 `.env` 文件（仅提交 `.env.example`）
|
||||
- 禁止提交 `build/` 目录
|
||||
- 禁止提交 `node_modules/`
|
||||
- 禁止提交敏感信息（密钥、密码、Token）
|
||||
|
||||
---
|
||||
|
||||
## 6. 已知问题
|
||||
|
||||
| 问题 | 影响 | 解决方案 |
|
||||
|---|---|---|
|
||||
| `gradlew` 脚本 `escape_args` bug | 后端启动/测试失败 | 用 `java -cp` 命令替代（详见 `.windsurfrules.DEV-RULES` §5.2） |
|
||||
| Flyway checksum 不匹配 | 后端启动失败 | 手动更新 `flyway_schema_history`（详见 `.windsurfrules.DEV-RULES` §5.2） |
|
||||
| 业务 Controller 缺少 `@PreAuthorize` | 权限控制不完整 | 新增 Controller 必须加 `@PreAuthorize`，存量逐步补充 |
|
||||
|
||||
---
|
||||
|
||||
## 7. AI Agent 行为约束
|
||||
|
||||
- **不猜测**：不确定时用工具查证，不编造 API/函数/参数
|
||||
- **不越权**：不修改未经授权的文件，不执行有副作用的命令
|
||||
- **不遗漏**：修改代码后同步更新相关文档和测试
|
||||
- **不简化**：不跳过错误处理、不删除边界检查、不忽略安全校验
|
||||
- **用中文沟通**：所有回复和注释使用中文
|
||||
Reference in New Issue
Block a user