From f20b8d2644f43d31b9626cf80192e69733642a6c Mon Sep 17 00:00:00 2001 From: zichun Date: Wed, 13 May 2026 16:02:22 +0800 Subject: [PATCH] chore: plan phase done --- .githooks/pre-push | 9 +++++++++ .gitignore | 32 ++++++++++++++++++++++++++++++++ CLAUDE.md | 261 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/01-需求清单/USR-用户管理/REQ-USR-001.md | 41 +++++++++++++++++++++++++++++++++++++++++ docs/01-需求清单/USR-用户管理/REQ-USR-002.md | 40 ++++++++++++++++++++++++++++++++++++++++ docs/01-需求清单/USR-用户管理/REQ-USR-003.md | 37 +++++++++++++++++++++++++++++++++++++ docs/01-需求清单/USR-用户管理/REQ-USR-004.md | 21 +++++++++++++++++++++ docs/01-需求清单/USR-用户管理/_module.md | 5 +++++ docs/01-需求清单/index.md | 15 +++++++++++++++ docs/02-开发计划.md | 29 +++++++++++++++++++++++++++++ docs/03-数据库设计文档 copy.md | 206 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/03-数据库设计文档.md | 231 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/04-技术规范.md | 207 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/05-API接口契约.md | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/06-UI交互规范.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/07-环境配置.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/08-模块任务管理.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/09-项目目录结构.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/10-验收检查清单.md | 16 ++++++++++++++++ scripts/setup-test-db.sh | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ scripts/test.sh | 40 ++++++++++++++++++++++++++++++++++++++++ sql/migrations/.gitkeep | 0 sql/migrations/V1__initial_schema.sql | 135 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ src/styles/tokens.css | 43 +++++++++++++++++++++++++++++++++++++++++++ 24 files changed, 1920 insertions(+), 0 deletions(-) create mode 100755 .githooks/pre-push create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 docs/01-需求清单/USR-用户管理/REQ-USR-001.md create mode 100644 docs/01-需求清单/USR-用户管理/REQ-USR-002.md create mode 100644 docs/01-需求清单/USR-用户管理/REQ-USR-003.md create mode 100644 docs/01-需求清单/USR-用户管理/REQ-USR-004.md create mode 100644 docs/01-需求清单/USR-用户管理/_module.md create mode 100644 docs/01-需求清单/index.md create mode 100644 docs/02-开发计划.md create mode 100644 docs/03-数据库设计文档 copy.md create mode 100644 docs/03-数据库设计文档.md create mode 100644 docs/04-技术规范.md create mode 100644 docs/05-API接口契约.md create mode 100644 docs/06-UI交互规范.md create mode 100644 docs/07-环境配置.md create mode 100644 docs/08-模块任务管理.md create mode 100644 docs/09-项目目录结构.md create mode 100644 docs/10-验收检查清单.md create mode 100755 scripts/setup-test-db.sh create mode 100755 scripts/test.sh create mode 100644 sql/migrations/.gitkeep create mode 100644 sql/migrations/V1__initial_schema.sql create mode 100644 src/styles/tokens.css diff --git a/.githooks/pre-push b/.githooks/pre-push new file mode 100755 index 0000000..8289050 --- /dev/null +++ b/.githooks/pre-push @@ -0,0 +1,9 @@ +#!/usr/bin/env bash +# .githooks/pre-push — run scripts/test.sh before every push. +# No --no-verify: the claude-code hook deny-no-verify.sh also blocks it. + +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +./scripts/test.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ac39aa6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,32 @@ +# ==== ERP 插件推荐忽略项（skeleton-gen 追加） ==== +# 本地运行时配置（含真实凭据，严禁入库） +.env.local +.env.*.local + +# Java / Maven +target/ +*.class + +# Node / 前端构建产物 +node_modules/ +dist/ +build/ +coverage/ + +# IDE +.idea/ +.vscode/ +*.iml + +# OS +.DS_Store +Thumbs.db + +# 日志 +*.log +logs/ + +# 插件运行时临时文件 +.tmp/ +*.raw +# ==== 结束 ==== diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..cbd9440 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,261 @@ +# CLAUDE.md — ERP项目 Claude Code 主指令文件 + +> 本文件是 Claude Code 的"操作手册"。Claude Code 启动时会自动读取此文件。 + +--- + +## 🎯 项目概述 + +- **项目名称**: 小羚羊 +- **项目简述**: 测试ERP +- **目标用户**: 企业内部管理人员 +- **部署方式**: 私有化部署 + +--- + +## 🔄 B 阶段开发流程（后端模块循环 → 前端整体阶段） + +B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-start`。 + +### 阶段路由（coding-start 内，只做分发） + +`coding-start` 每次入口做两段完成性检查后真值表派发： + +- 后端完成性检查 → `backend_done`（扫 docs/08 § 二 + GitLab state） +- 前端完成性检查 → `frontend_done`（扫 docs/08 § 三 整体 MR + state） + +| `backend_done` | `frontend_done` | 派发 | +|---|---|---| +| `false` | 任意 | `module-start`（写后端） | +| `true` | `false` | `frontend-start`（写前端） | +| `true` | `true` | "所有阶段已完成" | + +前端阶段前置（prototype/ 门禁）由 `frontend-start` 自带，不在 coding-start。`module-start` 与 `frontend-start` **互不感知对方**。 + +### 后端阶段（每模块一个 MR） + +- **模块循环（外）**：`module-start` → `test-gate(phase=backend)` → `module-report` → `mr-create` → 人工 Approve MR → 用户重跑 coding-start → coding-start 再次路由 +- **功能循环（内，每 REQ-XXX-NNN 一遍）**：`feature-brainstorm` → `feature-plan` → `feature-tdd` → `feature-verify` → `feature-review` +- 后端阶段任务严格落在 `backend/` 路径下；docs/01 REQ 卡片的 UI 描述在此阶段忽略，UI 推迟到前端阶段。 + +### 前端阶段（整体一个 MR，所有后端模块 merged 后启动） + +- **FE 清单（AI 自主推导，无审阅断点）**：`frontend-start` 进入时扫 prototype + docs/01 + docs/05 → AI 自主推导 FE 业务功能清单写入 `docs/08 § 三`（已有则加载）。**FE 是业务功能粒度，与 prototype HTML 文件数无关**——一个 HTML 可拆多个 FE，多个 HTML 也可合成一个 FE。FE 清单的合理性由 fe-feature-review / mr-create 在整体 MR 提交时一并校核（人工只在 MR Approve+Merge 处介入）。 +- **FE 循环（外）**：`frontend-start` → fe-feature 循环 → `test-gate(phase=frontend)` → `module-report(phase=frontend)` → `mr-create`（分支 `frontend-phase`，docs/08 § 三 整体 MR）。 +- **FE 功能循环（内，每个 FE-NN 一遍）**：`fe-feature-brainstorm` → `fe-feature-plan` → `fe-feature-tdd` → `fe-feature-verify` → `fe-feature-review`（专用 `fe-code-reviewer` agent，硬编码 7 维 review checklist） +- 前端阶段任务严格落在 `frontend/` 路径下；布局以 `prototype/` 为权威。 + +### MR 前测试闸门 + +- `test-gate`：后端阶段子会话跑 `scripts/test.sh`（含本模块新增 + 已合并模块回归）；前端阶段子会话跑 vitest + playwright。 +- `.githooks/pre-push` 兜底；`git push --no-verify` 被 `deny-no-verify.sh` 硬拦。 + +--- + +## ✅ 阶段完成判定规则 + +`docs/08-模块任务管理.md` 分两段： +- `§ 二`：后端模块元数据表（每个模块一行 bullet，记录依赖 / 路径 / MR iid / 功能子项） +- `§ 三`：前端阶段元数据（整体 MR + FE 子项清单，由 `frontend-start` 在所有后端模块 merged 后填入） + +**阶段完成判定**统一以 `MR:` 字段（§ 二 各模块） / `整体 MR:` 字段（§ 三）+ `GitLab API state=merged` 判定；子项勾选只作可视化进度，不参与完成判定。 + +### 后端模块格式 + +每个后端模块在 docs/08 § 二 中长这样： + +```markdown +- module_0 系统管理 + - 依赖: — + - 路径: backend/module/sys/ + - MR: — + - 功能: + - [ ] REQ-SYS-001 用户登录 + - [ ] REQ-SYS-002 用户注册 +``` + +- `MR:` 字段由 `mr-create` 在创建 MR 时从 `—` 改为 `!`。 +- 每个 `REQ-*` 子项由 `feature-review` 在 `verdict=approve` 时自动勾选为 `[x]`。 +- 路径限定为后端目录（如 `backend/module/sys/`）；前端代码不在此阶段产生。 + +### 前端阶段格式（§ 三） + +```markdown +- 整体 MR: — +- 功能: + - [ ] FE-01 用户登录与注册 ｜ 关联 REQ：REQ-SYS-001, REQ-SYS-002 ｜ 关联原型：prototype/auth.html + - [ ] FE-02 仪表盘总览 ｜ 关联 REQ：REQ-DASH-001 ｜ 关联原型：prototype/dashboard.html +``` + +- `整体 MR:` 字段由 `mr-create` 在创建前端 MR 时从 `—` 改为 `!`。 +- "功能:" 列表由 `frontend-start` 进入时由 AI 自主推导写入（无人工审阅断点）。FE 是业务功能粒度，与 prototype HTML 文件数无关；合理性由 fe-feature-review / 整体 MR 时统一校核。 +- 每个 `FE-NN` 子项由 `fe-feature-review` 在 `verdict=approve` 时自动勾选为 `[x]`。 +- 进入前端阶段前 `frontend-start` 步骤 1 自带 prototype/ 门禁，强制检查项目根 `prototype/` 至少含 1 个 `*.html` mockup。 + +### 状态语义（后端模块 + 前端阶段共用） + +| `MR:` 字段 | `GitLab API state` | 含义 | 你（Claude Code）的行为 | +|---|---|---|---| +| `—` | — | 该阶段未开始（未创建 MR） | ✅ 开始该阶段开发 | +| `!` | `opened` / `closed` | 阶段开发中 / 打回 | ✅ 继续推进该阶段 | +| `!` | `merged` | 阶段**已完成** | 🟢 后端：进入下一未完成模块；后端全完 → 前端阶段；前端 merged → 全部完成 | + +### 模块完成报告 + +由 `module-report` skill 产出，模板位于 由 module-report skill 持有（12 节标准化，含跨模块改动等 CLAUDE.md 软规则映射节）。CC 不手写模块报告，仅填模板。 + +--- + +## 🏷️ 占位符统一约定 + +项目文档里有 **2 种填写占位** + **1 种提示占位**： + +| 格式 | 谁填 | 使用阶段 | 说明 | +|------|-----|---------|------| +| `【人工填写：<简短说明>】` | 人 | 仅 A 阶段文档 | 密钥 / 账密 / 包名 / 命名约定 / 小版本号等人工才能决定的值；B 阶段 plan/spec 禁止出现，查不到真值时用 `AskUserQuestion` 问用户 | +| `TBD(<责任人>)` | CC 自动 | A 或 B | 后缀附带责任方（如 `TBD(A3 自动补)` / `TBD(A5 自动补)`）；由对应 skill 就地补填，`module-report` § ⑦ 检查 `TBD(CC 补)` 残留 | + +**HTML 注释 ``**：提示占位，是**插件内部大纲模板**里给 LLM 的**填空提示 / 章节引导**，指引 LLM 按结构填实际内容。skill 生成时会**剥除**这些注释，最终产物里注释不会保留。 + +--- + +## 📐 编码行为约束 + +### 你必须做的 ✅ + +1. **严格遵循** `docs/04-技术规范.md`——命名 / 编码 / 统一响应 / 异常处理 / 数据访问 / 配置与安全 等项目专属技术规约全部在此 +2. **严格遵循** `docs/09-项目目录结构.md`——文件放对位置 +3. **每个后端接口** 必须先在 `docs/05-API接口契约.md` 定义，再编码实现 +4. **每个功能可追溯到 `REQ-XXX-NNN`**——commit tag + 代码注释（如 `// REQ-SYS-001: 用户登录`）+ plan/spec 文件名均用此 tag +5. **遇到跨模块改动**（动到非当前模块的代码）——按 § 🟡 软规则 **S2** 执行（允许改，但必须留痕） +6. **遇到技术栈外组件引入**（`docs/04 § 零` 技术栈表外的框架 / 中间件 / 关键库），按 § 🟡 软规则 **S1** 执行（允许引入，但必须先 AskUserQuestion） + +### 你禁止做的 🚫 + +1. **主会话直接 `mysql -e` 跑业务 DDL**（只读查询 / 临时本地调试除外）——业务 schema 必须走 `sql/migrations/V_n__*.sql`，详见下方 Schema 演化规约 +2. **手动 Edit `docs/08 § 二/§ 三` 的 `MR:` / `整体 MR:` 字段**，必须要由 `mr-create` 自动回写 + +### Schema 演化规约（Flyway migration） + +1. **文件命名**：`sql/migrations/V__.sql`，例：`V5__add_user_email_unique_index.sql` +2. **版本号分配**：建文件前 `ls sql/migrations/V*.sql` 查当前最大 n，新文件 `n_max + 1` +3. **Apply 方式**：Spring Boot 启动 / 测试启动时 Flyway 自动 apply（项目必须在 `pom.xml` 声明 `flyway-core` + `flyway-mysql` 依赖）。`scripts/setup-test-db.sh` 只负责清空库，不做 apply +4. **已合并的 migration 永不修改**：发现错了写一个补救 migration（如 `V7__fix_V5_index_name.sql`），旧 `V_n.sql` +5. **临时调试 DDL**：临时在本地试字段/索引可手动 `mysql -e`，但不写 migration；下次 `setup-test-db.sh` 会 drop+create 清掉 +6. **A4 生成的 V1**：`V1__initial_schema.sql` 是 A 阶段由 `db-init` 从 `docs/03-数据库设计文档.md`（A3 正向设计的 schema SSoT）翻译生成的初始版本；后续 V2/V3/... 由 B 阶段每个 REQ 按需写入，**同时**反向同步更新 docs/03 对应表小节以保持 SSoT 一致 + +--- + +## 🗂️ Git 提交规范 + +每次提交必须遵循以下格式： + +``` +(): +``` + +- `scope`: 模块名，如 `user` / `inventory` / `order` +- `subject`: 简短描述；业务类（feat / fix / test）必须带 `REQ-XXX-NNN` 后缀 + +`type` 含义： + +| type | 看到它意味着 | +|-----|-------------| +| `feat` | **新能力上线**——用户多了一个功能、接口、页面或业务规则 | +| `fix` | **修 bug**——原来行为错了，这次改对 | +| `refactor` | **重构**——外部行为不变，只改代码结构 / 命名 / 抽象 | +| `docs` | **文档改动**——只动 Markdown / 代码注释，不动实现 | +| `style` | **格式调整**——空白 / 缩进 / import 顺序，逻辑 0 变化 | +| `test` | **只动测试代码**——补用例 / 修 fixture，不碰实现 | +| `chore` | **流程维护**——构建 / 依赖 / 工具 / 证据档案 / MR 元数据等非业务动作 | + +--- + +## 🚩 中断机制 + +功能循环（每个功能 REQ-XXX 的 Brainstorm → Plan → TDD → Verify → AI 自审）默认 **静默编程**，但触发以下任何一条必须**立刻停下、记录原因、等人决策**，不得自行绕过： + +| # | 中断 | 例子 | +| - | --- | --- | +| 1 | **测试反复失败** | 同一测试同一功能内连续 **10 次**修复失败 | +| 2 | **要改密钥 / 账密 / 包名** | `docs/07-环境配置.md` 里由人工标注必须填的字段 | +| 3 | **外部接口不可达** | 第三方 API 无法连接、证书失效等环境问题，并无法自行解决 | + +> 其余需要人类判断的场景一律走普通 `AskUserQuestion` Q&A，不中断、不写 Blocker 文件。 + +**触发中断时的固定动作：** + +1. 在当前功能的 plan 文件里追加一节 `## 🚩 Blocker`（报告格式由 `interrupt-check` 的 `interrupt-block-template.md` 持有） +2. 停止后续所有功能的静默执行 +3. 在主会话输出一句话摘要 + 指向 blocker 文件的路径，等人回复 + +--- + +## 🟡 软规则（允许继续，但有强制后续动作） + +以下情况 **不触发中断**，CC 可自行继续推进，但必须在约定位置留痕，模块完成时统一审计。 + +| # | 软规则 | 允许动作 | 强制后续 | +| - | ----- | ------- | ------- | +| S1 | **技术栈外组件引入** | 用 `AskUserQuestion` 给用户三选一：接受引入 / 换方案 / 拒绝 | ① **接受** → 同会话直接在 `docs/04 § 零` 追加一行 → 继续流程 ② **换方案 / 拒绝** → 视为常规歧义澄清，继续 Q&A 收敛 ③ 不写 Blocker、不中断流程 | +| S2 | **跨模块改动** | **默认不改**，仅为当前模块实现所必需时允许修改 | ① hook `log-cross-module.sh` 自动落存根 ② `module-report` 一次性调用 `cross-module-log` skill 批量补齐「原因 / 影响评估」+ 「跨模块改动」节完整贴入《模块完成报告》 | + +--- + +## 🧭 通用工作准则（General Principles） + +### 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +### 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +### 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +### 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. diff --git a/docs/01-需求清单/USR-用户管理/REQ-USR-001.md b/docs/01-需求清单/USR-用户管理/REQ-USR-001.md new file mode 100644 index 0000000..16d7399 --- /dev/null +++ b/docs/01-需求清单/USR-用户管理/REQ-USR-001.md @@ -0,0 +1,41 @@ +### REQ-USR-001 增加用户 + +**目标**: 管理员在后台新建用户账号，指定用户名、密码及角色，账号立即生效可用 + +- **输入**: + + - **表1**： + + | 字段 | 类型 | 必填 | 输入方式 | 显示来源 | 预加载 | 默认值 | 业务规则 | + | -------- | ---- | --- | ---- | ----------------- | --------- | --------- | ------------------- | + | 创建时间 | 日期时间 | — | 系统生成 | — | 页面加载时 | 当前日期 | 保存后自动生成；只读 | + | 制单人 | 文本 | — | 系统生成 | — | 页面加载时 | 当前登录用户 | 保存后自动生成；只读 | + | 员工名 | 文本 | 否 | 下拉单选 | `职员表` | 用户操作时 | — | 关联职员（可选） | + | 用户号 | 文本 | 是 | 手工输入 | — | 用户操作时 | — | 关联职员选择后自动输入员工姓名 | + | 用户名 | 文本 | 是 | 手工输入 | — | 用户操作时 | — | 关联职员选择后自动输入员工姓名 | + | 类型 | 文本 | 是 | 下拉单选 | 普通用户/超级管理员 | 页面加载时 | 普通用户 | — | + | 语言 | 文本 | 是 | 下拉单选 | 中文/英文/繁体 | 页面加载时 | — | — | + | 单据修改权限 | 布尔 | 否 | 复选框 | — | — | 否 | — | + | 密码 | 文本 | — | 系统生成 | 不显示 | — | 666666 | 保存后自动设为初始化 | + + - **表2** - 权限组： + + | 字段 | 类型 | 必填 | 输入方式 | 显示来源 | 预加载 | 默认值 | 业务规则 | + | -------- | ---- | --- | ---- | ----------------- | --------- | --------- | ------------------- | + | 复选框 | 布尔 | 否 | 复选框 | — | — | 否 | 是否选择当前行权限 | + | 权限分类 | 文本 | — | — | — | 页面加载时 | — | — | + + +- **输出**: + + - **表1**： + + | 字段 | 类型 | 显示来源 | + | --- | --- | --- | + | 用户号 | 文本 | — | + +- **跨字段规则**: 用户名在系统内全局唯一；角色取值受系统配置约束 +- **边界**: 密码以哈希形式存储 +- **验收**: 提交合法数据后用户记录出现在列表；重复用户名返回错误提示；普通账号无权访问此功能 +- **依赖表**: `tUser`（写入新用户主记录）、`tEmployee`（读取员工下拉）、`tPermission`（读取权限分类下拉）、`tUserPermission`（写入权限组勾选关系） +- **依赖接口**: `POST /api/usr/user`（本 REQ 自身接口） diff --git a/docs/01-需求清单/USR-用户管理/REQ-USR-002.md b/docs/01-需求清单/USR-用户管理/REQ-USR-002.md new file mode 100644 index 0000000..454332e --- /dev/null +++ b/docs/01-需求清单/USR-用户管理/REQ-USR-002.md @@ -0,0 +1,40 @@ +### REQ-USR-002 修改用户 + +**目标**: 管理员可更新已有用户的基本信息（姓名、角色、状态等），修改实时生效 + +- **输入**: 选中目标 + + - **表1**： + + | 字段 | 类型 | 必填 | 输入方式 | 显示来源 | 预加载 | 默认值 | 业务规则 | + | -------- | ---- | --- | ---- | ----------------- | --------- | --------- | ------------------- | + | 创建时间 | 日期时间 | — | 系统生成 | — | 页面加载时 | 原值 | 保存后自动生成；只读 | + | 制单人 | 文本 | — | 系统生成 | — | 页面加载时 | 原值 | 保存后自动生成；只读 | + | 员工名 | 文本 | 否 | 下拉单选 | `职员表` | 页面加载时 | 原值 | 关联职员（可选） | + | 用户号 | 文本 | 是 | 手工输入 | — | 页面加载时 | 原值 | 关联职员选择后自动输入员工姓名 | + | 用户名 | 文本 | 是 | 手工输入 | — | 页面加载时 | 原值 | 关联职员选择后自动输入员工姓名 | + | 类型 | 文本 | 是 | 下拉单选 | 普通用户/超级管理员 | 页面加载时 | 原值 | — | + | 语言 | 文本 | 是 | 下拉单选 | 中文/英文/繁体 | 页面加载时 | 原值 | — | + | 单据修改权限 | 布尔 | 否 | 复选框 | — | 页面加载时 | 原值 | — | + | 密码 | 文本 | — | 系统生成 | 不显示 | 页面加载时 | 原值 | 保存后自动设为初始化 | + + - **表2** - 权限组： + + | 字段 | 类型 | 必填 | 输入方式 | 显示来源 | 预加载 | 默认值 | 业务规则 | + | -------- | ---- | --- | ---- | ----------------- | --------- | --------- | ------------------- | + | 复选框 | 布尔 | 否 | 复选框 | — | 页面加载时 | 原值 | 是否选择当前行的权限 | + | 权限分类 | 文本 | — | — | — | 页面加载时 | — | — | + +- **输出**: + + - **表1**： + + | 字段 | 类型 | 显示来源 | + | --- | --- | --- | + | 用户 id | 文本 | `职员表` | + +- **跨字段规则**: 密码不在该接口修改；角色变更需具备相应权限 +- **边界**: 必须传入有效用户 id；字段格式与新增一致 +- **验收**: 修改角色或状态后立即反映在用户列表；被禁用账号无法登录并收到明确提示 +- **依赖表**: `tUser`（更新用户主记录）、`tEmployee`（读取员工下拉）、`tPermission`（读取权限分类下拉）、`tUserPermission`（重写权限组勾选关系） +- **依赖接口**: `PUT /api/usr/user/{userId}`（本 REQ 自身接口） diff --git a/docs/01-需求清单/USR-用户管理/REQ-USR-003.md b/docs/01-需求清单/USR-用户管理/REQ-USR-003.md new file mode 100644 index 0000000..314aa59 --- /dev/null +++ b/docs/01-需求清单/USR-用户管理/REQ-USR-003.md @@ -0,0 +1,37 @@ +### REQ-USR-003 查询用户 + +**目标**: 管理员可按用户名、角色或状态筛选并分页浏览用户列表 + +- **输入**: + + - **表1**： + + | 字段 | 类型 | 必填 | 输入方式 | 显示来源 | 预加载 | 默认值 | 业务规则 | + | ---- | ---- | --- | ---- | ----------------------------------------------- | ----- | ------- | --------------- | + | 查询字段 | 文本 | 否 | 下拉单选 | 用户名/员工名/用户号/部门/用户类型/作废/登录日期/制单人 | 页面加载时 | 用户名 | — | + | 匹配方式 | 文本 | 否 | 下拉单选 | 包含/不包含/等于 | 页面加载时 | 包含 | — | + | 查询值 | 文本 | 否 | 手工输入 | — | — | — | 与「查询字段」配合使用，空为选择全部 | + +- **输出**: + + - **表1**： + + | 字段 | 类型 | 显示来源 | + | ---- | ---- | ----- | + | 序号 | 数字 | 系统生成 | + | 用户名 | 文本 | `用户表` | + | 员工名 | 文本 | `职员表` | + | 用户号 | 文本 | `用户表` | + | 部门 | 文本 | `职员表` | + | 用户类型 | 文本 | `用户表` | + | 语言 | 文本 | `用户表` | + | 作废 | 布尔 | `用户表` | + | 登录日期 | 日期时间 | `用户表` | + | 制单人 | 文本 | `用户表` | + | 制单日期 | 日期时间 | `用户表` | + +- **跨字段规则**: - +- **边界**: 单页最大条数受限（默认 100）；密码与敏感字段不返回；查询为只读，不产生写副作用 +- **验收**: 按条件筛选返回正确结果集；无匹配时返回空列表而非报错；分页参数越界时返回最后一页 +- **依赖表**: `tUser`（主查询表）、`tEmployee`（LEFT JOIN 取员工名 / 部门） +- **依赖接口**: `GET /api/usr/user`（本 REQ 自身接口） diff --git a/docs/01-需求清单/USR-用户管理/REQ-USR-004.md b/docs/01-需求清单/USR-用户管理/REQ-USR-004.md new file mode 100644 index 0000000..61dfd4c --- /dev/null +++ b/docs/01-需求清单/USR-用户管理/REQ-USR-004.md @@ -0,0 +1,21 @@ +### REQ-USR-004 用户登录 + +**目标**: 用户通过用户名+密码完成身份认证，获取 JWT Token 用于后续接口鉴权 + +- **输入**: + + - **表1**： + + | 字段 | 类型 | 必填 | 输入方式 | 显示来源 | 预加载 | 默认值 | 业务规则 | + | --- | ---- | --- | ---- | ------- | ----- | --- | ----------- | + | 用户名 | 文本 | 是 | 手工输入 | — | — | — | — | + | 密码 | 文本 | 是 | 手工输入 | — | — | — | 输入显示星号 | + | 版本 | 文本 | 是 | 下拉单选 | `公司表` | 页面加载时 | 标准版 | | + +- **输出**: 成功/失败 + +- **跨字段规则**: 校验用户名 + 密码哈希；连续失败达到阈值临时锁定账号；登录成功签发限时 token 并返回基本用户信息 +- **边界**: token 设置合理过期时间；接口需具备防暴力破解保护 +- **验收**: 正确凭据返回 Token 且可通过鉴权接口验证；错误密码返回通用错误消息（不区分用户名或密码错误）；锁定账号返回锁定提示 +- **依赖表**: `tUser`（按用户名查询 + 校验密码 + 更新登录态 / 失败计数 / 锁定时间）、`tCompany`（读取版本下拉） +- **依赖接口**: `POST /api/auth/login`（本 REQ 自身接口） diff --git a/docs/01-需求清单/USR-用户管理/_module.md b/docs/01-需求清单/USR-用户管理/_module.md new file mode 100644 index 0000000..723d4f4 --- /dev/null +++ b/docs/01-需求清单/USR-用户管理/_module.md @@ -0,0 +1,5 @@ +# USR-用户管理 + +- **模块简述**: 用户的注册、登录、信息维护与查询，提供系统访问与权限识别的基础能力 +- **依赖模块**: —（基础模块，无上游依赖） +- **涉及表**: `tUser`, `tEmployee`, `tPermission`, `tUserPermission`, `tCompany` diff --git a/docs/01-需求清单/index.md b/docs/01-需求清单/index.md new file mode 100644 index 0000000..3ef4cdb --- /dev/null +++ b/docs/01-需求清单/index.md @@ -0,0 +1,15 @@ +# 需求清单 + +> 本目录按模块组织所有功能需求。每个模块一个子目录，含 `_module.md`（模块头）和 `REQ-XXX-NNN.md`（每张 REQ 卡片一个文件）。下方核心功能点供 CC 拆分出 REQ 编号 + 标题 + 草拟规则；卡片内输入 / 输出的简述句和 N 张字段表由人工编辑。 + +## 模块索引 + +| 模块代码 | 模块名称 | 核心功能点（简要） | +| ---- | ---- | ------------------- | +| USR | 用户管理 | 增加用户，修改用户，查询用户，登录用户 | + +## 填写说明 + +1. 每个模块占一行，`模块代码` 用大写英文缩写（如 SYS / PUR / INV / SAL / FIN / HR） +2. `核心功能点` 只需列关键词，CC 会基于此拆分出 N 张 REQ 卡片骨架（卡片内输入 / 输出的简述句和字段表仍由人工编辑） +3. 填完后运行 `/erp-workflow:plan-start`，CC 会自动检测并进入需求生成阶段 diff --git a/docs/02-开发计划.md b/docs/02-开发计划.md new file mode 100644 index 0000000..1e51ec0 --- /dev/null +++ b/docs/02-开发计划.md @@ -0,0 +1,29 @@ +# 02-开发计划 + +## 一、模块依赖表 + +| 模块 ID | 模块名 | 依赖模块 | 依赖表 | +|---|---|---|---| +| module_usr | 用户管理 | — | `tUser`, `tEmployee`, `tPermission`, `tUserPermission`, `tCompany` | + +## 二、开发顺序清单（CC 分发权威） + +> 本清单由 A5 `downstream-gen` 一次性生成。**每行是一个 REQ**，不是模块。CC 按表格行序从上到下扫描，对每个 REQ 所属模块查 `docs/08 § 二` 的 `MR:` 字段 + GitLab API `state`：`merged` 跳过，其他（`—` / opened / closed / 查不到）选为当前模块；`module-start` 会把该模块的所有 REQ 一次做完。 +> +> **约束**：同一模块的所有 REQ 必须**连续排列**。允许打破依赖拓扑（如环依赖、业务必须先做），但必须在「备注」列写明原因。 + +| # | REQ | 所属模块 | 选中理由 | 备注 | +|---|-----|---------|---------|------| +| 1 | **REQ-USR-001** | module_usr | 所属模块无依赖，基础模块；本 REQ 创建用户主记录，是后续修改 / 查询 / 登录的前置 | — | +| 2 | **REQ-USR-002** | module_usr | 依赖 REQ-USR-001 已在前（修改基于已存在的用户记录） | — | +| 3 | **REQ-USR-003** | module_usr | 依赖 REQ-USR-001 已在前（查询基于已存在的用户记录） | — | +| 4 | **REQ-USR-004** | module_usr | 依赖 REQ-USR-001 已在前（登录校验已存在的用户名 + 密码）；同模块尾位以承接前 3 个的用户数据 | — | + +> **后端模块全部 merged 后**：用户重跑 `/erp-workflow:coding-start` → coding-start 检测到 `backend_done=true && frontend_done=false` → 派发 `frontend-start`。`frontend-start` 步骤 1 自带 prototype/ 门禁（≥ 1 个 `*.html` mockup，缺失则 AskUserQuestion 提示用户补齐）。前端阶段以业务功能（不是 HTML 文件数）为粒度拆分 FE，每个 FE 跑一次 feature 循环（fe-feature-*），最后整个阶段合 1 个 MR（分支 `frontend-phase`，记录在 `docs/08 § 三 整体 MR`）。 + +## 三、关键说明 + +- **模块粒度合 MR**：本项目当前只有一个后端模块 `module_usr`，4 个 REQ 在同一分支（如 `module-usr`）里依次实现，最后合 1 个 MR。 +- **REQ 实现顺序**：在同模块内允许 CC 根据实际依赖局部调整（如先做骨架接口再做业务规则），但完成后所有 4 个 REQ 的子项必须勾选并通过 `feature-review`，否则 `test-gate` 不放行。 +- **种子数据**：`tEmployee` / `tPermission` / `tCompany` 三张字典表在 REQ-USR-001 实现前需要少量种子（通过 Flyway `R__seed.sql` 或集成测试 `@Sql` 注入），便于 REQ-USR-001 的"员工名/版本/权限组"下拉测试。具体种子内容由 feature-tdd 落到测试 fixture，不进 V_n migration。 +- **登录失败锁定**：REQ-USR-004 的"连续失败阈值"与"锁定时长"由 `application.yml` 配置项 `app.security.max-login-fail` / `app.security.lock-minutes` 注入，默认 5 / 30。 diff --git a/docs/03-数据库设计文档 copy.md b/docs/03-数据库设计文档 copy.md new file mode 100644 index 0000000..b038d06 --- /dev/null +++ b/docs/03-数据库设计文档 copy.md @@ -0,0 +1,206 @@ +# 03-数据库设计文档 + +- **Schema**: `xlyweberp_vibe_erp_test` +- **Migration 清单**: `sql/migrations/V*.sql`（由 Flyway 顺序 apply） +- **生成方式**: 由 A3 `db-design-gen` 基于 `docs/01-需求清单//REQ-*.md` REQ 卡片正向设计生成（schema SSoT）。 + +## 项目标准列约定 + +下文每张业务表的字段清单都自动包含以下 5 个标准列（匈牙利前缀 `i` int / `s` varchar / `t` datetime）。渲染时由 `docs-03-table-template.md` 模板内置原样输出。 + +| 列名 | 类型 | 可空 | 主键 | 说明 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | 是 | 整数主键 ID（自增方式由实现决定：DB `AUTO_INCREMENT` 或应用 / 触发器分配） | +| `sId` | varchar(100) | 是 | — | 业务 ID（对外暴露的字符串标识，如 UUID / 人类可读编号） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离） | +| `tCreateDate` | datetime | 否 | — | 记录创建时间 | + +字典 / 辅助表如有豁免，在该表业务注记里注明豁免原因。 + +## ER 关系概览 + +``` +usr_user（用户主表） + └─< usr_user_permission（用户权限关联，多对多中间表）>─ usr_permission_group（权限分类表） + +跨模块引用（当前阶段记录，对应表由后续模块设计）： + usr_user.sEmployeeId → 职员表.sId（跨模块，可空，ON DELETE SET NULL） +``` + +## 表清单 + +- `usr_user` — 用户账户主表，存储登录信息、类型、语言偏好及安全控制字段 +- `tStaff` — 职员维度（员工名 / 部门 / 编号） +- `usr_permission_group` — 权限分类/权限组定义表，每行对应一个可分配给用户的权限项 +- `usr_user_permission` — 用户与权限组的多对多关联表 +- `brand` — 公司/品牌主表，登录账号前缀来源 + +--- + +## `usr_user` — 用户账户主表，存储登录信息、类型、语言偏好及安全控制字段 + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） | +| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） | +| `tCreateDate` | datetime | 否 | — | 创建时间（标准列） | +| `sUserCode` | varchar(50) | 否 | — | 用户号（业务编号，人类可读唯一标识） | +| `sUsername` | varchar(100) | 否 | — | 用户名（登录标识，全局唯一，不可修改） | +| `sPasswordHash` | varchar(255) | 否 | — | BCrypt 哈希密码，禁止存储明文 | +| `sUserType` | varchar(20) | 否 | `普通用户` | 用户类型：`普通用户` / `超级管理员` | +| `sLanguage` | varchar(20) | 否 | `中文` | 界面语言：`中文` / `英文` / `繁体` | +| `bCanEditDoc` | tinyint(1) | 否 | `0` | 单据修改权限：0=否，1=是 | +| `bIsDisabled` | tinyint(1) | 否 | `0` | 是否作废/禁用：0=正常，1=禁用 | +| `sEmployeeId` | varchar(100) | 是 | NULL | 关联职员 ID（跨模块引用，职员未关联时为 NULL） | +| `sCreatorUsername` | varchar(100) | 是 | NULL | 制单人用户名（冗余字段，便于列表展示） | +| `tLastLoginDate` | datetime | 是 | NULL | 最后登录时间 | +| `iLoginFailCount` | int | 否 | `0` | 连续登录失败次数，用于防暴力破解 | +| `tLockUntil` | datetime | 是 | NULL | 账号锁定截止时间，NULL 表示未锁定 | + +### 索引 + +- `uk_usr_user_username_tenant` (UNIQUE): `(sUsername, sBrandsId)` — 用户名在同一 brand 内唯一（V2 迁移：原全局唯一改为多租户复合唯一） +- `uk_usr_user_usercode` (UNIQUE): `sUserCode` — 用户号唯一约束 +- `idx_usr_user_tenant` (INDEX): `sBrandsId, sSubsidiaryId` — 多租户隔离查询 +- `idx_usr_user_type` (INDEX): `sUserType` — 按用户类型过滤 +- `idx_usr_user_disabled` (INDEX): `bIsDisabled` — 按状态过滤 + +### 外键 + +- 无（`sEmployeeId` 为跨模块引用，职员表由其他模块管理，当前阶段不建强约束） + +### 业务注记 + +用户登录标识为 `sUsername`（全局唯一），`sUserCode` 为业务编号（可为工号等人类可读标识）。密码以 BCrypt 哈希存储于 `sPasswordHash`，禁止回显。`iLoginFailCount` 达到阈值（默认 5 次）时写入 `tLockUntil`（当前时间 +30 分钟），解锁后计数归零。`sEmployeeId` 软关联职员表，职员表由后续模块设计；`sCreatorUsername` 为冗余字段，记录新建时的操作人用户名。 + +--- + +## `tStaff` — 职员维度（员工名 / 部门 / 编号） + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） | +| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） | +| `tCreateDate` | datetime | 否 | — | 创建时间（标准列） | +| `sStaffNo` | varchar(50) | 是 | — | 职员编号；系统内唯一 | +| `sStaffName` | varchar(50) | 否 | — | 职员姓名 | +| `sDepartment` | varchar(100) | 是 | NULL | 所属部门（本期暂用字符串，未来如需独立 `tDepartment` 字典表再另行重构） | +| `sCreatedBy` | varchar(50) | 是 | — | 制单人 | +| `bDeleted` | bit(1) | 否 | 0 | 软删除标记 | +| `tDeletedDate` | datetime | 是 | NULL | 软删除时间 | +| `sDeletedBy` | varchar(50) | 是 | NULL | 软删除操作人 | + +### 索引 + +- `uk_staff_no` (UNIQUE): (`sStaffNo`) +- `idx_staff_name` (NORMAL): (`sStaffName`) +- `idx_department` (NORMAL): (`sDepartment`) + +### 外键 + +（无） + +### 业务注记 + +- USR 模块通过 `tUser.iStaffId` 引用本表；REQ-USR-003 列表的「员工名 / 部门」均来自本表。 +- 部门当前以字符串保存，便于本期快速落地；后续若需独立部门字典表（如审批流引用部门），改为 `iDepartmentId` 外键。 + +--- + +## `usr_permission_group` — 权限分类/权限组定义表，每行对应一个可分配给用户的权限项 + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） | +| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） | +| `tCreateDate` | datetime | 否 | — | 创建时间（标准列） | +| `sGroupCode` | varchar(100) | 否 | — | 权限代码（如 `usr:create`、`usr:edit`），全局唯一 | +| `sGroupName` | varchar(200) | 否 | — | 权限显示名称（如"新增用户"、"修改用户"） | +| `sCategory` | varchar(100) | 是 | NULL | 权限分类标签，用于前端权限分组展示 | + +### 索引 + +- `uk_usr_perm_group_code` (UNIQUE): `sGroupCode` — 权限代码唯一约束 +- `idx_usr_perm_group_tenant` (INDEX): `sBrandsId, sSubsidiaryId` — 多租户隔离查询 + +### 外键 + +- 无 + +### 业务注记 + +权限分类表存储系统内所有可分配权限项的定义，`sGroupCode` 即前端 `PermButton` 校验的权限码字符串。`sCategory` 用于将权限归组（如"用户管理"分类下含 `usr:create`、`usr:edit`、`usr:query` 等），对应前端 REQ-USR-001/002 权限组表格的"权限分类"列。 + +--- + +## `usr_user_permission` — 用户与权限组的多对多关联表 + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） | +| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） | +| `tCreateDate` | datetime | 否 | — | 创建时间（标准列） | +| `sUserId` | varchar(100) | 否 | — | 关联 `usr_user.sId` | +| `sPermGroupId` | varchar(100) | 否 | — | 关联 `usr_permission_group.sId` | + +### 索引 + +- `uk_usr_user_perm` (UNIQUE): `sUserId, sPermGroupId` — 防止重复授权 +- `idx_usr_user_perm_user` (INDEX): `sUserId` — 按用户查询其所有权限 +- `idx_usr_user_perm_group` (INDEX): `sPermGroupId` — 按权限组查询持有该权限的用户 + +### 外键 + +- `fk_usr_user_perm_user`: `sUserId` → `usr_user.sId` (ON DELETE CASCADE ON UPDATE CASCADE) +- `fk_usr_user_perm_group`: `sPermGroupId` → `usr_permission_group.sId` (ON DELETE CASCADE ON UPDATE CASCADE) + +### 业务注记 + +多对多中间表，记录每个用户持有的权限组。新增用户时（REQ-USR-001）保存权限组复选框选中项，修改用户时（REQ-USR-002）先删除该用户旧记录再批量插入新记录（replace 策略）。用户被删除或权限组被删除时，对应关联记录级联删除。 + +--- + +## `brand` — 公司表 + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） | +| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） | +| `tCreateDate` | datetime | 否 | — | 创建时间（标准列） | +| `sName` | varchar(100) | 是 | — | 公司名称 | +| `sShortName` | varchar(100) | 是 | — | 公司简称 | +| `sNo` | varchar(100) | 是 | — | 单位编号（登录账号根据单位编号作为前缀） | + +### 索引 + +- `uk_brand_no` (UNIQUE): `sNo` — 单位编号唯一约束（登录账号前缀来源，必须唯一） +- `idx_brand_name` (INDEX): `sName` — 按公司名称查询 + +### 外键 + +- 无 + +### 业务注记 + +公司/品牌主表，记录系统内每个租户的基础信息。`sNo` 为单位编号，登录用户的账号以该编号为前缀生成（参见 `usr_user.sUsername` 的命名规则）；因此 `sNo` 必须全局唯一。`sShortName` 为公司简称，用于前端列表 / 抬头等空间受限位置展示。本表为多租户体系的根表，其他业务表的 `sBrandsId` 软关联到本表 `sId`，当前阶段不建强外键约束。 diff --git a/docs/03-数据库设计文档.md b/docs/03-数据库设计文档.md new file mode 100644 index 0000000..4034a9d --- /dev/null +++ b/docs/03-数据库设计文档.md @@ -0,0 +1,231 @@ +# 03-数据库设计文档 + +- **Schema**: `xlyweberp_vibe_erp_test` +- **Migration 清单**: `sql/migrations/V*.sql`（由 Flyway 顺序 apply） +- **生成方式**: 由 A3 `db-design-gen` 基于 `docs/01-需求清单//REQ-*.md` REQ 卡片正向设计生成（schema SSoT）。 + +## 项目标准列约定 + +下文每张业务表的字段清单都自动包含以下 5 个标准列（匈牙利前缀 `i` int / `s` varchar / `t` datetime）。渲染时由 `docs-03-table-template.md` 模板内置原样输出。 + +| 列名 | 类型 | 可空 | 主键 | 说明 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | 是 | 整数主键 ID（自增方式由实现决定：DB `AUTO_INCREMENT` 或应用 / 触发器分配） | +| `sId` | varchar(100) | 是 | — | 业务 ID（对外暴露的字符串标识，如 UUID / 人类可读编号） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离） | +| `tCreateDate` | datetime | 否 | — | 记录创建时间 | + +字典 / 辅助表如有豁免，在该表业务注记里注明豁免原因。 + +## ER 关系概览 + +``` +tCompany (公司/版本字典) + ▲ + │ 登录时仅作为下拉来源，无 FK 引用 + +tEmployee (职员) + ▲ + │ iEmployeeId（可空） + │ +tUser ────────────────────────► tUserPermission ◄──── tPermission + (用户) N:M (经关联表) (权限分类字典) +``` + +- `tUser` 通过 `iEmployeeId` 可选关联 `tEmployee`（员工名/部门 等显示属性的来源）。 +- `tUser` 与 `tPermission` 经 `tUserPermission` 关联表实现多对多权限分配。 +- `tCompany` 在登录场景作为「版本」下拉值的来源，业务上独立，登录时不强约束 FK（避免账号跨公司复用受阻）。 + +## 表清单 + +- `tUser` — 系统用户主表（账号 / 类型 / 语言 / 密码哈希 / 登录态） +- `tEmployee` — 职员字典（员工名 / 部门），被用户表可选引用 +- `tPermission` — 权限分类字典 +- `tUserPermission` — 用户 ↔ 权限 多对多关联表 +- `tCompany` — 公司及其版本字典，用于登录页「版本」下拉 + +--- + +## `tUser` — 系统用户主表 + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） | +| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） | +| `tCreateDate` | datetime | 否 | CURRENT_TIMESTAMP | 创建时间（标准列） | +| `sUserCode` | varchar(32) | 否 | — | 用户号，业务唯一编码 | +| `sUserName` | varchar(50) | 否 | — | 用户名（登录标识），全局唯一 | +| `iEmployeeId` | int | 是 | NULL | 关联 `tEmployee.iIncrement`，可选；选填后页面回显员工名/部门 | +| `sUserType` | varchar(20) | 否 | 'NORMAL' | 用户类型：`NORMAL`=普通用户，`ADMIN`=超级管理员 | +| `sLanguage` | varchar(16) | 否 | 'zh-CN' | 界面语言：`zh-CN` 中文，`en` 英文，`zh-TW` 繁体 | +| `iCanEditDoc` | tinyint(1) | 否 | 0 | 单据修改权限：0=否，1=是 | +| `sPasswordHash` | varchar(100) | 否 | — | 密码哈希（BCrypt 或同强度算法），初始值由系统生成；REQ-USR-001 边界要求"以哈希形式存储" | +| `iIsDisabled` | tinyint(1) | 否 | 0 | 作废标志：0=有效，1=已作废（被作废后不可登录） | +| `tLastLoginDate` | datetime | 是 | NULL | 最近一次登录时间，登录成功时更新 | +| `iLoginFailCount` | int | 否 | 0 | 连续登录失败计数，登录成功清零（用于阈值锁定） | +| `tLockedUntil` | datetime | 是 | NULL | 临时锁定截止时间；非空且大于当前时刻视为锁定（REQ-USR-004 防暴破） | +| `sCreatedBy` | varchar(50) | 是 | NULL | 制单人（创建该用户的操作员用户名） | +| `tUpdateDate` | datetime | 否 | CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 修改时间 | + +### 索引 + +- `uk_tUser_sUserName` (UNIQUE): `sUserName` +- `uk_tUser_sUserCode` (UNIQUE): `sUserCode` +- `idx_tUser_iEmployeeId` (NORMAL): `iEmployeeId` +- `idx_tUser_tenant_status` (NORMAL): `sBrandsId, sSubsidiaryId, iIsDisabled` +- `idx_tUser_tLastLoginDate` (NORMAL): `tLastLoginDate` +- `idx_tUser_sUserType` (NORMAL): `sUserType` + +### 外键 + +- `fk_tUser_iEmployeeId`: `iEmployeeId` → `tEmployee.iIncrement` (ON DELETE SET NULL, ON UPDATE CASCADE) + +### 业务注记 + +- 用户名 `sUserName` 全局唯一，对应 REQ-USR-001 跨字段规则"用户名在系统内全局唯一"。 +- `sUserType` 取值受系统配置约束：当前仅 `NORMAL` / `ADMIN` 两类，由应用层枚举校验。 +- 密码字段只存哈希，禁止存明文；REQ-USR-001 初始密码 `666666` 由应用层哈希后写入。 +- `iLoginFailCount` + `tLockedUntil` 配合实现 REQ-USR-004 的"连续失败临时锁定账号"，具体阈值由 `application.yml` 配置（如 5 次失败锁 30 分钟）。 +- 作废用 `iIsDisabled` 软删除，禁止物理 DELETE；REQ-USR-002 中"被禁用账号无法登录"由 Service 层在登录时校验本字段。 + +--- + +## `tEmployee` — 职员字典 + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） | +| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） | +| `tCreateDate` | datetime | 否 | CURRENT_TIMESTAMP | 创建时间（标准列） | +| `sEmployeeCode` | varchar(32) | 否 | — | 员工号，业务唯一编码 | +| `sEmployeeName` | varchar(50) | 否 | — | 员工姓名 | +| `sDepartment` | varchar(100) | 是 | NULL | 所属部门名 | +| `iIsDisabled` | tinyint(1) | 否 | 0 | 作废标志：0=有效，1=已作废 | +| `tUpdateDate` | datetime | 否 | CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 修改时间 | + +### 索引 + +- `uk_tEmployee_sEmployeeCode` (UNIQUE): `sEmployeeCode` +- `idx_tEmployee_sEmployeeName` (NORMAL): `sEmployeeName` +- `idx_tEmployee_sDepartment` (NORMAL): `sDepartment` +- `idx_tEmployee_tenant` (NORMAL): `sBrandsId, sSubsidiaryId` + +### 外键 + +（无外向引用；本表作为字典被 `tUser.iEmployeeId` 反向引用） + +### 业务注记 + +- 字典表，提供 REQ-USR-001/002 中"员工名"下拉来源以及 REQ-USR-003 列表中"员工名 / 部门"的显示数据。 +- 部门字段当前为字符串扁平存储；如后续部门需要层级管理，再拆 `tDepartment` 表并将本字段改为外键。 +- 员工被作废（`iIsDisabled=1`）后，引用了该员工的 `tUser` 记录通过 `iEmployeeId` 仍可保留旧值；查询时需 LEFT JOIN 并过滤展示。 + +--- + +## `tPermission` — 权限分类字典 + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） | +| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） | +| `tCreateDate` | datetime | 否 | CURRENT_TIMESTAMP | 创建时间（标准列） | +| `sCategory` | varchar(100) | 否 | — | 权限分类编码（如 `usr:user:create`） | +| `sCategoryName` | varchar(100) | 否 | — | 权限分类中文名（用于权限组复选框展示） | +| `sDescription` | varchar(255) | 是 | NULL | 权限说明 | +| `iIsDisabled` | tinyint(1) | 否 | 0 | 作废标志：0=有效，1=已作废 | +| `tUpdateDate` | datetime | 否 | CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 修改时间 | + +### 索引 + +- `uk_tPermission_sCategory` (UNIQUE): `sCategory` +- `idx_tPermission_sCategoryName` (NORMAL): `sCategoryName` + +### 外键 + +（无） + +### 业务注记 + +- 提供 REQ-USR-001/002 表 2「权限组」复选框的下拉数据；新增 / 修改用户时配套写入 `tUserPermission`。 +- `sCategory` 作为程序内 RBAC 校验的字符串编码，规范见 `docs/04 § 1.6`；新增权限须同步发布到后端枚举与前端 ``。 +- 字典表，行数预期 < 1000；不做按租户隔离查询的复合索引。 + +--- + +## `tUserPermission` — 用户 ↔ 权限多对多关联表 + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） | +| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） | +| `tCreateDate` | datetime | 否 | CURRENT_TIMESTAMP | 创建时间（标准列） | +| `iUserId` | int | 否 | — | 用户主键，关联 `tUser.iIncrement` | +| `iPermissionId` | int | 否 | — | 权限主键，关联 `tPermission.iIncrement` | +| `sGrantedBy` | varchar(50) | 是 | NULL | 授权操作员用户名（审计用） | + +### 索引 + +- `uk_tUserPermission_user_perm` (UNIQUE): `iUserId, iPermissionId` +- `idx_tUserPermission_iPermissionId` (NORMAL): `iPermissionId` + +### 外键 + +- `fk_tUserPermission_iUserId`: `iUserId` → `tUser.iIncrement` (ON DELETE CASCADE, ON UPDATE CASCADE) +- `fk_tUserPermission_iPermissionId`: `iPermissionId` → `tPermission.iIncrement` (ON DELETE RESTRICT, ON UPDATE CASCADE) + +### 业务注记 + +- 关联表，承载 REQ-USR-001/002 表 2「权限组」的勾选结果。 +- 用户被删除时级联清理本表行；权限分类被删除时阻止（需先解除全部用户授权）。 +- 唯一索引 `(iUserId, iPermissionId)` 防止重复授权。 +- 字典关联表不带 `tUpdateDate` / `iIsDisabled`：授权关系采用"存在即生效，删除即撤销"语义，无需软删。 + +--- + +## `tCompany` — 公司及版本字典 + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +| `iIncrement` | int | 否 | — | 整数主键 ID（标准列） | +| `sId` | varchar(100) | 是 | — | 业务 ID（标准列） | +| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离，标准列） | +| `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离，标准列） | +| `tCreateDate` | datetime | 否 | CURRENT_TIMESTAMP | 创建时间（标准列） | +| `sCompanyName` | varchar(100) | 否 | — | 公司名称 | +| `sEdition` | varchar(32) | 否 | '标准版' | 版本：`标准版` / `专业版` / `企业版` 等 | +| `iIsDisabled` | tinyint(1) | 否 | 0 | 作废标志 | +| `tUpdateDate` | datetime | 否 | CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 修改时间 | + +### 索引 + +- `idx_tCompany_sCompanyName` (NORMAL): `sCompanyName` +- `idx_tCompany_sEdition` (NORMAL): `sEdition` + +### 外键 + +（无） + +### 业务注记 + +- 字典表，提供 REQ-USR-004 登录页「版本」下拉数据。 +- 不与 `tUser` 建外键：账号可在多公司 / 多版本之间复用；登录时仅用作上下文选择，由应用层校验"用户是否被允许进入该公司版本"。 +- 当 `sEdition` 的取值集合稳定后，可改为受控字典并迁移到 `tDictionary` 类公共字典表；当前阶段独立维护。 diff --git a/docs/04-技术规范.md b/docs/04-技术规范.md new file mode 100644 index 0000000..53034ca --- /dev/null +++ b/docs/04-技术规范.md @@ -0,0 +1,207 @@ +# 04-技术规范 + +## 零、技术栈总览 + +| 分层模块 | 技术 | 版本要求 | 说明 | +|---|---|---|---| +| 前端基础框架 | React | 18.x | 构建前端应用 | +| 前端 UI 组件 | Ant Design | 5.x | 页面组件与交互控件 | +| 前端状态管理 | Redux Toolkit | 最新稳定版 | 管理全局状态 | +| 前端路由管理 | React Router | v6 | 页面路由与导航 | +| 前端工程化构建 | Vite | 最新稳定版 | 前端开发与打包构建 | +| 前端接口通信 | Axios | 最新稳定版 | 调用后端 API | +| 后端基础框架 | Spring Boot | 3.x | 构建后端服务 | +| 后端数据访问 | MyBatis-Plus | 最新稳定版 | 数据库访问与 ORM 增强 | +| 工作流引擎 | Activiti | 6.x | 审批流、流程流转 | +| 缓存服务 | Redis | 最新稳定版 | 缓存、会话、分布式能力 | +| 报表打印 | JXLS | 2.8.1 | 基于 Excel 模板生成报表 | +| Excel 导入导出 | EasyExcel | 4.0.3 | Excel 数据导入导出 | +| 关系型数据库 | MySQL | 8.x | 核心业务数据存储 | +| 数据库 schema 迁移 | Flyway (`flyway-core` + `flyway-mysql`) | 10.x / 最新稳定版 | `sql/migrations/V_n__*.sql` 顺序 apply；Spring Boot 启动时自动应用 | +| 接口风格 | RESTful API | 统一规范 | 前后端接口设计规范 | +| 权限认证 | Spring Security / JWT | 最新稳定版 | 登录认证、权限控制 | +| API 文档 | OpenAPI / Swagger | 最新稳定版 | 接口文档与调试 | +| 项目构建管理 | Maven | 3.9.x | Java 项目依赖与构建 | +| JDK 运行环境 | Java | 17 / 21 | Spring Boot 3 推荐版本 | +| 部署容器 | Docker | 最新稳定版 | 容器化部署 | +| Web 服务器 / 反向代理 | Nginx | 最新稳定版 | 前端托管、反向代理、负载分发 | +| 日志管理 | Logback | 默认集成 / 最新稳定版 | 应用日志输出 | +| 对象映射工具 | MapStruct | 最新稳定版 | DTO / VO / Entity 转换 | +| 工具类库 | Hutool / Apache Commons | 最新稳定版 | 常用工具方法支持 | + +> 本表由 scope-lock 锁定。后续所有规范基于此表推导。 + +## 一、后端规范 + +### 1.1 分层结构 + +| 层 | 职责 | +|---|---| +| controller | 解析 HTTP 入参 / 校验请求体格式 / 返回 `Result`；不写业务逻辑 | +| service | 业务流程编排、事务边界、跨 Mapper 组合；接口 + impl 拆开 | +| mapper | 数据访问，对应一张表；XML 写 SQL，禁止跨表 JOIN 之外的业务判断 | +| entity | 与数据库表一一映射的 PO；不带业务方法 | +| dto / vo | 入参（DTO） / 出参（VO）专用结构；通过 MapStruct 与 entity 转换 | +| common | 跨模块基础设施（异常 / 响应 / 配置 / 工具 / 安全） | + +调用方向严格自上而下，禁止反向依赖（Controller 不能被 Service import）。 + +### 1.2 命名约定 + +- **包名**：根包`com.xly.test4`，全小写点分隔；模块代码小写作为子包（`USR` → `usr`）。 +- **类名**：大驼峰，按职责加后缀：`UserController` / `UserService` / `UserServiceImpl` / `UserMapper` / `UserCreateDTO` / `UserVO`。 +- **方法名 / 变量**：小驼峰；布尔以 `is` / `has` / `can` 开头。 +- **常量**：`UPPER_SNAKE_CASE`，定义在 `common.constant.Constants`。 + +示例： + +```java +// 示例 1：Controller +@RestController +@RequestMapping("/api/usr/user") +public class UserController { + public Result createUser(@Valid @RequestBody UserCreateDTO dto) { ... } +} + +// 示例 2：常量 +public final class UserConstants { + public static final int MAX_LOGIN_FAIL_TIMES = 5; +} +``` + +### 1.3 统一响应格式 + +所有 Controller 返回 `Result`，结构： + +```json +// 成功 +{ "code": "0", "msg": "ok", "data": { ... }, "traceId": "..." } + +// 失败 +{ "code": "USR-001", "msg": "用户名已存在", "data": null, "traceId": "..." } +``` + +错误码段位： + +| 段位 | 含义 | +|---|---| +| `0` | 成功 | +| `1xxx` | 通用框架错误（参数校验失败、权限不足、未登录） | +| `-` | 业务错误，MOD 与模块代码一致（如 `USR-001`） | +| `5xxx` | 系统内部错误（DB 异常、第三方调用失败） | + +### 1.4 异常处理 + +- 使用 `@RestControllerAdvice` 全局异常处理器，统一捕获并转 `Result.fail(...)`。 +- 业务异常用自定义 `BusinessException(code, msg)` 抛出，不要 catch 后吞掉。 +- 参数校验异常（`MethodArgumentNotValidException`）→ `1001` + 首个字段错误信息。 +- 未预期异常 → `5000` + 通用文案"系统繁忙，请稍后重试"；**接口响应禁止回显堆栈**，堆栈只进 Logback。 +- traceId 在 Filter 层注入 MDC，错误响应中回填便于排查。 + +### 1.5 事务 + +- `@Transactional` 仅打在 Service 实现类方法上，默认 `rollbackFor = Exception.class`。 +- Controller 层禁止打事务注解。 +- 一个 Service 方法只能跨当前模块的 Mapper；调用另一模块必须走对方 Service 的公共方法。 +- 跨服务（跨进程）调用 **禁止**包在事务里；如有最终一致性需求走异步 + 补偿。 + +### 1.6 认证 + +- 使用 Spring Security + JWT；登录接口签发 `accessToken`（24h）+ `refreshToken`（7 天）。 +- token 放 Authorization header，格式 `Bearer `。 +- 密钥从 `.env.local` → `JWT_SECRET` 注入到 `application.yml`，**代码里禁止硬编码**。 +- 刷新机制：accessToken 过期前 30 分钟前端用 refreshToken 换新；refreshToken 一次性使用，签发新 access 时同时滚动新 refresh。 + +## 二、前端规范 + +### 2.1 目录约定 + +| 目录 | 职责 | +|---|---| +| `api/` | 后端接口封装；每模块一文件；导出函数对应 REQ 接口 | +| `components/` | 跨页面通用组件；无业务耦合 | +| `pages/` | 业务页面；按模块代码分子目录 | +| `store/` | Redux Toolkit slice；按模块拆分 | +| `hooks/` | 自定义 hooks | +| `utils/` | 纯函数工具（日期、金额、字符串等） | +| `styles/` | 全局样式 + Design Tokens | + +**前端禁止直接写 SQL / 操作 DB / 直连数据库连接**；所有数据访问走 `api/` 层 axios 封装。 + +### 2.2 状态管理 + +- **服务端数据**：默认不存 Redux；通过 `useQuery` 风格 hook 或就近 `useState + useEffect` 拉取；如确实需跨页面共享（如当前用户信息），存 `store/` 对应 slice。 +- **全局状态**：登录态、当前用户、权限列表、菜单 → Redux。 +- **页面级状态**：表单字段、过滤条件、分页 → `useState` 或 `useReducer`，不进 Redux。 + +### 2.3 请求封装 + +- 单例 `axios` 实例，`baseURL` 由环境变量注入。 +- 请求拦截器：从 Redux 取 accessToken 注入 Authorization header。 +- 响应拦截器： + - `code === '0'` → resolve `data` + - 401 → 自动调 refresh 接口尝试续期；失败则清空登录态跳 `/login` + - 其他失败 → reject `Result`，由调用方决定弹窗 +- 默认超时 15s；GET 类请求允许业务侧覆盖至 60s（如导出大数据量列表）。 +- 重试：默认不重试；幂等查询接口（GET）业务侧可显式配置 1 次重试。 + +### 2.4 错误处理 + +- **网络错误**（无 response）：响应拦截器统一 `notification.error`「网络异常，请检查连接」。 +- **业务错误**（`code !== '0'`）：reject 给调用方；调用方根据场景决定 `message.error`（inline）或 `notification.error`（异步任务）。 +- **页面级错误**（路由懒加载失败 / 组件渲染异常）：用 React `ErrorBoundary` 兜底，展示 `Result` 错误页 + "重试"按钮。 + +### 2.5 样式与主题 + +- CSS 变量命名格式：`--color---` + - ``：`form` / `table-row` / `button` / 其他组件域名 + - ``：`bg` / `fg` / `border` + - ``：`edit` / `readonly` / `hover` / `selected` / `disabled` +- 文件位置：`src/styles/tokens.css`，由 skeleton-gen 生成空骨架，色值由 docs/06 § 二锁定后填入。 +- 组件样式中只允许 `var(--color-xxx)`，**禁止硬编码 hex / rgba**。 +- 与 Ant Design 5 对接：在 App 根层用 `ConfigProvider`，将 token 值绑定到 `theme.token.colorPrimary` 等。 +- 具体 token 表见 docs/06 § 二。 + +## 三、共同约定 + +### 3.1 Git 提交 + +`(): REQ-XXX-NNN` + +具体规则见 `CLAUDE.md § 🗂️ Git 提交规范`。 + +### 3.2 分页查询 + +- **后端入参**：`PageQuery { pageNum: int=1, pageSize: int=20, ... }`，pageSize 上限 100。 +- **后端出参**：`PageResult { records: List, total: long, pageNum: int, pageSize: int }`。 +- **前端**：Ant Design `Table` + `pagination` 双向绑定 `pageNum` / `pageSize`；切换时清空选中行。 +- 排序与过滤条件并入 PageQuery 子类（如 `UserPageQuery`），避免接口爆炸。 + +### 3.3 日期与金额 + +- **后端类型**：日期一律 `LocalDateTime`（含时分秒）或 `LocalDate`（仅日期）；JSON 序列化用 ISO-8601 字符串（`yyyy-MM-dd'T'HH:mm:ss`）。 +- **金额类型**：`BigDecimal`，标度（scale）= 2（保留 2 位小数），所有运算用 `BigDecimal.divide(..., RoundingMode.HALF_UP)` 避免 `double` 精度丢失。 +- **前端展示**： + - 日期用 `dayjs` 统一格式化，列表 `YYYY-MM-DD HH:mm`，详情 `YYYY-MM-DD HH:mm:ss`。 + - 金额展示用千分位 + 2 位小数；展示前必须 `Number.toFixed(2)`。 + +### 3.4 数据访问规约 + +- **SELECT 字段必须显式列举**，禁止 `SELECT *`；新增字段时同步更新 Mapper XML 与 entity。 +- **禁止循环中执行 DB 查询**（N+1 反模式）；改用： + - 批量查询：`Mapper.selectBatchIds(ids)` + - IN 子句：`Mapper.selectByIds(ids)` 一次拉取 + - JOIN：在 XML 内 JOIN 子表 +- Mapper XML 内字段与表名建议用 `` 复用片段或常量；禁止字符串拼接 SQL 片段。 +- MyBatis-Plus 的 `LambdaQueryWrapper` 优先于硬编码字符串列名。 + +### 3.5 配置与安全 + +- **配置外置**：DB 连接 / 端口 / 密钥 / 第三方 URL 等一律放 `application.yml` + `.env.local`； + - `application.yml` 写占位 `${JWT_SECRET}` + - 真实值放 `.env.local`（不入 git） + - 代码里**禁止硬编码**任何凭据。 +- **前端安全**： + - `localStorage` 不存敏感信息（token / 身份 / 个人数据）。 + - 推荐 HttpOnly Cookie 存 refreshToken；accessToken 放内存（Redux）+ 刷新机制兜底。 + - 接口响应**禁止回显后端异常堆栈**（与 § 1.4 一致），错误码 + 文案足够。 diff --git a/docs/05-API接口契约.md b/docs/05-API接口契约.md new file mode 100644 index 0000000..acbb799 --- /dev/null +++ b/docs/05-API接口契约.md @@ -0,0 +1,121 @@ +# 05-API接口契约 + +BasePath: `/api` +端口: `8080` + +## 全局约定 + +### 响应格式 +```json +{"code": 200, "message": "操作成功", "data": {}, "timestamp": 1700000000000} +``` + +### 错误码 +| 范围 | 含义 | +|---|---| +| 200 | 成功 | +| 400xx | 客户端参数错误 | +| 401xx | 认证/授权错误 | +| 403xx | 权限不足 | +| 404xx | 资源不存在 | +| 500xx | 服务端内部错误 | + +### 鉴权 + +- 所有 `/api/**` 接口默认要求 JWT；登录、版本下拉等少数白名单接口（见各接口 `Auth: 否`）匿名访问。 +- 客户端将登录返回的 `accessToken` 放入请求头：`Authorization: Bearer `。 +- accessToken 默认有效期 24h；过期前 30 分钟前端可用 `refreshToken` 续期（独立接口，本契约暂不展开）。 +- 锁定中（`tUser.tLockedUntil` 未过期）的账号即使密码正确也无法登录，返回 `40110`。 + +### 分页参数 + +请求查询参数（GET）或 body（POST 列表）统一： + +``` +pageNum: int = 1 // 页码，从 1 开始 +pageSize: int = 20 // 每页条数，上限 100 +``` + +响应 `data` 结构： + +```json +{ + "records": [ ... ], + "total": 123, + "pageNum": 1, + "pageSize": 20 +} +``` + +`pageSize > 100` 时后端自动截断为 100，并在响应 `message` 中提示 `pageSize 已截断到 100`。 + +## 接口清单 + +### REQ-USR-001 增加用户 + +- **Method**: POST +- **Path**: `/api/usr/user` +- **Auth**: 是 +- **Permission**: `usr:user:create`（仅超级管理员或被显式授权者） +- **请求**: JSON body，字段包括 `userCode`、`userName`、`employeeId`（可空）、`userType`（NORMAL/ADMIN）、`language`（zh-CN/en/zh-TW）、`canEditDoc`（bool）、`password`（明文，后端哈希后存储，缺省则使用配置项 `app.security.default-password`，默认 `666666`）、`permissionIds`（int[]，权限分类主键数组，对应 `tUserPermission` 关联）。 +- **响应**: `data` = `{ "userId": , "userCode": }`，对应 REQ-USR-001 输出表 1「用户号」。 + +#### 错误码 +- `40001` — 必填字段缺失或格式不合法 +- `40002` — `userName` 已存在（违反 `uk_tUser_sUserName`） +- `40003` — `userCode` 已存在（违反 `uk_tUser_sUserCode`） +- `40004` — `employeeId` 非法（在 `tEmployee` 中不存在或已作废） +- `40005` — `permissionIds` 中某个权限分类不存在或已作废 +- `40301` — 当前账号无 `usr:user:create` 权限 + +--- + +### REQ-USR-002 修改用户 + +- **Method**: PUT +- **Path**: `/api/usr/user/{userId}` +- **Auth**: 是 +- **Permission**: `usr:user:update`（管理员）或本人改本人非角色字段 +- **请求**: 路径参数 `userId` + JSON body，可选字段 `employeeId` / `userType` / `language` / `canEditDoc` / `iIsDisabled` / `permissionIds`。`userName` / `userCode` / `password` 不在本接口修改。 +- **响应**: `data` = `{ "userId": }`，对应 REQ-USR-002 输出表 1「用户 id」。 + +#### 错误码 +- `40001` — 字段格式不合法 +- `40006` — `userType` 变更需 `usr:user:assign-role` 权限 +- `40004` — `employeeId` 非法（不存在或已作废） +- `40005` — `permissionIds` 中某个权限分类不存在或已作废 +- `40402` — 目标 `userId` 不存在 +- `40301` — 当前账号无 `usr:user:update` 权限（且非本人） + +--- + +### REQ-USR-003 查询用户 + +- **Method**: GET +- **Path**: `/api/usr/user` +- **Auth**: 是 +- **Permission**: `usr:user:list`（管理员） +- **请求**: 查询参数 `queryField`（用户名/员工名/用户号/部门/用户类型/作废/登录日期/制单人）+ `matchMode`（包含/不包含/等于）+ `queryValue`（可空，空时不过滤）+ `pageNum` + `pageSize`。 +- **响应**: 分页结构，`records[]` 项对应 REQ-USR-003 输出表 1 全部字段：`index` / `userName` / `employeeName` / `userCode` / `department` / `userType` / `language` / `isDisabled` / `lastLoginDate` / `createdBy` / `createDate`。`employeeName` / `department` 由 LEFT JOIN `tEmployee` 取得。密码字段任何场景下都不返回。 + +#### 错误码 +- `40001` — `queryField` / `matchMode` 取值非法 +- `40301` — 当前账号无 `usr:user:list` 权限 + +--- + +### REQ-USR-004 用户登录 + +- **Method**: POST +- **Path**: `/api/auth/login` +- **Auth**: 否（匿名） +- **Permission**: 无 +- **请求**: JSON body `{ "userName": , "password": , "companyId": }`，`companyId` 对应 `tCompany.iIncrement`（前端「版本」下拉所选项）。 +- **响应**: `data` = `{ "accessToken": , "tokenType": "Bearer", "expiresIn": 86400, "user": { "userId": ..., "userName": ..., "userType": ..., "language": ..., "canEditDoc": ..., "permissions": [...] } }`。 + +#### 错误码 +- `40001` — `userName` / `password` / `companyId` 字段缺失 +- `40101` — 用户名或密码错误（统一返回，不区分具体哪个错；同时 `tUser.iLoginFailCount += 1`） +- `40110` — 账号已锁定（`tLockedUntil > NOW()`），返回锁定截止时间 +- `40111` — 账号已作废（`tUser.iIsDisabled = 1`） +- `40404` — `companyId` 对应公司不存在或已作废 diff --git a/docs/06-UI交互规范.md b/docs/06-UI交互规范.md new file mode 100644 index 0000000..e53bea5 --- /dev/null +++ b/docs/06-UI交互规范.md @@ -0,0 +1,97 @@ +# 06-UI交互规范 + +> 本项目所有页面布局以项目根 `prototype/` 目录下的静态 HTML mockup 为权威。前端阶段（fe-feature-*）实现时直接以 prototype/ HTML 推导组件树与样式。本文件仅承载跨页面通用规则与 Design Tokens。 + +## 一、通用交互规则 + +### 1.1 操作反馈 + +- **成功反馈**：表单提交 / 数据操作成功后，统一使用 Ant Design `message.success`（顶部居中，2 秒自动消失），文案以"操作动词 + 成功"格式，例如"保存成功""删除成功""登录成功"。 +- **失败反馈**：业务错误使用 `message.error`（4 秒），文案直接展示后端返回的 `msg` 字段；网络异常或 5xx 使用 `notification.error`（右上角，需手动关闭），标题统一"操作失败"，描述给出可复制的 traceId（便于排查）。 +- **危险操作二次确认**：删除、禁用、批量更新等不可逆或影响范围大的动作，统一使用 `Modal.confirm`（图标 `ExclamationCircleOutlined`），确认按钮使用 danger 主题，按钮文案"确认删除/确认禁用"，禁止默认聚焦确认按钮。 +- **长耗时按钮 loading 态**：所有提交按钮在请求未返回前必须置 `loading=true` 并禁用其他相关按钮；超过 10 秒未返回，前端在 button 上叠加文案"处理中…"提示用户耐心等待，不主动中断。 + +### 1.2 数据展示 + +- **空状态**：列表无数据统一使用 Ant Design `Empty` 组件，描述文案"暂无数据"；带筛选条件时改为"未找到匹配的记录，请调整筛选条件"。 +- **加载态**：列表 / 详情页统一使用 `Skeleton`（结构化骨架屏），不允许使用纯 spinner 遮罩整页；表格内联加载使用 Table 自带 `loading` 属性。 +- **异常态**：接口失败导致页面无法渲染时，使用 `Result` 组件（`status="error"`），标题"加载失败"，描述展示业务错误码与可复制 traceId，并提供"重试"主按钮。 + +### 1.3 权限控制（前端） + +- **路由级**：在 React Router 外层封装 ``，未登录跳 `/login`，已登录但权限不足跳 `/403`；权限定义由后端 RBAC 接口返回当前用户的 `permissions` 字符串数组（如 `usr:user:create`）。 +- **菜单级**：左侧菜单根据 `permissions` 过滤；用户看不到的模块完全不出现，不做置灰处理。 +- **按钮级**：封装 `` 组件，无权限时直接不渲染（而非禁用）。后端接口必须独立做权限校验，前端权限隐藏只是用户体验层。 + +## 二、Design Tokens + +### 2.1 全局调色板 + +所有色值统一以 CSS 变量定义于 `src/styles/tokens.css`，与 Ant Design 5 的 `ConfigProvider.theme.token` 双向对齐。 + +| 语义 | 变量名 | 默认值 | 用途 | +|---|---|---|---| +| 主色 | `--color-primary` | `#1677ff` | 主按钮、链接、选中态；映射 AntD `colorPrimary` | +| 成功 | `--color-success` | `#52c41a` | 成功态、有效状态指示 | +| 警告 | `--color-warning` | `#faad14` | 警告 tag / message | +| 错误 | `--color-error` | `#ff4d4f` | 错误 message、危险按钮、必填校验失败 | +| 主文字 | `--color-text` | `rgba(0,0,0,0.88)` | 标题、正文 | +| 次文字 | `--color-text-secondary` | `rgba(0,0,0,0.65)` | 表单 label、辅助说明 | +| 三级文字 | `--color-text-tertiary` | `rgba(0,0,0,0.45)` | placeholder、禁用文字 | +| 边框 | `--color-border` | `#d9d9d9` | 输入框、卡片、表格分割线 | +| 背景 | `--color-bg` | `#ffffff` | 卡片、模态框背景 | +| 页面背景 | `--color-bg-layout` | `#f5f5f5` | 整页底色 | + +### 2.2 组件级状态色 + +| 序号 | 组件 | 编辑 bg | 只读 bg | 悬浮 bg | 编辑 fg | 只读 fg | 悬浮 fg | 备注 | +|---|---|---|---|---|---|---|---|---| +| 1 | 表单输入框 | `var(--color-bg)` | `var(--color-bg-layout)` | `var(--color-bg)` | `var(--color-text)` | `var(--color-text-secondary)` | `var(--color-text)` | 只读使用 Input 的 readOnly 属性 | +| 2 | 表格行 | `var(--color-bg)` | — | `var(--color-row-hover)` | `var(--color-text)` | — | `var(--color-text)` | 表格 hover 高亮 | +| 3 | 选中行 | — | — | `var(--color-row-selected)` | — | — | `var(--color-primary)` | 单选 / 多选 | +| 4 | 主按钮 | `var(--color-primary)` | `var(--color-text-tertiary)` | `var(--color-primary-hover)` | `#fff` | `#fff` | `#fff` | 禁用态走只读列 | +| 5 | 危险按钮 | `var(--color-error)` | — | `var(--color-error-hover)` | `#fff` | — | `#fff` | 删除 / 禁用类操作 | + +Token 默认值（在 `src/styles/tokens.css` 定义）： + +| 变量名 | 默认值 | +|---|---| +| `--color-row-hover` | `#fafafa` | +| `--color-row-selected` | `#e6f4ff` | +| `--color-primary-hover` | `#4096ff` | +| `--color-error-hover` | `#ff7875` | + +### 2.3 引用约定 + +- 组件样式只用 `var(--color-xxx)`，禁止硬编码 hex / rgba。 +- 新增 token 须先登记到 § 2.1 / 2.2 再补 `tokens.css`，禁止"先写代码后补登记"。 +- 修改色值只改 `tokens.css` 一处，不允许组件层 `style` / CSS Module 覆盖；如确实业务需要新色，走"新增 token"流程。 + +## 三、页面清单 + +### module_usr 用户管理 + +- **登录页** (`/login`) + - 类型: 表单页 + - 对应 REQ: REQ-USR-004 + - 入口菜单: 系统外（匿名访问入口） + - 主要交互: 输入用户名 / 密码 / 选择版本（公司）→ 提交 → 成功跳 `/`；失败统一弹「用户名或密码错误」（不区分），账号锁定时弹锁定截止时间。 + +- **用户列表页** (`/usr/user`) + - 类型: 列表页 + - 对应 REQ: REQ-USR-003 + - 入口菜单: 系统管理 → 用户管理 + - 主要交互: 顶部筛选区（查询字段下拉 + 匹配方式下拉 + 查询值输入）+ 表格（分页 / 排序）+ 操作列（编辑 / 作废）+ 顶部「新增」按钮跳新增页。 + +- **用户新增页** (`/usr/user/new`) + - 类型: 表单页 + - 对应 REQ: REQ-USR-001 + - 入口菜单: 用户列表页「新增」按钮 + - 主要交互: 用户号 / 用户名手工输入，员工名下拉（来自 tEmployee），类型 / 语言下拉，单据修改权限复选，权限组复选框列表（来自 tPermission）。提交成功提示「保存成功」并返回列表。 + +- **用户编辑页** (`/usr/user/:userId/edit`) + - 类型: 表单页 + - 对应 REQ: REQ-USR-002 + - 入口菜单: 用户列表页「编辑」操作 + - 主要交互: 表单字段同新增，但用户号 / 用户名 / 密码不可编辑（置 readOnly 灰底）；权限组勾选反映当前授权状态。提交成功提示「保存成功」并返回列表。 + diff --git a/docs/07-环境配置.md b/docs/07-环境配置.md new file mode 100644 index 0000000..f521a15 --- /dev/null +++ b/docs/07-环境配置.md @@ -0,0 +1,48 @@ +# 07-环境配置 + +## 一、依赖清单 + +| 层 | 依赖 | 版本 | 说明 | +|---|---|---|---| +| 运行时 | JDK | 17 或 21 | Spring Boot 3 推荐 | +| 运行时 | Node.js | ≥ 18 LTS | Vite 5 / React 18 构建运行 | +| 运行时 | MySQL Server | 8.x | 业务数据存储 | +| 运行时 | Redis | 最新稳定版 | 缓存、会话 | +| 运行时 | Nginx | 最新稳定版 | 前端静态托管 + 反向代理 | +| 构建 | Maven | 3.9.x | 后端依赖管理与打包 | +| 构建 | npm 或 pnpm | npm ≥ 9 / pnpm ≥ 8 | 前端包管理；项目统一二选一 | +| 构建 | Flyway | 10.x | 数据库 migration（随 Spring Boot 启动 apply） | +| 容器 | Docker | 最新稳定版 | 容器化部署 | +| 容器 | Docker Compose | 最新稳定版 | 本地多服务编排 | +| CLI 工具 | git | ≥ 2.30 | 版本管理 | +| CLI 工具 | mysql-client | 8.x | `scripts/setup-test-db.sh` 需要 | +| CLI 工具 | glab 或 gh | 最新稳定版 | 创建 MR / PR | + +## 二、端口约定 + +| 服务 | 端口 | 说明 | +|---|---|---| +| 后端 HTTP | 8080 | Spring Boot 内嵌 Tomcat | +| 后端管理端点 | 8081 | Spring Boot Actuator（如启用，独立端口） | +| 前端 dev 服务器 | 5173 | Vite dev server | +| MySQL | 3306 | 业务数据库 | +| MySQL（测试库） | 3307 | 隔离的测试库；可与主库同实例不同 schema | +| Redis | 6379 | 缓存 / 会话 | +| Nginx | 80 / 443 | 生产反向代理（80 → 443 强跳） | + +## 三、环境变量 + +运行时凭据（数据库连接、JWT 密钥等）全部放在仓库根的 `.env.local`，不入 git。 +字段清单与占位符见该文件，真实值由开发者本地填写。 + +## 四、常用命令 + +| 命令 | 说明 | +|---|---| +| `cd backend && mvn spring-boot:run` | 本地启动后端（自动 apply Flyway migration） | +| `cd frontend && npm run dev` | 本地启动前端 dev server（监听 5173） | +| `cd backend && mvn clean package -DskipTests` | 打后端 jar | +| `cd frontend && npm run build` | 打前端静态资源到 `dist/` | +| `bash scripts/test.sh` | 一键跑全部测试（后端 build/lint/test + 前端 build/lint/test + e2e） | +| `bash scripts/setup-test-db.sh` | 重置测试库（DROP + CREATE，不 apply migration；migration 由 Spring Boot 启动时 Flyway 自动 apply） | +| `glab mr create` 或 `gh pr create` | 推送当前分支后创建 MR / PR | diff --git a/docs/08-模块任务管理.md b/docs/08-模块任务管理.md new file mode 100644 index 0000000..c1c6af2 --- /dev/null +++ b/docs/08-模块任务管理.md @@ -0,0 +1,80 @@ +# 08-工作流进度 + +> 全流程进度跟踪。CC 每完成一项产出就勾选一项。 +> - **§ 一 Plan（A0~A5）**：`plan-start` 找第一个未勾 A 子项分发到对应 skill +> - **§ 二 Coding（模块）**：分发以 `docs/02-开发计划.md § 二 开发顺序清单` 为准；`coding-start` 按 docs/02 顺序扫描，对每个 REQ 所属模块查询本 § 二的 `MR:` 字段 + GitLab API `state`，找第一个非 merged 模块分发。本 § 二 行序无语义，仅作模块元数据表 + +## 一、Plan 阶段（一次性） + +- [x] A0 项目初始化 — project-init + - [x] 依赖检查通过 + - [x] 项目文件骨架已创建（CLAUDE.md + docs/01-需求清单/index.md + docs/04-技术规范.md） + - [x] Git 已初始化 + +- [x] A1 范围锁定 — scope-lock + - [x] 项目概述已填写（CLAUDE.md § 🎯 项目概述） + - [x] 技术栈已确认（docs/04 § 零） + - [x] 需求清单索引已填写（docs/01-需求清单/index.md） + - [x] REQ 卡片骨架已生成（docs/01-需求清单//REQ-*.md，业务内容留待人工填写） + +- [x] A2 骨架生成 — skeleton-gen + - [x] 架构文档已生成（docs/04 § 一+、docs/06、docs/07、docs/09） + - [x] 工具脚本已生成（scripts/*.sh、.githooks/pre-push、.env.local） + - [x] .gitignore 已配置 + +- [x] A3 DB 设计 + REQ 回填 — db-design-gen + - [x] docs/03-数据库设计文档.md 已生成 + - [x] docs/01 各 REQ 卡片"依赖表" + 模块头"涉及表" 已回填 + +- [x] A4 DB 初始化 — db-init + - [x] sql/migrations/V1__initial_schema.sql 已生成 + - [x] DDL 与 docs/03 全量一致 + - [x] .env.local 凭据已验证（mysql -e "SELECT 1" OK） + - [x] setup-test-db.sh 防护通过 + DROP+CREATE + apply V1 已执行 + - [x] SHOW TABLES 行数 == docs/03 表数量 + +- [x] A5 下游文档生成 — downstream-gen + - [x] docs/02 开发计划已生成 + - [x] docs/05 API 契约已生成 + - [x] docs/06 § 三 页面清单已填入 + - [x] docs/10 验收清单已生成 + - [x] 下方模块列表已填入 + - [x] REQ 卡片依赖接口已回填 + +## 二、Coding 阶段（后端模块循环） + +（A5 填入后，每行一个后端模块。每个模块的 `MR:` 字段在 `—` 和 `!` 之间变化，完成由 GitLab API `state=merged` 判定。`coding-start` 每次按 docs/02 REQ 序扫每模块的 MR state 决定派发。后端模块全部 merged 后自动进入 § 三 前端阶段。） + + + +- module_usr 用户管理 + - 依赖: — + - 路径: backend/src/main/java/com/xly/test4/module/usr/ + - MR: — + - 功能: + - [ ] REQ-USR-001 增加用户 + - [ ] REQ-USR-002 修改用户 + - [ ] REQ-USR-003 查询用户 + - [ ] REQ-USR-004 用户登录 + +## 三、Coding 阶段（前端整体） + +（`frontend-start` 进入时扫 prototype/ + docs/01 + docs/05 → AI 自主推导 FE 业务功能清单写到下方"功能:"项（无人工审阅断点；合理性由整体 MR 时统一校核）。已有清单则直接加载。整个前端阶段 1 个 MR，分支 `frontend-phase`。） + +- 整体 MR: — +- 功能: + diff --git a/docs/09-项目目录结构.md b/docs/09-项目目录结构.md new file mode 100644 index 0000000..8e7c94e --- /dev/null +++ b/docs/09-项目目录结构.md @@ -0,0 +1,141 @@ +# 09-项目目录结构 + +> 根包名 / 命名空间占位由人工补填一次，其他文档复用： +> - **后端根包名**：`com.xly.test4` + +## 一、仓库顶层 + +``` +/ +├── CLAUDE.md # Claude Code 主指令 +├── README.md # 项目说明（可选） +├── .env.local # 本地凭据（不入 git） +├── .env.example # 凭据模板（可选） +├── .gitignore +├── .githooks/ +│ └── pre-push # MR 前测试闸门兜底 +├── scripts/ +│ ├── test.sh # 一键测试 +│ └── setup-test-db.sh # 重置测试库 +├── docs/ # 项目文档（结构见 § 四） +├── sql/ +│ └── migrations/ # Flyway V_n__*.sql +├── prototype/ # 前端原型 HTML mockup（前端阶段权威布局） +├── backend/ # Spring Boot 后端工程（结构见 § 二） +└── frontend/ # Vite + React 前端工程（结构见 § 三） +``` + +## 二、后端目录 + +``` +backend/ +├── pom.xml +├── src/ +│ ├── main/ +│ │ ├── java/ +│ │ │ └── com/xly/test4/ +│ │ │ ├── Application.java # @SpringBootApplication 入口 +│ │ │ ├── common/ # 跨模块基础设施 +│ │ │ │ ├── config/ # Spring 配置类 +│ │ │ │ ├── exception/ # 全局异常处理器 + 业务异常类 +│ │ │ │ ├── response/ # 统一响应包装 Result +│ │ │ │ ├── security/ # Spring Security + JWT +│ │ │ │ └── util/ # 工具类 +│ │ │ └── module/ # 业务模块（按 docs/01 index） +│ │ │ └── usr/ # USR 用户管理 +│ │ │ ├── controller/ +│ │ │ ├── service/ +│ │ │ ├── mapper/ +│ │ │ ├── entity/ +│ │ │ ├── dto/ +│ │ │ └── vo/ +│ │ └── resources/ +│ │ ├── application.yml +│ │ ├── application-dev.yml +│ │ └── mapper/ # MyBatis-Plus XML +│ │ └── usr/ +│ └── test/ +│ └── java/ +│ └── com/xly/test4/ +│ └── module/usr/ # 与 main 同包结构 +``` + +业务模块按 `docs/01-需求清单/index.md` 的模块代码（小写）落到 `module//` 下；本项目当前模块： + +| 模块代码 | 后端目录 | +|---|---| +| USR | `backend/src/main/java/com/xly/test4/module/usr/` | + +## 三、前端目录 + +``` +frontend/ +├── package.json +├── vite.config.ts +├── tsconfig.json +├── index.html +└── src/ + ├── main.tsx # 入口 + ├── App.tsx # 顶层路由 + ├── api/ # 后端 API 客户端（按模块分文件） + │ └── usr.ts + ├── components/ # 跨页面通用组件 + ├── pages/ # 业务页面（按模块分子目录） + │ └── usr/ + │ ├── LoginPage.tsx + │ └── UserListPage.tsx + ├── store/ # Redux Toolkit slice + │ └── usrSlice.ts + ├── hooks/ # 自定义 hooks + ├── utils/ # 纯工具函数 + ├── styles/ + │ └── tokens.css # Design Tokens（docs/06 § 二） + └── types/ # 全局 TS 类型 +``` + +业务模块按 `docs/01-需求清单/index.md` 的模块代码（小写）落到 `pages//`、`api/.ts`、`store/Slice.ts`。 + +## 四、docs/ 结构 + +``` +docs/ +├── 01-需求清单/ # 每模块一子目录（_module.md 模块头 + REQ-*.md 卡片） +├── 02-开发计划.md +├── 03-数据库设计文档.md +├── 04-技术规范.md +├── 05-API接口契约.md +├── 06-UI交互规范.md +├── 07-环境配置.md +├── 08-模块任务管理.md +├── 09-项目目录结构.md +├── 10-验收检查清单.md +└── superpowers/ # CC 运行时产物 +``` + +## 五、命名与放置约定 + +### 5.1 后端 + +- **根包名**：`com.xly.test4`（顶部已声明，本节作引用）。 +- **包路径**：全小写、点分隔；模块代码作为子包名转小写（`USR` → `usr`）。 +- **Controller**：`<根包>.module..controller.Controller`，仅处理 HTTP 参数解析与响应包装，禁止写业务逻辑。 +- **Service**：`<根包>.module..service.Service` + 实现 `impl/ServiceImpl`，业务逻辑与事务边界落在此层。 +- **Mapper**：`<根包>.module..mapper.Mapper` + `resources/mapper//Mapper.xml`，仅数据访问，禁止跨模块查询。 +- **Entity**：`<根包>.module..entity.`，与数据库表一一对应。 +- **DTO** / **VO**：`dto/CreateDTO` 等用于入参，`vo/VO` 用于出参；DTO → Entity → VO 转换走 MapStruct。 +- **类名**：大驼峰；**方法名 / 变量**：小驼峰；**常量**：全大写下划线分隔；**布尔变量/方法**：`is` / `has` / `can` 前缀。 + +### 5.2 前端 + +- **页面组件**：大驼峰 + `Page` 后缀，如 `UserListPage.tsx`。 +- **通用组件**：大驼峰，如 `AuthButton.tsx`。 +- **api 文件**：模块代码小写 + `.ts`，如 `usr.ts`；导出函数名小驼峰，如 `loginUser`、`createUser`。 +- **store slice**：模块代码小写 + `Slice.ts`。 +- **hooks**：`use` 前缀小驼峰，如 `useCurrentUser.ts`。 +- **样式 token**：变量名 `--color---`（见 docs/04 § 2.5）。 + +### 5.3 跨层禁止事项 + +- 前端 **禁止** 直接写 SQL / 访问数据库；所有数据访问走 `api/` 层封装。 +- Controller **禁止** 注入 Mapper；必须通过 Service 中转。 +- 跨模块调用 **禁止** 直接 import 另一模块的 Mapper / Entity；必须通过对方模块暴露的 Service 公共方法。 diff --git a/docs/10-验收检查清单.md b/docs/10-验收检查清单.md new file mode 100644 index 0000000..3a9c860 --- /dev/null +++ b/docs/10-验收检查清单.md @@ -0,0 +1,16 @@ +# 10-验收检查清单 + +通用验收项（全项目适用）： + +- [ ] `scripts/test.sh` 本地全绿 +- [ ] 所有 schema 改动都有对应 `sql/migrations/V_n__.sql` +- [ ] 所有新接口在 `docs/05` 中有契约定义 +- [ ] 所有新功能代码注释含 REQ-XXX-NNN +- [ ] 统一响应格式 `{code, message, data, timestamp}` +- [ ] 异常走全局处理器，不暴露堆栈到前端 +- [ ] 前端不存敏感信息到 localStorage + +> 本文档仅维护项目级验收 SOP。粒度更细的验收信息分散在： +> - **每 REQ 的业务验收点**：`docs/01-需求清单//.md § 验收` +> - **每模块的实测验收（数据 / UI / 自动化用例位置）**：由 B 阶段 `module-report` 在该模块完成时填入模块完成报告 +> - **REQ 开发进度（feature-review approve 状态）**：`docs/08 § 二` diff --git a/scripts/setup-test-db.sh b/scripts/setup-test-db.sh new file mode 100755 index 0000000..41a3970 --- /dev/null +++ b/scripts/setup-test-db.sh @@ -0,0 +1,65 @@ +#!/usr/bin/env bash +# scripts/setup-test-db.sh — 数据库重置脚本：drop + create 空库。 +# schema apply 由 Flyway 在 Spring Boot 启动时自动处理（见 docs/04 技术栈 + sql/migrations/V*.sql）。 +# seed 数据由测试框架负责（Spring @Sql / Flyway R__seed.sql / data.sql）。 +# +# 使用场景： +# - scripts/test.sh 开头：清空库，让 Spring 启动时 Flyway 从 V1 开始重放所有 migration +# - scripts/test.sh 结尾：清空库，避免测试遗留污染下次运行 +# - 手动调试时：reset 到零状态 +# +# 防护：本脚本只允许在本地 host + 测试库名上执行；非预期目标会被拒绝， +# 避免 .env.local 误指向 staging/prod 时触发不可逆 DROP。 + +set -euo pipefail + +ENV_FILE="$(dirname "$0")/../.env.local" +[ -f "$ENV_FILE" ] || { echo "[setup-test-db] ⚠️ .env.local 不存在（$ENV_FILE）" >&2; exit 1; } + +# 用 set -a 加载，让 KEY=VALUE 导出为环境变量；密码中含特殊字符时 .env.local 请用单引号包裹 +set -a; . "$ENV_FILE"; set +a + +# 防护 1：默认只允许本地 host（localhost / 127.0.0.1 / ::1）。 +# 若要为本项目额外允许某些远程 host（如公司测试 MySQL），在 .env.local 里设： +# TEST_DB_ALLOWED_HOSTS="118.178.19.35 test-mysql.internal" # 空格或逗号分隔 +# 被列入者可直接 DROP CREATE，不再需要 TEST_DB_ALLOW_REMOTE=1。 +ALLOWED_HOSTS="localhost 127.0.0.1 ::1 ${TEST_DB_ALLOWED_HOSTS//,/ }" +host_allowed=0 +for h in $ALLOWED_HOSTS; do + [ "${DB_HOST:-}" = "$h" ] && { host_allowed=1; break; } +done +if [ "$host_allowed" -ne 1 ]; then + echo "[setup-test-db] ⚠️ 拒绝在非白名单 host (${DB_HOST}) 上执行 DROP DATABASE" >&2 + echo " 当前白名单：${ALLOWED_HOSTS}" >&2 + echo " 加入 host：在 .env.local 追加 TEST_DB_ALLOWED_HOSTS=\" \"" >&2 + echo " 一次性绕过：TEST_DB_ALLOW_REMOTE=1 $0" >&2 + [ "${TEST_DB_ALLOW_REMOTE:-0}" = "1" ] || exit 1 +fi + +# 防护 2：schema 名需像测试/开发库（含 test / _dev / _local），否则要求显式确认 +case "${DB_SCHEMA:-}" in + *test*|*_dev|*_local|*_ci) + ;; + *) + echo "[setup-test-db] ⚠️ schema '${DB_SCHEMA}' 不像测试库（期望命名含 test / _dev / _local / _ci）" >&2 + echo " 如确为期望行为，请显式声明：TEST_DB_ALLOW_PROD_NAME=1 $0" >&2 + [ "${TEST_DB_ALLOW_PROD_NAME:-0}" = "1" ] || exit 1 + ;; +esac + +# 防护 3：显式 banner，让人看见自己在 drop 什么；远程 host 额外提示白名单内容 +echo "[setup-test-db] 即将 DROP + CREATE \`${DB_SCHEMA}\` on ${DB_HOST}:${DB_PORT}" +case "${DB_HOST:-}" in + localhost|127.0.0.1|::1) ;; + *) + echo "[setup-test-db] ⚠️ 目标是 **远程** host（已在 TEST_DB_ALLOWED_HOSTS 白名单中，每次 test.sh 都会 DROP）" + echo "[setup-test-db] 当前白名单: ${ALLOWED_HOSTS}" + echo "[setup-test-db] 若不希望每次自动 DROP，从 .env.local 的 TEST_DB_ALLOWED_HOSTS 删掉此 host" + ;; +esac + +MYSQL_CMD="mysql -h${DB_HOST} -P${DB_PORT} -u${DB_USER} -p${DB_PASSWORD}" + +$MYSQL_CMD -e "DROP DATABASE IF EXISTS \`${DB_SCHEMA}\`; CREATE DATABASE \`${DB_SCHEMA}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" + +echo "[setup-test-db] done — schema will be applied by Flyway when Spring Boot starts" diff --git a/scripts/test.sh b/scripts/test.sh new file mode 100755 index 0000000..fa209ce --- /dev/null +++ b/scripts/test.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +# scripts/test.sh —— 合并到默认分支（main / master）前的测试闸门。 +# 顺序：detect → setup-db → build → lint → unit+integration → e2e → reset-db +# 由 .githooks/pre-push 和 test-gate skill（通过子会话）调用。 + +set -euo pipefail + +PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)" +cd "$PROJECT_ROOT" + +# Stack detection (runtime, mode-agnostic) +HAS_BACKEND=0; [ -d backend ] && HAS_BACKEND=1 +HAS_FRONTEND=0; [ -d frontend ] && HAS_FRONTEND=1 +if [ $HAS_BACKEND -eq 0 ] && [ $HAS_FRONTEND -eq 0 ]; then + echo "[test.sh] FATAL: neither backend/ nor frontend/ exists" >&2 + exit 1 +fi + +echo "[test.sh] 1/6 setup test db" +./scripts/setup-test-db.sh + +echo "[test.sh] 2/6 build" +if [ $HAS_BACKEND -eq 1 ]; then (cd backend && mvn -B clean package -DskipTests); else echo "[test.sh] skip backend build"; fi +if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npm run build); else echo "[test.sh] skip frontend build"; fi + +echo "[test.sh] 3/6 lint" +if [ $HAS_BACKEND -eq 1 ]; then (cd backend && mvn -B compile); else echo "[test.sh] skip backend lint"; fi +if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npm run lint); else echo "[test.sh] skip frontend lint"; fi + +echo "[test.sh] 4/6 unit + integration" +if [ $HAS_BACKEND -eq 1 ]; then (cd backend && mvn -B test); else echo "[test.sh] skip backend test"; fi +if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npm run test); else echo "[test.sh] skip frontend test"; fi + +echo "[test.sh] 5/6 E2E" +echo "[test.sh] e2e 略" + +echo "[test.sh] 6/6 reset test db" +./scripts/setup-test-db.sh + +echo "[test.sh] GREEN" diff --git a/sql/migrations/.gitkeep b/sql/migrations/.gitkeep new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/sql/migrations/.gitkeep diff --git a/sql/migrations/V1__initial_schema.sql b/sql/migrations/V1__initial_schema.sql new file mode 100644 index 0000000..a96dcc8 --- /dev/null +++ b/sql/migrations/V1__initial_schema.sql @@ -0,0 +1,135 @@ +-- Flyway migration V1 — initial schema for 小羚羊 +-- Generated: 2026-05-13T07:35:36Z +-- Source: 由 A4 db-init 从 docs/03-数据库设计文档.md 翻译生成（schema SSoT 是 docs/03） +-- This is the FIRST migration; subsequent schema changes must be written as new files sql/migrations/V2__.sql, V3__... etc. +-- Apply: Flyway runs this automatically at Spring Boot startup. +-- Do not hand-edit this file after it is committed; write a new migration instead. + +SET NAMES utf8mb4; +SET FOREIGN_KEY_CHECKS = 0; + +-- ============================================================ +-- tUser — 系统用户主表 +-- ============================================================ +CREATE TABLE `tUser` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL COMMENT '品牌 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `sUserCode` VARCHAR(32) NOT NULL COMMENT '用户号，业务唯一编码', + `sUserName` VARCHAR(50) NOT NULL COMMENT '用户名（登录标识），全局唯一', + `iEmployeeId` INT NULL DEFAULT NULL COMMENT '关联 tEmployee.iIncrement，可选；选填后页面回显员工名/部门', + `sUserType` VARCHAR(20) NOT NULL DEFAULT 'NORMAL' COMMENT '用户类型：NORMAL=普通用户，ADMIN=超级管理员', + `sLanguage` VARCHAR(16) NOT NULL DEFAULT 'zh-CN' COMMENT '界面语言：zh-CN 中文，en 英文，zh-TW 繁体', + `iCanEditDoc` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '单据修改权限：0=否，1=是', + `sPasswordHash` VARCHAR(100) NOT NULL COMMENT '密码哈希（BCrypt 或同强度算法），初始值由系统生成；以哈希形式存储', + `iIsDisabled` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '作废标志：0=有效，1=已作废（被作废后不可登录）', + `tLastLoginDate` DATETIME NULL DEFAULT NULL COMMENT '最近一次登录时间，登录成功时更新', + `iLoginFailCount` INT NOT NULL DEFAULT 0 COMMENT '连续登录失败计数，登录成功清零（用于阈值锁定）', + `tLockedUntil` DATETIME NULL DEFAULT NULL COMMENT '临时锁定截止时间；非空且大于当前时刻视为锁定', + `sCreatedBy` VARCHAR(50) NULL DEFAULT NULL COMMENT '制单人（创建该用户的操作员用户名）', + `tUpdateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间', + PRIMARY KEY (`iIncrement`), + UNIQUE KEY `uk_tUser_sUserName` (`sUserName`), + UNIQUE KEY `uk_tUser_sUserCode` (`sUserCode`), + KEY `idx_tUser_iEmployeeId` (`iEmployeeId`), + KEY `idx_tUser_tenant_status` (`sBrandsId`, `sSubsidiaryId`, `iIsDisabled`), + KEY `idx_tUser_tLastLoginDate` (`tLastLoginDate`), + KEY `idx_tUser_sUserType` (`sUserType`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='系统用户主表'; + +-- ============================================================ +-- tEmployee — 职员字典 +-- ============================================================ +CREATE TABLE `tEmployee` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL COMMENT '品牌 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `sEmployeeCode` VARCHAR(32) NOT NULL COMMENT '员工号，业务唯一编码', + `sEmployeeName` VARCHAR(50) NOT NULL COMMENT '员工姓名', + `sDepartment` VARCHAR(100) NULL DEFAULT NULL COMMENT '所属部门名', + `iIsDisabled` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '作废标志：0=有效，1=已作废', + `tUpdateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间', + PRIMARY KEY (`iIncrement`), + UNIQUE KEY `uk_tEmployee_sEmployeeCode` (`sEmployeeCode`), + KEY `idx_tEmployee_sEmployeeName` (`sEmployeeName`), + KEY `idx_tEmployee_sDepartment` (`sDepartment`), + KEY `idx_tEmployee_tenant` (`sBrandsId`, `sSubsidiaryId`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='职员字典'; + +-- ============================================================ +-- tPermission — 权限分类字典 +-- ============================================================ +CREATE TABLE `tPermission` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL COMMENT '品牌 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `sCategory` VARCHAR(100) NOT NULL COMMENT '权限分类编码（如 usr:user:create）', + `sCategoryName` VARCHAR(100) NOT NULL COMMENT '权限分类中文名（用于权限组复选框展示）', + `sDescription` VARCHAR(255) NULL DEFAULT NULL COMMENT '权限说明', + `iIsDisabled` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '作废标志：0=有效，1=已作废', + `tUpdateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间', + PRIMARY KEY (`iIncrement`), + UNIQUE KEY `uk_tPermission_sCategory` (`sCategory`), + KEY `idx_tPermission_sCategoryName` (`sCategoryName`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='权限分类字典'; + +-- ============================================================ +-- tUserPermission — 用户 ↔ 权限多对多关联表 +-- ============================================================ +CREATE TABLE `tUserPermission` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL COMMENT '品牌 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `iUserId` INT NOT NULL COMMENT '用户主键，关联 tUser.iIncrement', + `iPermissionId` INT NOT NULL COMMENT '权限主键，关联 tPermission.iIncrement', + `sGrantedBy` VARCHAR(50) NULL DEFAULT NULL COMMENT '授权操作员用户名（审计用）', + PRIMARY KEY (`iIncrement`), + UNIQUE KEY `uk_tUserPermission_user_perm` (`iUserId`, `iPermissionId`), + KEY `idx_tUserPermission_iPermissionId` (`iPermissionId`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户 ↔ 权限多对多关联表'; + +-- ============================================================ +-- tCompany — 公司及版本字典 +-- ============================================================ +CREATE TABLE `tCompany` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL COMMENT '品牌 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `sCompanyName` VARCHAR(100) NOT NULL COMMENT '公司名称', + `sEdition` VARCHAR(32) NOT NULL DEFAULT '标准版' COMMENT '版本：标准版 / 专业版 / 企业版 等', + `iIsDisabled` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '作废标志', + `tUpdateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间', + PRIMARY KEY (`iIncrement`), + KEY `idx_tCompany_sCompanyName` (`sCompanyName`), + KEY `idx_tCompany_sEdition` (`sEdition`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='公司及版本字典'; + +-- ============================================================ +-- 外键 +-- ============================================================ +ALTER TABLE `tUser` + ADD CONSTRAINT `fk_tUser_iEmployeeId` + FOREIGN KEY (`iEmployeeId`) REFERENCES `tEmployee` (`iIncrement`) + ON DELETE SET NULL ON UPDATE CASCADE; + +ALTER TABLE `tUserPermission` + ADD CONSTRAINT `fk_tUserPermission_iUserId` + FOREIGN KEY (`iUserId`) REFERENCES `tUser` (`iIncrement`) + ON DELETE CASCADE ON UPDATE CASCADE; + +ALTER TABLE `tUserPermission` + ADD CONSTRAINT `fk_tUserPermission_iPermissionId` + FOREIGN KEY (`iPermissionId`) REFERENCES `tPermission` (`iIncrement`) + ON DELETE RESTRICT ON UPDATE CASCADE; + +SET FOREIGN_KEY_CHECKS = 1; diff --git a/src/styles/tokens.css b/src/styles/tokens.css new file mode 100644 index 0000000..bc8a542 --- /dev/null +++ b/src/styles/tokens.css @@ -0,0 +1,43 @@ +/* + * src/styles/tokens.css — Design Tokens + * 命名规范见 docs/04-技术规范.md § 2.5 + * 色值锁定见 docs/06-UI交互规范.md § 四 + * + * 命名格式：--color--- + * 组件域：form / table-row / table-header / ... + * 作用：bg（背景）/ fg（前景/字体）/ border + * 状态：edit / readonly / hover / selected（无状态时省略） + * + * 约束： + * - 组件样式中只用 var(--color-xxx)，禁止硬编码 hex / rgba + * - 修改色值只改本文件，不允许在组件级覆盖 + * - 新增 token 须先登记到 docs/06 § 4.1 / 4.2，再补到此处 + */ + +:root { + /* === 1. 全局调色板（与 Ant Design 主题对齐） === */ + --color-primary: #1890ff; + --color-success: #52c41a; + --color-warning: #faad14; + --color-error: #ff4d4f; + --color-text: rgba(0, 0, 0, 0.85); + --color-text-secondary: rgba(0, 0, 0, 0.45); + --color-border: #d9d9d9; + --color-bg-base: #f0f2f5; + + /* === 2. 组件级状态色（与 docs/06 § 4.2 一一对应） === */ + + /* form：输入框 / 备注框 / 时间框 / 下拉框共用 */ + --color-form-bg-edit: #ffffff; + --color-form-bg-readonly: #f1f2f8; + --color-form-bg-hover: #f5f5f5; /* 仅下拉框使用 */ + --color-form-fg: #000000; + + /* table */ + --color-table-row-bg-selected: #86d5fb; + --color-table-row-bg-hover: #fff7e6; + --color-table-row-bg-readonly: #f1f2f8; /* = rgb(241, 242, 248) */ + --color-table-row-fg: #000000; + --color-table-header-bg: #f5f5f5; + --color-table-header-fg: rgba(0, 0, 0, 0.85); /* = #000000D9 */ +} -- libgit2 0.22.2