亮乡源·大众版 (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

开发命令

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

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 单行注释标注含义，尤其是枚举类型字段需注明可选值：

/** 状态: 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 来请求文档.

CLAUDE.md 4.2 KB Cronologia Originale