# 迁移指南 - kylx365server → miaoguo_system_server

## 核心转换规则

### 1. 模块系统
```js
// 旧: CommonJS
const xxx = require('xxx');
exports.Fn = function* () { ... };

// 新: ESM
import xxx from 'xxx.js';
export async function Fn(ctx) { ... }
```

### 2. Koa generator → async/await
```js
// 旧: Koa v1 generator
exports.GetXxx = function* () {
    var param = this.query;
    var result = yield mysql.queryAsync(sql);
    this.body = result;
};

// 新: Koa v2+ async/await
export async function GetXxx(ctx) {
    const param = ctx.query;
    const result = await query(sql, params);
    ctx.body = result;
}
```

### 3. 数据库
```js
// 旧: mysql + bluebird, 字符串拼接
var sql = "SELECT * FROM Users WHERE UserID=" + obj.UserID;
return mysql.queryAsync(sql);

// 新: mysql2/promise, 参数化查询
import { query } from '../../util/db.js';
const sql = "SELECT * FROM Users WHERE UserID=?";
return await query(sql, [obj.UserID]);
```

### 4. HTTP 请求
```js
// 旧: request-promise
var rp = require('request-promise');
var result = yield rp(url).then(...);

// 新: axios
import axios from 'axios';
const result = await axios.get(url).then(res => res.data);
```

### 5. 路由
```js
// 旧: 单文件 routes.js, koa-router v5
var Router = require("koa-router")();
Router.get('/api/Xxx', controller.Xxx);
module.exports = function(app) { app.use(Router.routes()); };

// 新: 模块化 routes.js, @koa/router v13
import Router from '@koa/router';
import * as controller from './controller.js';
const router = new Router();
router.get('/api/Xxx', controller.Xxx);
export default router;
```

### 6. ctx 参数映射
```
this.query           → ctx.query
this.request.body    → ctx.request.body / ctx.request (POST body)
this.params          → ctx.params
this.body            → ctx.body
this.status          → ctx.status
this.throw(status)   → ctx.throw(status)
```

### 7. 常用依赖替换
```
koa-router (v5)       → @koa/router (v13)
koa-multer            → @koa/multer
koa-bodyparser        → koa-bodyparser (已有)
request-promise       → axios
moment                → moment (保留)
lodash                → lodash (保留)
cos-nodejs-sdk-v5     → cos-nodejs-sdk-v5 (保留)
bluebird              → 删除 (mysql2 内置 Promise)
```

### 8. 错误处理
```js
// 旧
try { ... } catch(err) { console.log(err); }

// 新
try { ... } catch(err) { console.error('描述:', err); ctx.throw(500, err.message); }
```

## 文件放置规则
- Controller: `src/api/<module>/<module>Controller.js`
- Routes: `src/api/<module>/routes.js`
- Model: `src/model/<module>.js`
- 注册路由: 在 `src/app.js` 中 import 并 use

## 注意事项
1. 所有 SQL 必须参数化（? 占位符），禁止字符串拼接
2. `global.config` 改为 `import config from '../../config/index.js'`
3. `BufferMemory` 改为 `import { globalCache } from '../../util/GlobalCache.js'`
4. 保留原有注释和业务逻辑不变
5. `WXBizDataCrypt` 已存在于 `src/util/WXBizDataCrypt.js`
6. `crypto` 工具已存在于 `src/util/crypto/index.js`
7. `stringUtils` 已存在于 `src/util/stringClass.js`