refactor: harden production readiness and split ERP services

.antigravity/skills/diagnose.md

@@ -0,0 +1,77 @@
+---
+name: diagnose
+description: Structured debugging loop for hard bugs or performance regressions. Use when a bug is hard to fix, has multiple possible causes, or requires systematic investigation.
+---
+
+# Diagnose
+
+## Philosophy
+
+Debugging is a science. Don't guess; verify. The goal is to move from "something is broken" to "I have a reproducible, minimal case that proves exactly why it's broken."
+
+## Workflow
+
+### 1. Reproduce
+
+Before changing any code, you must be able to trigger the bug reliably.
+
+- [ ] Create a script, test case, or curl command that fails
+- [ ] Confirm it fails 100% of the time (or has a known probability)
+- [ ] Document the exact environment and inputs
+
+If you can't reproduce it, you can't prove you fixed it.
+
+### 2. Minimise
+
+A giant codebase is a noisy place to debug. Strip away everything that isn't the bug.
+
+- [ ] Reduce the input data to the smallest possible set
+- [ ] Remove unrelated code paths
+- [ ] Try to reproduce in a standalone script or unit test
+
+**Target**: A "pure" reproduction that involves the minimum number of moving parts.
+
+### 3. Hypothesise
+
+List possible causes. Don't just pick one; list them all.
+
+- [ ] "Is it a race condition?"
+- [ ] "Is it an unhandled null?"
+- [ ] "Is it a dependency version mismatch?"
+
+Rank them by likelihood.
+
+### 4. Instrument
+
+Add logging, assertions, or use a debugger to verify your hypothesis.
+
+- [ ] "If hypothesis A is true, I should see X in the logs here."
+- [ ] Add `console.log` or `DEBUG` statements
+- [ ] Use `command_status` to inspect state if running in background
+
+**Rule**: Never change implementation code to fix the bug in this step. Only add observability.
+
+### 5. Fix
+
+Once you've proven the cause, apply the minimal fix.
+
+- [ ] Address the root cause, not the symptom
+- [ ] Ensure the fix doesn't break other behaviors (refer to existing tests)
+
+### 6. Regression Test
+
+Prove the bug is gone and stays gone.
+
+- [ ] Run your reproduction case from Step 1 → it should now pass
+- [ ] Convert the reproduction into a permanent automated test
+- [ ] Run the full test suite
+
+## Checklist
+
+```
+[ ] Bug is reliably reproducible
+[ ] Reproduction case is minimal
+[ ] Hypothesis was verified by data, not gut feel
+[ ] Fix addresses root cause
+[ ] Regression test is added to the suite
+```

.antigravity/skills/grill-me.md

@@ -0,0 +1,55 @@
+---
+name: grill-me
+description: Deep-dive interview to uncover hidden assumptions and reach shared understanding. Use when a plan is complex, has high risk, or when you want the user to challenge your design.
+---
+
+# Grill Me
+
+## Philosophy
+
+The best designs survive scrutiny. "Grilling" is a process of asking tough questions to ensure every angle has been considered. It's not about finding fault; it's about finding clarity.
+
+## Workflow
+
+### 1. Preparation
+
+The proposer (usually the AI) presents a clear plan or design.
+
+- [ ] Clear goal statement
+- [ ] Proposed implementation steps
+- [ ] Identified risks
+
+### 2. The Grilling
+
+The interviewer (the user, or the AI acting as a devil's advocate) asks a series of "How", "Why", and "What if" questions.
+
+- [ ] "How does this handle [Edge Case X]?"
+- [ ] "Why choose [Approach A] over [Approach B]?"
+- [ ] "What if [Dependency Y] is unavailable?"
+
+**Resolution**: Each question must be answered. If an answer is unknown, it becomes a research task.
+
+### 3. Decision Tree Resolution
+
+The grilling continues until all branches of the decision tree have a recommended path.
+
+- [ ] No "we'll figure this out later" allowed for critical paths
+- [ ] Trade-offs are explicitly documented
+
+### 4. Final Approval
+
+Once the proposer has successfully answered the questions, the plan is updated and approved.
+
+## Tips for the Interviewer
+
+- Be relentless but constructive
+- Focus on boundaries and interfaces
+- Look for state management complexities
+- Ask about failure modes
+
+## Tips for the Proposer
+
+- Don't be defensive
+- If you don't know, say so (and then go find out)
+- Use examples to clarify complex logic
+- Document the "Why" behind choices

.antigravity/skills/tdd.md

@@ -0,0 +1,109 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```

.env.example

@@ -1,66 +1,87 @@
 # ============================================================
-#  Enterprise ERP (.env.example)
-#  复制本文件为 .env 并填写实际值:  cp .env.example .env
+#  OneERP environment template
+#  Copy this file to .env and replace every CHANGE_ME value.
+#
+#  For local trial deployment, prefer scripts/quickstart.*. It copies
+#  .env.quickstart and generates local secrets automatically.
 # ============================================================
 
-# ---- 数据库 (PostgreSQL) ----
-# Prisma 和 Kysely 均使用此连接串
-DATABASE_URL=postgresql://eip_user:eip_password@localhost:5432/eip_db
+# ---- PostgreSQL ----
+POSTGRES_USER=oneerp
+POSTGRES_PASSWORD=CHANGE_ME_DATABASE_PASSWORD
+POSTGRES_DB=oneerp
+
+# Prisma and Kysely both read DATABASE_URL.
+# Keep this value aligned with POSTGRES_* when you change database credentials.
+DATABASE_URL=postgresql://oneerp:CHANGE_ME_DATABASE_PASSWORD@localhost:5432/oneerp
 
-# ---- JWT 认证 ----
-# 用于签发和校验 Bearer Token，请使用足够随机的强密钥
-JWT_SECRET=EIP_SECRET_KEY_SUPER_SECURE
+# ---- JWT authentication ----
+# Use a unique random value of at least 32 bytes for real deployments.
+JWT_SECRET=CHANGE_ME_JWT_SECRET
 
 # ---- Redis ----
 REDIS_HOST=localhost
 REDIS_PORT=6379
 
-# ---- MinIO 对象存储 ----
+# ---- MinIO object storage ----
 MINIO_ENDPOINT=127.0.0.1
 MINIO_PORT=9000
 MINIO_USE_SSL=false
-MINIO_ACCESS_KEY=minio_admin
-MINIO_SECRET_KEY=minio_password
+MINIO_ACCESS_KEY=oneerp_minio
+MINIO_SECRET_KEY=CHANGE_ME_MINIO_SECRET
+
+# ---- Initial production admin ----
+# Change the initial password immediately after first login.
+INIT_ADMIN_EMAIL=admin@oneerp.local
+INIT_ADMIN_PASSWORD=CHANGE_ME_ADMIN_PASSWORD
+INIT_ADMIN_NAME=Administrator
+INIT_COMPANY_NAME=OneERP Company
 
 # ============================================================
-#  端口 & URL 对应关系说明
+#  Ports and URL routing
 # ============================================================
-#  本地开发 (docker compose up + npm run start:dev / dev)
-#  ┌─────────────────┬──────────────┬─────────────────────────────────────┐
-#  │ 服务            │ 默认端口     │ 访问地址                            │
-#  ├─────────────────┼──────────────┼─────────────────────────────────────┤
-#  │ NestJS API      │ API_PORT     │ http://localhost:{API_PORT}/api     │
-#  │ Next.js Web     │ WEB_PORT     │ http://localhost:{WEB_PORT}         │
-#  │ Swagger 文档    │ API_PORT     │ http://localhost:{API_PORT}/api/docs│
-#  └─────────────────┴──────────────┴─────────────────────────────────────┘
+# Local development:
+#   API docs: http://localhost:${API_PORT}/api/docs
+#   Web:      http://localhost:${WEB_PORT}
 #
-#  前端 → 后端的请求链路:
-#  浏览器 ──NEXT_PUBLIC_API_BASE_URL──▶ API 服务
-#  开发环境默认值: http://127.0.0.1:{API_PORT}/api (代码内置回退)
-#  Docker 内部通信: http://api:{API_PORT}/api (compose 网络)
-#  生产环境反向代理: /api/proxy (搭配 Next.js rewrites)
+# Browser -> Web -> API:
+#   Development fallback: http://127.0.0.1:${API_PORT}/api
+#   Docker internal API:  http://api:${API_PORT}/api
+#   Same-origin proxy:    /api/proxy
 # ============================================================
 
-# ---- API 服务端口 ----
-# NestJS API 服务监听端口，docker-compose.prod.yml 中也使用此变量
 API_PORT=8000
-# 兼容旧配置（NestJS main.ts 读取 process.env.PORT）
-PORT=${API_PORT}
-
-# ---- Web 前端端口 ----
-# Next.js Web 应用监听端口，docker-compose.prod.yml 中也使用此变量
+PORT=8000
 WEB_PORT=3000
 
-# ---- OpenAI (可选) ----
-# 配置后可启用 AI Command Bar / Chat2SQL / Chat2Dash 等 AI 功能
-# 未配置时 AI 功能自动降级为规则引擎
+# For production, use real trusted Web origins only.
+CORS_ORIGINS=http://localhost:3000
+NEXT_PUBLIC_API_BASE_URL=/api/proxy
+
+# ---- Image-based deployment (docker-compose.prod.yml) ----
+REGISTRY=ghcr.io
+IMAGE_PREFIX=CHANGE_ME_IMAGE_PREFIX
+IMAGE_TAG=latest
+
+# ---- AI provider (optional, backend only) ----
+# Never expose API keys through NEXT_PUBLIC_* variables.
+# If AI_API_KEY is empty, AI features degrade to deterministic/rule-based paths.
+AI_PROVIDER=openai-compatible
+AI_BASE_URL=https://token-plan-sgp.xiaomimimo.com/v1
+AI_API_KEY=
+AI_MODEL=mimo-v2.5
+AI_PRO_MODEL=mimo-v2.5-pro
+AI_REQUEST_TIMEOUT_MS=30000
+# Comma-separated allowlist for exact public HTTPS AI API base URLs.
+AI_ALLOWED_BASE_URLS=https://token-plan-sgp.xiaomimimo.com/v1
+AI_SETTINGS_ENCRYPTION_KEY=CHANGE_ME_AI_SETTINGS_ENCRYPTION_KEY
+AI_WRITE_ENABLED=false
+
+# Backward-compatible OpenAI variables. Keep empty unless you intentionally
+# want the backend to fall back to them.
 OPENAI_API_KEY=
-OPENAI_MODEL=gpt-4o-mini
+OPENAI_MODEL=
 
-# ---- Web 前端 (Next.js) ----
-# 以下变量需在 apps/web/.env.local 中配置（供客户端使用，需 NEXT_PUBLIC_ 前缀）
-# NEXT_PUBLIC_API_BASE_URL  — 前端 axios 请求后端 API 的 baseURL
-#   开发环境可留空（代码内置回退到 http://127.0.0.1:8000/api）
-#   生产环境请根据实际部署地址配置，例如:
-#     NEXT_PUBLIC_API_BASE_URL=https://api.example.com/api
-#     NEXT_PUBLIC_API_BASE_URL=/api/proxy  (搭配 Next.js rewrites 反向代理)
+# ---- Backup policy ----
+# Copy ops/backup-policy.example.json and adjust local/offsite paths.
+BACKUP_POLICY_FILE=ops/backup-policy.example.json