docs: CLAUDE.md 强化 — 新增步骤 0「阅读 Wiki」强制起点 + 更新常用命令为实际环境
- 闭环工作法新增步骤 0:收到任务必须先读 wiki(环境配置、已知问题) - 步骤 4 功能验证:明确要求启动服务在浏览器中实际操作 - 反模式警告新增「不看 wiki 就开干」 - 常用命令:移除 Docker 相关,改为 Windows 原生 PostgreSQL 实际路径 - Phase 完成标准:Docker 环境改为 PostgreSQL 服务
This commit is contained in:
60
CLAUDE.md
60
CLAUDE.md
@@ -127,20 +127,32 @@ erp-server (→ 所有 crate,组装入口)
|
|||||||
|
|
||||||
每次改动**必须**按顺序完成以下步骤,不允许跳过:
|
每次改动**必须**按顺序完成以下步骤,不允许跳过:
|
||||||
|
|
||||||
1. **理解需求** — 确认改动的目标模块和影响范围
|
0. **阅读 Wiki(强制起点)** — 收到任何任务后,**先读 wiki 再动手**:
|
||||||
2. **最小实现** — 只改必要的代码,保持模块边界
|
- 读取 `wiki/index.md` 了解项目全貌和当前进度
|
||||||
3. **验证通过** — 必须全部通过才可继续:
|
- 根据任务涉及的范围,读取相关 wiki 页面(`wiki/infrastructure.md`、`wiki/testing.md`、`wiki/wasm-plugin.md` 等)
|
||||||
|
- wiki 中包含实际的环境配置(数据库连接、端口、登录凭据、启动方式),不看 wiki 就无法正确验证
|
||||||
|
- **违反此步骤 = 盲目工作,浪费时间去猜环境配置,产出不可信**
|
||||||
|
1. **现状确认(强制)** — 动手之前,先检查代码里已经有什么:
|
||||||
|
- 用 Grep/Glob/Read 工具搜索相关文件,确认哪些能力已存在
|
||||||
|
- 明确列出"已有"和"缺失",不允许凭印象断言缺失
|
||||||
|
- 如果不确定现有实现状态,停下来问用户,不要编造
|
||||||
|
- 违反此步骤 = 所有后续工作可能脱离实际,白费力气
|
||||||
|
2. **理解需求** — 确认改动的目标模块和影响范围
|
||||||
|
3. **最小实现** — 只改必要的代码,保持模块边界
|
||||||
|
4. **验证通过** — 必须全部通过才可继续:
|
||||||
- `cargo check` — 编译无错误
|
- `cargo check` — 编译无错误
|
||||||
- `cargo test --workspace` — 所有测试通过(有相关测试时)
|
- `cargo test --workspace` — 所有测试通过(有相关测试时)
|
||||||
- `pnpm dev` — 前端页面可正常渲染(涉及前端时)
|
- 功能验证 — 启动后端 + 前端服务,在浏览器中实际操作验证改动生效(涉及 API 或 UI 时)
|
||||||
- 功能验证 — 启动服务实际测试改动是否生效(涉及 API 或 UI 时)
|
- `pnpm build` — 前端生产构建通过(涉及前端时)
|
||||||
4. **提交** — 验证通过后按 §10 规范提交
|
5. **提交** — 验证通过后按 §10 规范提交
|
||||||
5. **文档同步** — 更新相关文档(如果涉及架构、接口、模块变化)
|
6. **文档同步** — 更新相关文档(如果涉及架构、接口、模块变化)
|
||||||
6. **推送到仓库** — 提交后立即 `git push`,确保远程仓库同步
|
7. **推送到仓库** — 提交后立即 `git push`,确保远程仓库同步
|
||||||
|
|
||||||
**铁律:**
|
**铁律:**
|
||||||
- **步骤 3 验证不通过 = 任务未完成**,不允许跳过验证直接提交。
|
- **步骤 0 阅读 Wiki 是绝对起点** — 不读 wiki 就开干 = 连环境配置都不知道,所有验证步骤都是空谈。
|
||||||
- **步骤 6 推送是强制环节**,不推送就等于没完成。不允许"等一下再推"。
|
- **步骤 1 现状确认是强制起点** — 不检查就开干 = 脱离实际,所有产出不可信。
|
||||||
|
- **步骤 4 功能验证必须实际操作** — 只看编译通过不算验证,必须启动服务、在浏览器中确认功能正常。
|
||||||
|
- **步骤 7 推送是强制环节**,不推送就等于没完成。不允许"等一下再推"。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -287,7 +299,7 @@ docker exec erp-postgres psql -U erp -c "\dt"
|
|||||||
|
|
||||||
- [ ] `cargo check` 全 workspace 通过
|
- [ ] `cargo check` 全 workspace 通过
|
||||||
- [ ] `cargo test` 全部通过
|
- [ ] `cargo test` 全部通过
|
||||||
- [ ] Docker 环境正常启动
|
- [ ] PostgreSQL 服务正常运行,迁移自动执行
|
||||||
- [ ] 所有迁移可正/反向执行
|
- [ ] 所有迁移可正/反向执行
|
||||||
- [ ] API 端点可通过 Swagger UI 测试
|
- [ ] API 端点可通过 Swagger UI 测试
|
||||||
- [ ] 桌面端可正常启动并展示对应 UI
|
- [ ] 桌面端可正常启动并展示对应 UI
|
||||||
@@ -364,36 +376,23 @@ docker exec erp-postgres psql -U erp -c "\dt"
|
|||||||
# === Rust ===
|
# === Rust ===
|
||||||
cargo check # 编译检查
|
cargo check # 编译检查
|
||||||
cargo test --workspace # 运行所有测试
|
cargo test --workspace # 运行所有测试
|
||||||
cargo run -p erp-server # 启动后端服务
|
cargo run -p erp-server # 启动后端服务(需从 crates/erp-server 目录 + 环境变量)
|
||||||
cargo fmt --check # 检查格式
|
cargo fmt --check # 检查格式
|
||||||
cargo clippy -- -D warnings # Lint 检查
|
cargo clippy -- -D warnings # Lint 检查
|
||||||
|
|
||||||
# === Docker ===
|
|
||||||
cd docker && docker compose up -d # 启动 PostgreSQL + Redis
|
|
||||||
docker compose -f docker/docker-compose.yml ps # 查看服务状态
|
|
||||||
docker compose -f docker/docker-compose.yml down # 停止服务
|
|
||||||
|
|
||||||
# === 前端 ===
|
# === 前端 ===
|
||||||
cd apps/web && pnpm install # 安装依赖
|
cd apps/web && pnpm install # 安装依赖
|
||||||
cd apps/web && pnpm dev # 开发模式
|
cd apps/web && pnpm dev # 开发模式(固定端口 5174)
|
||||||
cd apps/web && pnpm build # 构建生产版本
|
cd apps/web && pnpm build # 构建生产版本
|
||||||
|
|
||||||
# === 数据库 ===
|
# === 数据库(Windows 原生 PostgreSQL) ===
|
||||||
docker exec -it erp-postgres psql -U erp # 连接数据库
|
PGPASSWORD=123123 "D:\postgreSQL\bin\psql.exe" -U postgres -h localhost -d erp # 连接数据库
|
||||||
|
|
||||||
# === WASM 插件 ===
|
# === WASM 插件 ===
|
||||||
cargo build -p erp-plugin-test-sample --target wasm32-unknown-unknown --release # 编译测试插件
|
cargo build -p erp-plugin-test-sample --target wasm32-unknown-unknown --release # 编译测试插件
|
||||||
wasm-tools component new target/wasm32-unknown-unknown/release/erp_plugin_test_sample.wasm -o target/erp_plugin_test_sample.component.wasm # 转为 Component
|
wasm-tools component new target/wasm32-unknown-unknown/release/erp_plugin_test_sample.wasm -o target/erp_plugin_test_sample.component.wasm # 转为 Component
|
||||||
cargo test -p erp-plugin-prototype # 运行插件集成测试
|
cargo test -p erp-plugin-prototype # 运行插件集成测试
|
||||||
|
|
||||||
# === 集成测试 (需要 Docker) ===
|
|
||||||
docker compose -f docker/docker-compose.yml up -d # 确保 Docker 运行
|
|
||||||
cargo test -p erp-server --test integration # 运行集成测试
|
|
||||||
|
|
||||||
# === E2E 测试 (需要前后端运行) ===
|
|
||||||
cd apps/web && pnpm test:e2e # 运行 Playwright E2E 测试
|
|
||||||
cd apps/web && pnpm test:e2e:ui # Playwright 可视化界面
|
|
||||||
|
|
||||||
# === 一键启动 (PowerShell) ===
|
# === 一键启动 (PowerShell) ===
|
||||||
.\dev.ps1 # 启动前后端(自动清理端口占用)
|
.\dev.ps1 # 启动前后端(自动清理端口占用)
|
||||||
.\dev.ps1 -Stop # 停止前后端
|
.\dev.ps1 -Stop # 停止前后端
|
||||||
@@ -511,6 +510,7 @@ chore(docker): 添加 PostgreSQL 健康检查
|
|||||||
|
|
||||||
## 13. 反模式警告
|
## 13. 反模式警告
|
||||||
|
|
||||||
|
- ❌ **不要**不看 wiki 就开干 — wiki 包含环境配置、数据库连接、启动方式、已知问题,不看就做等于盲猜,浪费时间且产出不可信
|
||||||
- ❌ **不要**在业务 crate 之间创建直接依赖 — 只通过事件和 trait 通信
|
- ❌ **不要**在业务 crate 之间创建直接依赖 — 只通过事件和 trait 通信
|
||||||
- ❌ **不要**跳过多租户中间件 — 所有数据操作必须带 `tenant_id` 过滤
|
- ❌ **不要**跳过多租户中间件 — 所有数据操作必须带 `tenant_id` 过滤
|
||||||
- ❌ **不要**硬编码配置值 — 使用 config.toml + 环境变量
|
- ❌ **不要**硬编码配置值 — 使用 config.toml + 环境变量
|
||||||
@@ -522,6 +522,8 @@ chore(docker): 添加 PostgreSQL 健康检查
|
|||||||
- ❌ **不要**忽略 `version` 字段 — 所有更新操作必须检查乐观锁
|
- ❌ **不要**忽略 `version` 字段 — 所有更新操作必须检查乐观锁
|
||||||
- ❌ **不要**在动态表 SQL 中拼接用户输入 — 使用 `sanitize_identifier` 防注入
|
- ❌ **不要**在动态表 SQL 中拼接用户输入 — 使用 `sanitize_identifier` 防注入
|
||||||
- ❌ **不要**在插件 crate 中直接依赖 erp-auth — 权限注册用 raw SQL,保持模块边界
|
- ❌ **不要**在插件 crate 中直接依赖 erp-auth — 权限注册用 raw SQL,保持模块边界
|
||||||
|
- ❌ **不要**在 plugin.toml 中使用与实体名不一致的权限码 — `permissions[].code` 前缀必须与 `schema.entities[].name` 完全一致(如实体 `customer_tag` → 权限码 `customer_tag.list`/`customer_tag.manage`,不能写成 `tag.manage`),否则页面 403
|
||||||
|
- ❌ **不要**漏掉实体的 `.list` 权限 — 每个实体必须同时声明 `.list` 和 `.manage`,缺少 `.list` 导致列表页 403
|
||||||
- ❌ **不要**跳过验证直接提交 — 编译/测试/功能验证必须全部通过
|
- ❌ **不要**跳过验证直接提交 — 编译/测试/功能验证必须全部通过
|
||||||
- ❌ **不要**提交后忘记推送 — 不推送等于没完成,远程仓库必须同步
|
- ❌ **不要**提交后忘记推送 — 不推送等于没完成,远程仓库必须同步
|
||||||
- ❌ **不要**忘记更新文档 — 涉及架构、接口、模块变化时必须同步更新相关文档
|
- ❌ **不要**忘记更新文档 — 涉及架构、接口、模块变化时必须同步更新相关文档
|
||||||
@@ -534,6 +536,6 @@ chore(docker): 添加 PostgreSQL 健康检查
|
|||||||
- 当遇到**新增 API** → 添加 utoipa 注解,确保 OpenAPI 文档同步
|
- 当遇到**新增 API** → 添加 utoipa 注解,确保 OpenAPI 文档同步
|
||||||
- 当遇到**新增表** → 创建 SeaORM migration + Entity,包含所有标准字段
|
- 当遇到**新增表** → 创建 SeaORM migration + Entity,包含所有标准字段
|
||||||
- 当遇到**新增页面** → 使用 Ant Design 组件,i18n key 引用文案
|
- 当遇到**新增页面** → 使用 Ant Design 组件,i18n key 引用文案
|
||||||
- 当遇到**新增业务模块插件** → 参考 `wiki/wasm-plugin.md` 的插件制作完整流程,创建 cdylib crate + 实现 Guest trait + 编译为 WASM Component
|
- 当遇到**新增业务模块插件** → 参考 `wiki/wasm-plugin.md` 的插件制作完整流程和 `.claude/skills/plugin-development/SKILL.md`,创建 cdylib crate + 实现 Guest trait + 编译为 WASM Component。**权限码必须与实体名一致(每个实体声明 `.list` + `.manage`)**
|
||||||
|
|
||||||
<!-- ANTI-PATTERN-END -->
|
<!-- ANTI-PATTERN-END -->
|
||||||
|
|||||||
Reference in New Issue
Block a user