# CLAUDE.md — 水利安全生产监管信息系统

## Project Overview

- **Name**: 水利安全生产监管信息系统 (Water Safety Production Supervision System)
- **Group/Artifact**: `com.goldenwater:slaj:3.9.2`
- **Database**: Migrating from Oracle → PostgreSQL (HighGo/瀚高)

## Tech Stack

| Layer | Technology | Version |
|-------|-----------|---------|
| Java | JDK | 17 |
| Framework | Spring Boot | 4.0.3 |
| ORM | MyBatis Spring Boot | 4.0.1 |
| Database | PostgreSQL (HighGo) | — |
| UI | Vue 3 + Element Plus | 3.5.26 / 2.13.1 |
| Build (FE) | Vite | — |
| Connection Pool | Druid | 1.2.28 |

## Module Structure

```
slaj/
├── gw-admin/       # Admin web module (controllers, composite services) — main entry point
├── gw-common/      # Shared entities, VOs, domain objects
├── gw-framework/   # Framework base classes (BaseController, etc.)
├── gw-quartz/      # Scheduled tasks
├── gw-slaj/        # Slaj business module (mappers, domain, controllers)
├── gw-system/      # System module (common mappers, services, sys_dept, etc.)
├── gw-ui/          # Vue 3 frontend
└── docs/           # DDL scripts, documents
```

## Database Configuration

- **Schema**: `slaj`
- **MyBatis**: `mapUnderscoreToCamelCase=true` → DB columns `org_name` auto-map to Java `orgName`
- **PageHelper**: `helperDialect: postgresql` (set in application.yml)
- **Dev DB**: `39.98.38.2:5866/highgo`
- **Test DB**: `192.168.0.149:5866/highgo`

## Key Conventions

### 1. Result Mapping in MyBatis XML
Use `resultType` (auto-mapping) for JOIN query results. DO NOT use `resultMap` — PostgreSQL returns lowercase column names, but `mapUnderscoreToCamelCase=true` handles the conversion automatically. When using `resultMap`, column aliases must match the resultMap column names exactly, which may conflict with PostgreSQL's lower-case behavior.

### 2. PostgreSQL Compatibility
- **`find_in_set`** → `ANY(string_to_array(col, ','))`
- **Upsert**: Use `INSERT ... ON CONFLICT (guid) DO UPDATE SET ...`
- **String concat**: `'%' || #{param} || '%'` (not MySQL `CONCAT('%', #{param}, '%')`)

### 3. Organization Types (3 types)

| Type | 中文名 | Tables | Description |
|------|--------|--------|-------------|
| Water Org | 水利机构 | `sys_dept` + `att_org_base` + `att_org_ext` | Government water departments |
| Uwat Org | 参建单位 | `sys_dept` + `att_org_base` + `att_org_uwat_ext` | Construction units |
| Wsub Org | 分包单位 | `sys_dept` + `att_org_base` + `att_org_wsub` | Subcontractor units |

**Shared UUID pattern**: `sys_dept.dept_id` = `att_org_base.guid` = extension_table.`org_guid`

### 4. Organization Insert Order (CRITICAL)
`SysDeptServiceImpl.insertDept()` internally regenerates UUID (line 230), so:
1. Insert `sys_dept` FIRST
2. Get the generated `deptId` from the returned dept object
3. Use that `deptId` as the shared UUID for `att_org_base.guid` and extension table's `org_guid`

### 5. Composite Services (gw-admin)
All composite org operations (`add`/`update`/`delete`) are in `gw-admin/src/main/java/com/goldenwater/web/service/`:
- `OrgCompositeService.java` — Water org (水利机构): sys_dept + att_org_base + att_org_ext
- `OrgUwatCompositeService.java` — Uwat org (参建单位): sys_dept + att_org_base + att_org_uwat_ext
- `OrgWsubCompositeService.java` — Wsub org (分包单位): sys_dept + att_org_base + att_org_wsub

All operations are **@Transactional** — all succeed or all roll back.

### 6. Redundant Table Sync (ATT_* → OBJ_*)
13 pairs of main/redundant tables. On every INSERT/UPDATE/DELETE to a main ATT_* table, the corresponding `ObjSyncMapper` upserts the OBJ_* redundant table via `ON CONFLICT DO UPDATE`.

| Main Table | Redundant Table |
|-----------|-----------------|
| ATT_ENG_BASE | OBJ_ENG |
| ATT_ENG_RES | OBJ_RES |
| ATT_ENG_WAGA | OBJ_WAGA |
| ATT_ENG_PUST | OBJ_PUST |
| ATT_ENG_HYST | OBJ_HYST |
| ATT_ENG_DIKE | OBJ_DIKE |
| ATT_ENG_IRR | OBJ_IRR |
| ATT_ENG_WADI | OBJ_WADI |
| ATT_ENG_SD | OBJ_SD |
| ATT_ENG_CWS | OBJ_CWS |
| ATT_ENG_OTHE | OBJ_OTHE |
| ATT_PROJ_BASE | OBJ_PROJ |
| ATT_AD_BASE | OBJ_AD |

### 7. Business Relationship Chain
```
项目 (ATT_PROJ_BASE) → 工程 (ATT_ENG_BASE) → 标段 (OBJ_TEND) → 参建单位
```
- **项目↔工程**: Through `REL_PROJ_ORG` table (`proj_guid` + `org_guid` + `from_date` + `to_date`)
  - `fromDate` is auto-set by `RelProjOrgServiceImpl.insertRelProjOrg()`
- **工程↔标段**: `OBJ_TEND.eng_guid` → `ATT_ENG_BASE.guid`
- **标段↔参建单位**: `REL_TEND_ORG` table

### 8. Frontend Page Templates — Standard Styles

ALL new pages MUST follow one of the two patterns below. Reference implementations:

| Pattern | Example File |
|---------|-------------|
| Standalone page | `gw-ui/src/views/slaj/woas/ObjWoas.vue` |
| Tree-sidebar page | `gw-ui/src/views/system/orgext/index.vue` |

#### 8a. Standalone Page Pattern (no sidebar)

Wrapper: `<div class="system-page config-page">` (NOT `app-container`).

```html
<template>
  <div ref="containerRef" class="system-page config-page">
    <el-card class="page-card">
      <template #header>
        <div class="card-header">
          <div class="header-left">
            <el-icon :size="20" color="#409EFF"><OfficeBuilding /></el-icon>
            <span class="page-title">页面标题</span>
          </div>
          <div class="search-right">
            <el-button type="primary" plain @click="handleAdd"><el-icon><Plus /></el-icon> 新增</el-button>
            <el-button type="danger" plain :disabled="multiple" @click="handleDelete"><el-icon><Delete /></el-icon> 删除</el-button>
            <right-toolbar v-model:showSearch="showSearch" @queryTable="getList" ... />
          </div>
        </div>
      </template>

      <div class="search-bar" v-show="showSearch">
        <el-form :model="queryParams" ref="queryRef" :inline="true">
          <!-- form items use el-icon component syntax for buttons -->
          <el-form-item>
            <el-button type="primary" @click="handleQuery"><el-icon><Search /></el-icon> 搜索</el-button>
            <el-button @click="resetQuery"><el-icon><Refresh /></el-icon> 重置</el-button>
          </el-form-item>
        </el-form>
      </div>

      <el-table :height="tableHeight" v-loading="loading" :data="dataList" @selection-change="handleSelectionChange">
        <el-table-column type="selection" width="50" align="center" />
        <!-- ... -->
        <el-table-column label="操作" align="center" width="160" fixed="right">
          <template #default="scope">
            <el-button link type="primary" @click="handleUpdate(scope.row)">修改</el-button>
            <el-button link type="danger" @click="handleDelete(scope.row)">删除</el-button>
          </template>
        </el-table-column>
      </el-table>

      <div class="pagination">
        <el-pagination
          v-show="total > 0"
          v-model:current-page="queryParams.pageNum"
          v-model:page-size="queryParams.pageSize"
          :total="total"
          :page-sizes="[10, 20, 50, 100]"
          layout="total, sizes, prev, pager, next, jumper"
          @size-change="getList"
          @current-change="getList"
        />
      </div>
    </el-card>

    <el-dialog :title="title" v-model="open" width="760px" append-to-body>
      <!-- form -->
      <template #footer>
        <el-button @click="cancel">取消</el-button>
        <el-button type="primary" @click="submitForm">确定</el-button>
      </template>
    </el-dialog>
  </div>
</template>
```

#### 8b. Tree-Sidebar Page Pattern (with TreePanel)

Wrapper: `<div class="app-container tree-sidebar-manage-wrap">` with TreePanel on the left.

Key differences from standalone:
- `content-inner` needs `style="padding: 0;"`
- `el-card` needs `style="height: 100%;" :body-style="{height: '100%'}"`
- `el-table` uses `height="calc(100% - 100px)"` instead of `:height="tableHeight"`

```html
<template>
  <div class="app-container tree-sidebar-manage-wrap">
    <tree-panel :key="deptTreeKey" title="组织机构" :tree-data="deptOptions" :tree-props="treeProps"
      search-placeholder="请输入机构名称" storage-key="xxx-sidebar-width"
      node-key="deptId" lazy :load="loadDeptNode"
      @node-click="handleNodeClick" @refresh="getDeptTree" ref="deptTreeRef" />
    <div class="tree-sidebar-content">
      <div class="content-inner" ref="containerRef" style="padding: 0;">
        <el-card class="page-card" style="height: 100%;" :body-style="{height: '100%'}">
          <template #header>
            <div class="card-header">
              <div class="header-left">
                <el-icon :size="20" color="#409EFF"><OfficeBuilding /></el-icon>
                <span class="page-title">页面标题</span>
              </div>
              <div class="search-right">
                <el-button type="primary" plain @click="handleAdd"><el-icon><Plus /></el-icon> 新增</el-button>
                <el-button type="danger" plain :disabled="multiple" @click="handleDelete"><el-icon><Delete /></el-icon> 删除</el-button>
                <right-toolbar v-model:showSearch="showSearch" @queryTable="getList" />
              </div>
            </div>
          </template>

          <div class="search-bar" v-show="showSearch">
            <el-form :model="queryParams" ref="queryRef" :inline="true">
              <!-- ... same as standalone ... -->
            </el-form>
          </div>

          <el-table height="calc(100% - 100px)" v-loading="loading" :data="dataList" @selection-change="handleSelectionChange">
            <!-- ... -->
          </el-table>

          <div class="pagination">
            <el-pagination ... />
          </div>
        </el-card>

        <el-dialog :title="title" v-model="open" width="820px" append-to-body>
          <!-- form -->
          <template #footer>
            <el-button @click="cancel">取消</el-button>
            <el-button type="primary" @click="submitForm">确定</el-button>
          </template>
        </el-dialog>
      </div>
    </div>
  </div>
</template>
```

#### 8c. Shared Styles (global, no per-page duplication)

All shared page styles are defined in [`gw-ui/src/assets/styles/goldenwater.scss`](gw-ui/src/assets/styles/goldenwater.scss) under the `/* Shared Page Styles */` comment block. Pages do **NOT** need `<style scoped>` blocks for the following — they inherit globally:

- `.system-page` — wrapper padding, background, min-height, input/textarea border-radius
- `.page-card` — card border-radius, shadow, header/body padding overrides
- `.card-header` — flex layout, `.header-left` (icon + title), `.search-right` (buttons)
- `.search-bar` — light blue background (`#f8faff`), flex layout, form item spacing
- `.pagination` — margin + right-alignment
- `.el-table` — header background (`#f5f7fa`), link button colors

**Pages only need a `<style scoped>` block if they have page-specific overrides** (e.g., `.projbase-form .el-divider`, `.tend-form .el-textarea__inner`).

```scss
<style scoped lang="scss">
// For standalone pages: wrap everything in .system-page { ... }
// For tree-sidebar pages: styles are at root level (no .system-page wrapper needed)

.system-page {                         // ← standalone pages only
  padding: 0px;
  background-color: #f5f7fa;
  min-height: calc(100vh - 10px);

  :deep(.el-input__wrapper)   { border-radius: 4px; }
  :deep(.el-textarea__inner)  { border-radius: 4px; }
}                                      // ← close .system-page

.page-card {
  border-radius: 1px;
  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.05);

  :deep(.el-card__header) {
    padding: 8px 20px !important;
    border-bottom: 1px solid #ebeef5;
    background-color: #fff;
    border-radius: 8px 8px 0 0;
  }

  :deep(.el-card__body) {
    padding: 0px !important;
    background-color: #fff;
  }
}

.card-header {
  display: flex;
  justify-content: space-between;
  align-items: center;

  .header-left {
    display: flex;
    align-items: center;
    gap: 10px;
    .page-title { font-size: 18px; font-weight: 600; color: #303133; }
  }

  .search-right {
    display: flex;
    gap: 10px;
  }
}

.search-bar {
  margin-bottom: 0px;
  background-color: #f8faff;
  padding: 6px 10px;
  border-radius: 6px;
  display: flex;
  justify-content: space-between;
  align-items: center;

  :deep(.el-form) {
    display: flex;
    flex-wrap: wrap;
    gap: 10px;

    .el-form-item {
      margin-bottom: 0;
      margin-right: 15px;
      .el-form-item__label { font-weight: 500; }
    }
  }
}

.pagination {
  margin-top: 8px;
  margin-bottom: 8px;
  display: flex;
  justify-content: flex-end;
}

:deep(.el-table) {
  border-radius: 4px;
  overflow: auto;

  th.el-table__cell {
    background-color: #f5f7fa !important;
    color: #606266;
    font-weight: 600;
  }

  .el-button--primary.is-link { color: #409eff; }
  .el-button--danger.is-link  { color: #f56c6c; }
}
</style>
```

#### 8d. Key Rules Summary

| Rule | Do | Don't |
|------|----|----- |
| Page wrapper | `system-page config-page` (standalone) or `app-container tree-sidebar-manage-wrap` (sidebar) | `app-container` alone |
| Card | `el-card class="page-card"` wraps table+search+pagination | Table outside card |
| Header | `card-header` > `header-left` (icon+title) + `search-right` (buttons) | Buttons in a separate toolbar row |
| Search | `<div class="search-bar">` with `#f8faff` bg | Plain el-form without wrapper |
| Icons | `<el-icon><Search /></el-icon>` component syntax | `icon="Search"` attribute syntax |
| Table header | `#f5f7fa` (light gray) background, `#606266` text | `#d4e7fd` (blue) background |
| Pagination | `<el-pagination>` inside `<div class="pagination">` | Custom `<pagination>` component |
| Dialog footer | `<el-button @click="cancel">取消</el-button>` + `<el-button type="primary" @click="submitForm">确定</el-button>` directly | Wrapped in extra `div.dialog-footer` |
| Input size | Default Element Plus height | Compact `26px` override |
| Select width | Explicit `style="width: 120px"` (or appropriate) on each `<el-select>` | Default or `style="width:100%"` |
| Page size | `:page-sizes="[10, 20, 50, 100]"`, default `pageSize: 10` | Other page size arrays |

#### 8e. Other Frontend Conventions

- **API files**: `gw-ui/src/api/` — separate files per module (e.g., `slaj/eng.js`, `system/attOrgWsub.js`)
- **OrgSelect component**: `@/components/OrgSelect/` — supports `scope` (all/water/uwat) and `showScope` props
- **Backend does data assembly**: JOIN queries return merged VOs; frontend only displays, no multiple API calls
- **Icon imports**: Always import used icons explicitly from `@element-plus/icons-vue`

### 9. Frontend Router Convention
- Routes defined in `gw-ui/src/router/index.js`
- URL pattern: `/system/{entity}/index` for list pages
- Parameterized routes: `/system/projbase-eng/index/:projGuid`

### 10. Key Backend Packages
| Package | Module | Contents |
|---------|--------|----------|
| `com.goldenwater.slaj.hidd` | gw-slaj | Core business mappers/domain/controllers |
| `com.goldenwater.system` | gw-system | Sys dept, shared mappers, common services |
| `com.goldenwater.web` | gw-admin | Composite services, system controllers |
| `com.goldenwater.common.core.domain` | gw-common | Shared entities and VOs |
| `com.goldenwater.common.core.domain.obj` | gw-common | Redundant OBJ_* entities |
| `com.goldenwater.common.core.domain.entity` | gw-common | Entity classes (RelProjOrg, SysDept, etc.) |

### 11. Import Path Aliases (Frontend)
- `@/` → `gw-ui/src/`

## Common Pitfalls

1. **VO in wrong module**: VOs used by gw-system mappers must be in gw-common, not gw-admin
2. **Premature UUID**: Don't set UUID before `insertDept()` — it will be overwritten
3. **OBJ_TEND has no proj_guid**: Filter by project via JOIN `att_eng_base` on `eng_guid`
4. **Status default**: New orgs should have status `"0"` (enabled), not `"1"` (disabled)
5. **Parent dept null check**: Always validate parent dept exists before insert, or throw clear error