# guide-svn **Repository Path**: wanghan9620/guide-svn ## Basic Information - **Project Name**: guide-svn - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-30 - **Last Updated**: 2026-11-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # guide-svn · 骑点 Guide 后端 「骑点 Guide」的服务端,Java 单体应用,同时为微信小程序和运营后台提供接口。 > ⚠️ **本地开发前必读**:项目依赖一个独立的逆地址解析服务 **geotoolcn**(默认 `http://127.0.0.1:28080`)。 > 该服务需**单独启动**,不由本项目拉起。未启动时接口会自动降级到天地图 / bigdatacloud,速度慢且依赖外网与配额。 > 启动方式见「快速开始」第 2 步。 ## 技术栈 Java 8 · Spring Boot 2.5.6 · MyBatis-Plus · Redis · MySQL · Quartz · Maven 多模块 ## 两个入口,一套业务代码 | starter | 端口 | context-path | 服务对象 | 线上地址 | | --- | --- | --- | --- | --- | | `aidex-admin-starter` | 8080 | `/admin-api` | 运营后台 `guide-admin-web` | `https://adminprod.motomao.com/admin-api` | | `aidex-front-starter` | 8081 | `/front-api` | 微信小程序 `qimiao_guide` | `https://mtmapp.motomao.com/front-api/` | 两个 starter 复用同一批 `aidex-framework` / `aidex-system` 模块,只是装配的 controller 不同。 ## 模块 | 模块 | 职责 | | --- | --- | | `aidex-common` | `ResponseUtil` 响应契约、AES 加解密、`BaseController`、通用域对象 | | `aidex-framework` | Security / JWT、`@LoginUser` 解析器、拦截器、Redis、MyBatis 配置、对象存储 | | `aidex-system` | domain / mapper / service,按域分包:`club`(社区:话题、活动、打卡、评价、标签)、`yh`(驿站商家,`sj_*` 表) | | `aidex-controller` | 后台接口 `web/controller/{club,system,monitor,tool}` | | `aidex-front-controller` | 小程序接口 `front/controller/web` | | `aidex-quartz` / `aidex-generator` | 定时任务 / 代码生成 | | `aidex-ui` | 上游自带模板,**本项目不使用**(运营后台在 `guide-admin-web` 仓库) | ## 响应契约 所有对外接口返回 `ResponseUtil` 结构 `{ errno, errmsg, data|datas }`: - 小程序接口用 `ResponseUtil.ok(data)` → 数据 **AES 加密**后放在 `datas` 字段,前端解密后使用 - 后台接口用 `ResponseUtil.ok_admin(data)` → 明文 `data`,不做加密 两端必须配套发布,只改一端会导致数据取不到。 ## 快速开始 ### 1. 构建(必须 JDK 8) Lombok 在 JDK 16+ 下会编译失败,先切 JDK: ```bash export JAVA_HOME=$(/usr/libexec/java_home -v 1.8.0_202) cd aidex-sharp mvn -DskipTests package ``` 产物:`aidex-sharp/aidex-admin-starter/target/aidex-admin-starter.jar`、`aidex-sharp/aidex-front-starter/target/aidex-front-starter.jar`。 > 改了 `framework` / `system` / `controller` 等被依赖模块后,务必用 `mvn -DskipTests clean package -pl aidex-front-starter -am`。 > 增量打包可能 BUILD SUCCESS 但 fat jar 里仍是旧模块 jar。 ### 2. 启动逆地址解析服务 geotoolcn(占 28080) **必须单独启动**,否则首页城市名解析会降级到外部服务: ```bash # Docker 方式 docker run -d --name geotoolcn --restart unless-stopped -p 28080:8080 ghcr.io/justinchen13/geotoolcn # 或单文件二进制方式(macOS / Linux) # macOS Intel 用 darwin-amd64,Apple Silicon 用 darwin-arm64,Linux 用 linux-amd64 curl -sL -o /tmp/geotoolcn \ https://github.com/justinchen13/GeoToolCN/releases/download/cli-v3.1.1/geotoolcn-darwin-amd64 install -m 755 /tmp/geotoolcn ~/.local/bin/geotoolcn geotoolcn serve --addr 127.0.0.1:28080 ``` 验证: ```bash curl "http://127.0.0.1:28080/reverse?lat=30.2741&lng=120.1551" # city.name 应为「杭州市」 ``` 服务地址存在数据库 `geocode_config.geotoolcnUrl`,由运营后台「逆地址解析配置」维护,不在配置文件里。 ### 3. 启动后端 ```bash java -jar aidex-sharp/aidex-front-starter/target/aidex-front-starter.jar \ "--spring.config.additional-location=file:$(pwd)/.local/config/" \ --spring.profiles.active=druid,local ``` admin-starter 同理,只换 jar 名和端口(8080)。 ## 数据库与缓存 同一套代码连两个环境,靠**启动配置**区分: | 环境 | MySQL | Redis | | --- | --- | --- | | 线上(默认) | `mysql57:3306/aidex`;外网 `106.54.62.2:3307` | `redis:6379` | | 测试 | `1.15.104.68:3306/aidex` | `1.15.104.68:6379` | - 仓库里 `application-druid.yml` / `application.yml` 的**默认值就是线上配置**,并且会被打进 jar。**不要为本地调试直接改这两个文件**。 - 本地覆盖项写进 `.local/config/application-local.yml`(已被 `.gitignore` 覆盖),启动时用 `--spring.config.additional-location` 显式加载。 ## 开发约定 - 接口改动**三端对齐**:后端 controller/domain、小程序 `src/http/api/*.ts`、后台 `src/api/**/*.js`,字段名和枚举值完全一致。 - 分支:`master` 为默认,功能分支 `feature/<短横线主题>`。 - 提交信息:中文 + conventional 前缀(`feat:` / `fix:` / `chore:` / `docs:`)。 - 新增配置里的密钥放本地未跟踪文件或环境变量,不要提交。 ## 更多文档 - 详细开发约定、坑位与排查方法见 [`AGENTS.md`](./AGENTS.md) - 跨仓库术语以仓库群根目录 `CONTEXT.md` 为准 - 英文版 [`README.en.md`](./README.en.md)