艾灸椅管理后台系统交接验收设计文档

本文面向系统验收、运维交接和二次开发交接。内容以当前代码仓库为准，详细业务说明可结合附录中的专项文档查看。

1. 文档说明

项目	内容
系统名称	艾灸椅管理后台系统
后端工程	`code/backend`
前端工程	`code/frontend`
后端服务名	`aijiuyi-admin`
文档用途	验收交接、部署说明、后续维护参考
文档版本	v1.1
最后更新	2026-05-11

2. 项目概述

2.1 系统定位

艾灸椅管理后台系统是一套用于艾灸椅业务运营管理的 Web 后台，覆盖账号、用户档案、穴位、艾灸方案、设备、手法、用户穴位坐标、模拟测试和系统日志等管理能力。

系统通过采集用户体型数据，结合穴位定位算法 3.0，为用户生成个性化穴位坐标，并支持将用户、设备、方案和穴位数据组织为可验收、可维护的后台业务闭环。

2.2 使用角色

角色	说明
超级管理员	拥有全部后台管理权限
运营人员	负责日常数据维护、方案维护、设备与用户管理
只读用户	查看业务数据和日志，原则上不做写入操作
专家/普通用户	作为应用用户数据被后台管理，可参与方案归属和用户档案关联

3. 交付范围

3.1 本次交付内容

类型	交付物	说明
后端源码	`code/backend`	Spring Boot 后端服务，提供 REST API
前端源码	`code/frontend`	Vue 3 后台管理页面
数据库脚本	`code/backend/src/main/resources/sql`	初始化脚本、穴位导入脚本、算法迁移脚本
配置文件	`application.yml`、环境配置	服务端口、数据源、Redis、鉴权白名单等配置
业务文档	`code/*.md`	各模块设计说明、算法说明、规范说明
静态资源	`code/frontend/src/assets`	前端图片资源和页面展示素材

3.2 范围说明

本文重点说明当前仓库已实现的后台管理能力。设备固件、真实设备通信协议、外部系统联调细节，以对应交付物或联调文档为准。

4. 系统架构

4.1 总体架构

层级	组成	职责
前端层	Vue 3、Vue Router、Pinia、Element Plus、Axios、Vite	后台页面、表单交互、权限路由、接口调用
后端层	Spring Boot、Spring MVC、MyBatis Plus、Redis、AOP	业务接口、鉴权拦截、数据处理、日志审计
数据层	MySQL、Redis	业务数据存储、Token 状态管理
部署层	JDK、Maven、Node.js、Nginx	后端运行、前端构建、静态资源和接口代理

4.2 业务架构图

4.3 技术栈

分类	技术
后端	JDK 1.8、Spring Boot 2.7.18、MyBatis Plus 3.5.3.1、JWT、FastJSON、Lombok
前端	Vue 3.5、Vue Router 4.6、Pinia 3.0、Element Plus 2.13、Axios 1.14、Vite 8
数据库	MySQL 8.0+
缓存	Redis 6.0+
构建工具	Maven 3.6+、Node.js 20+、npm

4.4 项目结构摘要

code/
├── backend/                       后端工程
│   ├── src/main/java/com/aijiuyi/admin
│   │   ├── common/                通用配置、鉴权、异常、日志、工具
│   │   ├── controller/            REST 接口控制器
│   │   ├── service/               业务服务接口与实现
│   │   ├── mapper/                MyBatis 数据访问层
│   │   ├── entity/                数据实体
│   │   └── controller/dto/        请求和响应 DTO
│   ├── src/main/resources
│   │   ├── mapper/                MyBatis XML
│   │   ├── sql/                   初始化与迁移 SQL
│   │   └── application*.yml       环境配置
│   └── pom.xml
│
├── frontend/                      前端工程
│   ├── src/api/                   接口封装
│   ├── src/views/                 业务页面
│   ├── src/router/                路由与登录守卫
│   ├── src/store/                 用户状态
│   ├── src/utils/                 请求、存储、Excel 工具
│   └── package.json
│
└── *.md                           模块说明文档

5. 功能模块验收清单

模块	已实现能力	验收关注点
认证登录	登录、退出、当前用户信息、Token 校验	正确登录；退出后 Token 失效；未登录访问受限页面跳转登录
账号管理	应用用户列表、详情、新增、编辑、删除、启停	管理员、专家、普通用户数据可维护；禁用账号不可正常使用
管理员管理	管理员维护、角色维护、路由权限配置	超级管理员、运营人员、只读用户权限区分明确
用户档案	子用户档案维护、批量导入、用户选项	肩宽、脊柱长度、身高、体重、指寸等数据校验正常
穴位管理	穴位列表、详情、新增、编辑、删除、导入、导出	穴位名称、经络、定位描述、解析状态、坐标参数可维护
用户穴位	根据用户档案生成个性化穴位坐标、查询坐标	输入体型数据后可生成 X/Y/Z 坐标和置信度
方案管理	方案维护、步骤维护、发布、下架、批量操作	方案步骤可关联穴位和手法；发布/下架状态流转正确
用户方案	用户方案分页、详情查询	能查看用户关联方案及方案明细
设备管理	设备维护、批量导入、绑定用户、解绑用户、主用户设置	设备编号唯一；设备与用户绑定关系正确
用户设备	从用户维度查看和维护设备绑定关系	绑定、解绑、主设备状态展示一致
艾灸手法	手法维护、启停、温度/时间/运动参数管理	手法参数可被方案步骤引用
模拟测试	按用户和方案组装模拟推送数据	能验证方案、穴位坐标、温度、时长、手法等输出数据
系统日志	操作日志分页、导出、用户筛选	关键接口写操作可追踪操作人、时间、模块、请求结果

6. 核心业务流程

6.1 登录与权限流程

用户提交用户名和密码。
后端校验账号状态和密码，生成 JWT Token。
Token 写入 Redis，前端保存 Token 并进入后台。
前端路由守卫检查登录态；后端拦截器校验 Token 和白名单。
退出登录时，后端删除 Redis 中的 Token，使当前登录态失效。

6.2 用户穴位生成流程

维护应用用户和子用户档案。
子用户档案录入肩宽、脊柱长度、身高、体重、指寸等体型数据。
后端根据穴位基础表和算法 3.0 计算用户个性化穴位坐标。
坐标结果写入 user_acupoint，包含 X/Y/Z 坐标、侧别、置信度。
方案模拟测试或后续设备联调可读取用户穴位坐标。

6.3 方案维护流程

创建方案基础信息，设置模式、功效、适用人群和描述。
为方案添加步骤，步骤关联穴位、侧别、温度、时长和艾灸手法。
草稿方案确认无误后发布。
已发布方案可用于用户方案查询和模拟测试。
不再使用的方案可下架，保留历史数据兼容性。

6.4 设备与用户绑定流程

录入或导入艾灸椅设备。
在设备详情中绑定一个或多个子用户。
可设置其中一个子用户为主用户。
支持单个解绑、批量解绑，并保持绑定关系状态可追踪。

7. 数据设计与初始化

7.1 核心数据表清单

表名	作用	关键数据
`app_user`	应用用户与后台账号	用户名、手机号、密码、用户类型、管理员角色、状态
`admin_permission`	管理员路由权限	管理员 ID、可访问路由 JSON
`user_profile`	子用户档案	姓名、性别、年龄、肩宽、脊柱长度、身高、体重、指寸
`acupoint`	穴位基础数据	穴位编码、名称、经络、定位描述、偏移量、归一化 Y 系数
`user_acupoint`	用户个性化穴位坐标	用户 ID、穴位 ID、侧别、X/Y/Z 坐标、置信度
`plan`	艾灸方案主表	方案编码、名称、模式、功效、适用人群、状态
`plan_step`	方案步骤	方案 ID、穴位、侧别、温度、时长、手法
`moxibustion_technique`	艾灸手法	手法编码、运动模式、温度范围、时间范围、运动参数
`device`	艾灸椅设备	设备编号、型号、序列号、固件版本、在线状态
`user_device`	用户设备绑定关系	用户 ID、设备编码、绑定状态、主设备标记
`user_plan`	用户方案	用户 ID、方案 ID、步骤 JSON、使用次数
`sys_log`	系统操作日志	操作人、接口、参数、结果、模块、请求 ID

7.2 数据表结构明细

7.2.1 `sys_log` 系统操作日志表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`user_id`	BIGINT	-	idx_user_id	请求用户 ID
`user_name`	VARCHAR(100)	-	-	请求用户名
`user_type`	TINYINT	-	-	操作者类型：1=普通用户，2=专家，3=管理员
`request_url`	VARCHAR(500)	-	-	请求接口路径
`request_params`	TEXT	-	-	请求参数，JSON 格式
`request_result`	TEXT	-	-	请求结果，JSON 格式，超长时截断
`api_desc`	VARCHAR(200)	-	-	接口说明，来自 `@Log` 注解
`operation_type`	VARCHAR(20)	-	-	操作方式：查询、新增、更新、删除、其他
`request_ip`	VARCHAR(50)	-	-	请求客户端 IP
`operation_module`	VARCHAR(100)	-	-	操作模块，来自 `@Log` 注解
`request_id`	VARCHAR(50)	-	idx_request_id	请求唯一 ID
`create_time`	DATETIME	-	idx_create_time	创建时间

7.2.2 `app_user` 应用用户表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`phone`	VARCHAR(20)	-	UNIQUE `uk_phone`	手机号，用于登录
`username`	VARCHAR(64)	-	UNIQUE `uk_username`	用户名，管理员登录用
`password`	VARCHAR(64)	-	-	密码，MD5 加密，管理员用
`nickname`	VARCHAR(100)	-	-	昵称
`avatar`	VARCHAR(500)	-	-	头像 URL
`user_type`	TINYINT	NOT NULL, DEFAULT 1	-	用户类型：1=普通用户，2=专家，3=管理员
`status`	TINYINT	NOT NULL, DEFAULT 1	-	状态：1=正常，0=禁用
`deleted`	TINYINT	NOT NULL, DEFAULT 0	-	逻辑删除：0=未删除，1=已删除
`create_time`	DATETIME	-	-	创建时间
`update_time`	DATETIME	-	-	更新时间
`admin_role`	TINYINT	DEFAULT NULL	-	管理员角色：1=超级管理员，2=运营人员，3=只读用户
`last_login_time`	DATETIME	DEFAULT NULL	-	最后登录时间

7.2.3 `admin_permission` 管理员权限配置表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`admin_id`	BIGINT	NOT NULL	UNIQUE `uk_admin_id`	管理员 ID，关联 `app_user.id`
`route_paths`	TEXT	-	-	可访问路由路径，JSON 数组
`deleted`	TINYINT	NOT NULL, DEFAULT 0	-	逻辑删除：0=未删除，1=已删除
`create_time`	DATETIME	-	-	创建时间
`update_time`	DATETIME	-	-	更新时间

7.2.4 `user_profile` 子用户信息表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`user_id`	BIGINT	-	idx_user_id	所属应用用户 ID，关联 `app_user.id`
`name`	VARCHAR(50)	NOT NULL	-	姓名
`gender`	TINYINT	-	-	性别：1=男，2=女
`age`	INT	-	-	年龄
`phone`	VARCHAR(20)	-	idx_phone	手机号
`shoulder_width`	DECIMAL(5,1)	-	-	肩宽，单位 cm
`body_height`	DECIMAL(5,1)	-	-	身长/坐高，单位 cm
`spine_length`	DECIMAL(5,1)	-	-	脊柱长度 C7-S4，单位 cm，建议范围 30-60
`height`	DECIMAL(5,1)	-	-	身高，单位 cm
`weight`	DECIMAL(5,1)	-	-	体重，单位 kg
`finger_width_1`	DECIMAL(4,2)	-	-	1 寸指宽，单位 cm
`finger_width_15`	DECIMAL(4,2)	-	-	1.5 寸指宽，单位 cm
`finger_width_3`	DECIMAL(4,2)	-	-	3 寸指宽，单位 cm
`acupoint_table_id`	BIGINT	-	-	用户穴位表 ID
`deleted`	TINYINT	NOT NULL, DEFAULT 0	-	逻辑删除：0=未删除，1=已删除
`create_time`	DATETIME	-	-	创建时间
`update_time`	DATETIME	-	-	更新时间

7.2.5 `device` 艾灸椅设备表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`device_code`	VARCHAR(50)	NOT NULL	UNIQUE `uk_device_code`	设备编号
`device_name`	VARCHAR(100)	NOT NULL	-	设备名称
`device_model`	VARCHAR(50)	-	-	设备型号
`serial_no`	VARCHAR(50)	-	UNIQUE `uk_serial_no`	设备序列号
`firmware_version`	VARCHAR(20)	-	-	固件版本
`online_status`	TINYINT	NOT NULL, DEFAULT 0	-	在线状态：1=在线，0=离线
`last_online_time`	DATETIME	-	-	最后在线时间
`remark`	VARCHAR(200)	-	-	备注
`deleted`	TINYINT	NOT NULL, DEFAULT 0	-	逻辑删除：0=未删除，1=已删除
`create_time`	DATETIME	-	-	创建时间
`update_time`	DATETIME	-	-	更新时间

7.2.6 `user_device` 用户设备绑定表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`user_id`	BIGINT	NOT NULL	idx_user_id	所属子用户 ID，关联 `user_profile.id`
`device_code`	VARCHAR(100)	NOT NULL	idx_device_code	设备唯一编码
`device_name`	VARCHAR(100)	-	-	设备名称
`device_model`	VARCHAR(100)	-	-	设备型号
`is_primary`	TINYINT	NOT NULL, DEFAULT 0	-	是否主设备：1=是，0=否
`online_status`	TINYINT	NOT NULL, DEFAULT 0	-	在线状态：1=在线，0=离线
`status`	TINYINT	NOT NULL, DEFAULT 1	-	绑定状态：1=已绑定，0=已解绑
`bind_time`	DATETIME	-	-	绑定时间
`deleted`	TINYINT	NOT NULL, DEFAULT 0	-	逻辑删除：0=未删除，1=已删除
`create_time`	DATETIME	-	-	创建时间
`update_time`	DATETIME	-	-	更新时间

7.2.7 `acupoint` 穴位信息表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`acupoint_code`	VARCHAR(100)	NOT NULL	UNIQUE `uk_acupoint_code`	穴位编码，唯一标识
`excel_serial_no`	VARCHAR(20)	-	-	Excel 原始序号
`name`	VARCHAR(50)	NOT NULL	-	穴位名称
`single_double`	VARCHAR(20)	-	-	单/双穴，Excel 原始字段
`meridian`	VARCHAR(100)	-	-	所属经络
`body_part`	VARCHAR(50)	-	-	身体部位，Excel 原始字段
`body_region`	VARCHAR(50)	-	-	部位分区，Excel 原始字段
`location_description`	VARCHAR(500)	-	-	穴位定位原文
`relative_position`	VARCHAR(200)	-	-	相对位置原文
`indications`	VARCHAR(1000)	-	-	主管疾病/主治
`product_symptoms`	VARCHAR(500)	-	-	产品症状覆盖
`acupoint_method`	VARCHAR(500)	-	-	取穴说明
`product_acupoint`	TINYINT	NOT NULL, DEFAULT 0	-	是否艾灸椅产品穴位：1=是，0=否
`effects`	VARCHAR(500)	-	-	功效描述，逗号分隔
`location_type`	TINYINT	-	-	定位方式，当前固定为 1=相对定位
`longitude_offset`	DECIMAL(6,2)	-	-	相对大椎穴纵向偏移，单位寸
`lateral_offset`	DECIMAL(6,2)	-	-	相对大椎穴横向偏移，单位寸
`normalized_y`	DECIMAL(6,4)	-	-	Panjabi 归一化 Y 位置系数，范围 0-1
`y_reference_term`	VARCHAR(100)	-	-	Y 轴医学定位术语
`parse_status`	VARCHAR(20)	-	-	定位描述解析状态：已解析、待复核、暂不支持
`parse_confidence`	VARCHAR(10)	-	-	定位描述解析置信度：高、中、低
`parse_message`	VARCHAR(500)	-	-	定位描述解析说明
`side`	TINYINT	-	-	侧别：1=中心，2=左侧，3=右侧，4=双侧
`finger_width_type`	TINYINT	-	-	指寸类型：1=一寸，2=1.5寸，3=三寸
`gender`	TINYINT	NOT NULL, DEFAULT 0	-	适用性别：0=不限，1=仅男，2=仅女
`status`	TINYINT	NOT NULL, DEFAULT 1	-	状态：1=活跃，0=待完善
`deleted`	TINYINT	NOT NULL, DEFAULT 0	-	逻辑删除：0=未删除，1=已删除
`create_time`	DATETIME	-	-	创建时间
`update_time`	DATETIME	-	-	更新时间

7.2.8 `user_acupoint` 用户穴位坐标表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`user_id`	BIGINT	NOT NULL	idx_user_id	子用户 ID，关联 `user_profile.id`
`acupoint_id`	BIGINT	NOT NULL	idx_acupoint_id	穴位 ID，关联 `acupoint.id`
`acupoint_name`	VARCHAR(50)	NOT NULL	-	穴位名称，冗余存储
`acupoint_side`	VARCHAR(10)	NOT NULL, DEFAULT `center`	-	侧别：center=中心，left=左侧，right=右侧
`cun_value`	DECIMAL(6,2)	-	-	相对大椎穴纵向偏移，单位寸
`cun_type`	VARCHAR(10)	-	-	指寸类型：1寸、1.5寸、3寸
`coordinate_x`	DECIMAL(8,2)	-	-	X 坐标，单位 mm，向右为正
`coordinate_y`	DECIMAL(8,2)	-	-	Y 坐标，单位 mm，向下为正
`coordinate_z`	DECIMAL(8,2)	-	-	Z 坐标，单位 mm，体表为 0
`confidence`	VARCHAR(10)	-	-	置信度：high=高，medium=中，low=低
`create_time`	DATETIME	-	-	首次生成时间
`update_time`	DATETIME	-	-	最后更新时间

7.2.9 `moxibustion_technique` 艾灸手法表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`technique_code`	VARCHAR(50)	NOT NULL	UNIQUE `uk_technique_code`	手法编码，唯一标识
`name`	VARCHAR(50)	NOT NULL	-	手法名称
`motion_mode`	VARCHAR(20)	NOT NULL	-	运动模式：default、fixed、updown、circular、dotted
`temp_min`	DECIMAL(4,1)	NOT NULL	-	温度范围最小值，单位摄氏度
`temp_max`	DECIMAL(4,1)	NOT NULL	-	温度范围最大值，单位摄氏度
`time_min`	INT	NOT NULL	-	时间范围最小值，单位分钟
`time_max`	INT	NOT NULL	-	时间范围最大值，单位分钟
`motion_amplitude`	DECIMAL(4,1)	-	-	运动幅度，单位 mm
`motion_speed`	DECIMAL(4,1)	-	-	运动速度，单位 mm/s
`status`	TINYINT	NOT NULL, DEFAULT 1	-	状态：1=启用，0=禁用
`remark`	VARCHAR(200)	-	-	备注
`deleted`	TINYINT	NOT NULL, DEFAULT 0	-	逻辑删除：0=未删除，1=已删除
`create_time`	DATETIME	-	-	创建时间
`update_time`	DATETIME	-	-	更新时间

7.2.10 `plan` 方案表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`plan_code`	VARCHAR(50)	NOT NULL	UNIQUE `uk_plan_code`	方案编码
`name`	VARCHAR(100)	NOT NULL	-	方案名称
`mode_type`	TINYINT	NOT NULL	-	模式类型：1=一键艾灸，2=专业模式，3=自定义模式，4=延年圣手
`effect_type`	VARCHAR(20)	-	-	功效类型：驱寒、祛湿、祛风、化瘀、活血、化痰、养颜、扶阳
`symptoms`	VARCHAR(500)	-	-	适用症状，逗号分隔
`applicable_gender`	TINYINT	NOT NULL, DEFAULT 0	-	适用人群：0=不限，1=仅男，2=仅女
`age_min`	INT	NOT NULL, DEFAULT 1	-	适用年龄最小值
`age_max`	INT	NOT NULL, DEFAULT 120	-	适用年龄最大值
`description`	VARCHAR(200)	-	-	方案描述
`author_type`	TINYINT	NOT NULL, DEFAULT 1	-	创作人类型：1=管理员，2=普通用户，3=专家
`author_id`	BIGINT	-	-	创作人 ID，关联 `app_user.id`
`author_name`	VARCHAR(100)	-	-	创作人名称，冗余存储
`status`	TINYINT	NOT NULL, DEFAULT 0	-	状态：0=草稿，1=已发布，2=已下架
`use_count`	INT	NOT NULL, DEFAULT 0	-	使用人数
`avg_rating`	DECIMAL(3,1)	-	-	平均评分
`last_use_time`	DATETIME	-	-	最后使用时间
`deleted`	TINYINT	NOT NULL, DEFAULT 0	-	逻辑删除：0=未删除，1=已删除
`create_time`	DATETIME	-	-	创建时间
`update_time`	DATETIME	-	-	更新时间

7.2.11 `plan_step` 方案步骤表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`plan_id`	BIGINT	NOT NULL	idx_plan_id	方案 ID，关联 `plan.id`
`step_order`	INT	NOT NULL	-	步骤序号，从 1 开始
`acupoint_id`	BIGINT	-	-	穴位 ID，关联 `acupoint.id`
`acupoint_name`	VARCHAR(50)	NOT NULL	-	穴位名称，冗余存储
`side`	TINYINT	NOT NULL	-	侧别：1=中心，2=左侧，3=右侧，4=双侧
`temperature`	DECIMAL(4,1)	NOT NULL	-	温度，单位摄氏度，建议范围 35-50
`duration`	INT	NOT NULL	-	时间，单位分钟，建议范围 1-30
`technique_id`	BIGINT	-	-	艾灸手法 ID，关联 `moxibustion_technique.id`
`technique_name`	VARCHAR(50)	-	-	艾灸手法名称，冗余存储
`remark`	VARCHAR(100)	-	-	备注
`deleted`	TINYINT	NOT NULL, DEFAULT 0	-	逻辑删除：0=未删除，1=已删除
`create_time`	DATETIME	-	-	创建时间
`update_time`	DATETIME	-	-	更新时间

7.2.12 `user_plan` 用户方案表

字段	类型	约束/默认值	索引	备注
`id`	BIGINT	NOT NULL, AUTO_INCREMENT	PRIMARY KEY	主键 ID
`user_id`	BIGINT	NOT NULL	idx_user_id	子用户 ID，关联 `user_profile.id`
`plan_id`	BIGINT	NOT NULL	idx_plan_id	方案 ID，关联 `plan.id`
`plan_code`	VARCHAR(50)	NOT NULL	-	方案编码，冗余存储
`plan_name`	VARCHAR(100)	NOT NULL	-	方案名称，冗余存储
`mode_type`	TINYINT	NOT NULL	-	模式类型：1=一键艾灸，2=专业模式，3=自定义模式，4=延年圣手
`author_name`	VARCHAR(100)	-	-	创作人名称，冗余存储
`step_count`	INT	NOT NULL, DEFAULT 0	-	步骤数量
`use_count`	INT	NOT NULL, DEFAULT 0	-	使用次数
`steps_json`	TEXT	-	-	个性化工艺步骤，JSON 格式，含坐标、温度、时间等
`deleted`	TINYINT	NOT NULL, DEFAULT 0	-	逻辑删除：0=未删除，1=已删除
`create_time`	DATETIME	-	-	订阅/生成时间
`update_time`	DATETIME	-	-	更新时间

7.3 数据兼容原则

业务表使用 deleted 字段进行逻辑删除，避免物理删除影响历史数据。
方案、穴位、手法、设备均使用编码或唯一编号辅助识别，便于导入和后续联调。
穴位和方案数据涉及既有业务规则，维护时应保持字段含义和历史数据兼容。
用户穴位坐标为计算结果数据，可按用户档案重新生成，但应避免无确认地覆盖生产验证数据。

7.4 初始化与迁移脚本

脚本	说明
`init.sql`	创建核心表并初始化管理员、穴位、手法、默认方案等基础数据
`acupoint_full_data_import.sql`	完整穴位数据导入脚本
`migration_acupoint_auto_parse.sql`	穴位定位解析相关字段迁移
`migration_algorithm_v3.sql`	穴位定位算法 3.0 相关字段迁移

默认初始化账号：

用户名	密码	角色
`admin`	`admin123`	超级管理员

8. 核心算法说明

8.1 算法定位

穴位定位算法 3.0 用于根据用户体型数据计算背部/颈部相关穴位的个性化坐标。该算法服务于艾灸椅定位和方案模拟，属于辅助定位能力，不替代医学诊断。

8.2 输入参数

参数	要求	用途
脊柱长度 C7-S4	必填，建议 30-60cm	计算 Y 轴位置
肩宽	必填，建议 30-50cm	推算背部横向一寸宽度
1 寸、1.5 寸、3 寸指宽	可选	提高指寸换算精度
身高、体重	条件必填	未填指寸时用于 BMI 推算

8.3 计算流程

根据实测指寸计算 A 路指寸值。
根据 BMI 计算 B 路指寸值。
融合 A/B 路结果，得到最终指寸和置信度。
结合肩宽和指寸计算背部一寸宽度。
根据 Panjabi 归一化 Y 系数计算纵向坐标。
根据经络侧线、区域系数和八髎穴规则计算横向坐标。
背部/颈部体表穴位 Z 坐标统一为 0。

8.4 输出结果

输出	说明
`coordinate_x`	横向坐标，单位 mm，右侧为正
`coordinate_y`	纵向坐标，单位 mm，自 C7 向下
`coordinate_z`	体表坐标，当前为 0
`confidence`	坐标置信度：`high`、`medium`、`low`

8.5 代码位置

内容	位置
用户穴位生成接口	`UserAcupointController`
算法主实现	`UserAcupointServiceImpl`
穴位定位解析	`AcupointLocationParser`
Y 轴参考项	`AcupointYReference`

9. 接口与页面索引

9.1 接口基础信息

后端服务配置：

配置	值
服务端口	`18888`
接口前缀	`/api`
前端请求方式	Axios 统一封装
Token 请求头	`Authorization: Bearer {token}`

9.2 主要接口模块

模块	后端路径	主要能力
认证	`/api/auth`	登录、退出、当前用户信息
账号	`/api/user/app`	应用用户列表、详情、新增、编辑、删除、启停
管理员	`/api/admin`	管理员维护、权限配置、状态管理
用户档案	`/api/user/profile`	用户档案维护、导入、选项列表
穴位	`/api/acupoint`	穴位维护、导入、导出、Y 轴参考项
用户穴位	`/api/user/acupoint`	用户穴位坐标生成与查询
方案	`/api/plan`	方案维护、发布、下架、批量操作
用户方案	`/api/user-plan`	用户方案分页和详情
设备	`/api/device`	设备维护、导入、设备绑定用户
用户设备	`/api/user/device`	用户维度设备绑定管理
艾灸手法	`/api/moxibustion-technique`	手法维护、启停、参数管理
模拟测试	`/api/simulation`	方案模拟推送数据组装
系统日志	`/api/log`	操作日志分页、导出、用户选项

9.3 前端页面路由

页面	路由	说明
登录	`/login`	后台登录页
账号管理	`/user/app`	应用用户维护
用户档案	`/user/profile`	子用户档案维护
用户方案	`/user/plan`	用户方案查看
用户设备	`/user/device`	用户设备绑定关系
穴位管理	`/acupoint`	穴位数据维护
设备管理	`/device`	设备数据维护
设备用户	`/device/users`	设备绑定用户维护
艾灸手法	`/moxibustion`	手法参数维护
方案管理	`/plan`	艾灸方案维护
模拟测试	`/simulation`	用户方案推送数据模拟
管理员	`/system/admin`	管理员和权限维护
系统日志	`/system/log`	操作日志查看

10. 安全与审计

10.1 鉴权机制

登录成功后生成 JWT Token，签名算法为 HS256。
Token 存入 Redis，用于控制登录态有效性和退出失效。
前端请求统一携带 Authorization: Bearer {token}。
后端 TokenInterceptor 校验 Token，并将用户信息写入请求上下文。
白名单接口包括登录、注册、Actuator 和接口文档相关路径。

10.2 权限控制

权限项	说明
用户类型	普通用户、专家、管理员
管理员角色	超级管理员、运营人员、只读用户
路由权限	通过 `admin_permission.route_paths` 控制可访问页面
前端守卫	未登录时跳转登录页，已登录时加载用户权限

10.3 操作审计

使用 @Log 注解标记需要记录日志的业务接口。
LogAspect 统一记录操作人、接口、参数、结果、IP、模块和请求 ID。
日志可在系统日志页面分页查看并导出。

10.4 数据安全

用户密码使用 MD5 存储。
返回前端的用户信息不应返回明文密码。
业务删除默认采用逻辑删除。
生产环境应修改 JWT 密钥、数据库密码、Redis 密码等敏感配置。

11. 部署运行说明

11.1 环境要求

组件	版本
JDK	1.8+
Maven	3.6+
MySQL	8.0+
Redis	6.0+
Node.js	20+，当前验证环境为 v22.22.2
npm	与 Node.js 版本匹配，当前验证环境为 10.9.7

11.2 后端部署

创建数据库。

CREATE DATABASE aijiuyi_admin DEFAULT CHARACTER SET utf8mb4;

执行初始化脚本。

mysql -u root -p aijiuyi_admin < code/backend/src/main/resources/sql/init.sql

按环境修改数据库和 Redis 配置。

code/backend/src/main/resources/application-dev.yml
code/backend/src/main/resources/application-prod.yml

打包并运行后端。

cd code/backend
mvn clean package -DskipTests
java -jar target/aijiuyi-admin-1.0.0.jar

11.3 前端部署

cd code/frontend
npm install
npm run build

构建产物位于 code/frontend/dist，可部署至 Nginx 等静态资源服务。

11.4 Nginx 代理示例

server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /path/to/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://localhost:18888;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

11.5 常用端口

服务	端口
MySQL	`3306`
Redis	`6379`
后端 API	`18888`
前端开发服务	`5173`

12. 验收建议

12.1 基础验收

使用初始化账号登录后台，确认菜单、路由和退出登录正常。
新增、编辑、删除一条用户档案，确认表单校验和列表刷新正常。
新增或编辑穴位、手法、设备，确认基础 CRUD 正常。
创建方案并维护方案步骤，确认发布、下架、批量操作正常。
绑定设备与用户，确认主用户设置、解绑、批量解绑正常。
查看系统日志，确认关键操作产生审计记录。

12.2 算法验收

录入包含肩宽、脊柱长度、身高、体重和指寸的用户档案。
触发用户穴位生成，确认用户穴位列表存在坐标数据。
检查生成结果包含穴位名称、侧别、X/Y/Z 坐标和置信度。
使用同一用户和方案执行模拟测试，确认输出数据包含方案步骤和穴位坐标。

12.3 部署验收

后端服务启动后可访问 /api/auth/login。
前端构建成功，部署后页面可正常刷新和路由跳转。
MySQL、Redis 连接正常。
生产环境配置与本地开发配置分离，敏感配置不提交到 Git。

13. 交接资料

文档	说明
`智能穴位定位系统设计文档.md`	穴位定位整体设计
`算法3.0.md`	算法 3.0 详细说明
`穴位管理.md`	穴位管理模块说明
`用户管理.md`	用户档案模块说明
`用户穴位管理.md`	用户穴位坐标模块说明
`方案管理和用户方案管理.md`	方案与用户方案说明
`设备管理和用户设备管理.md`	设备及绑定关系说明
`艾灸手法管理.md`	艾灸手法模块说明
`管理员管理.md`	管理员与权限说明
`日志管理.md`	操作日志说明
`规范说明.md`	开发与协作规范

文档版本：v1.1 最后更新：2026-05-11

技术文档.md 33 KB Historik Rå

艾灸椅管理后台系统 交接验收设计文档

目录