收录 zhengquan-site 前后端完整代码:24 朝数据、24 幅权力结构图、 5 条沿革(67 节点 / 269 条细释)、44 个词条,以及部署配置与接口测试。
282 lines
12 KiB
Markdown
282 lines
12 KiB
Markdown
# 舆纪历史 · 政体志
|
||
|
||
`incarnation.cn` 的第四个子站,主题是中国历代**国体、政体、政权组织架构与官制沿革**。从夏商到当代,按朝展示中央与地方的权力结构、各机构的职掌,并用五条专线串起制度在四千年间的因革。
|
||
|
||
- 站点建议域名:`zhengquan.incarnation.cn`
|
||
- 目录:`zhengquan-site/`(前后端同仓,后端直接托管前端)
|
||
- 内容:24 个朝代或时期(春秋/战国、三国/两晋/南北朝、五代/十国、北宋/南宋等分卷)、24 幅中央权力结构图(2–4 层、5–9 个分支)、239 处机构、5 条沿革(67 个节点、269 条细释)、44 个词条
|
||
|
||
## 功能
|
||
|
||
| 页面 | 说明 |
|
||
| --- | --- |
|
||
| 总目 `#/` | 竖排书名、朝代尺、八段二十四朝总目(按常规断代分卷:战国、新莽、三国、西晋、东晋、南北朝、十国、南宋等单列),五条沿革入口、凡例(编例说明并入首页第 04 节,不单设页签) |
|
||
| 朝代页 `#/dynasty/:slug` | 国体与政体、中央权力结构图(桌面 SVG / 窄屏纵向树)、机构职掌表、地方层级、选官/监察/军事、沿革要点、史料引文 |
|
||
| 沿革 `#/threads`、`#/thread/:slug` | 宰相、监察、地方行政、选官、军事五条时间轴,按朝代分节;每节点附分条细释与史料依据 |
|
||
| 词典 `#/glossary` | 按类筛选、检索职官与制度术语 |
|
||
| 检索 `#/search` | 跨朝代、沿革、词条全文检索,命中高亮 |
|
||
|
||
设计沿用主站的宣纸、朱印、宋体与细线体系:纸色 `#fdf9f3`、朱红 `#b8261f`、赭金 `#7c5a1f`。字体不加载中文 Web Font:正文走系统无衬线栈(macOS PingFang SC、Windows Microsoft YaHei),标题与机构名走宋体栈(Songti SC / SimSun)。全站响应式,移动端表格自动转为卡片,时间轴与朝代尺可横向滑动。
|
||
|
||
## 技术栈
|
||
|
||
- **前端**:原生 ES Modules + 手写 CSS,无构建步骤、无前端框架依赖。哈希路由,直接由后端托管。
|
||
- **后端**:Node.js 18+ / Express 4,启动时加载 JSON 数据并做引用校验;提供 REST API、全文检索、静态托管与 SPA 回退。
|
||
- **数据**:`backend/src/data/` 下的 JSON 文件,改完重启即可生效;不需要数据库。
|
||
|
||
## 目录
|
||
|
||
```
|
||
zhengquan-site/
|
||
├── package.json # 根级便捷脚本
|
||
├── backend/
|
||
│ ├── package.json
|
||
│ ├── src/
|
||
│ │ ├── index.js # 启动入口(PORT 默认 5180)
|
||
│ │ ├── app.js # 路由、静态托管、错误处理
|
||
│ │ ├── data.js # 数据加载、校验、摘要与统计
|
||
│ │ ├── search.js # 轻量全文检索
|
||
│ │ └── data/
|
||
│ │ ├── meta.json # 站点信息、八个时代
|
||
│ │ ├── charts.json # 24 朝组织架构图数据
|
||
│ │ ├── threads.json # 五条沿革(含战国、西晋、南北朝、十国、南宋等细化节点)
|
||
│ │ ├── glossary.json # 44 个词条
|
||
│ │ └── dynasties/*.json # 24 个朝代或时期
|
||
│ └── test/smoke.mjs # 接口冒烟测试
|
||
├── frontend/
|
||
│ ├── index.html
|
||
│ ├── favicon.svg
|
||
│ ├── og.png
|
||
│ └── assets/
|
||
│ ├── css/style.css
|
||
│ └── js/
|
||
│ ├── app.js # 路由与全局事件
|
||
│ ├── api.js # API 封装与缓存
|
||
│ ├── store.js # 启动数据
|
||
│ ├── layout.js # 书眉与页脚
|
||
│ ├── orgchart.js # 结构图布局与渲染,窄屏转纵向树
|
||
│ ├── util.js
|
||
│ └── views/ # 各页面视图
|
||
└── deploy/
|
||
├── nginx.conf.example
|
||
└── zhengquan-site.service
|
||
```
|
||
|
||
## 本地运行
|
||
|
||
```bash
|
||
cd zhengquan-site
|
||
npm run install:all # 安装后端依赖
|
||
npm start # 启动,默认 http://localhost:5180
|
||
```
|
||
|
||
开发时可用 `npm run dev`(`node --watch`,改后端代码自动重启;前端是静态文件,刷新即可)。
|
||
|
||
```bash
|
||
npm test # 8 项接口冒烟测试
|
||
```
|
||
|
||
环境变量:
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
| --- | --- | --- |
|
||
| `PORT` | `5180` | 监听端口 |
|
||
| `HOST` | `0.0.0.0` | 监听地址,置于 Nginx 后可改为 `127.0.0.1` |
|
||
| `NODE_ENV` | — | 设为 `production` 可关闭请求日志 |
|
||
|
||
## 数据格式
|
||
|
||
每个朝代一个文件:`backend/src/data/dynasties/<slug>.json`。
|
||
|
||
```jsonc
|
||
{
|
||
"slug": "qin",
|
||
"name": "秦",
|
||
"fullName": "秦朝",
|
||
"subtitle": "皇帝制度、三公九卿与郡县制",
|
||
"period": "前221—前207",
|
||
"startYear": -221, // 用于排序与朝代尺,公元前为负
|
||
"endYear": -207,
|
||
"era": "qinhan", // 对应 meta.json 的 eras[].id
|
||
"capital": "咸阳",
|
||
"founder": "秦始皇嬴政",
|
||
"summary": "……",
|
||
"tags": ["皇帝制度", "三公九卿", "郡县制"],
|
||
"stateForm": { "label": "国体", "value": "……", "note": "……" },
|
||
"govForm": { "label": "政体", "value": "……", "note": "……" },
|
||
"org": {
|
||
"note": "架构说明",
|
||
"flow": ["皇帝", "丞相 · 太尉 · 御史大夫", "九卿", "郡", "县"],
|
||
"tiers": [
|
||
{
|
||
"label": "皇帝", "caption": "……",
|
||
"nodes": [
|
||
{ "name": "皇帝", "duty": "……", "note": "皇权世袭",
|
||
"children": [{ "name": "……", "duty": "……" }] }
|
||
]
|
||
}
|
||
]
|
||
},
|
||
"institutions": [
|
||
{ "name": "丞相", "chief": "丞相", "duty": "……", "note": "金印紫绶" }
|
||
],
|
||
"local": {
|
||
"system": "郡县制(郡—县—乡—亭—里)",
|
||
"summary": "……",
|
||
"levels": [{ "name": "郡", "chief": "郡守", "duty": "……" }],
|
||
"note": "……"
|
||
},
|
||
"selection": { "system": "……", "text": "……" },
|
||
"supervision": { "system": "……", "text": "……" },
|
||
"military": { "system": "……", "text": "……" },
|
||
"changes": [{ "title": "……", "text": "……" }],
|
||
"quotes": [{ "text": "……", "source": "《史记·秦始皇本纪》", "paraphrase": false }],
|
||
"sources": ["《史记》"],
|
||
"prev": "chunqiu", "next": "han-west"
|
||
}
|
||
```
|
||
|
||
新增一朝:
|
||
|
||
1. 复制一个结构相同的 JSON,改 `slug`、`startYear`、`endYear`、`era`。
|
||
2. 把相邻朝代的 `next` / `prev` 接上。
|
||
3. 若开启新时段,在 `meta.json` 的 `eras` 里加一项;数据按 `era` 字段自动归组。
|
||
4. 重启服务。`data.js` 会校验 slug 唯一性与前后引用,坏数据会在启动时报错。
|
||
|
||
### 组织架构图
|
||
|
||
`backend/src/data/charts.json` 按 slug 收录各朝架构图,与朝代正文分开维护,便于单独调整图形:
|
||
|
||
```json
|
||
"qin": {
|
||
"caption": "皇帝之下三公分权,九卿分理庶务……",
|
||
"root": {
|
||
"name": "皇帝",
|
||
"note": "总揽军政",
|
||
"tone": "root",
|
||
"children": [
|
||
{
|
||
"name": "丞相",
|
||
"note": "百官之长 · 领九卿",
|
||
"tone": "core",
|
||
"items": ["奉常", "郎中令", "卫尉", "太仆", "廷尉"]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
- `tone`:`root` 朱红、`core` 金底、`watch` 绿底(监察)、`local` 虚线框(地方)。
|
||
- `items`:机构内部的下属职官或部门,渲染为节点内的小标签。
|
||
- `children`:下级机构。桌面端生成横向树状图,860px 以下自动切换为纵向缩进树。
|
||
- `dashed`:为 true 时连线用虚线,表示监察、派出或地方直隶。
|
||
- 每个朝代都必须在 `charts.json` 中有图;缺失会在服务启动时报错。
|
||
|
||
### 沿革与词条
|
||
|
||
`threads.json` 的节点结构按朝代分节:`year` 为朝代名(页面主标签),`era` 为大时段(夏商周、秦汉、魏晋南北朝、隋唐、宋元、明清、近现代),`when` 为具体年份或时期,显示在节点头部右侧。`details` 为分条细释,`source` 为主要史料;二者在服务启动时校验,每节点至少 2 条细释:
|
||
|
||
```json
|
||
{
|
||
"year": "明", "era": "明清", "when": "1380", "dynasty": "ming",
|
||
"title": "废除丞相", "text": "……",
|
||
"details": [
|
||
{ "label": "胡惟庸案", "text": "……" },
|
||
{ "label": "制度代价", "text": "……" }
|
||
],
|
||
"source": "《明太祖实录》《明史·职官志》"
|
||
}
|
||
```
|
||
|
||
`glossary.json` 的词条结构:
|
||
|
||
```json
|
||
{ "term": "军机处", "category": "中央", "definition": "……", "related": ["qing"] }
|
||
```
|
||
|
||
## API
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET | `/api/bootstrap` | 站点信息、时代、统计、朝代摘要、沿革摘要、随机史料 |
|
||
| GET | `/api/dynasties` | 朝代摘要列表 |
|
||
| GET | `/api/dynasties/:slug` | 朝代详情(含前后朝与相关词条) |
|
||
| GET | `/api/threads` | 五条沿革全文 |
|
||
| GET | `/api/threads/:slug` | 单条沿革(节点补朝代名与年代) |
|
||
| GET | `/api/glossary?q=&category=` | 词条筛选 |
|
||
| GET | `/api/search?q=&limit=` | 跨三类内容检索 |
|
||
| GET | `/api/quote` | 随机一条史料 |
|
||
| GET | `/api/health` | 健康检查 |
|
||
|
||
除 `/api/*` 外的路径都会回退到 `frontend/index.html`,可直接支持哈希路由。
|
||
|
||
## 部署
|
||
|
||
后端同时托管前端,因此只需要一个 Node 进程,不需要额外的前端服务器。
|
||
|
||
```bash
|
||
# 服务器上
|
||
git clone <repo> /opt/zhengquan-site
|
||
cd /opt/zhengquan-site
|
||
npm --prefix backend ci --omit=dev
|
||
PORT=5180 NODE_ENV=production node backend/src/index.js
|
||
```
|
||
|
||
用 systemd 常驻:
|
||
|
||
```bash
|
||
sudo cp deploy/zhengquan-site.service /etc/systemd/system/
|
||
sudo chown -R www-data:www-data /opt/zhengquan-site
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now zhengquan-site
|
||
```
|
||
|
||
Nginx 反向代理与 HTTPS 见 `deploy/nginx.conf.example`。要点:
|
||
|
||
- `proxy_pass http://127.0.0.1:5180;`
|
||
- `/assets/` 可加长缓存(后端已设 `Cache-Control: max-age=604800`)
|
||
- `index.html` 不缓存(后端已设 `no-cache`),保证发版后立即生效
|
||
- 证书可用 certbot 申请,把示例中的路径替换为实际证书路径
|
||
|
||
## 挂到主站
|
||
|
||
主站首页目前写着「凡三处」,需要改为「凡四处」,并在 `toc-list` 里追加一行。可直接使用主站现有的样式类:
|
||
|
||
```html
|
||
<li class="row">
|
||
<a class="row-link" href="https://zhengquan.incarnation.cn" target="_blank" rel="noopener">
|
||
<span class="row-no">04</span>
|
||
<span class="row-name">
|
||
政体志
|
||
<span class="row-desc">夏商至当代 · 国体政体 · 官制沿革</span>
|
||
<span class="row-detail"><b>16</b> 朝 · <b>162</b> 处机构 · <b>5</b> 条沿革</span>
|
||
</span>
|
||
<span class="row-lead" aria-hidden="true"></span>
|
||
<span class="row-num"><b>40</b> 词条</span>
|
||
<span class="row-go">
|
||
在线
|
||
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
|
||
<path d="M7 17 17 7M8 7h9v9" />
|
||
</svg>
|
||
</span>
|
||
</a>
|
||
</li>
|
||
```
|
||
|
||
同时建议更新:
|
||
|
||
- 主站 `<title>` / `description` / `og:description` 中的「三处」「三处刊行」为「四处」;
|
||
- 首屏题记补一句制度卷的读法;
|
||
- 「摘录」区可加三条政体志的条目,链到 `#/dynasty/qin`、`#/thread/xiangquan`、`#/glossary?q=三省六部`。
|
||
|
||
## 口径与资料来源
|
||
|
||
- **国体**指国家的阶级性质,**政体**指政权的组织形式。古代部分采用中国史学界通行表述(夏商周为奴隶主阶级专政、秦汉至清为地主阶级专政),并对史料局限与学界讨论随文注明。
|
||
- 年代取通行说法;先秦年代多依夏商周断代工程。制度名称、官称从正史与政书,异说另注。
|
||
- 引文标出处;属于今人概括而非原文的,标「大意」。
|
||
- 主要依据:历代正史职官志/百官志、《周礼》《唐六典》《通典》《文献通考》《明会典》《清会典》、《中华民国临时约法》《中华人民共和国宪法》,以及钱穆《中国历代政治得失》、严耕望《中国地方行政制度史》等近人研究。
|
||
|
||
## 许可
|
||
|
||
内容与代码用于 `incarnation.cn` 及其子站。转载、引用请注明出处;史料引文请复核原书。
|