# 亮乡源·大众版 (xiangyuan-app)

乡村文化数字化保护平台，大众版小程序。支持微信小程序、H5等多端。

## 技术栈

- **框架**: Uniapp 3.0 + Vue 3 (Composition API)
- **语言**: TypeScript
- **状态管理**: Pinia 3.0
- **UI 组件库**: NaEasy UI (`src/components/`)
- **构建工具**: Vite 5
- **样式**: Sass/SCSS
- **API 请求**: `@imengyu/js-request-transform` + `@imengyu/imengyu-utils`

## 开发命令

```bash
npm run dev:h5            # H5 开发
npm run dev:mp-weixin     # 微信小程序开发
npm run build:mp-weixin   # 构建微信小程序
npm run type-check        # TypeScript 类型检查
```

## 项目结构

```
src/
├── api/              # API 请求模块，按业务域分组
│   ├── auth/         # 登录/用户认证
│   ├── agent/        # AI 智能体
│   ├── inheritor/    # 内容模型（活动、产品等）
│   ├── inhert/       # 村落与传承人
│   ├── light/        # 点亮村落、乡源树
│   ├── map/          # 地图相关
│   ├── restful/      # RESTful 通用服务
│   ├── system/       # 系统配置
│   ├── BaseAppServerRequestModule.ts  # 请求拦截器/错误处理基类
│   ├── RequestModules.ts             # 服务端请求模块
│   └── CommonContent.ts             # 通用内容基类
├── common/           # 通用功能
│   ├── components/   # 共享组件
│   ├── composeabe/   # 组合式函数 (useAppInit, useUserTools 等)
│   ├── config/       # 配置 (AppConfig, ApiConfig, Theme)
│   ├── style/        # 全局 SCSS
│   └── utils/        # 工具函数
├── components/       # NaEasy UI 组件库
├── pages/            # 页面
│   ├── home/         # 首页/村落相关
│   ├── article/      # 文章
│   ├── chat/         # AI 对话
│   ├── dig/          # 采集投稿
│   ├── editor/       # 编辑器
│   └── user/         # 用户/登录
├── store/            # Pinia 状态管理
│   ├── auth.ts       # 认证状态
│   ├── village.ts    # 村落数据
│   └── collect.ts    # 采集状态
└── pages.json        # 路由配置
```

## API 层规范

### DataModel 模式

所有 API 数据模型继承 `DataModel`，使用 `setNameMapperCase('Camel', 'Snake')` 自动转换字段命名：
- 客户端使用 **camelCase**
- 服务端使用 **snake_case**

```typescript
export class ExampleItem extends DataModel<ExampleItem> {
  constructor() {
    super(ExampleItem, '示例');
    this.setNameMapperCase('Camel', 'Snake');
    this._convertTable = {
      id: { clientSide: 'number', serverSide: 'number', clientSideRequired: true },
      // 需要类型转换的字段在此声明
    };
  }
  id!: number;
  name = '';
}
```

### API 模块模式

- API 类继承 `AppServerRequestModule`，按业务域组织
- 每个模块导出为单例：`export default new XxxApi()`
- 请求方法使用 `this.post()` / `this.get()`，第二个参数为中文标签（用于错误提示）
- 分页列表统一使用 `parsePagedList()` 辅助方法

### 请求拦截

`BaseAppServerRequestModule` 自动注入：
- `token` — 用户令牌
- `user_id` — 用户 ID
- `main_body_id` — 主体 ID

## 编码规范

### 命名

- **类/类型**: PascalCase (`VillageListItem`, `UserApi`)
- **函数/变量**: camelCase (`getVillageList`, `isLogged`)
- **文件**: API 模块 PascalCase (`TreeApi.ts`)，页面/组件 kebab-case
- **Composable**: `use` 前缀 (`useAuthStore`, `useUserTools`)

### 字段注释

API 数据模型字段使用 JSDoc 单行注释标注含义，尤其是枚举类型字段需注明可选值：
```typescript
/** 状态: 0=完善中, 1=已归档 */
status = 0;
/** 列入少数民族特色村寨试点示范: 0=否, 1=是 */
isFeaturedVillage = 0;
```

### Vue 组件

- 使用 `<script setup lang="ts">` 组合式 API
- 样式使用 `<style lang="scss" scoped>`

## API 文档

项目 API 文档托管在 ShowDoc：`https://www.showdoc.com.cn/minnanCE/`

添加新接口时应参考文档补充完整的数据模型字段和类型转换表。

**优先使用 chrome-devtools MCP 来请求文档**.