53 lines
3.4 KiB
Markdown
53 lines
3.4 KiB
Markdown
# 服务端 AGENTS.md
|
|
|
|
本目录是门户和管理后台共用的唯一业务后端。不要再为 `portal/` 或 `admin/` 各建一套 Python 工程或各接一个数据库。教育平台若最终不采用 PlayEdu，课程与进度也放在这里；若采用 PlayEdu，它自带服务，账号标识仍与本服务对齐。仓库根目录 `AGENTS.md` 同时有效。
|
|
|
|
## 职责
|
|
|
|
- REST API。没有明确调用方时不做第二套 RPC。
|
|
- 账号、角色、菜单与按钮资源、强密码、账号注销。
|
|
- 敏感字段加密存储（AES-256 或 SM4）和接口脱敏。
|
|
- 附件：公开对象与私有对象分开。私有对象用鉴权或短期链接。上传大小可配置，禁止不限制大小。
|
|
- 全量接口访问日志。不记录密码、验证码、身份证号、完整手机号。
|
|
- 管理端接口必须登录，且只接受工作人员令牌。会员数据接口只允许本人，只接受会员令牌。两种令牌不能混用。公开接口与登录接口在 `/api/site` 下分开注册。
|
|
- 业务接口只有两个前缀：门户 `/api/site`，管理后台 `/api/admin`。不允许在这两个前缀之外新增业务接口。
|
|
- JSON 体支持应用层加解密，由环境变量开关控制，门户、管理端和本服务必须使用同一开关和同一算法。默认关闭，便于联调。生产是否开启在部署时同时打开。文件上传和下载不加密。算法用 AES-GCM。密钥放环境变量，不写进源码。这项不代替 HTTPS，也不代替登录鉴权。
|
|
- 内容审核与敏感词：未发布数据不能被门户读到。富文本来自 wangEditor-next，保存时按白名单过滤 HTML，去掉脚本、事件属性和非本站图片地址。
|
|
- IP 黑名单。
|
|
|
|
应用层 JSON 加解密按上一节的开关执行。传输加密始终使用 HTTPS。数据库里的身份证、手机号仍然用 AES-256 或 SM4 加密存储，与接口加解密无关。
|
|
|
|
## 数据
|
|
|
|
- MySQL、Redis、MinIO。
|
|
- 连接信息只放环境变量。提交 `.env.example` 时使用占位符，不要从 `docs/理解/个人对需求的理解.md` 抄真实口令。
|
|
- 开发测试库不是生产库。生产在天翼云，规格见根目录 `AGENTS.md`。
|
|
|
|
## 目录约定
|
|
|
|
栏目专篇未写完时，只允许公共能力进入代码，不按十一项栏目建业务包。
|
|
|
|
```text
|
|
server/
|
|
AGENTS.md
|
|
.env.example
|
|
app/
|
|
api/
|
|
site/ # 前缀 /api/site，其下再分 public 与 member
|
|
admin/ # 前缀 /api/admin，全部要求工作人员登录
|
|
core/ # 配置、鉴权、加解密、日志、脱敏
|
|
models/
|
|
services/
|
|
```
|
|
|
|
机构名录不要单独造一套与会员无关的机构主数据。报告查询只对照报告备案，不要做文件验真、核验码或报告审核的保存接口，见 `docs/adr/0010-report-query-is-filing-lookup.md`。数据挖掘、智能估价、中房学和住建厅的数据对接，不要建客户端或同步任务。
|
|
|
|
投诉时限、专家回复时限放配置，不写死。行业自律的投诉、警示案例、诚信档案和结果公示见 `docs/adr/0012-industry-discipline-articles-and-complaint-code.md`。
|
|
|
|
## 接口约定
|
|
|
|
- 路径与 JSON 字段使用英文，文档用中文说明业务含义。
|
|
- 脱敏在返回前完成，不依赖前端遮盖。需要脱敏的字段在模型或序列化处集中声明。
|
|
- 错误响应不回传 SQL、堆栈或内部路径。
|
|
- 批量导出和查看敏感数据要写审计日志。
|