docs: CLAUDE.md 强化 — 新增步骤 0「阅读 Wiki」强制起点 + 更新常用命令为实际环境
Some checks failed
CI / rust-check (push) Has been cancelled
CI / rust-test (push) Has been cancelled
CI / frontend-build (push) Has been cancelled
CI / security-audit (push) Has been cancelled

- 闭环工作法新增步骤 0:收到任务必须先读 wiki(环境配置、已知问题)
- 步骤 4 功能验证:明确要求启动服务在浏览器中实际操作
- 反模式警告新增「不看 wiki 就开干」
- 常用命令:移除 Docker 相关,改为 Windows 原生 PostgreSQL 实际路径
- Phase 完成标准:Docker 环境改为 PostgreSQL 服务
This commit is contained in:
iven
2026-04-18 20:38:02 +08:00
parent be2f43c624
commit 1dbda4c1e8

View File

@@ -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 -->