# 技术设计: <功能名称>

> 输入: 需求分析报告 (analysis.md)
> 设计日期: <日期>

---

## 1. 数据库设计

### 1.1 表结构

#### 表: <table_name>

```sql
CREATE TABLE <table_name> (
    id              NUMBER(19)      NOT NULL,
    -- 业务字段
    <column>        <type>          <constraint>,
    -- 审计字段
    created_by      VARCHAR2(64),
    created_date    DATE            DEFAULT SYSDATE,
    last_updated_by VARCHAR2(64),
    last_updated_date DATE          DEFAULT SYSDATE,
    CONSTRAINT pk_<table_name> PRIMARY KEY (id)
);

COMMENT ON TABLE <table_name> IS '<表中文名>';
COMMENT ON COLUMN <table_name>.id IS '主键';
-- 其他字段注释
```

**索引**:

| 索引名 | 字段 | 类型 | 说明 |
|--------|------|------|------|
| | | UNIQUE / NORMAL | |

**数据库操作方式**:
- [ ] 优先使用 dbx MCP 工具建表
- [ ] 备选: 执行 SQL 脚本

---

## 2. API 接口设计

### 2.1 接口清单

| # | Method | Path | 描述 | 请求体 | 响应体 |
|:-:|--------|------|------|--------|--------|
| 1 | POST | `/{entity}/search` | 分页查询 | PageForm<Entity> | Page<Entity> |
| 2 | POST | `/{entity}/add` | 新增 | Entity | — |
| 3 | PUT | `/{entity}/update` | 修改 | Entity | — |
| 4 | DELETE | `/{entity}/delete` | 批量删除 | Long[] ids | — |
| 5 | POST | `/{entity}/export` | 导出 Excel | Entity | file |
| 6 | POST | `/{entity}/uploadExcel` | 导入 Excel | file | — |

### 2.2 接口详情

#### API-1: 分页查询

- **路径**: `POST /{entity}/search`
- **描述**: 分页查询<实体>列表
- **请求体**:
```json
{
    "size": 20,
    "current": 1,
    "condition": {
        "<field1>": "<value>"
    }
}
```
- **响应体**:
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "records": [...],
        "total": 100,
        "size": 20,
        "current": 1
    }
}
```

<!-- 按需补充其他接口详情 -->

---

## 3. 后端代码结构

### 3.1 Entity

**路径**: `modules-center/{module}-center/{module}-service/src/main/java/com/twsz/mom/{module}/{sub}/model/{Entity}.java`

```java
@Data
@EqualsAndHashCode(callSuper = false)
@JsonInclude(JsonInclude.Include.NON_NULL)
@TableName("<table_name>")
public class {Entity} extends BaseModel implements Serializable {

    private static final long serialVersionUID = 1L;

    @TableId(type = IdType.ASSIGN_ID)
    @JsonSerialize(using = ToStringSerializer.class)
    private Long id;

    // 业务字段（含 @ExcelProperty 注解）
}
```

### 3.2 Mapper

**接口路径**: `.../{module}/mapper/{Entity}Mapper.java`
**XML 路径**: `resources/mapper/{module}/{Entity}Mapper.xml`

```java
@Mapper
public interface {Entity}Mapper extends BaseMapper<{Entity}> {
    IPage<{Entity}> pageSearch(Page<{Entity}> p, @Param("entity") {Entity} entity);
    List<{Entity}> list(@Param("entity") {Entity} entity);
}
```

**XML 关键片段**:
- `<sql id="Columns">` — 字段列表
- `<sql id="Where">` — 查询条件
- `pageSearch` — 分页查询
- `list` — 不分页列表

### 3.3 Service

**接口路径**: `.../{module}/service/{Entity}Service.java`

```java
public interface {Entity}Service extends IService<{Entity}> {
    ResponseWrapper<?> insert({Entity} entity);
    ResponseWrapper<String> update({Entity} entity);
    ResponseWrapper<String> deleteByIds(Collection<BigDecimal> ids);
    ResponseWrapper<Page<{Entity}>> search(PageForm<{Entity}> pageForm);
    List<{Entity}> list({Entity} entity);
}
```

### 3.4 ServiceImpl

**路径**: `.../{module}/service/impl/{Entity}ServiceImpl.java`

关键逻辑:
- `insert()`: 校验唯一性等
- `update()`: 校验存在性 + 唯一性
- `deleteByIds()`: 批量删除
- `search()`: 分页查询

### 3.5 Controller

**路径**: `.../{module}/controller/{Entity}Controller.java`

```java
@RestController
@RequestMapping("/api/{api-path}/{entity}")
public class {Entity}Controller {

    @PostMapping("/search")
    public ResponseWrapper<Page<{Entity}>> search(@RequestBody PageForm<{Entity}> pageForm) { ... }

    @PostMapping("/add")
    public ResponseWrapper<?> add(@RequestBody {Entity} entity) { ... }

    @PutMapping("/update")
    public ResponseWrapper<String> update(@RequestBody {Entity} entity) { ... }

    @DeleteMapping("/delete")
    public ResponseWrapper<String> delete(@RequestBody Collection<BigDecimal> ids) { ... }

    @PostMapping("/export")
    public void export(@RequestBody {Entity} entity, HttpServletResponse response) { ... }

    @PostMapping("/uploadExcel")
    public ResponseWrapper<?> uploadExcel(@RequestParam("file") MultipartFile file) { ... }
}
```

---

## 4. 前端代码结构

### 4.1 API 文件

**路径**: `src/api/{domain}/{entity}.js`

```javascript
import axios from '@/libs/request'
import { exportExcel } from '../file'
const root = '/mm/api'  // 根据实际微服务调整

// search, add, update, delete, export, uploadExcel
```

### 4.2 列表页

**路径**: `src/views/{domain}/{entity}/index.vue`

- 组件: `search-table` + `indexPage` mixin
- 搜索条件: <列出搜索字段>
- 表格列: <列出列定义>
- 工具栏: 新增 / 编辑 / 查看 / 删除 / 导出 / 导入

### 4.3 表单页

**路径**: `src/views/{domain}/{entity}/{entity}-form.vue`

- 组件: `master-sub`
- 表单字段: <列出字段及校验规则>
- 提交逻辑: 判断新增/编辑 → 调用对应 API

---

## 5. 业务逻辑流程

### 5.1 核心流程

```
<ASCII 流程图>
```

### 5.2 校验规则

| 编号 | 校验项 | 规则 | 错误提示 |
|:----:|--------|------|----------|
| V-01 | | | |

### 5.3 状态流转（如有）

```
<状态机图>
```

---

## 6. 集成点

### 6.1 被调用方

| 调用方 | 接口方式 | 说明 |
|--------|----------|------|
| | | |

### 6.2 菜单权限

| 菜单名 | 权限标识 | 类型 |
|--------|----------|------|
| | | 路由 / 按钮 / API |

---

## 7. 设计决策记录

| 决策 | 选项 | 结论 | 原因 |
|------|------|------|------|
| | | | |